X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=d3661ab39ab7e6c8700ce0073d3409ed769efa40;hb=86556b093195ee643543fbfae12a5f2ce2857101;hp=63ae075085f0f388e343a7c253f0296d78784d20;hpb=6c34122ce027f09d14416cacfde6860089694e94;p=lilypond.git

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 63ae075085..d3661ab39a 100644
--- 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
@@ -65,22 +70,25 @@ main docs
 
     Music glossary: @rglos{foo}, @rglos{bar}.
 
-    User manual: @ref{baz}, @ref{foozle}.
+    Learning Manual: @rlearning{baz}, @rlearning{foozle}
+
+    Notation Reference: @ruser{faazle}, @ruser{boo}.
+
+    Application Usage: @rprogram{blah}.
+
+    Installed files: @file{blahz}.
 
-    Snippets: @lsrdir{section}.
+    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.)
 
-    Program reference: @internalsref{fazzle}, @internalsref{booar}.
+    Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
 
   ("Snippets" is REQUIRED; the others are optional)
 
 * To create links, use @ref{} if the link is within the same
-  manual.  If you are linking to another manual (say,
-  learning->glossary or user->program usage), then use:
-    @rlearning{}
-    @ruser{}
-    @rprogram{}
-    @rglos{}
-    @internalsref{}
+  manual.
 
 * @commonprop and @refbugs are optional.
 
@@ -215,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       **
@@ -233,6 +240,17 @@ main docs
 	@warning{}: produces a "Note: " box.  Use for important
       messages.
 
+* References must occur at the end of a sentence, for more
+  information see @ref{the texinfo manual}.  Ideally this should
+  also be the final sentence of a paragraph, but this is not
+  required.  Any link in a doc section must be duplicated in the
+  @seealso section at the bottom.
+
+* Introducing examples may be done with
+     . (ie finish the previous sentence/paragaph)
+     : (ie `in this example:')
+     , (ie `may add foo with the blah construct,')
+
 
 %%%%% READABILITY
 
@@ -253,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