Changeset 703

Timestamp:

09/13/10 16:00:45 (21 months ago)

Author:

mgalloy

Message:

Draft for reference manual.

Files:

• trunk/reference/idldoc-reference.rst (modified) (1 diff)

trunk/reference/idldoc-reference.rst

@@ -582 +582 @@
 The *rst* markup style is the default markup style for the *rst* format style.
 
-TODO: describe rst markup style
-
-#. links, both kinds
-#. code blocks
-#. headers
+The *rst* markup style attempts to make its format definition similar to what someone would do normally for readability in a text document. For example, paragraphs are created by simply skipping a line::
+
+  ; Merges a string array into a single string separated by carriage 
+  ; return/linefeeds. 
+  ;
+  ; Defaults to use just linefeed on UNIX platforms and both carriage returns 
+  ; and linefeeds on Windows platforms unless the UNIX or WINDOWS keywords are 
+  ; set to force a particular separator.
+
+There is other special syntax for some annotations that are common when documenting code. To place a block of code into the documentation, end a line with ``::``, skip a line, indent the block of code, and skip another line::
+
+  ; Set the decomposed mode, if available in the current graphics device i.e.
+  ; equivalent to::
+  ; 
+  ;    device, get_decomposed=oldDec
+  ;    device, decomposed=dec
+  ;
+  ; The main advantage of this routine is that it can be used with any graphics
+  ; device; it will be ignored in devices which don't support it.
+
+Another common annotation is to place a link in the documentation. For example, to link "http://michaelgalloy.com" to the phrase "my website", simply do::
+
+    ; Check out `my website <http://michaelgalloy.com>`.
+    
+But often, links are to other items in the documentation. For example, the comments for a routine, might briefly mention some of its keywords and it would be convenient to link to the documentation for these keywords. In this case, just put the method names in backticks like::
+
+    ; :Returns:
+    ;    Returns a triple as a `bytarr(3)` or `bytarr(3, n)` by default if a single
+    ;    color name or n color names are given. Returns a decomposed color index 
+    ;    as a long or lonarr(n) if `INDEX` keyword is set.
+    ; 
+    ;    Returns a string array for the names if `NAMES` keyword is set.
+
+IDL will search for a name matching the quoted string and link to the closest one it finds. If the name is not found, as in ``bytarr(3)`` above, it will simply be displayed in a monospace space font as code.
+
+Different level headers can be added to comments, particularly useful for `.idldoc` files. Just underline with ``-``, ``=``, or ``~``. For example, the following beginning to an `.idldoc` file, creates a level 1 header "TxDAP API Introduction", with a level 2 header "Basic Use" immediately after::
+
+    TxDAP API Introduction
+    ======================
+
+    Basic Use
+    ---------
+
+The order of use of the underlining determines the level of the header: the first underlined header is assumed to be level 1. The second, unless it is the same as the first, is assumed to be level 2, etc. From then on, titles underlined with "=" are level 1 headers and those underlined with "-" are level 2 headers.
 
 *Directives* provide a more general markup syntax. Currently, there are three directives defined: