| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>Platform Specific Documentation</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" |
| type="text/css"> |
| <style> |
| table,td,th { font-size: 10pt; font-family: arial, helvetica, geneva;} |
| </style> |
| <style media="screen"> |
| th {background-color: #334070; color:#ffffff;} |
| .on {background-color: #ffff66;} |
| </style> |
| <style media="print"> |
| .on {font-weight: bold;} |
| </style> |
| |
| </head> |
| <body style="background-color: rgb(255, 255, 255);"> |
| <table width="100%"> |
| <tbody> |
| <tr> |
| <td |
| style="background: rgb(0, 128, 192) none repeat scroll 0% 50%; -moz-background-clip: initial; -moz-background-origin: initial; -moz-background-inline-policy: initial;"><b><span |
| style="color: white;">Proposal</span></b></td> |
| </tr> |
| </tbody> |
| </table> |
| <center> |
| <h2>Proposal: Platform Specific Documentation</h2> |
| </center> |
| <h3>Abstract</h3> |
| The documentation in Eclipse currently lacks the ability for ISVs to |
| override |
| widget set specific screenshots and lacks the ability to turn off or |
| override |
| platform specific content. This proposal attempts to address these |
| issues by |
| adding support for resource overriding to the help system and by adding |
| CSS |
| class tags documentation with platform specific content. |
| <h3>Requirements</h3> |
| <p>A complete solution would satisfy the following requirements: </p> |
| <ol> |
| <li>Replaceable resources (screenshots, HTML files and CSS files)</li> |
| <li>Control over the display of platform specific content</li> |
| <li>The solution should allow the documentation to be customized |
| without the need to modify the base documentation plug-ins</li> |
| </ol> |
| <h3>Proposal</h3> |
| <h4>Replaceable Resources - Screenshots and HTML files</h4> |
| <p>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.</p> |
| <p>As an example, the search path for zh_CN locale with gtk |
| widget set on Linux would be:<br> |
| </p> |
| <ul> |
| <li>/ws/gtk/doc.zip!file</li> |
| <li>/os/linux/doc.zip!file</li> |
| <li>/nl/zh/CN/doc.zip!file</li> |
| <li>/nl/zh/doc.zip!file</li> |
| <li>/doc.zip!file</li> |
| <li>/ws/gtk/file</li> |
| <li>/os/linux/file</li> |
| <li>/nl/zh/CN/file</li> |
| <li>/nl/zh/file</li> |
| <li>/file</li> |
| </ul> |
| <p>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). |
| </p> |
| <p>This solution allows ISVs to have a documentation fragment that |
| contains |
| either resources from a single language with multiple widget sets / |
| operating |
| systems <b>or</b> 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.</p> |
| <h4> Control Over The Display of Platform Specific Content</h4> |
| <p>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.</p> |
| <p>Platform specific content will be marked with either: <br> |
| </p> |
| <ul> |
| <li>class=all_os_ws (for generic documentation that displays |
| the operation of all operating systems and widget sets) |
| <li>class=default_os (not win32, ie. executable names that do not |
| have .exe) </li> |
| <li>class=win32 (OLE, DND and .exe executable names) </li> |
| </ul> |
| Widget Set specific content will be marked with these: <br> |
| <ul> |
| <li>class=default_ws (things that apply to all widget sets except the |
| ones marked below - Windows is in this category)</li> |
| <li>class=gtk (widget used on Unix-like platforms - including Linux)</li> |
| <li>class=carbon (widget set used on Mac OS X)</li> |
| </ul> |
| <p>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. |
| </p> |
| <p>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.</p> |
| |
| <p>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 <b>off</b> |
| (the remaining class, all_os_ws remains on). |
| </p> |
| |
| <p>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. </p> |
| |
| <table border="1" cellpadding="3" cellspacing="0"> |
| <tr><th rowspan="3">O/S</th><th colspan="6">CSS</th></tr> |
| <tr><th colspan="2">Path names</th><th colspan="3">Help Key</th><th rowspan="2" width="75" valign="bottom">all_os_ws</th></tr> |
| <tr><th width="75">win32</th><th>default_os</th><th width="75">gtk</th><th width="75">carbon</th><th>default_ws</th></tr> |
| |
| <tr><td>Win32</td><td class="on">on</td><td>off</td><td>off</td><td>off</td><td class="on">on</td><td>off</td></tr> |
| <tr><td>Linux Gtk</td><td>off</td><td class="on">on</td><td class="on">on</td><td>off</td><td>off</td><td>off</td></tr> |
| <tr><td>Linux Other</td><td>off</td><td class="on">on</td><td>off</td><td>off</td><td class="on">on</td><td>off</td></tr> |
| |
| <tr><td>Mac</td><td>off</td><td class="on">on</td><td>off</td><td class="on">on</td><td>off</td><td>off</td></tr> |
| <tr><td>Unix Gtk</td><td>off</td><td class="on">on</td><td class="on">on</td><td>off</td><td>off</td><td>off</td></tr> |
| <tr><td>Unix Other</td><td>off</td><td class="on">on</td><td>off</td><td>off</td><td class="on">on</td><td>off</td></tr> |
| |
| <tr><td>Generic</td><td>off</td><td>off</td><td>off</td><td>off</td><td>off</td><td class="on">on</td></tr> |
| </table> |
| |
| <p>The directory structure is as follows:</p> |
| |
| <ul> |
| <li>PRODUCT_PLUGIN/book.css (needs to import a bookos.css)</li> |
| <li>For Windows, a single CSS file, PRODUCT_PLUGIN/os/win32/bookos.css, |
| as there is only one widget set. This sets win32 on, default_ws on; all_os_ws off, default_os off, |
| gtk off, carbon off.</li> |
| <li>For gtk, a single CSS file, PRODUCT_PLUGIN/ws/gtk/bookos.css, |
| as this widget set implies the operating system. |
| This sets default_os on, gtk on; |
| all_os_ws off, win32 off, carbon off, default_ws off.</li> |
| <li>For Mac, a single CSS file, PRODUCT_PLUGIN/ws/carbon/bookos.css, that sets |
| default_os on, carbon on; all_os_ws off, win32 off, gtk off, default_ws off.</li> |
| </ul> |
| |
| <p>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). |
| </p> |
| |
| <p>Sample CSS files will be part of this solution so that ISVs can |
| easily achieve this automatic selection. </p> |
| |
| <p>All of this means that the documentation |
| <b>must</b> 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.</p> |
| |
| <h4>Solution Should Allow Customization Without Modification To The Doc |
| Plug-ins</h4> |
| |
| <p>This solution allows the eclipse.org documentation to be customized |
| without modification.</p> |
| <h3>Issues</h3> |
| <p>This section describes some of the issues that were encountered and |
| possible solutions to these issues.</p> |
| <h4> PDF Generation</h4> |
| <p>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.</p> |
| <p>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.</p> |
| <p>Unfortunately, certain doctypes (XHTML) are not properly supported in |
| Internet Explorer and cause an unneeded scrollbar to appear, therefore this |
| remains an outstanding issue.</p> |
| |
| <h4>Searching</h4> |
| |
| <p>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. |
| |
| <h4>Remote Info Centres</h4> |
| |
| <p>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.</p> |
| |
| <h3>TODO</h3> |
| |
| <ul> |
| <li>Implement resource resolution for screenshots, HTML and CSS files</li> |
| <li>Create sample CSS (book.css and bookws.css) files for testing |
| automatic content display</li> |
| <li>Add CSS support to the HTML parser used by the search facilities |
| in the help system</li> |
| <li>Mark up the platform and widget set specific content in the |
| documentation with the new CSS classes</li> |
| <li>Change the HTML to get the CSS files from ../PRODUCT_PLUGIN/book.css </li> |
| <li>Consolidate all of the 5 CSS files if they are different</li> |
| <li>Move the consolidated CSS file to org.eclipse.platform/book.css</li> |
| <li><img src="../images/small_check.png">Create a style guide for documentation writers - PNG as standard image format <br /> |
| See: <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-doc-home/docs/EclipseStyle.htm"> |
| http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-doc-home/docs/EclipseStyle.htm</a></li> |
| <li>Implement info center os and ws command line parameters</li> |
| </ul> |
| |
| <h3>Authors</h3> |
| |
| <p>This proposal can be mostly blamed on <a |
| href="mbehm_att_redhat_dott_com">Michael Behm</a>, |
| <a href="konradk_att_ca_dott_ibm_dott_com">Konrad Kolosowski</a>, |
| <a href="bkonrath_att_redhat_dott_com">Ben Konrath</a> and |
| <a href="jpound_att_redhat_dott_com">Jeff Pound</a> |
| </p> |
| <h3>ChangeLog</h3> |
| <ul> |
| <li>17 Jan 2005: Add link to style guide. </li> |
| <li>29 Nov 2004: Initial version posted. </li> |
| </ul> |
| </body> |
| </html> |