Remove @samp.

[lilypond.git] / Documentation / user / policy.txt

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 148b4f681b9abef8a61a874692edd9368830e8c8..d3661ab39ab7e6c8700ce0073d3409ed769efa40 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -37,8 +37,8 @@ know what the notation means; explaining musical concepts happens
 in the Music Glossary.
 
 
-* Program Usage: information about using the program lilypond with
-  other programs (lilypond-book, operating systems, GUIs,
+* Application Usage: information about using the program lilypond
+  with other programs (lilypond-book, operating systems, GUIs,
   convert-ly, etc).  This section is written in formal technical
   writing style.
 
@@ -50,12 +50,17 @@ Users are not expected to read this manual from start to finish.
 
 Users are not expected to read this manual from start to finish.
 
+* Internals Reference: not really a documentation book, since it
+  is automagically generated from the source, but this is its
+  name.
+
 
 %%%%% SECTION ORGANIZATION
 
 The order of headings inside documentation sections should be:
 
 main docs
+@refcommands
 @commonprop
 @seealso
 @refbugs
@@ -69,9 +74,16 @@ main docs
 
     Notation Reference: @ruser{faazle}, @ruser{boo}.
 
-    Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}
+    Application Usage: @rprogram{blah}.
+
+    Installed files: @file{blahz}.
 
-    Program reference: @internalsref{fazzle}, @internalsref{booar}.
+    Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
+      (if there is only one entry, omit a final period.  If there
+       are multiple entries, separate them by commas, do not
+       include an `and', and end with a period.)
+
+    Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
 
   ("Snippets" is REQUIRED; the others are optional)
 
@@ -211,7 +223,6 @@ main docs
 * Specially-marked text:
 
     @code{}: actual lilypond code or property/context names.
-    @samp{}: ditto, for single-letter code.
 
 
       ** Any `\' used inside the commands below must be       **
@@ -260,6 +271,8 @@ main docs
   do not bother with the @code{} (they are added automatically).  These
   items are added to both the command index and the unified index.
 
+  Both index commands should go in front of the actual material.
+
 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 
 * Colon usage