Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into kainhofer

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 329b72427ec6a20f6bbfb894b12b3afebd2a1643..e259f39135c2b4fcc7e246c7c12c5c9298f7ac04 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,10 +80,10 @@ 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
@@ -121,7 +130,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 +142,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