Merge branch 'master' of git://git.sv.gnu.org/lilypond.git into td-lily

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 329b72427ec6a20f6bbfb894b12b3afebd2a1643..4dac1c28f5fdd89f1752dbda586cb458f205792d 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -31,21 +31,30 @@ start-to-finish.
 
 * Notation Reference: a (hopefully complete) description of
   LilyPond input notation.  Some material from here may be
-  duplicated in the Learning Manual (for teaching).  The material is
-  presented in an approximate order of increasing difficulty, but
-  the goal is _not_ to provide a step-by-step learning environment.
-  For example, all material under "Pitches" should remain in that
-  section, even though microtonal accidentals may seem more advanced
-  than info about clefs or time signatures -- "Pitches" should be a
-  one-stop reference about the pitch portion of notes.  This section
-  is written in formal technical writing style.
-
-Users are not expected to read this manual from start to finish.
-However, they should be familiar with the material in the Learning
-Manual (particularly ``Fundamental Concepts''), so do not repeat
-that material in each section of this book.  Also, you should
-assume that users know what the notation means; explaining musical
-concepts happens in the Music Glossary.
+  duplicated in the Learning Manual (for teaching), but consider
+  the NR to be the "definitive" description of each notation
+  element, with the LM being an "extra".  The goal is _not_ to
+  provide a step-by-step learning environment -- do not avoid
+  using notation that has not be introduced previously in the
+  NR  (for example, use \break if appropriate).  This section is
+  written in formal technical writing style.
+
+Avoid duplication.  Although users are not expected to read this
+manual from start to finish, they should be familiar with the
+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
+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
+text, but ask about this first.
+
+Finally, you should assume that users know what the notation
+means; explaining musical concepts happens in the Music Glossary.
 
 
 * Application Usage: information about using the program lilypond
@@ -71,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}.
 
-    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}.
 
-    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)
 
@@ -121,7 +148,10 @@ main docs
 
   Both index commands should go in front of the actual material.
 
-  @cindex should not be capitalized.
+  @cindex entries should not be capitalized, ie
+    @cindex time signature
+  is preferred.  (instead of `Time signature')   Only use capital
+  letters for musical terms which demand them, like D.S. al Fine.
 
 * Preferred terms:
     - in general, use the American spellings.  The internal
@@ -130,8 +160,8 @@ main docs
 canceled
 simultaenous    NOT concurrent
 measure: the unit of music
-bar line: the symbol delimiting a measure
-
+bar line: the symbol delimiting a measure   NOT barline
+note head   NOT notehead
 
 
 %%%%% TECHNICAL WRITING STYLE