platform-help-home/proposals/platform-specific-docs.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (download) (as text) (annotate)
Tue Nov 30 01:08:30 2004 UTC (4 years, 11 months ago) by kkolosow
Branch: MAIN 
*** empty log message ***

<!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">
</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=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>
The Eclipse SDK will ship with its CSS file in
org.eclipse.platform/book.css. The CSS in this file will display the
content
for all platforms and widget sets. This means that the documentation
<b>must</b> be written in such a way that it makes sense both when the
content
is all displayed and when only one class of content is displayed. This
point
will be stressed in the documentation style guide and an example will
be given.
<p>ISVs can also achieve
automatic selection of marked up content with multiple
style sheets read by the help system, according to system settings.
In this case the branding plug-in will have two or more CSS
files, one to turn on platform specific content, the other to turn on
widget
set specific content. The help system resource
resolution will apply to the CSS
files in the product (branding)
plug-in. The directory
structure in this case would be as follows:</p>
<ul>
  <li>PRODUCT_PLUGIN/book.css (default_os on, win32 off - needs to
import a bookws.css)</li>
  <li>PRODUCT_PLUGIN/os/win32/book.css (default_os off, win32 on,
default_ws on - does not need import a bookws.css)</li>
  <li>PRODUCT_PLUGIN/bookws.css (gtk off, carbon off, default_ws on)</li>
  <li>PRODUCT_PLUGIN/ws/gtk/bookws.css (gtk on, carbon off, default_ws
off)</li>
  <li>PRODUCT_PLUGIN/ws/carbon/bookws.css (gtk off, carbon on,
default_ws off)</li>
</ul>
<p>As noted above, book.css for the case that default_os is displayed
will need
to import a bookws.css file, while book.css for the case that win32
is
displayed will not have to import a bookws.css file. This is because
non-windows platforms can have multiple widget sets while windows only
has one
widget set. Sample CSS files will be part of this solution so that ISVs
can
easily achieve this automatic selection. </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>Create a style guide for documentation writers - PNG as standard image format </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>29 Nov 2004: Initial version posted. </li>
</ul>
</body>
</html>