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

Parent Directory | Revision Log | Patch

-revision 1.1, Tue Nov 30 01:08:30 2004 UTC
+revision 1.2, Wed Dec  1 22:43:55 2004 UTC
 Line 6
    <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%">
-Line 128
+Line 139
  <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>
-Line 135
+Line 148
  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>
-Line 159
+Line 172
  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
+ <p>The Eclipse SDK will ship with its CSS file in
- content
+ org.eclipse.platform/book.css, and this will call a bookos.css file
- for all platforms and widget sets. This means that the documentation
+ that sets default_os, win32, default_ws, gtk, and carbon <b>off</b>
- <b>must</b> be written in such a way that it makes sense both when the
+ (the remaining class, all_os_ws remains on).
- content
+ </p>
- 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.
+ 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 two or more CSS
+ In this case the branding plug-in will have a book.css file and one or two additional CSS
- files, one to turn on platform specific content, the other to turn on
+ files, one to disable all but particular platform-specific content, and optionally a second to
- widget
+ disable all but particular widget-set specific content. The help system resource
- set specific content. The help system resource
+ resolution will apply the appropriate CSS
- resolution will apply to the CSS
+ files to the product (branding)
- files in the product (branding)
+ plug-in. </p>
- plug-in. The directory
- structure in this case would be as follows:</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 (default_os on, win32 off - needs to
+   <li>PRODUCT_PLUGIN/book.css (needs to import a bookos.css)</li>
- import a bookws.css)</li>
+   <li>For Windows, a single CSS file, PRODUCT_PLUGIN/os/win32/bookos.css,
-   <li>PRODUCT_PLUGIN/os/win32/book.css (default_os off, win32 on,
+   as there is only one widget set. This sets win32 on, default_ws on; all_os_ws off, default_os off,
- default_ws on - does not need import a bookws.css)</li>
+   gtk off, carbon off.</li>
-   <li>PRODUCT_PLUGIN/bookws.css (gtk off, carbon off, default_ws on)</li>
+   <li>For gtk, a single CSS file, PRODUCT_PLUGIN/ws/gtk/bookos.css,
-   <li>PRODUCT_PLUGIN/ws/gtk/bookws.css (gtk on, carbon off, default_ws
+   as this widget set implies the operating system.
- off)</li>
+   This sets default_os on, gtk on;
-   <li>PRODUCT_PLUGIN/ws/carbon/bookws.css (gtk off, carbon on,
+   all_os_ws off, win32 off, carbon off, default_ws off.</li>
- 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
+ <p>The book.css for each of the cases noted above imports a single bookos.css file,
- to import a bookws.css file, while book.css for the case that win32
+ because these cases have operating systems that imply the widget set, or a widget
- is
+ set that implies the operating system.
- displayed will not have to import a bookws.css file. This is because
+ An ISV that wants to release a version of Eclipse that runs under Windows, Unix gtk and
- non-windows platforms can have multiple widget sets while windows only
+ some other Unix widget set would need to call a book.css that imports a bookos.css
- has one
+ (which would disable either win32 or default_os) and a bookws (which would disable
- widget set. Sample CSS files will be part of this solution so that ISVs
+ all_os_ws, carbon, and either gtk or default_ws).
- can
+ </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>

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
-Removed from v.1.1
+Added in v.1.2

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3