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

[Konrad Kolosowski <konradk@xxxxxxxxxx>]

Hi Ben,

Your requirments make perfect sense,
but I do not see a need for help system changing a lot to satisfy them.
 I think this is good and hope you agree.  I believe most effort
will need to go in the documentation work.  The issues that touch
the infrastructure - help system - can be solved by leveraging features
already supported by Eclipse runtime or help system with little change.
 See if it is satisfactory.


(1) replaceable screenshots

It is clear to that displaying OS specific
files falls within the same category of issues as displaying NL specific
versions of files.  Eclipse can be shipped with an English documentation
and Windows images, and it should be possible to add screen shots from
other OSes as it is possible for other languages.  Help system should
retrieve the correct files automatically and transparently, based on the
current NL or OS.

Presently, help system searches nl subdirectories
of a plugin and its fragments for a file before looking at a root for a
default one.  Noting that help system allows documentation be delivered
in doc.zip, this is the sample search order for a file:

nl/zh/CN/doc.zip!file,
nl/zh/doc.zip!file,
doc.zip!file,
nls/zh/CN/file,
nl/zh/file,
file

Each path is being tried from plug-ins
and fragments, until first success.

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.

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


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.
-        Images
in the doc plug-ins can be changed to use PNG extension, but it is an independent
issue from ability to replace


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

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.


TODOs:
- mark Windows specific paragraphs in
Eclipse documentation with class=win32
- 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.

(4) implementation should accommodate
points 1 - 3 without modification of the base documentation
It is met by (1) and (2) above.



I subscribe to both platform-doc-dev
and platform-help-dev.  Until we agree on some direction, there is
no clear separation between doc or help issues so using platform-help-dev
or cross post to both lists makes sense.  Later on, I suppose there
will be more doc specific details to discuss on platform-doc-dev list.

Konrad Kolosowski, IBM
Eclipse Help System

Ben Konrath <bkonrath@xxxxxxxxxx>
Sent by: platform-doc-dev-admin@xxxxxxxxxxx

11/02/2004 08:36 PM

Please respond to
platform-doc-dev

To	platform-doc-dev@xxxxxxxxxxx, platform-help-dev@xxxxxxxxxxx
cc	Jim des Rivieres/Ottawa/IBM@IBMCA, Michael Van Meekeren/Ottawa/IBM@IBMCA, Andrea Covas/Ottawa/IBM@IBMCA
Subject	[platform-doc-dev] new help system proposal

Hello,

Attached is a proposal for the new help system. Jeff Pound
(jpound@xxxxxxxxxx) and I are available to help implement a solution.
During the meeting it was mentioned that some of the help system people
would be interested in this as well. Will this message reach these
people? Could someone cc the person who attended the meeting by
teleconference (sorry I forget her name).

Jeff, Mike and I are signed up to platform-doc-dev and I'm signed up to
platform-help-dev. Which list should we use to hash out a solution for
this stuff?

I'm looking forward to hearing some comments and suggestions.

Cheers, Ben
[attachment "new-help-system.txt" deleted by Konrad Kolosowski/Toronto/IBM]