doc/Documentation_Standards.org: Major update

Thanks to Thomas Dye for providing a patch to enhance this page.

doc/Documentation_Standards.org

@@ -5,7 +5,7 @@
 #+STARTUP:  showall
 #+TEXT:     Notes to myself justifying the conventions and standards in my
 #+TEXT:     set of recent doc patches.
-#+OPTIONS:  H:3 num:t toc:t \n:nil @:t ::t |:t ^:t *:t TeX:t
+#+OPTIONS:  H:3 num:t toc:t \n:nil @:t ::t |:t ^:nil *:t TeX:t
 
 * Background
 
@@ -33,7 +33,7 @@ capture some of the existing guidelines and standards that have been
 used in the patches I am submitting and, which I hope, may be adopted
 by others when making their own contributions.
 
-* Org - Referencing systems, packages, modes and much else
+* Referencing systems, packages, modes and much else
  
 Originally Org was a single mode and there was no ambiguity about what
 Org mode could refer to.  Things have changed rapidly though and it
@@ -50,13 +50,13 @@ perfect, merely a start):
 
 - Be more specific and write, for example, "the Orgtbl minor mode"
   when referring to something unique to that feature.  It may be, for
-   example, a command is only available when you are actually editing
-   a file using just that mode, add-on package or plug-in.
+  example, a command is only available when you are actually editing a
+  file using just that mode, add-on package or plug-in.
 
 - Prefer "Org mode" to "Org-mode" or "org-mode".  This is simply
-   because it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]]
-   which consistently documents mode names in this form - "Text mode",
-   "Outline mode", "Mail mode" etc.
+  because it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]] which
+  consistently documents mode names in this form - "Text mode",
+  "Outline mode", "Mail mode", etc.
 
 - Likewise refer, if at all possible, to "Org file or "Org buffer"
   meaning with, great generality, any file or buffer which requires
@@ -67,9 +67,9 @@ perfect, merely a start):
 
 * Other Org specific conventions
 
-Unless there is a good reason to do otherwise then try and adopt the
+Unless there is a good reason to do otherwise, then try and adopt the
 following conventions.  (I think all can be justified by reference to
-Carsten or precedent in other significant Emacs documentation...unless
+Carsten or precedent in other significant Emacs documentation, unless
 I have made them up of course).
 
 - Org has *lots* of commands and a /lot/ of them take prefix arguments of
@@ -79,31 +79,48 @@ I have made them up of course).
 
 - Org lives in various states of harmony and discord with other Emacs
   packages.  Try and write the names of those packages as their
-   authors and maintainers write them.  So it should be (I think)
-   BBDB, MH-E, Rmail, VM, Gnus, CDLaTeX etc.
+  authors and maintainers write them.  So it should be (I think) BBDB,
+  MH-E, Rmail, VM, Gnus, CDLaTeX etc.
 
 - TODO keywords, whether Org or user defined, are written in capitals.
 
- - Built-in tags with a special meaning (eg ARCHIVE) are written in
-   uppercase.  User defined tags (eg boss, home) are written in
+- Built-in tags with a special meaning (e.g. ARCHIVE) are written in
+  uppercase.  User defined tags (e.g. boss, home) are written in
   lowercase.
 
- - Built-in properties (eg PRIORITY) are written in uppercase.  User
-   defined properties (eg Release) are written in lowercase.
+- Built-in properties (e.g. PRIORITY) are written in uppercase.  User
+  defined properties (e.g. Release) are written in lowercase.
 
- - [[info:org:Top][The Org Manual]] uses the @chapter, @section and @subsection Texinfo
-   commands for sectioning.  I have tried to capitalize significant
-   words in @chapter headings.  In @section and @subsection headings,
-   just the first word is capitalized and all other words are
-   lowercase (with exceptions of course...).  Thus, use:
+- Entries in the concept index are normally all lower case unless some
+  other rule dictates otherwise.
 
-   @chapter Properties and Columns
+* orgmanual.org specific conventions
 
-   @section Visibility cycling
+Org git repository comes with an .org version of the manual in the
+=contrib/= directory.  Here are indications that are specific to this
+version of the manual.
 
- *but*
+- Five of the standard Texinfo indexes are used in the Org manual:
 
-   @section Fast access to TODO states
+  + #+cindex: :: concept index, for general concepts
+  + #+findex: :: function index, for function and function-like names
+  + #+kindex: :: keystroke index, for keyboard commands
+  + #+pindex: :: program index, for names of programs
+  + #+vindex: :: variable index, for variable names
+
+- Use fixed-width area for one-line examples.
+
+- Use example blocks for Org syntax instead of "begin_src org".
+
+- Internal links to headlines always start with a star.
+
+- Tags, node properties, are not shown with the surrounding colons.
+
+- When to use = ... = or ~ ... ~ markup:
+
+  + files or extensions use = ... =,
+  + anything that is meant to be written in the Org buffer uses = ... =,
+  + any meaningful token in a programming language uses ~ ... ~.
 
 * Miscellaneous
 
@@ -139,11 +156,9 @@ I have made them up of course).
    associated word and replacement files, captures some of the more
    detailed and somewhat arbitrary rules I have used.
 
- - Org has really low entry barriers.  The requirements seem simply to
-   be:
+ - Org has really low entry barriers.  Requirements seem simply to be:
 
    + You can use Text mode or, pretty much, any derivative of it
-
    + You have some motivation to become slightly better organized.
 
    Therefore, try and write the documentation so that it is relevant