platform-ua/proposals/platform-specific-docs.html - www.eclipse.org/eclipse - Git at Google

 <!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>
	<!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>