[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[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
New Help System proposal
========================
This document is an attempt to describe ideas that were discussed during a
documentation meeting in Ottawa on October 18, 2004 and a subsequent internal
meeting with Mike Behm, Jeff Pound and myself. This document is very much a
work in progress and is by no means authoritative. Comments, suggestions and
improvements are welcome.
Requirements
============
(1) replaceable screenshots
(2) replaceable platform specific content
(3) ability to generate pdfs from the docs
(4) implementation should accommodate points 1 - 3 without modification of
the base documentation
Point 1
=======
It would be best to break the platform specific images off into their own
plugin. This will allow ISVs to remove the default screenshots to save
resources if they choose.
First, we should standardize on a file format to use for images. I would like
to suggest PNG as the CDT currently uses this format and it is the format that
we here at Red Hat have standardized on due to the past patent issues with the
GIF format - I believe this is no longer a concern though. It should be
fairly easy to convert the current screenshots from GIF so they don't have to
be re-taken. Icons that are not platform specific could remain in their
current format, although we may want to consider converting them to PNG for
consistency.
The help system would detect the presence of the "screenshot pack" and pull
screenshots, css file and copyright image from it. The directory structure of
the "screenshot pack" would mirror that of the default win32 pack. This
originally would be just taken from the existing plugins - I don't foresee the
need to change this though. The actual image names would not be platform
specific as was discussed in the meeting on October 18th.
Here is a visual example:
org.eclipse.jdt.doc.user org.eclipse.jdt.doc.user.win32
+-----------------------+ +----------------------------+
| | | |
| | | win32context.xml |
| | | images |
| | | ... |
| | <--> | tasks-31.png |
| | | tasks-32.png |
| | | ... |
| | | |
| content and images | +----------------------------+
| that are common to |
| all platforms | org.eclipse.jdt.doc.user.gtk
| | +----------------------------+
| | | |
| | | gtkcontent.xml |
| | | images |
| | | ... |
| | <--> | tasks-31.png |
| | | tasks-32.png |
| | | ... |
| | | |
+-----------------------+ +----------------------------+
We still have to figure out how to implement the actual image replacement.
From our initial investigations, it seems that when the user clicks on an
entry in the toc, mozilla is called with the specified html file, css file and
copyright image. One thought is to filter the html before it gets to mozilla.
The path in the img tag would be changed depending on the which "screenshot
pack" is present. At this stage this just an idea; we haven't investigated the
feasibility yet.
Point 2
=======
First, documentation should be modified to be platform neutral wherever
possible - I think this was discussed on the 18th. For the remaining
documentation that is platform specific, we would like to use a system similar
to the ResourceBundle system in Java. Instead of putting the platform
specific content directly in the html file, a reference to this content should
be used. The reference would be replaced with the appropriate content when the
html is filtered (see above). If there is content that exists on one platform
but not another, the entry in the content file could be left empty.
As an intermediate step, we might want to consider a css solution. Platform
specific content could be marked with class=widgetset or class=platform. These
would be added to <p> tags or <span> tags as required. For Example, if there
is a paragraph that is windows specific, <p> windows specific content </p>
would become <p class=win32> windows specific content </p>.
During the meeting someone mentioned that there was an html editor for eclipse.
Perhaps as a long term goal we could develop this editor to interpret the html
for a specified platform to give a preview of what the html would look like
after it is filtered. This would help keep the flow of the text consistent.
Point 3
=======
If we use XHTML that validates for all of the documentation, then converting to
other formats should be as easy as writing an XSLT stylesheet. We will probably
use htmldoc to convert the html to pdf for the foreseeable future, but this
will allow the documentation to be converted to an XML based solution should
the need crop up.
For those who are not familiar with XHTML, it is just HTML 4.0 re-formulated
to be a valid subset of XML. The noticeable differences are as follows:
1) Set the DOCTYPE:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
2) Close all tags:
<br />
<img src="file.png" />
<hr />
