[platform-help-dev] Re: new help system proposal

[Konrad Kolosowski <konradk@xxxxxxxxxx>]

Mike, Ben and all,


It looks like we agree on the changes required to
help system component.  Very good.  Remaining unknowns are now
about changes to documentation plug-ins and their contributions.  I
continued the trend of inlining the response, added technical details and
suggestions.  I hover cannot confirm this is the way to go as I do
not have such authority over the doc component.  Doc people need to
add their touch to this.  Thank you.

Konrad Kolosowski
Eclipse Help System

> Hi Ben,
> 
> My comments are interspersed too.
> 
> 
> 
> Mike
> 
> 
> Ben Konrath wrote:
> 
> > Hi Konrad,
> > 
> > My comments are interspersed below. 
> > 
> > On Thu, 2004-11-04 at 23:46 -0500, Konrad Kolosowski wrote:
> > 
> > 
> >>(1) replaceable screenshots 
> > 
> > 
> > <snip>
> > 
> >>Enhancing help system to search paths under os specific locations
> >>like: 
> >>os/linux/x86/doc.zip!file, 
> >>os/linux/doc.zip!file, 
> >>nl/zh/CN/doc.zip!file, 
> >>nl/zh/doc.zip!file, 
> >>doc.zip!file, 
> >>os/linux/x86/file, 
> >>os/linux/file, 
> >>nls/zh/CN/file, 
> >>nl/zh/file, 
> >>file 
> >>solves the problem.  Windows screen capture can be packaged
in doc.zip
> >>of a plug-in as done today, and Linux fragment can be later
added with
> >>os/linux/doc.zip containing a Linux equivalent image.
> > 
> > 
> > I think that this solution will work. We might want to use the
widget
> > set instead of the platform/architecture. I think that most of
the content
> > specific stuff is broken down by widget set not by platform [1]
-- I
> > still have to check out the specific details. There might be
stuff
> > common to all unix-like platforms as well, using eclipse instead
of
> > eclipse.exe comes to mind.
If content is widget set specific, we could look-up
in
ws/gtk/doc.zip!file
instead of
os/linux/x86/doc.zip!file, 
os/linux/doc.zip!file
or we can do them all.  It will not make much
difference from the help system point of view.

> > 
> > [1] of course win32 seems to be referred to as both a platform
and a widget
> > set.
> > 
> > 
> >>Advantages of this solution: 
> >>-        image file names and URL links
do not need to be changed. 
> >>-        no need to separate Windows images
into "screenshot pack"
> > 
> > 
> > The initial reason for separating the windows screenshots was
so that
> > ISVs would not have to ship two sets of images. This would save
some
> > disk space and bandwidth. To get an estimate of how much space
the
> > images consume, I copied all of the images out of the documentation
> > directory and zipped them up. This zip file was 8.9M.  

I understand the 8.9 M.  It is comparable number
to about 2.5 MB of zips with English HTML files that are installed, yet
not used in Eclipse with NL pack running in one of the translated languages.
 Yet we always ship English (in a common plug-in).  There is
more MBs to be gained by removing Windows documentation, but I think the
cost of issues caused by not having a one safe default set of files exceeds
the benefit.
In addition, I think the number of screenshots could
be reduced (as a completely separate effort).  Most of the screenshots
are useless.  They look nice, but they depict the UI, that user is
seeing in the workbench anyway.  That would decrease the size overhead.

> > 
> > We would like to donate our screenshots (gtk with bluecurve theme)
to
> > eclipse.org so that they can be useful to the linux community
as a whole
> > [2]. If our screenshots do make it upstream, the screenshots
would add ~
> > 9M to zip. Now let say that an ISV that releases a product for
OSX
> > carbon wants to donate their screenshots. That would add another
9M. And
> > so on for motif and any other widget set that might be supported
in the
> > future.
Not necessary.  A sensible solution is to have
default images in the plug-in (always present) and images for other WSes
in their own fragments.  It is an improvement over NL translation
fragments donated to Eclipse, where all not English languages are bundled
in one fragment.
This way Eclipse windows build has 9MB of images.
 If fragment of other system is available, that build will have only
9+9 MB.  And very importantly, there is nothing broken or to do with
builds for other systems, where there is no screenshot fragment contributed.

