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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (view) (download) (as text)

1 : kkolosow 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 :     <html>
3 :     <head>
4 :     <title>Platform Specific Documentation</title>
5 :     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 :     <meta http-equiv="Content-Style-Type" content="text/css">
7 :     <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet"
8 :     type="text/css">
9 : kkolosow 1.2 <style>
10 :     table,td,th { font-size: 10pt; font-family: arial, helvetica, geneva;}
11 :     </style>
12 :     <style media="screen">
13 :     th {background-color: #334070; color:#ffffff;}
14 :     .on {background-color: #ffff66;}
15 :     </style>
16 :     <style media="print">
17 :     .on {font-weight: bold;}
18 :     </style>
19 :    
20 : kkolosow 1.1 </head>
21 :     <body style="background-color: rgb(255, 255, 255);">
22 :     <table width="100%">
23 :     <tbody>
24 :     <tr>
25 :     <td
26 :     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
27 :     style="color: white;">Proposal</span></b></td>
28 :     </tr>
29 :     </tbody>
30 :     </table>
31 :     <center>
32 :     <h2>Proposal: Platform Specific Documentation</h2>
33 :     </center>
34 :     <h3>Abstract</h3>
35 :     The documentation in Eclipse currently lacks the ability for ISVs to
36 :     override
37 :     widget set specific screenshots and lacks the ability to turn off or
38 :     override
39 :     platform specific content. This proposal attempts to address these
40 :     issues by
41 :     adding support for resource overriding to the help system and by adding
42 :     CSS
43 :     class tags documentation with platform specific content.
44 :     <h3>Requirements</h3>
45 :     <p>A complete solution would satisfy the following requirements: </p>
46 :     <ol>
47 :     <li>Replaceable resources (screenshots, HTML files and CSS files)</li>
48 :     <li>Control over the display of platform specific content</li>
49 :     <li>The solution should allow the documentation to be customized
50 :     without the need to modify the base documentation plug-ins</li>
51 :     </ol>
52 :     <h3>Proposal</h3>
53 :     <h4>Replaceable Resources - Screenshots and HTML files</h4>
54 :     <p>To allow ISVs the ability to provide their own platform / widget set
55 :     specific resources in a custom fragment, the search path for resources
56 :     in a
57 :     documentation plug-in needs to be expanded. Currently, only the $nl$
58 :     directories are searched. The proposed search path adds widget set (ws)
59 :     and
60 :     operating system (os) to the existing natural language (nl) search
61 :     path. An ISV
62 :     can override files by contributing a fragment containing the files
63 :     which need
64 :     to be overridden in the correct directory. The search order will be ws,
65 :     then os
66 :     and finally nl. Compressed files in "doc.zip" will continue to be
67 :     searched
68 :     before files that are not compressed.</p>
69 :     <p>As an example, the search path for zh_CN locale with gtk
70 :     widget set on Linux would be:<br>
71 :     </p>
72 :     <ul>
73 :     <li>/ws/gtk/doc.zip!file</li>
74 :     <li>/os/linux/doc.zip!file</li>
75 :     <li>/nl/zh/CN/doc.zip!file</li>
76 :     <li>/nl/zh/doc.zip!file</li>
77 :     <li>/doc.zip!file</li>
78 :     <li>/ws/gtk/file</li>
79 :     <li>/os/linux/file</li>
80 :     <li>/nl/zh/CN/file</li>
81 :     <li>/nl/zh/file</li>
82 :     <li>/file</li>
83 :     </ul>
84 :     <p>This allows widget set and operating system specific documentation
85 :     to
86 :     be
87 :     contributed (in fragments) and
88 :     displayed without altering the
89 :     existing doc plug-ins. If no
90 :     fragment is
91 :     installed the end result would
92 :     be exactly the same as it is in the current
93 :     help system. To accomplish this, the help system will have to use the
94 :     system's nl, ws, and os settings to explicitly search the possible
95 :     paths for
96 :     the file. The use of $nl$, $ws$, and $os$, accepted by the
97 :     Platform.find() API,
98 :     must be avoided in the help system to ensure the root
99 :     directory is not searched to early (or multiple times).
100 :     </p>
101 :     <p>This solution allows ISVs to have a documentation fragment that
102 :     contains
103 :     either resources from a single language with multiple widget sets /
104 :     operating
105 :     systems <b>or</b> resources from the same widget set or operating
106 :     system with
107 :     different languages. The solution does not allow for all permutations
108 :     of
109 :     language, operating system and widget set to be placed in one fragment
110 :     -
111 :     separate fragments would still
112 :     be required. For example, an ISV could make a fragment
113 :     that has gtk-English and gtk-Chinese resources by placing the resources
114 :     in the
115 :     appropriate nl folders. In a separate fragment, this ISV could also
116 :     support
117 :     carbon-English and gtk-English by placing the files in the appropriate
118 :     ws directory. This lack of support for all
119 :     permutations is
120 :     not problematic as this requirement is relatively rare and if the need
121 :     should
122 :     arise, there is a way to handle it. It should be noted that the
123 :     Eclipse SDK
124 :     language pack does not contain language specific screenshots.</p>
125 :     <h4> Control Over The Display of Platform Specific Content</h4>
126 :     <p>The current documentation in Eclipse SDK has a mix of both platform
127 :     and
128 :     widget set specific content. This content will be marked with
129 :     appropriate CSS
130 :     classes to give ISVs control over which of the platform and / or widget
131 :     set
132 :     specific content is displayed. The information described below is
133 :     currently a
134 :     draft of the final solution. The documentation from eclipse.org will be
135 :     marked
136 :     up over the next little while to test if this solution will work. There
137 :     may be
138 :     some minor changes.</p>
139 :     <p>Platform specific content will be marked with either: <br>
140 :     </p>
141 :     <ul>
142 : kkolosow 1.2 <li>class=all_os_ws (for generic documentation that displays
143 :     the operation of all operating systems and widget sets)
144 : kkolosow 1.1 <li>class=default_os (not win32, ie. executable names that do not
145 :     have .exe) </li>
146 :     <li>class=win32 (OLE, DND and .exe executable names) </li>
147 :     </ul>
148 :     Widget Set specific content will be marked with these: <br>
149 :     <ul>
150 :     <li>class=default_ws (things that apply to all widget sets except the
151 : kkolosow 1.2 ones marked below - Windows is in this category)</li>
152 : kkolosow 1.1 <li>class=gtk (widget used on Unix-like platforms - including Linux)</li>
153 :     <li>class=carbon (widget set used on Mac OS X)</li>
154 :     </ul>
155 :     <p>The idea is that content common to most supported platforms and
156 :     widget sets falls under the default category. This designation has
157 :     nothing to do with the popularity of a given platform. Content specific
158 :     to just a few
159 :     platforms and widgets sets is tagged with the appropriate CSS classes
160 :     described
161 :     above. So far we have
162 :     identified that only win32, gtk, and carbon classes are needed to
163 :     differentiate content that is not common to all. The set of
164 :     classes can be expanded if the need arises.
165 :     </p>
166 :     <p>The CSS file will reside in the root of product plug-in
167 :     (PRODUCT_PLUGIN/book.css). References to this CSS file will be prefixed
168 :     with PRODUCT_PLUGIN in the HTML of all the documentation. This allows
169 :     ISVs to
170 :     override the default CSS file with a custom CSS file in the root of
171 :     their
172 :     branding plug-in. This CSS file would specify which platforms and
173 :     widget sets
174 :     should not be displayed.</p>
175 : kkolosow 1.2
176 :     <p>The Eclipse SDK will ship with its CSS file in
177 :     org.eclipse.platform/book.css, and this will call a bookos.css file
178 :     that sets default_os, win32, default_ws, gtk, and carbon <b>off</b>
179 :     (the remaining class, all_os_ws remains on).
180 :     </p>
181 :    
182 : kkolosow 1.1 <p>ISVs can also achieve
183 :     automatic selection of marked up content with multiple
184 : kkolosow 1.2 style sheets read by the help system; which CSS files are used is determined by the system settings.
185 :     In this case the branding plug-in will have a book.css file and one or two additional CSS
186 :     files, one to disable all but particular platform-specific content, and optionally a second to
187 :     disable all but particular widget-set specific content. The help system resource
188 :     resolution will apply the appropriate CSS
189 :     files to the product (branding)
190 :     plug-in. </p>
191 :    
192 :     <table border="1" cellpadding="3" cellspacing="0">
193 :     <tr><th rowspan="3">O/S</th><th colspan="6">CSS</th></tr>
194 :     <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>
195 :     <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>
196 :    
197 :     <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>
198 :     <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>
199 :     <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>
200 :    
201 :     <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>
202 :     <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>
203 :     <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>
204 :    
205 :     <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>
206 :     </table>
207 :    
208 :     <p>The directory structure is as follows:</p>
209 :    
210 : kkolosow 1.1 <ul>
211 : kkolosow 1.2 <li>PRODUCT_PLUGIN/book.css (needs to import a bookos.css)</li>
212 :     <li>For Windows, a single CSS file, PRODUCT_PLUGIN/os/win32/bookos.css,
213 :     as there is only one widget set. This sets win32 on, default_ws on; all_os_ws off, default_os off,
214 :     gtk off, carbon off.</li>
215 :     <li>For gtk, a single CSS file, PRODUCT_PLUGIN/ws/gtk/bookos.css,
216 :     as this widget set implies the operating system.
217 :     This sets default_os on, gtk on;
218 :     all_os_ws off, win32 off, carbon off, default_ws off.</li>
219 :     <li>For Mac, a single CSS file, PRODUCT_PLUGIN/ws/carbon/bookos.css, that sets
220 :     default_os on, carbon on; all_os_ws off, win32 off, gtk off, default_ws off.</li>
221 : kkolosow 1.1 </ul>
222 : kkolosow 1.2
223 :     <p>The book.css for each of the cases noted above imports a single bookos.css file,
224 :     because these cases have operating systems that imply the widget set, or a widget
225 :     set that implies the operating system.
226 :     An ISV that wants to release a version of Eclipse that runs under Windows, Unix gtk and
227 :     some other Unix widget set would need to call a book.css that imports a bookos.css
228 :     (which would disable either win32 or default_os) and a bookws (which would disable
229 :     all_os_ws, carbon, and either gtk or default_ws).
230 :     </p>
231 :    
232 :     <p>Sample CSS files will be part of this solution so that ISVs can
233 : kkolosow 1.1 easily achieve this automatic selection. </p>
234 : kkolosow 1.2
235 :     <p>All of this means that the documentation
236 :     <b>must</b> be written in such a way that it makes sense both when the
237 :     all_os_ws content is displayed and when only one class of content is displayed.
238 :     Therefore the source HTML files will have duplicated content, but the help browser
239 :     will show only the content that is appropriate for the user.
240 :     This point will be stressed in the documentation style guide and an example will
241 :     be given.</p>
242 : kkolosow 1.1
243 :     <h4>Solution Should Allow Customization Without Modification To The Doc
244 :     Plug-ins</h4>
245 :    
246 :     <p>This solution allows the eclipse.org documentation to be customized
247 :     without modification.</p>
248 :     <h3>Issues</h3>
249 :     <p>This section describes some of the issues that were encountered and
250 :     possible solutions to these issues.</p>
251 :     <h4> PDF Generation</h4>
252 :     <p>Currently, the SDK PDFs on eclipse.org are generated with htmldoc
253 :     which does
254 :     not support CSS. This does not pose a problem for Eclipse SDK PDFs
255 :     because they
256 :     will be displaying content for all platforms. This will, however, pose
257 :     a problem for
258 :     ISVs who wish to generate PDFs that display content for only one
259 :     platform and/or
260 :     widget set.</p>
261 :     <p>A solution to this is to use fully validating XHTML for all of the
262 :     documentation in the Eclipse SDK. This allows ISVs to convert to other
263 :     formats
264 :     by writing an XSLT style-sheet and/or by using one of the plethora of
265 :     XML
266 :     conversion tools that exist.</p>
267 :     <p>Unfortunately, certain doctypes (XHTML) are not properly supported in
268 :     Internet Explorer and cause an unneeded scrollbar to appear, therefore this
269 :     remains an outstanding issue.</p>
270 :    
271 :     <h4>Searching</h4>
272 :    
273 :     <p>The searching mechanism in the help system currently doesn't support CSS and
274 :     thus a user will get inaccurate search results if an ISV chooses to hide some
275 :     platform or widget set specific content. The easiest solution is to add
276 :     rudimentary CSS support to the help system. The plan is to add support for only
277 :     the CSS tags that are described in this document.
278 :    
279 :     <h4>Remote Info Centres</h4>
280 :    
281 :     <p>By default, the Eclipse SDK will show content for all platforms and widget
282 :     sets. If an administrator wishes to change this, they can add a custom branding
283 :     plug-in, or fragments to the existing branding plug-in, to override the default
284 :     CSS file. The administrator can also add fragments to the documentation with
285 :     platform and widget set specific screenshots and HTML files.&nbsp; As part of
286 :     this proposal, we will add support for command line parameters that can
287 :     override actual OS and WS of the system hosting the info center.</p>
288 :    
289 :     <h3>TODO</h3>
290 :    
291 :     <ul>
292 :     <li>Implement resource resolution for screenshots, HTML and CSS files</li>
293 :     <li>Create sample CSS (book.css and bookws.css) files for testing
294 :     automatic content display</li>
295 :     <li>Add CSS support to the HTML parser used by the search facilities
296 :     in the help system</li>
297 :     <li>Mark up the platform and widget set specific content in the
298 :     documentation with the new CSS classes</li>
299 :     <li>Change the HTML to get the CSS files from
300 :     ../PRODUCT_PLUGIN/book.css </li>
301 :     <li>Consolidate all of the 5 CSS files if they are different</li>
302 :     <li>Move the consolidated CSS file to org.eclipse.platform/book.css</li>
303 :     <li>Create a style guide for documentation writers - PNG as standard image format </li>
304 :     <li>Implement info center os and ws command line parameters</li>
305 :     </ul>
306 :    
307 :     <h3>Authors</h3>
308 :    
309 :     <p>This proposal can be mostly blamed on <a
310 :     href="mbehm_att_redhat_dott_com">Michael Behm</a>,
311 :     <a href="konradk_att_ca_dott_ibm_dott_com">Konrad Kolosowski</a>,
312 :     <a href="bkonrath_att_redhat_dott_com">Ben Konrath</a> and
313 :     <a href="jpound_att_redhat_dott_com">Jeff Pound</a>
314 :     </p>
315 :     <h3>ChangeLog</h3>
316 :     <ul>
317 :     <li>29 Nov 2004: Initial version posted. </li>
318 :     </ul>
319 :     </body>
320 :     </html>