Merge branch 'master' of git://git.sv.gnu.org/lilypond

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index d24d285e3f4962949cbd517716d5acf66b1d9876..3c762f2c57eceb574248e0c538f29a77f54fd726 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.
@@ -32,9 +43,9 @@ start-to-finish.
 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 this book.  Also, you should assume that users
-know what the notation means; explaining musical concepts happens
-in the Music Glossary.
+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.
 
 
 * Application Usage: information about using the program lilypond
@@ -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
@@ -87,6 +98,9 @@ main docs
 
   ("Snippets" is REQUIRED; the others are optional)
 
+  Any new concepts or links which require an explanation should go
+  as a full sentence(s) in the main text.
+
 * To create links, use @ref{} if the link is within the same
   manual.
 
@@ -107,11 +121,20 @@ main docs
 
   Both index commands should go in front of the actual material.
 
+  @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
       lilypond property names use this spelling.
     - list of specific terms:
-canceled, 
+canceled
+simultaenous    NOT concurrent
+measure: the unit of music
+bar line: the symbol delimiting a measure
+
 
 
 %%%%% TECHNICAL WRITING STYLE