> > 
> > Here are a couple of options that would avoid this scenario:
> > 
> > o Don't accept any other screenshots - only use win32.
> >    * my personal opinion is that eclipse.org should
not do this as it  
> >      re-enforces the idea that other platforms
are secondary to
> >      windows
> > 
If you mean that Eclipse should not accept contribution
of other screenshots at all.  I agree its a sick idea.
If you mean that Eclipse SDK build should not contain
other screenshots but Windows, I think it is acceptable.  As long
as there is a way to add other images this is not a problem.  As with
the translations a feature with other screenshot can be added and Eclipse
run in a desired language.  Whether the feature is published on Eclipse.org
web site, or not does not enable things, but will give the benefits open
source provides.
As for which windowing system is chosen as the default
is up to the organization developing a particular feature.  Theoretically
the default images could be a mix from different WSes, whichever was available
to developer writing a particular document.  Practically, since most
Eclipse SDK developers use Windows, it makes sense to have all default
set of screenshot for features in SDK taken on Windows, and eliminate a
need for a windows specific fragment.

> > o Include the win32 +  platform / widget set screenshots
in each zip.  
> >   For example, the Solaris 8 (SPARC/Motif) zip would only
have win32 
> >   and Motif screenshots. The selection of the screenshot
package could 
> >   happen at build time.      
> >    * at most there will be an extra 9M used
> >    * this allows other ISVs (besides Red Hat) to donate
screenshots
I do not think it make sense to have win32 and another
platform in one zip.  It is not possible to require that screenshots
are taken on all platforms, so a version of each image would have to exist
in a common plug-in.  That plug-in cannot differ from build to build
depending on the widget set it is for.  A given plug-in or fragment
must be identical no matter where it is going to be installed.  

> > 
> > o As an extension to the option 2, the build could detect the
presence 
> >   of the platform / widget set specific images and remove
the win32 
> >   ones where appropriate 
> >    * [+] minimal waste of space
> >    * [+] allows other ISVs (besides Red Hat) to donate
screenshots if 
> >          they choose to, but also allow
ISVs to replace the 
> >          screenshots and even if they
don't want to donate them
> >    * [+] doesn't have to be implemented right away
- could be added 
> >          later
> >    * [-] more complex to implement
> >      
> > o Other suggestions are welcome.
The build can will pick different features, that will
contain the same plug-in and different, OS or WS specific fragments (or
less likely a fragment with all not Windows versions of images).
You can notice, I am arguing very strongly that common
plug-in holds all default images.  If it did not, that it would be
easily possible to create a build with all dependencies satisfied, yet
missing images at all.  Images for all fragments, used by different
builds would have to be supplied simultaneously, which would put a burden
on developers discouraging changing docs, affecting quality and completeness
of documentation.  Right now a developer writes English version of
document and adds Windows screen shot during development.  Their work
is done and everything works.  Translations and such can be added
as needed months later, or after the release is complete.

Hoping that 9MB of space wasted on Linux by default
(Windows) images, is not a critical problem for you, I keep arguing my
version of the proposal, acknowledging there will be some wasted space
and clarifying that:
- ws/gtk/doc.zip!file should be searched in addition
of searching with os/ subdirectories;
- that Windows SDK screenshots should be kept in the
plug-in;
- that other screenshots should be added in /ws or
/os subdirectories of a _fragment_ (one fragment for linux ws, another
fragment for Solaris motif etc.)
- I have no say whether fragments should be included
in daily builds or posted separately; if someone commits to ensuring screenshots
in the fragments are in sync with screenshots in the plug-in every week
as they change, a release team or PMCs can decide to include and build
as part of SDK.  Otherwise a periodic contribution (lets say for each
milestone and final build) can be posted.

> > 
> > [2] As I recall, there is some hesitation to accept our screenshots
> > because bluecurve performs 30% slower on perspective changes
when
> > compared to other gtk themes. It would be nice to get a definitive
> > answer so we know where this stands.
If screenshots are contributed as a separate feature (with fragments),
accepting and publishing them has no drawbacks, I can see.  To include
these fragments in the SDK build on Linux, means they are not separable
for anybody building purely on top of the SDK.  I am speaking from
help system point of view.  Perhaps later Jim des Rivieres can gather
what doc/releng or PMCs decide.

