GDP: NR 2 Reorganisation: Chords headings and move Figured bass

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 481394249972e99f936dffd7f963e70e4017a89f..4dac1c28f5fdd89f1752dbda586cb458f205792d 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -45,8 +45,9 @@ material in the Learning Manual (particularly ``Fundamental
 Concepts''), so do not repeat that material in each section of
 this book.  Also watch out for common constructs, like ^ - _ for
 directions -- those are explained in NR 3.  In NR 1, you can
-mention that "dynamics (or whatever) may be placed above or below
-the staff, for details see @ref{Up and down}".
+write:
+DYNAMICS may be manually placed above or below the
+staff, see @ref{Controlling direction and placement}.
 
 Most tweaks should be added to LSR and not placed directly in the
 .itely file.  In some cases, tweaks may be placed in the main
@@ -79,30 +80,48 @@ Users are not expected to read this manual from start to finish.
 The order of headings inside documentation sections should be:
 
 main docs
-@refcommands
-@commonprop
+@predefined
+@snippets
 @seealso
-@refbugs
+@knownissues
 
 * You _must_ include a @seealso.  The order of items inside the
   @seealso section is
 
-    Music Glossary: @rglos{foo}, @rglos{bar}.
+    Music Glossary:
+    @rglos{foo},
+    @rglos{bar}.
 
-    Learning Manual: @rlearning{baz}, @rlearning{foozle}
+    Learning Manual:
+    @rlearning{baz},
+    @rlearning{foozle}
 
-    Notation Reference: @ruser{faazle}, @ruser{boo}.
+    Notation Reference:
+    @ruser{faazle},
+    @ruser{boo}.
 
-    Application Usage: @rprogram{blah}.
+    Application Usage:
+    @rprogram{blah}.
 
-    Installed Files: @file{path/to/dir/blahz}.
+    Installed Files:
+    @file{path/to/dir/blahz}.
 
-    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.)
+    Snippets:
+    @lsrdir{section},
+    @lsr{specific/example-name.ly}.
 
-    Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
+    Internals Reference:
+    @internalsref{fazzle},
+    @internalsref{booar}.
+
+      If there are multiple entries, separate them by commas
+      but do not include an `and'.
+
+      Always end with a period.
+
+      Place each link on a new line as above; this makes it much
+      easier to add or remove links.  In the output, they
+      appear on a single line.
 
   ("Snippets" is REQUIRED; the others are optional)