[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[platform-doc-dev] Patch for the style guide
|
Hi Jim,
Here is a patch for the Eclipse Style Guide that updates the CSS naming
conventions.
Best regards,
Mike
-------------------------------
Mike Behm
Red Hat Canada Ltd.
Toronto, ON
416.482.2661 X312
-------------------------------
Index: docs/EclipseStyle.htm
===================================================================
RCS file: /home/eclipse/platform-doc-home/docs/EclipseStyle.htm,v
retrieving revision 1.3
diff -u -r1.3 EclipseStyle.htm
--- docs/EclipseStyle.htm 16 Dec 2004 22:33:24 -0000 1.3
+++ docs/EclipseStyle.htm 24 Jan 2005 19:27:27 -0000
@@ -1,630 +1,640 @@
-<html>
-<head>
-<meta http-equiv="Content-Language" content="en-us">
-<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
-<title>Eclipse Style Guide</title>
-<link rel="stylesheet" type="text/css" href="help.css">
-<style>
-
-body { font-size: 10pt; background: white; font-family: arial, helvetica, geneva;}
-table,td,th { font-size: 10pt; font-family: arial, helvetica, geneva;}
-.code { margin-left: 3%; margin-top: 3%; margin-right 3%; font-family: Courier; }
-.old { text-decoration: line-through; color: red;}
-.guilabel { font-weight: bold;}
-.guibutton { color: #000000; font-family: helvetica, arial, sans-serif; font-weight: bold;
- background-color: #DCDCDC; padding: 1px 5px; font-size: 10pt; border: outset 2px;
- text-decoration: none; line-height:175%; }
-.whkeycap {
- color: #333333; font-family: helvetica, arial, sans-serif; font-size: 10pt;
- background-color: #e4e0d0; padding: 0px 6px 2px 1px; border: outset 2px;
- text-decoration: none; line-height:175%; }
-tr { vertical-align: top; }
-span.underlinered {border-bottom: thin solid red;}
-ul {margin-left:18px;}
-ol {margin-left:25px;}
-dt {font-weight: bold;}
-dd, li {padding-top:3px; padding-bottom:3px;}
-.fakelink {color:blue; text-decoration: underline;}
-</style>
-
-<style media="screen">
-pre { font-family: Courier; }
-th {background-color: #334070; color:#ffffff;}
-.on {background-color: #ffff66;}
-</style>
-
-<style media="print">
-pre { font-family: Courier; font-size:8pt;}
-.break {page-break-before: always;}
-.on {font-weight: bold;}
-</style>
-
-</head>
-<body>
-
-<h1>Eclipse Style Guide</h1>
-
-<p>Version 0.81 - Last modified Dec. 10, 2004</p>
-
-<p>This document gives the style conventions to be used in Eclipse help.
-The Eclipse help has the following topic types: Tutorial (Getting Started),
-Concept, Task, and Reference.
-These topic types are based on the
-<i><a href="http://www-106.ibm.com/developerworks/xml/library/x-dita1/";>Darwin
-Information Typing Architecture (DITA)</a></i> standards.
-</p>
-
-<table border="1" cellpadding="3" cellspacing="0">
-
-<!-- *************************** topic titles ************************ -->
-
-<tr><th>Topic Titles</th><th>Example</th></tr>
-
-<tr>
-<td>A topic's <i>title</i> (heading) is marked with a heading value that matches
-the topic's position in the table of contents.
-The topic shown here is at the top level, so it is tagged as an <b><<tt>h1</tt>></b>.
-</td>
-<td><code><h1>A Tour of the Workbench</h1></code></td>
-</tr>
-
-<tr>
-<td>The text in a topic's <<tt>title</tt>> must match the text in the heading.
-</td>
-<td>From <tt>concepts-2.htm</tt>:
-
-<pre>
-<title><span style="text-decoration:line-through;">The </span>Workbench</title>
-...
-<h1>Workbench</h1>
-</pre>
-</td>
-</tr>
-
-<tr>
-<td>A topic's <<tt>title</tt>> must be <i>unique</i> to enable users to make a correct
-choice after a search.
-<p>Use sentence capitalization for all titles.</p>
-</td>
-<td>Results of searching for <b>workbench</b>:
-
-<pre style="font-family: sans-serif;">
-<b>88% The workbench</b> (concepts-2.htm)
-<b>74% Workbench</b> (ref-10.htm)
-<b>70% The workbench</b> (qs-02a.htm)
-</pre>
-
-<p>Better titles:</p>
-
-<pre style="font-family: sans-serif;">
-<b>88% What is the workbench?</b> (concepts-2.htm)
-<b>74% Workbench reference</b> (ref-10.htm)
-<b>70% Launching the workbench</b> (qs-02a.htm)
-</pre>
-
-</td>
-</tr>
-<tr>
-<td>Begin "task" and "getting started" titles with a gerund.</td>
-<td><b>Creating a project</b></td>
-</tr>
-
-<!-- *************************** lists ************************ -->
-
-<tr><th>Lists</th><th>Example</th></tr>
-
-<tr>
-<td>Use a sentence fragment followed by a colon before numbered steps.</td>
-<td>To hide files by type:</td>
-</tr>
-
-<tr>
-<td>Each numbered list item should include only one step.</td>
-<td> </td>
-</tr>
-
-<tr>
-<td>If you have an ordered list within an ordered list, use:
-<br>
-<tt><ol type="a"></ol></tt>
-</td>
-<td>To do X:
-<ol>
-<li>Step 1 text.</li>
-<li>Step 2 introductory text:
- <ol type="a">
- <li>Sub-step 1.</li>
- <li>Sub-step 2.</li>
- </ol>
-</li>
-</ol></td>
-</tr>
-
-<tr>
-<td>If you need to start an ordered list at a number other than 1,
-use
-<br>
-<tt><li value="3">text</li></tt>
-</td>
-<td><ol>
-<li value="3">text</li>
-</ol>
-</td>
-</tr>
-
-<tr>
-<td>Each task topic should contain a reasonable number of steps.
-"Reasonable" is a judgment call, and your freedom
-may be restricted by the complexity of the software.
-However, if you find that you are over 10 steps,
-see if you can break the steps into two sub-topics.
-</td>
-<td> </td>
-</tr>
-
-<!-- *************************** inline markup ************************ -->
-
-<tr class="break"><th>Inline Markup</th><th>Example</th></tr>
-
-<tr>
-<td>Elements names that appear in the GUI should be identified as such.
-
-<p>The standard convention for GUI elements is to display the name in a bold font.
-There are different ways this can be done:</p>
-
-<ul compact>
-<li>Use <b> tags</li>
-<li>Use the <strong> tags and expect that they will render as bold</li>
-<li>Use <span> tags with different class types.
-For example:
-<ul>
-<li><span class="guilabel">Preferences</span></li>
-<li><span class="guibutton">OK</span></li>
-</ul>
-</li>
-</ul>
-
-<p>The benefit of using class types is that the CSS file can then declare:</p>
-<pre>
-.guilabel {font-weight: bold;}
-</pre>
-
-<p>Or for a more elaborate display:</p>
-
-<pre>
-.guibutton { color: #000000; font-weight: bold;
- font-family: helvetica, sans-serif;
- background-color: #DCDCDC; padding: 1px 5px;
- font-size: 10pt; border: outset 2px;
- text-decoration: none; line-height:175%; }
-</pre>
-
-</td>
-<td><span class="guilabel">Preferences</span>
-<br>
-<span class="guibutton">OK</span>
-</td>
-</tr>
-
-<!-- *************************** Topic content ************************ -->
-
-<tr><th>Topic Content</th><th>Example</th></tr>
-
-<tr>
-<td>Provide a short description of what the user will accomplish.</td>
-<td>Files that you do not need to see can be hidden by file type in
-the <b>C/C++ Projects</b> view.
-<p style="font-size: 11px;">(Note: That wording could be better—see below.)</p>
-</td>
-</tr>
-
-<tr>
-<td>Use the active voice.</td>
-<td>You can hide file types that you do not need to see in
-the <b>C/C++ Projects</b> view.
-<p style="font-size: 11px;">(Note: That wording could <i>still</i> be better—see below.)</p>
-</td>
-</tr>
-
-<tr>
-<td>Wherever possible, make statements positive.</td>
-<td>In the <b>C/C++ Projects</b> view,
-you can display only the file types that you need to see.</td>
-</tr>
-
-<tr>
-<td>Include no more than one task for each topic.</td>
-<td> </td>
-</tr>
-
-<tr>
-<td>Document how to access a feature through the menu bar, as opposed to
-using toolbar buttons or the context menu.
-
-<p>Avoid providing multiple ways to do something unless the menu-driven method is
-not always available.
-Project properties are an example of this:
-you can set project properties in the New Project wizard, but after the project is
-created you can set properties only by right-clicking on an individual
-project or in preferences (for all projects).</p>
-</td>
-<td>Click <b>File > New > Project</b>.
-
-<p>Note that the term "menu" is not used and that the menu path is in bold.</p>
-</td>
-</tr>
-
-<tr class="break">
-<td>When you must provide multiple ways to do something use the
-format in the example.</td>
-<td>
-<ol>
-<li>Do one of the following:
-<ul>
-<li>To set properties for future Standard Make projects, click
-<b>Window > Preferences </b>. Expand<b> C/C++,</b> click <b>New Make Projects</b>.</li>
-<li>In the <b>C/C++ Projects</b> view, right-click a project, and select
-<b>Properties</b>.
-Select <b>C/C++ Make Project</b> from the list.</li>
-</ul>
-</li>
-</ol>
-</td>
-</tr>
-<tr>
-<td>To instruct the user to make a choice, use the format in the
- example.</td>
-<td>
-<ol>
-<li>Do one of the following:
-<ul>
-<li>To stop the build when an error is encountered, select <b>Stop on
-error</b>.</li>
-<li>To continue the build even if an error is encountered, select <b>
-Keep going on error</b>.</li>
-</ul>
-</li>
-</ol>
-</td>
-</tr>
-
-<tr>
-<td>When describing how to use the context menu (shortcut menu),
-instruct the user to "right-click <something>
-and select <something>."
-<p>Do not say, "From the context-menu, choose <something>
-as the term context-menu is not obvious to new users.</p>
-</td>
-<td>In the <b>C/C++ Projects</b> view, right-click a project and
-select <b>Properties</b>.</td>
-</tr>
-
-<tr>
-<td>Bold the name of the item being acted on (that is, the text), not the name
-of interface control.</td>
-<td>Type the name <code><b>JanesProject</b></code> in the <b>Project name</b> field.</td>
-</tr>
-
-<tr>
-<td>For the results of a step, do not add the sentence,
-"The New Project wizard opens."
-Instead, give the name of the dialog box or wizard that
-opens as an introductory phrase at the beginning of the next step.</td>
-<td>
-<ol>
-<li>Click <b>File > New > Project</b>.</li>
-<li>In the <b>New Project</b> wizard, click <b>C</b> or <b>C++</b>.</li>
-</ol>
-</td>
-</tr>
-
-<tr>
-<td>Begin a step, where applicable, by telling the user "To <do
-this>, <do that>."
-
-<p>In other words, give the consequences of the action before you give the instructions
-to perform.</p>
-</td>
-<td>To change tab settings, type a value in the <b>Value</b> box.</td>
-</tr>
-
-<tr>
-<td>Do not use the word "button", simply tell the reader to
-"click <<b>name of button</b>>."</td>
-<td>Click <b>Next</b>.</td>
-</tr>
-
-<tr>
-<td>Use the verbs "select" or "clear" for check boxes;
-bold only the name of the check box.</td>
-<td>Select or clear the <b>Blank</b> check box.</td>
-</tr>
-
-<tr>
-<td>Do not use the word "radio button".
-Use "click <<b>name of radio button</b>>."</td>
-<td>To change the background color, click <b>Custom</b>.</td>
-</tr>
-
-<tr>
-<td>Do not instruct the user to "click on" something.
-Use "click", "right-click" or "double-click."</td>
-<td>In the <b>C/C++ Projects</b> view, double-click your project.</td>
-</tr>
-
-<tr>
-<td>Do not instruct the user to "click on".
-Use "click the <<b>name of tab</b>> tab."</td>
-<td>Click the <b>General</b> tab.</td>
-</tr>
-
-<tr>
-<td>Do not use the word "tree".
-Use "Expand <<b>something</b>>,
-click <<b>something else</b>>.</td>
-<td>
-<ol>
-<li>Click <b>Window > Preferences</b>.</li>
-<li>Expand<b> C/C++</b>, click <b>C/C++ Editor</b>.</li>
-</ol>
-</td>
-</tr>
-
-<tr>
-<td>Use "type" instead of "enter."
-
-<p>("Enter" means "type <text> and press [Enter].)</p>
-</td>
-<td>In the <b>Name</b> box, type a name.</td>
-</tr>
-
-<tr class="break">
-<td>Consider having inline links to concepts that are Eclipse-specific.</td>
-<td>
-<pre>
-<p>This tutorial provides a step-by-step walk-through
-of the features in the Eclipse
-<a href="../concepts/concepts-2.htm">Workbench</a>.
-You will learn how to use these features by creating
-a <a href="../concepts/concepts-12.htm">project</a>,
-then creating, running, and debugging a simple
-program.</p>
-</pre>
-
-<p>This tutorial provides a step-by-step
-walk-through of the features in the Eclipse
-<span class="fakelink">Workbench</span>.
-You will learn how to use these features by creating
-a <span class="fakelink">project</span>,
-then creating, running, and debugging a simple
-program.
-</p>
-
-</td>
-</tr>
-
-<!-- *************************** tables ************************ -->
-
-<tr><th>Tables</th><th>Example</th></tr>
-
-<tr>
-<td>Declare tables consistently.
-</td>
-<td>
-<tt><table border="1" cellpadding="3" cellspacing="0"></tt>
-</td>
-</tr>
-
-<tr>
-<td>Set the vertical alignment for rows to "top" in the CSS file.
-</td>
-<td>
-<tt>tr { vertical-align: top; }</tt>
-</td>
-</tr>
-
-<!-- *************************** operating system specific content ************************ -->
-
-<tr><th>Operating system specific content</th><th>Example</th></tr>
-
-<tr>
-<td>Remove all generator tags and author tags.</td>
-<td><pre><meta name="GENERATOR">
-<meta name="author" content="JFK"></pre></td>
-</tr>
-
-<tr>
-<td>Use class tags to mark text that is specific to a particular
-operating system (and in Unix, to a particular widget set).
-At the time of this writing, these are the proposed classes:
-
-<dl>
-<dt>class=win32</dt>
-<dd>For Windows-specific content such as executable names
-(<code>eclipse.exe</code>) and path names (<code>C:\eclipse\workbench</code>).
-</dd>
-
-<dt>default_os</dt>
-<dd>For all operating systems other than Windows (that is, Unix and Mac OS X).</dd>
-
-<dt>class=gtk</dt>
-<dd>For Unix/Linux systems that run the gtk widget set.
-You would normally use this class to mark the key to press
-to access the help system (in this case, [Ctrl]+[F1]).</dd>
-
-<dt>class=carbon</dt>
-<dd>For the Mac OS X widget set, under which you press [Help]
-to access the Help system
-and press [Ctrl]+click
-to access the context menu.</dd>
-
-<dt>class=notcarbon</dt>
-<dd>For widget sets other than Mac OS X, under which you right-click
-to access the context menu.</dd>
-
-<dt>class=default_ws</dt>
-<dd>For all systems other than gtk and carbon (press [F1] for help).</dd>
-
-<dt>class=all_os_ws</dt>
-<dd>This category combines the information from the above classes into
-a single grouping.
-This enables vendors to disable the display of the "all" category and
-all unwanted specific categories.
-</dd>
-</dl>
-
-</td>
-
-<td>
-<p>In the HTML file:</p>
-<pre>
-<div class="all_os_ws">
-<p>To access the help system:</p>
-<ul>
-<li>On Windows, press [F1]</li>
-<li>On Mac, press [Help]</li>
-<li>On Linux(gtk), press [Ctrl]+[F1]</li>
-<li>On all other systems), press [F1].</li>
-</ul>
-</div>
-
-<p class="default_ws">To access the
-help system, press [F1].</p>
-
-<p class="gtk">To access the help
-system, press [Ctrl]+[F1].</p>
-
-<p class="carbon">To access the
-help system, press [Help].</p>
-</pre>
-
-<p>And in the CSS file that prints generic documentation
-(and in which by default all_os_ws is enabled):</p>
-<pre>
-.gtk {display: none;}
-.carbon {display: none;}
-.default_ws {display: none;}
-</pre>
-
-<p>And in the CSS file for a gtk system:</p>
-<pre>
-.all_os_ws {display: none;}
-.carbon {display: none;}
-.default_ws {display: none;}
-</pre>
-</td>
-</tr>
-
-<!-- *************************** CSS ************************ -->
-
-<tr class="break"><th colspan="2">CSS Class Summary</th></tr>
-
-<tr>
-<td colspan="2">There are the following CSS files:
-<ul>
-<li>book.css defines how to render text and calls bookws.css</li>
-<li>bookos.css defines which content to hide by operating system</li>
-<li>bookws.css defines which content to hide by widget set.</li>
-</ul>
-
-<p>When the operating system implies the widget set (or vice versa), the
-content of bookws.css can be added to bookos.css. </p>
-
-<p>To call the book.css file, change the current markup from
-<br>
-<code><link rel="stylesheet" href="../book.css" type="text/css"></code>
-<br>
-to
-<br>
-<code><link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css"></code>
-<br>
-(The help system will make the appropriate changes to the path at run time.)
-</p>
-
-<table border="1" cellpadding="3" cellspacing="0">
-<tr><th rowspan="3">O/S</th><th colspan="8">CSS</th></tr>
-<tr><th colspan="2">Path names</th><th colspan="3">Help Key</th><th colspan="2">Mouse</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>
-<th>notcarbon</th><th width="75">carbon</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 class="on">on</td><td>off</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 class="on">on</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 class="on">on</td><td>off</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><td class="on">on</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 class="on">on</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 class="on">on</td><td>off</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>off</td><td>off</td><td class="on">on</td></tr>
-</table>
-
-
-</td>
-
-</tr>
-
-<!-- *************************** graphics ************************ -->
-
-<tr><th>Graphics</th><th>Example</th></tr>
-
-<tr>
-<td>There are two types of graphics in the online help at present:
-icons (which can be taken from the icon sets for the user interface)
-and screen captures.
-<p>Icons are system-independent, so there are no reasons to give
-them class names or to be concerned about their file type.
-</p>
-<p>On the other hand, screen captures are system-dependent,
-so it is important that different systems can display the
-appropriate screen captures.
-To do this, vendors need to be able to create a zip file of screen
-captures that the help system can display properly and automatically:
-</p>
-<ul>
-<li>Screen captures must be ".png" files.</li>
-<li>Image declarations must <b><i>not</i></b> specify image sizes.</li>
-<li>Image declarations should have "alt" attributes (this is
-an accessibility feature).</li>
-<li>Image declarations may have a <title> attribute.</li>
-</ul>
-<p>The default platform for screen captures is Windows XP.</p>
-</td>
-<td><code><img border="0" src="../images/Image201_fillet" alt="Define a New File Type dialog"></code></td>
-</tr>
-
-<!-- *************************** indexing ************************ -->
-
-<tr class="break"><th>Indexing</th><th>Example</th></tr>
-
-<tr>
-<td>Eclipse indexes its help files by looking at the text
-in the page and weighting titles over paragraphs.
-However, there can be times when you want the index
-to show text that does not display on the page.
-For example, if Eclipse uses its own terminology for a function,
-you might want users to be able to look up synonyms.
-
-<p>To have the Eclipse index generate a hit for "autosave"
-(a function that Eclipse has under another name) add a
-<tt>meta "keywords"</tt> tag before the </head> tag.</p>
-</td>
-<td><pre>
-<meta name="keywords" content="autosave">
-</pre>
-</td>
-</tr>
-
-
-<!-- *************************** html or xhtml declaration ************************ -->
-
-<tr><th colspan="2">HTML Doctype</th></tr>
-<tr>
-<td colspan="2">XHTML doctypes are not properly supported in Internet Explorer
-(they cause an unneeded scrollbar to appear), so the default
-DOCTYPE is:<br>
-<code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"></code></td>
-</tr>
-
-</table>
-
-
-
-</body>
-</html>
+<html>
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>Eclipse Style Guide</title>
+<link rel="stylesheet" type="text/css" href="help.css">
+<style>
+
+body { font-size: 10pt; background: white; font-family: arial, helvetica, geneva;}
+table,td,th { font-size: 10pt; font-family: arial, helvetica, geneva;}
+.code { margin-left: 3%; margin-top: 3%; margin-right 3%; font-family: Courier; }
+.old { text-decoration: line-through; color: red;}
+.guilabel { font-weight: bold;}
+.guibutton { color: #000000; font-family: helvetica, arial, sans-serif; font-weight: bold;
+ background-color: #DCDCDC; padding: 1px 5px; font-size: 10pt; border: outset 2px;
+ text-decoration: none; line-height:175%; }
+.whkeycap {
+ color: #333333; font-family: helvetica, arial, sans-serif; font-size: 10pt;
+ background-color: #e4e0d0; padding: 0px 6px 2px 1px; border: outset 2px;
+ text-decoration: none; line-height:175%; }
+tr { vertical-align: top; }
+span.underlinered {border-bottom: thin solid red;}
+ul {margin-left:18px;}
+ol {margin-left:25px;}
+dt {font-weight: bold;}
+dd, li {padding-top:3px; padding-bottom:3px;}
+.fakelink {color:blue; text-decoration: underline;}
+</style>
+
+<style media="screen">
+pre { font-family: Courier; }
+th {background-color: #334070; color:#ffffff;}
+.on {background-color: #ffff66;}
+</style>
+
+<style media="print">
+pre { font-family: Courier; font-size:8pt;}
+.break {page-break-before: always;}
+.on {font-weight: bold;}
+</style>
+
+</head>
+<body>
+
+<h1>Eclipse Style Guide</h1>
+
+<p>This document gives the style conventions to be used in Eclipse help.
+The Eclipse help has the following topic types: Tutorial (Getting Started),
+Concept, Task, and Reference.
+These topic types are based on the
+<i><a href="http://www-106.ibm.com/developerworks/xml/library/x-dita1/";>Darwin
+Information Typing Architecture (DITA)</a></i> standards.
+</p>
+
+<table border="1" cellpadding="3" cellspacing="0">
+
+<!-- *************************** topic titles ************************ -->
+
+<tr><th>Topic Titles</th><th>Example</th></tr>
+
+<tr>
+<td>A topic's <i>title</i> (heading) is marked with a heading value that matches
+the topic's position in the table of contents.
+The topic shown here is at the top level, so it is tagged as an <b><<tt>h1</tt>></b>.
+</td>
+<td><code><h1>A Tour of the Workbench</h1></code></td>
+</tr>
+
+<tr>
+<td>The text in a topic's <<tt>title</tt>> must match the text in the heading.
+</td>
+<td>From <tt>concepts-2.htm</tt>:
+
+<pre>
+<title><span style="text-decoration:line-through;">The </span>Workbench</title>
+...
+<h1>Workbench</h1>
+</pre>
+</td>
+</tr>
+
+<tr>
+<td>A topic's <<tt>title</tt>> must be <i>unique</i> to enable users to make a correct
+choice after a search.
+<p>Use sentence capitalization for all titles.</p>
+</td>
+<td>Results of searching for <b>workbench</b>:
+
+<pre style="font-family: sans-serif;">
+<b>88% The workbench</b> (concepts-2.htm)
+<b>74% Workbench</b> (ref-10.htm)
+<b>70% The workbench</b> (qs-02a.htm)
+</pre>
+
+<p>Better titles:</p>
+
+<pre style="font-family: sans-serif;">
+<b>88% What is the workbench?</b> (concepts-2.htm)
+<b>74% Workbench reference</b> (ref-10.htm)
+<b>70% Launching the workbench</b> (qs-02a.htm)
+</pre>
+
+</td>
+</tr>
+<tr>
+<td>Begin "task" and "getting started" titles with a gerund.</td>
+<td><b>Creating a project</b></td>
+</tr>
+
+<!-- *************************** lists ************************ -->
+
+<tr><th>Lists</th><th>Example</th></tr>
+
+<tr>
+<td>Use a sentence fragment followed by a colon before numbered steps.</td>
+<td>To hide files by type:</td>
+</tr>
+
+<tr>
+<td>Each numbered list item should include only one step.</td>
+<td> </td>
+</tr>
+
+<tr>
+<td>If you have an ordered list within an ordered list, use:
+<br>
+<tt><ol type="a"></ol></tt>
+</td>
+<td>To do X:
+<ol>
+<li>Step 1 text.</li>
+<li>Step 2 introductory text:
+ <ol type="a">
+ <li>Sub-step 1.</li>
+ <li>Sub-step 2.</li>
+ </ol>
+</li>
+</ol></td>
+</tr>
+
+<tr>
+<td>If you need to start an ordered list at a number other than 1,
+use
+<br>
+<tt><li value="3">text</li></tt>
+</td>
+<td><ol>
+<li value="3">text</li>
+</ol>
+</td>
+</tr>
+
+<tr>
+<td>Each task topic should contain a reasonable number of steps.
+"Reasonable" is a judgment call, and your freedom
+may be restricted by the complexity of the software.
+However, if you find that you are over 10 steps,
+see if you can break the steps into two sub-topics.
+</td>
+<td> </td>
+</tr>
+
+<!-- *************************** inline markup ************************ -->
+
+<tr class="break"><th>Inline Markup</th><th>Example</th></tr>
+
+<tr>
+<td>Elements names that appear in the GUI should be identified as such.
+
+<p>The standard convention for GUI elements is to display the name in a bold font.
+There are different ways this can be done:</p>
+
+<ul compact>
+<li>Use <b> tags</li>
+<li>Use the <strong> tags and expect that they will render as bold</li>
+<li>Use <span> tags with different class types.
+For example:
+<ul>
+<li><span class="guilabel">Preferences</span></li>
+<li><span class="guibutton">OK</span></li>
+</ul>
+</li>
+</ul>
+
+<p>The benefit of using class types is that the CSS file can then declare:</p>
+<pre>
+.guilabel {font-weight: bold;}
+</pre>
+
+<p>Or for a more elaborate display:</p>
+
+<pre>
+.guibutton { color: #000000; font-weight: bold;
+ font-family: helvetica, sans-serif;
+ background-color: #DCDCDC; padding: 1px 5px;
+ font-size: 10pt; border: outset 2px;
+ text-decoration: none; line-height:175%; }
+</pre>
+
+</td>
+<td><span class="guilabel">Preferences</span>
+<br>
+<span class="guibutton">OK</span>
+</td>
+</tr>
+
+<!-- *************************** Topic content ************************ -->
+
+<tr><th>Topic Content</th><th>Example</th></tr>
+
+<tr>
+<td>Provide a short description of what the user will accomplish.</td>
+<td>Files that you do not need to see can be hidden by file type in
+the <b>C/C++ Projects</b> view.
+<p style="font-size: 11px;">(Note: That wording could be better—see below.)</p>
+</td>
+</tr>
+
+<tr>
+<td>Use the active voice.</td>
+<td>You can hide file types that you do not need to see in
+the <b>C/C++ Projects</b> view.
+<p style="font-size: 11px;">(Note: That wording could <i>still</i> be better—see below.)</p>
+</td>
+</tr>
+
+<tr>
+<td>Wherever possible, make statements positive.</td>
+<td>In the <b>C/C++ Projects</b> view,
+you can display only the file types that you need to see.</td>
+</tr>
+
+<tr>
+<td>Include no more than one task for each topic.</td>
+<td> </td>
+</tr>
+
+<tr>
+<td>Document how to access a feature through the menu bar, as opposed to
+using toolbar buttons or the context menu.
+
+<p>Avoid providing multiple ways to do something unless the menu-driven method is
+not always available.
+Project properties are an example of this:
+you can set project properties in the New Project wizard, but after the project is
+created you can set properties only by right-clicking on an individual
+project or in preferences (for all projects).</p>
+</td>
+<td>Click <b>File > New > Project</b>.
+
+<p>Note that the term "menu" is not used and that the menu path is in bold.</p>
+</td>
+</tr>
+
+<tr class="break">
+<td>When you must provide multiple ways to do something use the
+format in the example.</td>
+<td>
+<ol>
+<li>Do one of the following:
+<ul>
+<li>To set properties for future Standard Make projects, click
+<b>Window > Preferences </b>. Expand<b> C/C++,</b> click <b>New Make Projects</b>.</li>
+<li>In the <b>C/C++ Projects</b> view, right-click a project, and select
+<b>Properties</b>.
+Select <b>C/C++ Make Project</b> from the list.</li>
+</ul>
+</li>
+</ol>
+</td>
+</tr>
+<tr>
+<td>To instruct the user to make a choice, use the format in the
+ example.</td>
+<td>
+<ol>
+<li>Do one of the following:
+<ul>
+<li>To stop the build when an error is encountered, select <b>Stop on
+error</b>.</li>
+<li>To continue the build even if an error is encountered, select <b>
+Keep going on error</b>.</li>
+</ul>
+</li>
+</ol>
+</td>
+</tr>
+
+<tr>
+<td>When describing how to use the context menu (shortcut menu),
+instruct the user to "right-click <something>
+and select <something>."
+<p>Do not say, "From the context-menu, choose <something>
+as the term context-menu is not obvious to new users.</p>
+</td>
+<td>In the <b>C/C++ Projects</b> view, right-click a project and
+select <b>Properties</b>.</td>
+</tr>
+
+<tr>
+<td>Bold the name of the item being acted on (that is, the text), not the name
+of interface control.</td>
+<td>Type the name <code><b>JanesProject</b></code> in the <b>Project name</b> field.</td>
+</tr>
+
+<tr>
+<td>For the results of a step, do not add the sentence,
+"The New Project wizard opens."
+Instead, give the name of the dialog box or wizard that
+opens as an introductory phrase at the beginning of the next step.</td>
+<td>
+<ol>
+<li>Click <b>File > New > Project</b>.</li>
+<li>In the <b>New Project</b> wizard, click <b>C</b> or <b>C++</b>.</li>
+</ol>
+</td>
+</tr>
+
+<tr>
+<td>Begin a step, where applicable, by telling the user "To <do
+this>, <do that>."
+
+<p>In other words, give the consequences of the action before you give the instructions
+to perform.</p>
+</td>
+<td>To change tab settings, type a value in the <b>Value</b> box.</td>
+</tr>
+
+<tr>
+<td>Do not use the word "button", simply tell the reader to
+"click <<b>name of button</b>>."</td>
+<td>Click <b>Next</b>.</td>
+</tr>
+
+<tr>
+<td>Use the verbs "select" or "clear" for check boxes;
+bold only the name of the check box.</td>
+<td>Select or clear the <b>Blank</b> check box.</td>
+</tr>
+
+<tr>
+<td>Do not use the word "radio button".
+Use "click <<b>name of radio button</b>>."</td>
+<td>To change the background color, click <b>Custom</b>.</td>
+</tr>
+
+<tr>
+<td>Do not instruct the user to "click on" something.
+Use "click", "right-click" or "double-click."</td>
+<td>In the <b>C/C++ Projects</b> view, double-click your project.</td>
+</tr>
+
+<tr>
+<td>Do not instruct the user to "click on".
+Use "click the <<b>name of tab</b>> tab."</td>
+<td>Click the <b>General</b> tab.</td>
+</tr>
+
+<tr>
+<td>Do not use the word "tree".
+Use "Expand <<b>something</b>>,
+click <<b>something else</b>>.</td>
+<td>
+<ol>
+<li>Click <b>Window > Preferences</b>.</li>
+<li>Expand<b> C/C++</b>, click <b>C/C++ Editor</b>.</li>
+</ol>
+</td>
+</tr>
+
+<tr>
+<td>Use "type" instead of "enter."
+
+<p>("Enter" means "type <text> and press [Enter].)</p>
+</td>
+<td>In the <b>Name</b> box, type a name.</td>
+</tr>
+
+<tr class="break">
+<td>Consider having inline links to concepts that are Eclipse-specific.</td>
+<td>
+<pre>
+<p>This tutorial provides a step-by-step walk-through
+of the features in the Eclipse
+<a href="../concepts/concepts-2.htm">Workbench</a>.
+You will learn how to use these features by creating
+a <a href="../concepts/concepts-12.htm">project</a>,
+then creating, running, and debugging a simple
+program.</p>
+</pre>
+
+<p>This tutorial provides a step-by-step
+walk-through of the features in the Eclipse
+<span class="fakelink">Workbench</span>.
+You will learn how to use these features by creating
+a <span class="fakelink">project</span>,
+then creating, running, and debugging a simple
+program.
+</p>
+
+</td>
+</tr>
+
+<!-- *************************** tables ************************ -->
+
+<tr><th>Tables</th><th>Example</th></tr>
+
+<tr>
+<td>Declare tables consistently.
+</td>
+<td>
+<tt><table border="1" cellpadding="3" cellspacing="0"></tt>
+</td>
+</tr>
+
+<tr>
+<td>Set the vertical alignment for rows to "top" in the CSS file.
+</td>
+<td>
+<tt>tr { vertical-align: top; }</tt>
+</td>
+</tr>
+
+<!-- *************************** operating system specific content ************************ -->
+
+<tr><th>Operating system specific content</th><th>Example</th></tr>
+
+<tr>
+<td>Remove all generator tags and author tags.</td>
+<td><pre><meta name="GENERATOR">
+<meta name="author" content="JFK"></pre></td>
+</tr>
+
+<tr>
+<td>Use class tags to mark text that is specific to a particular
+operating system (and in Unix, to a particular widget set).
+At the time of this writing, these are the proposed classes:
+
+<dl>
+<dt>class="win32"</dt>
+<dd>For Windows-specific content such as executable names
+(<code>eclipse.exe</code>) and path names (<code>C:\eclipse\workbench</code>).
+</dd>
+
+<dt>class="unix"</dt>
+<dd>For all operating systems other than Windows (that is, Unix and Mac OS X).</dd>
+
+<dt>class="ctrlf1"</dt>
+<dd>For Unix/Linux systems that run the gtk widget set.
+You would normally use this class to mark the key to press
+to access the help system (in this case, [Ctrl]+[F1]).</dd>
+
+<dt>class="helpkey"</dt>
+<dd>For the Mac OS X widget set, under which you press [Help]
+to access the Help system
+and press [Ctrl]+click
+to access the context menu.</dd>
+
+<dt>class="f1"</dt>
+<dd>For all systems other than gtk and carbon (press [F1] for help).</dd>
+
+<dt>class="rtclick"</dt>
+<dd>For widget sets other than Mac OS X, under which you right-click
+to access the context menu.</dd>
+
+<dt>class="ctrlclick"</dt>
+<dd>For Mac OS X, under which you Ctrl-click
+to access the context menu.</dd>
+
+<dt>class="all_platforms"</dt>
+<dd>This category combines the information from the above classes into
+a single grouping.
+This enables vendors to disable the display of the "all" category and
+all unwanted specific categories.
+</dd>
+</dl>
+
+</td>
+
+<td>
+<p>In the HTML file:</p>
+<pre>
+<div class="all_platforms">
+<p>To access the help system:</p>
+<ul>
+<li>On Windows, press [F1]</li>
+<li>On Mac, press [Help]</li>
+<li>On Linux(gtk), press [Ctrl]+[F1]</li>
+<li>On all other systems), press [F1].</li>
+</ul>
+</div>
+
+<p class="f1">To access the
+help system, press [F1].</p>
+
+<p class="ctrlf1">To access the help
+system, press [Ctrl]+[F1].</p>
+
+<p class="helpkey">To access the
+help system, press [Help].</p>
+</pre>
+
+<p>And in the CSS file that prints generic documentation
+(and in which by default all_platforms is enabled):</p>
+<pre>
+.ctrlf1 {display: none;}
+.helpkey {display: none;}
+.f1 {display: none;}
+</pre>
+
+<p>And in the CSS file for a gtk system:</p>
+<pre>
+.all_platforms {display: none;}
+.helpkey {display: none;}
+.f1 {display: none;}
+</pre>
+</td>
+</tr>
+
+<!-- *************************** CSS ************************ -->
+
+<tr class="break"><th colspan="2">CSS Class Summary</th></tr>
+
+<tr>
+<td colspan="2">There are the following CSS files:
+<ul>
+<li>book.css defines how to render text and calls bookws.css</li>
+<li>bookos.css defines which content to hide by operating system</li>
+<li>bookws.css defines which content to hide by widget set.</li>
+</ul>
+
+<p>When the operating system implies the widget set (or vice versa), the
+content of bookws.css can be added to bookos.css. </p>
+
+<p>To call the book.css file, change the current markup from
+<br>
+<code><link rel="stylesheet" href="../book.css" type="text/css"></code>
+<br>
+to
+<br>
+<code><link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css"></code>
+<br>
+(The help system will make the appropriate changes to the path at run time.)
+</p>
+
+<table border="1" cellpadding="3" cellspacing="0">
+<tbody><tr><th rowspan="3">O/S</th><th colspan="8">CSS</th></tr>
+
+<tr><th colspan="2">Path names</th><th colspan="3">Help Key</th><th colspan="2">Mouse</th><th rowspan="2" width="75" valign="bottom">all_platforms</th></tr>
+<tr><th width="75">win32</th><th width="75">unix</th><th width="75">ctrlf1</th><th width="75">helpkey</th><th width="75">f1</th>
+<th width="75">rtclick</th><th width="75">ctrlclick</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 class="on">on</td><td>off</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 class="on">on</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 class="on">on</td><td>off</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><td class="on">on</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 class="on">on</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 class="on">on</td><td>off</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>off</td><td>off</td><td class="on">on</td></tr>
+
+</tbody></table>
+
+
+</td>
+
+</tr>
+
+<!-- *************************** graphics ************************ -->
+
+<tr><th>Graphics</th><th>Example</th></tr>
+
+<tr>
+<td>There are two types of graphics in the online help at present:
+icons (which can be taken from the icon sets for the user interface)
+and screen captures.
+<p>Icons are system-independent, so there are no reasons to give
+them class names or to be concerned about their file type.
+</p>
+<p>On the other hand, screen captures are system-dependent,
+so it is important that different systems can display the
+appropriate screen captures.
+To do this, vendors need to be able to create a zip file of screen
+captures that the help system can display properly and automatically:
+</p>
+<ul>
+<li>Screen captures must be ".png" files.</li>
+<li>Image declarations must <b><i>not</i></b> specify image sizes.</li>
+<li>Image declarations should have "alt" attributes (this is
+an accessibility feature).</li>
+<li>Image declarations may have a <title> attribute.</li>
+</ul>
+<p>The default platform for screen captures is Windows XP.</p>
+</td>
+<td><code><img border="0" src="../images/Image201_fillet" alt="Define a New File Type dialog"></code></td>
+</tr>
+
+<!-- *************************** indexing ************************ -->
+
+<tr class="break"><th>Indexing</th><th>Example</th></tr>
+
+<tr>
+<td>Eclipse indexes its help files by looking at the text
+in the page and weighting titles over paragraphs.
+However, there can be times when you want the index
+to show text that does not display on the page.
+For example, if Eclipse uses its own terminology for a function,
+you might want users to be able to look up synonyms.
+
+<p>To have the Eclipse index generate a hit for "autosave"
+(a function that Eclipse has under another name) add a
+<tt>meta "keywords"</tt> tag before the </head> tag.</p>
+</td>
+<td><pre>
+<meta name="keywords" content="autosave">
+</pre>
+</td>
+</tr>
+
+
+<!-- *************************** html or xhtml declaration ************************ -->
+
+<tr><th colspan="2">HTML Doctype</th></tr>
+<tr>
+<td colspan="2">XHTML doctypes are not properly supported in Internet Explorer
+(they cause an unneeded scrollbar to appear), so the default
+DOCTYPE is:<br>
+<code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"></code></td>
+</tr>
+
+</table>
+
+<!-- div class="gtk" style="margin-bottom:-15px;">
+
+<br>
+</div -->
+
+</body>
+</html>
