doc/Documentation_Standards.org: Major update

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

1 files changed, 62 insertions, 47 deletions

diff --git a/doc/Documentation_Standards.org b/doc/Documentation_Standards.org
index ea6e675..9d8f19f 100644
--- a/doc/Documentation_Standards.org
+++ b/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,77 +33,94 @@ 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
 seems that Carsten now thinks of Org as the system encompassing the
 major mode, some minor modes, and an increasing number of additional
-packages and plug-ins that build on the core Org functionality. It is
+packages and plug-ins that build on the core Org functionality.  It is
 really hard to find a consistent way to refer to all these things, but
 what I am trying to do is follow these guidelines (which are not
 perfect, merely a start):
 
- - In general write "Org" as much as possible and, in particular, when
-   discussing concepts, features and functions that are generally
-   applicable to Org as a whole.
+- In general write "Org" as much as possible and, in particular, when
+  discussing concepts, features and functions that are generally
+  applicable to Org as a whole.
 
- - Be more specific and write, for example, "the Orgtbl minor mode"
-   when referring to something unique to that feature.  It maybe, for
-   example, a command is only available when you are actually editing
-   a file using just that mode, add-on package or plug-in.
+- 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.
 
- - 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.
+- 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.
 
- - Likewise refer, if at all possible, to "Org file or "Org buffer"
-   meaning with, great generality, any file or buffer which requires
-   use of some part of Org to edit it properly.
+- Likewise refer, if at all possible, to "Org file or "Org buffer"
+  meaning with, great generality, any file or buffer which requires
+  use of some part of Org to edit it properly.
 
- - Org uses "org-..." to ring fence a name space for itself in the
-   Emacs code base.  This is obviously retained in code snippets.
+- Org uses "org-..." to ring fence a name space for itself in the
+  Emacs code base.  This is obviously retained in code snippets.
 
 * 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
-   one sort or another.  Write in full "prefix argument", "numeric
-   prefix argument" or, maybe, "a numeric prefix argument N" when you
-   want to refer to the argument again.
+- Org has *lots* of commands and a /lot/ of them take prefix arguments of
+  one sort or another.  Write in full "prefix argument", "numeric
+  prefix argument" or, maybe, "a numeric prefix argument N" when you
+  want to refer to the argument again.
 
- - 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.
+- 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.
 
- - TODO keywords, whether Org or user defined, are written in capitals.
+- 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
-   lowercase.
+- 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