[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[platform-doc-dev] Re: [Fwd: Re: help-system-proposal.html]
|
Hi Konrad,
I've created a patch for the platform-specific documentation proposal.
This patch changes the "Control Over The Display of Platform Specific
Content" section so that book.css calls bookos.css and, if necessary,
bookws.css.
In many cases, the content of bookos.css and bookws.css can be combined
into one file, but by separating the CSS file for OS from the CSS file
for WS, ISVs could release versions for any combination of operating
system and widget set.
For the case of generic documentation, such as you would read by looking
at the online help on eclipse.org, readers will see only content marked
as class=all_os_ws.
Users looking at the help on their own system will see only the content
for their operating system/widget set combination.
I think that this patch meets all of our goals. If you agree, could you
commit it? Thanks!
Best regards,
Mike
Index: platform-specific-docs.html
===================================================================
RCS file: /home/eclipse/platform-help-home/proposals/platform-specific-docs.html,v
retrieving revision 1.1
diff -u -r1.1 platform-specific-docs.html
--- platform-specific-docs.html 30 Nov 2004 01:08:30 -0000 1.1
+++ platform-specific-docs.html 1 Dec 2004 21:25:29 -0000
@@ -6,6 +6,17 @@
<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%">
@@ -128,6 +139,8 @@
<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>
@@ -135,7 +148,7 @@
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>
+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>
@@ -159,48 +172,73 @@
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>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, 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>
+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 (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>
+ <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>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
+
+<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>
