[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[platform-doc-dev] Proposed changes to the Eclipse help
|
I would like to offer to make some changes to the Workbench User Guide
and the Java Development User Guide. These changes are mainly to make
the topics more portable between operating systems, but there are also
suggestions about style and HTML coding practices.
To give you an idea of the sorts of changes I would like to make, I've
taken a random file (org.eclipse.jdt.doc.user/tasks/tasks-99.htm) and
made some comments. One additional suggestion I would like to make, but
which does not apply to this particular topic, is that we give all
OS-specific paragraphs a class:
<p class=windows">Windows text...</p>
This would enable Eclipse on non-Windows systems to have a CSS file that
includes:
.windows {display: none;}
Here is the commented version of tasks-99.htm:
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<meta name="GENERATOR" content="Mozilla/4.76 [en] (Windows NT 5.0; U)
[Netscape]">
<!--
********************************************************************
** It would be better if there were no generator tags **
********************************************************************
-->
<title>Parameters page</title>
<!--
********************************************************************
** This is really a reference topic, so a better title would be, **
** "Change Method Signature parameters page". The proper tasks **
** page for this task is tasks-98.htm. **
** **
** This renaming applies to the <h1></h1> as well. **
********************************************************************
-->
<link rel="stylesheet" href="../book.css" charset="ISO-8859-1"
type="text/css">
<!--
********************************************************************
** My validator my be out of date, but it claims that **
** <link> does not support "charset" **
********************************************************************
-->
</head>
<body>
<h1>Parameters page</h1>
<!--
********************************************************************
** This topic tells the reader how to select an item and click **
** a button. What a reader is more likely to want to know is how **
** to get to this dialog. That information needs to be here. To **
** do this, just add a link to tasks-98.htm. **
** **
** Granted, tasks-98.htm is immediately above this page in the **
** TOC, but adding the link means that this page can stand **
** alone--which would enable it to move to the reference section, **
** for example. **
********************************************************************
-->
<img src="../images/tasks-32.gif" width="432" height="454"
alt="Parameters page of the Change Method Signature refactoring wizard">
<!--
*********************************************************************
** We find it useful not to specify width and height attributes **
** (updated screen captures are easier). **
** **
** Most images in Eclipse help are contained in <p></p> tags, so **
** we follow that convention. **
** **
** It would also be helpful to have a naming convention that would **
** identify OS-specific screen captures. In this case, renaming **
** tasks-32.gif to tasks-32-win.gif would make it possible for us **
** to do a global search-and-replace of "win.gif" to "lnx.png". **
*********************************************************************
-->
<p>Parameters Page for the Change Method Signature Refactoring Command
</p>
<!--
********************************************************************
** Many screen captures do not have a caption, so I would be **
** inclined to remove this one--particularly if the page title **
** were more descriptive. If you wanted a caption, it would be **
** an excellent opportunity to use <p class="caption"> and use **
** some CSS to make the caption distinct from the regular text. **
********************************************************************
-->
<ul>
<li>Click in the <strong>Name</strong> column on the row containing the
parameter you want to change or select the row and press
<strong>Edit</strong> and type a new name for the parameter.</li>
</ul>
<!--
********************************************************************
** We do not use lists with a single list item. **
** **
** I believe what was intended here is: **
** **
** <p>Double-click on the name of the parameter you **
** want to change and type a new name for the parameter. **
** Alternatively, select the row and click **
** <strong>Edit</strong>.</p> **
** **
** We use "press" only for keyboard keys. **
** **
** We end topics with an <hr width="90%"> to separate the content **
** from the "other information" links. **
********************************************************************
-->
<p><img src="../images/ngrelt.gif" alt="Related tasks" border="0"
height="27" width="159">
</p>
<p><a href="tasks-82.htm">See Refactoring without Preview</a>
<br><a href="tasks-83.htm">See Refactoring with Preview</a>
<br><a href="tasks-74.htm">See Showing a Type's Compilation Unit in the
Packages View</a>
</p>
<!--
********************************************************************
** We separate the links from the graphic with a single <br>, **
** rather than </p><p>. The saves space and makes the links **
** more obviously associated with the graphic above them. **
** **
** These links should not begin with the word "See". **
********************************************************************
-->
</ul>
<!--
********************************************************************
** This orphaned </ul> causes the page to not validate. **
********************************************************************
-->
<p><a href="../notices.html"><img src="../cpy.gif" border="0" alt="Legal
notices" width="324" height="14"></a>
</p>
</body>
</html>
********************************************************************
** Here is the proposed new version of tasks-99.htm: **
********************************************************************
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Change Method Signature parameters page</title>
<link rel="stylesheet" href="../book.css" type="text/css">
</head>
<body>
<h1>Change Method Signature parameters page</h1>
<p><img src="../images/tasks-32-win.gif" alt="Parameters page of the
Change Method Signature refactoring wizard">
</p>
<p class="caption">Parameters Page for the Change Method Signature
Refactoring Command
</p>
<p>Double-click on the name of the parameter you want to change
and type a new name for the parameter.
Alternatively, select the row and click <strong>Edit</strong>.
</p>
<hr width="90%">
<p><img src="../images/ngrelt.gif" alt="Related tasks" border="0"
height="27" width="159">
<br><a href="tasks-82.htm">Refactoring without Preview</a>
<br><a href="tasks-83.htm">Refactoring with Preview</a>
<br><a href="tasks-74.htm">Showing a Type's Compilation Unit in the
Packages View</a>
</p>
<p><a href="../notices.html"><img src="../cpy.gif" border="0" alt="Legal
notices" width="324" height="14"></a>
</p>
</body>
</html>
