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

Parent Directory Parent Directory | Revision Log Revision Log

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