Create a style guide for documentation writers - PNG as standard image format See: http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-doc-home/docs/EclipseStyle.htm
| Proposal |
A complete solution would satisfy the following requirements:
To allow ISVs the ability to provide their own platform / widget set specific resources in a custom fragment, the search path for resources in a documentation plug-in needs to be expanded. Currently, only the $nl$ directories are searched. The proposed search path adds widget set (ws) and operating system (os) to the existing natural language (nl) search path. An ISV can override files by contributing a fragment containing the files which need to be overridden in the correct directory. The search order will be ws, then os and finally nl. Compressed files in "doc.zip" will continue to be searched before files that are not compressed.
As an example, the search path for zh_CN locale with gtk
widget set on Linux would be:
This allows widget set and operating system specific documentation to be contributed (in fragments) and displayed without altering the existing doc plug-ins. If no fragment is installed the end result would be exactly the same as it is in the current help system. To accomplish this, the help system will have to use the system's nl, ws, and os settings to explicitly search the possible paths for the file. The use of $nl$, $ws$, and $os$, accepted by the Platform.find() API, must be avoided in the help system to ensure the root directory is not searched to early (or multiple times).
This solution allows ISVs to have a documentation fragment that contains either resources from a single language with multiple widget sets / operating systems or resources from the same widget set or operating system with different languages. The solution does not allow for all permutations of language, operating system and widget set to be placed in one fragment - separate fragments would still be required. For example, an ISV could make a fragment that has gtk-English and gtk-Chinese resources by placing the resources in the appropriate nl folders. In a separate fragment, this ISV could also support carbon-English and gtk-English by placing the files in the appropriate ws directory. This lack of support for all permutations is not problematic as this requirement is relatively rare and if the need should arise, there is a way to handle it. It should be noted that the Eclipse SDK language pack does not contain language specific screenshots.
The current documentation in Eclipse SDK has a mix of both platform and widget set specific content. This content will be marked with appropriate CSS classes to give ISVs control over which of the platform and / or widget set specific content is displayed. The information described below is currently a draft of the final solution. The documentation from eclipse.org will be marked up over the next little while to test if this solution will work. There may be some minor changes.
Platform specific content will be marked with either:
The idea is that content common to most supported platforms and widget sets falls under the default category. This designation has nothing to do with the popularity of a given platform. Content specific to just a few platforms and widgets sets is tagged with the appropriate CSS classes described above. So far we have identified that only win32, gtk, and carbon classes are needed to differentiate content that is not common to all. The set of classes can be expanded if the need arises.
The CSS file will reside in the root of product plug-in (PRODUCT_PLUGIN/book.css). References to this CSS file will be prefixed with PRODUCT_PLUGIN in the HTML of all the documentation. This allows ISVs to override the default CSS file with a custom CSS file in the root of their branding plug-in. This CSS file would specify which platforms and widget sets should not be displayed.
The Eclipse SDK will ship with its CSS file in org.eclipse.platform/book.css, and this will call a bookos.css file that sets default_os, win32, default_ws, gtk, and carbon off (the remaining class, all_os_ws remains on).
ISVs can also achieve automatic selection of marked up content with multiple style sheets read by the help system; which CSS files are used is determined by the system settings. In this case the branding plug-in will have a book.css file and one or two additional CSS files, one to disable all but particular platform-specific content, and optionally a second to disable all but particular widget-set specific content. The help system resource resolution will apply the appropriate CSS files to the product (branding) plug-in.
| O/S | CSS | |||||
|---|---|---|---|---|---|---|
| Path names | Help Key | all_os_ws | ||||
| win32 | default_os | gtk | carbon | default_ws | ||
| Win32 | on | off | off | off | on | off |
| Linux Gtk | off | on | on | off | off | off |
| Linux Other | off | on | off | off | on | off |
| Mac | off | on | off | on | off | off |
| Unix Gtk | off | on | on | off | off | off |
| Unix Other | off | on | off | off | on | off |
| Generic | off | off | off | off | off | on |
The directory structure is as follows:
The book.css for each of the cases noted above imports a single bookos.css file, because these cases have operating systems that imply the widget set, or a widget set that implies the operating system. An ISV that wants to release a version of Eclipse that runs under Windows, Unix gtk and some other Unix widget set would need to call a book.css that imports a bookos.css (which would disable either win32 or default_os) and a bookws (which would disable all_os_ws, carbon, and either gtk or default_ws).
Sample CSS files will be part of this solution so that ISVs can easily achieve this automatic selection.
All of this means that the documentation must be written in such a way that it makes sense both when the all_os_ws content is displayed and when only one class of content is displayed. Therefore the source HTML files will have duplicated content, but the help browser will show only the content that is appropriate for the user. This point will be stressed in the documentation style guide and an example will be given.
This solution allows the eclipse.org documentation to be customized without modification.
This section describes some of the issues that were encountered and possible solutions to these issues.
Currently, the SDK PDFs on eclipse.org are generated with htmldoc which does not support CSS. This does not pose a problem for Eclipse SDK PDFs because they will be displaying content for all platforms. This will, however, pose a problem for ISVs who wish to generate PDFs that display content for only one platform and/or widget set.
A solution to this is to use fully validating XHTML for all of the documentation in the Eclipse SDK. This allows ISVs to convert to other formats by writing an XSLT style-sheet and/or by using one of the plethora of XML conversion tools that exist.
Unfortunately, certain doctypes (XHTML) are not properly supported in Internet Explorer and cause an unneeded scrollbar to appear, therefore this remains an outstanding issue.
The searching mechanism in the help system currently doesn't support CSS and thus a user will get inaccurate search results if an ISV chooses to hide some platform or widget set specific content. The easiest solution is to add rudimentary CSS support to the help system. The plan is to add support for only the CSS tags that are described in this document.
By default, the Eclipse SDK will show content for all platforms and widget sets. If an administrator wishes to change this, they can add a custom branding plug-in, or fragments to the existing branding plug-in, to override the default CSS file. The administrator can also add fragments to the documentation with platform and widget set specific screenshots and HTML files. As part of this proposal, we will add support for command line parameters that can override actual OS and WS of the system hosting the info center.
Create a style guide for documentation writers - PNG as standard image format This proposal can be mostly blamed on Michael Behm, Konrad Kolosowski, Ben Konrath and Jeff Pound