[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[platform-help-dev] Re: [platform-doc-dev] new help system proposal


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]