[cdt-doc-dev] C/C++ Development User Guide

[Mike Behm <mbehm@xxxxxxxxxx>]

Here are some comments on the first two sections of the C/C++ 
Development User Guide. It's looking very good!



Getting Started
---------------
 -I like this practice of having text on introductory pages.
  Some of these pages in the base Eclipse documentation are
  blank--basically they act as headings in the TOC and add
  nothing in the body pane.
 -The copyright notice on the base Eclipse pages is a
  link to a copyright page. If you change this notice
  to be a link, you should adjust the ALT tags to be
  ALT="Copyright IBM Corporation 2003. All Rights Reserved."

  If you don't like having to change the artwork for the
  copyright graphic each year, you can also do something like this:

  <p class="copyright"><a href="../hglegal2002.htm"
  class="copyright">&nbsp;&#169; Copyright IBM Corporation 2003.
  All Rights Reserved.</a></p>

  where class="copyright" maps to:
  p.copyright { font-family: sans-serif, Helvetica, Verdana;
	font-size: 7pt; color: #3450ac; }
  a.copyright { color: #3450ac; text-decoration: none; }


CDT Overview
------------
 -Para. 1, Sent. 1 is true, but you might want to phrase it in terms
  of the CDT being a plug-in, rather than it being an IDE. (It's
  probably more common to think of Eclipse as being an IDE.)
 -Sent. 3 could have links to the "C/C++ editor" and "C/C++ views"
  topics when those page are done. Alternatively, if you want to
  minimize inline links, you could add those links to the "Related
  Reference" section.

 -Para. 2, Sent. 1 could be reworked a bit. The CDT isn't really
  complementary to command-line tools, it is a graphical interface to
  those tools.

 -CDT updates, Sent. 1: "The Install/Update perspective..."
  (as opposed to "The Install/Update view...")
 -There has been a little discussion about whether or not to apply some
  markup (such as bolding) to names that appear on the GUI.
  Most pages in the base documentation do apply some tags to the names
  of views and perspectives (typically just <b></b> tags). However,
  there is another way to approach: use class names. By tagging
  screen names with <span class="guilabel"></span> you could apply font
  changes universally by modifying book.css as required.
  (The suggested classname is similar to SGML mark up.)


What's new
----------
 -Better error recovery bullet: Don't forget to end the "If" clause with
  a comma.
 -I expect that the Related Task link will eventually go to
  "Tasks > Updating the CDT". That, in turn, points to the Workbench
  User Guide. You might want to just point the reader to the Workstation
  User Guide from here. (Alternatively, you could give the full
  instructions in "Tasks > Updating the CDT" and include that required
  URL that is currently in "Getting Started > CDT Overview". Actually, I
  quite like that idea...sorry that it would mean extra work.)


Creating your makefile
----------------------
 -You should add a note that says the indented lines are indented by
  tab characters, not spaces.


Debugging your project
----------------------
 -In this page <b></b> tags are used to indicate:
   -Menu items (Run > Debug)
   -Buttons (Debug)
   -Fields (Name)
   -Keyboard input (Hello World)  (one 'm' was missed)
   -View names (Variable view).
  You might want to use <kbd></kbd> for the keyboard input (or
  better yet, <span class="userinput"></span>). As for the other
  elements, bold is probably the way to go...although if all
  buttons were marked up as <span class="guibutton">Debug</span>,
  you could add this to book.css:
  .guibutton {
	color: #000000;
	font-family: helvetica, arial, sans-serif;
	background-color: #DCDCDC;
	padding: 1px 3px;
	font-size: 10pt;
	border: outset 2px;
	text-decoration: none;
        line-height:175%; }

  OK--that's all I'll write about classes. ;)