Changeset 700

Timestamp:

09/12/10 22:18:43 (21 months ago)

Author:

mgalloy

Message:

More on tutorial and reference manual.

Location:

trunk/reference

Files:

• idldoc-reference.rst (modified) (2 diffs)
• idldoc-tutorial.rst (modified) (2 diffs)

trunk/reference/idldoc-reference.rst

@@ -85 +85 @@
 -------------
 
-TODO: what is a format style? legacy format styles "IDLdoc", "IDL"; not recommended for new comments
-
 
 rst format style
@@ -589 +587 @@
 #. code blocks
 #. headers
-#. image directive
-#. embed directive
-#. title directive
+
+*Directives* provide a more general markup syntax. Currently, there are three directives defined:
+
+  #. image directive
+  #. embed directive
+  #. title directive
+
+The "image" directive allows images to be placed into comments. To use, put the following on the end of a line::
+
+    .. image:: filename
+    
+where `filename` is any image file format read by `READ_IMAGE`. The `filename` specified will be copied into the output directory.
+
+The "embed" directive allows `.svg` files to be embedded in the documentation. To use, put the following on the end of a line::
+
+    .. embed:: filename
+
+The "title" directive is available to provide a title for `.idldoc` files::
+
+    .. title:: cpt-city color tables
+    
+This title is used for the `.idldoc` file in the table of contents of available documentation.
+
 
 verbatim markup style

trunk/reference/idldoc-tutorial.rst

@@ -25 +25 @@
 The rst format and markup styles are inspired by reStructuredText and Markdown projects
 
-IDLdoc 3.0 was completely rewritten separately from the IDLdoc 2.x code base.
+In *The Mythical Man Month*, Fred Brooks argues to "build one to throw away." For reasons out of my control, IDLdoc 3.0 was completely rewritten separately from the IDLdoc 2.x code base and now follows Brooks' rule. 
 
 This tutorial intends to get a new user up to speed in using IDLdoc in the simplest way using the newer, more modern style of IDLdoc commenting. Don't worry, though, IDLdoc still supports legacy commenting styles so you don't have to go changing existing documentation (unless you want to make use of some of the cool, new features!). Experienced users will probably learn some new things too, since documentation for IDLdoc has been spotty in the past.
@@ -70 +70 @@
 
 TODO: "rst" is the modern supported style for both format and markup in current versions of IDLdoc (although not the default); legacy format/markup is described in the reference manual.
+
+The format style defines the format for comments within specially marked comment headers. Comment blocks which start with `;+` and end with `;-` are considered by IDLdoc::
+
+    ;+
+    ; This is a comment block.
+    ;-
+
+These comments start with a general description of the file or routine they are documenting, but the format styles define a format for adding comments about particular aspects such as individual parameters/keywords of a routine or author of a file.
+
+There are three format styles allowed in IDLdoc comments: "rst", "IDLdoc", and "IDL." The "IDLdoc" and "IDL" format styles are for provided for legacy documentation headers; new comments should be written in the "rst" format style.