> > 
> > 
> >>-        solution works for images, CSS,
or even whole HTML
> >>documents. 
> >>-        allows overriding of subset of
common files, does not require
> >>up front knowledge of which images will be changed on different
OS. 
> > 
> > 
> > I really think that this is a good idea. I noticed that the screenshots
> > came out relatively late in the 3.0 release cycle. If an ISV
doesn't
> > have time to do *all* of their screenshots before they release,
they
> > will not be left with broken images.
> > 
> > 
> >>TODOs: 
> >>-        change the help system to look-up
files in the specified
> >>order (including os/* directories as first priority).  This
is not
> >>trivial as Platform.find() does not look inside doc.zip and
does not
> >>tell where it found the file, but it is doable.
> > 
> > 
> > Ok, I took a quick look but I want to hold off doing anything
until we
> > come to an agreement.

> > 
> > 
> >>-        Images in the doc plug-ins can
be changed to use PNG
> >>extension, but it is an independent issue from ability to
replace 
> > 
> > 
> > I don't agree that this is an independent issue. The way I understand
> > your proposal is the image file names have to be same for them
to
> > override the default windows images. If Red Hat chooses use PNGs
and the
> > default is GIF then the file names will be different. 
I agree with you. I did not mean not to switch to PNG.

> > 
> > Previously I indicated that the patent issues with GIF were resolved.
> > This was a mistake. I've just done some poking around and found
that IBM
> > still holds a patent on the LZW algorithm used by the GIF format
[3].
> > While this patent has not been enforced, and I have no reason
to believe
> > it will be enforced in the future, I personally think standardizing
on
> > PNG is the way to go. The article also indicates that PNG offers
better
> > compression compared to GIF.
> > 
> > [3] http://en.wikipedia.org/wiki/GIF
> > 
> > 
> >>(2) replaceable platform specific content 
> >>The files that are very OS specific can be replaced as a whole
by
> >>providing a Linux version of it in os/linux/doc.zip in a fragment,
> >>leveraging mechanism explained above for images.
> > 
> > 
> > If linux specific content was merged into the main eclipse.org
docs
> > (and we hope it is), there might be a problem if this content
is
> > translated to other languages. IIRC, it is only windows content
that
> > falls in this category so it shouldn't be a problem. Perhaps
Mike Behm
> > can comment.
> 
> Red Hat does not localize Eclipse documentation now and there are
> (currently) no plans to do so in the future. But this raises an 
> interesting question: I gather that a user of Eclipse on Windows in
> Germany would automatically see online help in German. Given that
there 
> is no German online help for the Linux version, it would be useful
if we 
> could present the user with the choice of viewing the Windows-German
> help or the Linux-English help.
Ben, you also indicated in the later post this is not a problem.

> 
> >>For the remaining files with little OS specific content it
is not
> >>natural to separate some paragraphs and perform keyword substitution
> >>in all HTML at runtime.  It is possible today by documentation
plug-in
> >>providing IContentProducer implemented to perform filtering
of all
> >>content, but I believe it is an overkill for a simple issue.
 I like
> >>your intermediate step involving CSS better.  Post 3.0M3
help system
My typo.  In case it does not work for you, I
should have written "3.1M3".

> >>supports "PRODUCT_PLUGIN" keyword to be used as
name of the plug-in in
> >>URLs of documents.  Referring to this plug-in will resolve
to
> >>different real plug-in depending on which product runs.  This
feature
> >>allows non Windows product to provide its own custom copy
of the CSS
> >>in its product plug-in.  This CSS can, for example, define
style for
> >>win32 class to be display: none. 
> > 
> > 
> > My only concern with a CSS solution is that it may be too much
of a
> > burden to maintain. For example,        
                 
> > org.eclipse.platform.doc.user/concepts/chelpsys.htm has the line:
> > 
> > Bring focus to the interface widget in question by clicking on
it or
> > using the Tab key, and then press F1 (Ctrl+F1 on GTK+, and Help
key on
> > Carbon)
> > 
> > I envision the mark up to be something like:
> > 
> > <p>Bring focus to the interface widget in question by clicking
on it or
> > using the Tab key, and then press <span class=win32>F1</span>
> > <span class=gtk>Ctrl+F1</span><span class=carbon>the
Help key</span></p>
> > 
> > Motif is not mentioned in this section but it's possible there
could be
> > another span tag to accommodate it. I probably won't be writing
content
> > so I think that the people who will be should comment.
> 
> This is pretty standard practice at places such as IBM--except that
the 
> <span> tags would probably be at the sentence level. (This makes
it 
> easier for the localization team.)
> 
> > Also, the technical writers expressed interest in a system that
allows
> > them to write content in WYSIWYG editors such front page and
> > dreamweaver. Do these tools support a system like this?
> 
> Sure--you can mark areas of text and apply classnames to them.
> 
> >>TODOs: 
> >>- mark Windows specific paragraphs in Eclipse documentation
with
> >>class=win32
> > 
> > 
> > I believe this is already done in our internal cvs. 
> > 
> > Mike Behm:
> > 
> > Can you confirm this?
> 
> This is not done in our internal CVS. Ben, you recall when we had
to 
> rework the entire Eclipse documentation set in 15 working days? I
ripped 
> out text rather than apply CSS tags. However, as we've been asked
to 
> provide two patches to every file (one for format and one for content),
> I'll have to work from the eclipse.org CVS tree. That means that I'll
be 
> able to tag-out the operating-system-specific text.
> 
> We do need to agree on the CSS class names, however. Are they:
>   -win32
>   -gtk
>   -osx
In separate note Ben suggested:
           -win32  
(things specific to the platform and widget set)
                
   -unix    (things common to unix like platforms,
see 1 below)
                
   -gtk     (widget set)
           -motif   (widget set)
           -carbon  (widget set)

org.eclipse.core.runtime.Platform defines possible string values for OS,
and WS.  That would be for WS:
- win32
- gtk
- motif
- carbon 
- photon
- unknown
However for OS there are:
- aix
- hpux
....
Total of 7 + "unknown".  It would be
nice to use them, but that would mean lot of work.  There is no one
value to represent unix (and like), and the unknown ws collides with unknown
os.  CSSes can use their own set of values, that as little work as
necessary but allow marking all OS or Ws sensitive pieces and cover all
possible ws/os combinations.  I would think the following is complete:
To mark OS specific content
- win32
- other_os (effectively acting as unix or !win32)

To mark WS specific content
- win32 (same as win32 for OS)
- gtk
- motif
- carbon
- other_ws (effectively photon or other unknown)
Total of 6 classes.  A sentence that is OS specific
will need to appear in the document twice (one marked with win32, and the
other with other_os).  A sentence that is WS specific will need to
appear 4 times, marked with different class each time.

If it looks good, than CSS files in org.eclipse.platform
plug-in can be placed, (this is just an example assuming all CSS are in
the plug-in, not optional fragments) as follows:

/os/win32/book.css (makes win32 class visible, make
rest of the classes hidden)
/book.css (makes other_os class visible, win32 hidden,
imports wsbook.css)
/wsbook.css (makes other_ws class visible, gtk,motif,carbon
hidden)
/ws/gtk/wsbook.css (makes gtk class visible, motif,carbon,other_ws
hidden)
/ws/motif/wsbook.css (makes motif class visible, gtk,carbon,other_ws
hidden)
/ws/carbon/wsbook.css (makes carbon class visible,
gtk,motif,other_ws hidden)

> 
> >>- place CSS used by Eclipse books in org.eclipse.platform
plug-in 
> >>- change references from Eclipse topics to CSS to be
> >>???../PRODUCT_PLUGIN/book.css". 
> >>
> >>(3) ability to generate pdfs from the docs 
> >>I agree. 
> > 
> > 
> > Great. We might want to lower the requirement to XHTML Transitional
-
> > IIRC, it's a little less .. umm ... strict :)
> > 
> > Ben's TODO List
> > 
> > * look at the details of the platform specific content to determine
the 
> >   best approach for content -- widget set vs. platform specific
options.
> > * investigate the changes required to modify the help system
to look-up 
> >   files in the specified order
> > 
> > I'm a little bit tied down right now because of an impending
Red Hat
> > Developer Suite release, but I should be able to look at this
more next
> > week.  
> > 
> > I'm looking forward to any comments.
> > 
> > Cheers, Ben
> > 
> > _______________________________________________
> > platform-doc-dev mailing list
> > platform-doc-dev@xxxxxxxxxxx
> > http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
> 
> _______________________________________________
> platform-doc-dev mailing list
> platform-doc-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-doc-dev