<!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&nbsp;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.&nbsp; 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>