Update from Ralph.

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 6665bc13e0f42e0675e63a992af0b4f2fd02331f..80bb6cc8b1096a9783961ddeff49b177233884f1 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -8,11 +8,22 @@ There are four parts to the documentation: the Learning Manual,
 the Notation Reference, the Program Reference, and the Music
 Glossary.
 
-* Learning Manual: long, chatty, friendly explanations go here.
-  This is aimed at users learning something for the first time --
-  not necessarily just learning lilypond notation, but also things
-  like learning how to deal with projects, tweaking, preparing parts
-  for orchestras, etc.  Less formal language may be used here.
+* Learning Manual:
+  The LM is written in a tutorial style which introduces the most
+  important concepts, structure and syntax of the elements of a
+  LilyPond score in a carefully graded sequence of steps.
+  Explanations of all musical concepts used in the Manual can be
+  found in the Music Glossary, and readers are assumed to have no
+  prior knowledge of LilyPond.  The objective is to take readers to
+  a level where the Notation Reference can be understood and
+  employed to both adapt the templates in the Appendix to their
+  needs and to begin to construct their own scores.  Commonly used
+  tweaks are introduced and explained.  Examples are provided
+  throughout which, while being focussed on the topic being
+  introduced, are long enough to seem real in order to retain the
+  readers' interest.  Each example builds on the previous material,
+  and comments are used liberally.  Every new aspect is thoroughly
+  explained before it is used.
 
 Users are encouraged to read the complete Learning Manual from
 start-to-finish.
@@ -68,7 +79,7 @@ main docs
 * 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}
 
@@ -76,7 +87,7 @@ main docs
 
     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
@@ -110,7 +121,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
@@ -119,8 +133,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