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

[Ben Konrath <bkonrath@xxxxxxxxxx>]

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.

[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.   

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.

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

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

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.

[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.

> -        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. 

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 language. IIRC, it is only windows content that
falls in this category so it shouldn't be a problem. Perhaps Mike Behm
can comment.

> 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
> 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.

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?

> 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?

> - 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