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

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 80bb6cc8b1096a9783961ddeff49b177233884f1..0460e7ad3b4bff11187deb9b2a64481f05b678b1 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
 
 * 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
 
 
 * Application Usage: information about using the program lilypond


@@ -57,7 +66,7 @@ Users are not expected to read this manual from start to finish.
 
 
 * Music Glossary: information about the music notation itself.
 
 
 * Music Glossary: information about the music notation itself.

-  Explainations and translations about notation terms go here.
+  Explanations and translations about notation terms go here.

 
 Users are not expected to read this manual from start to finish.
 
 
 Users are not expected to read this manual from start to finish.
 


@@ -71,45 +80,82 @@ Users are not expected to read this manual from start to finish.
 The order of headings inside documentation sections should be:
 
 main docs
 The order of headings inside documentation sections should be:
 
 main docs

-@refcommands
-@commonprop
+@predefined
+@endpredefined
+@snippets

 @seealso
 @seealso

-@refbugs
+@knownissues

 
 * You _must_ include a @seealso.  The order of items inside the
   @seealso section is
 
 
 * 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: @rlsr{section}.

 
 

-    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:
+    @rinternals{fazzle},
+    @rinternals{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)
 
   Any new concepts or links which require an explanation should go
   as a full sentence(s) in the main text.
 
 
   ("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.
 

+  Don't insert an empty line between @seealso and the first entry!
+  Otherwise there is excessive vertical space in the PDF output.
+

 * To create links, use @ref{} if the link is within the same
   manual.
 
 * To create links, use @ref{} if the link is within the same
   manual.
 

+* @predefined ... @endpredefined is for commands in ly/*-init.ly
+  FIXME?
+

 * Do not include any real info in second-level sections (ie 1.1
   Pitches).  A first-level section may have introductory material,
   but other than that all material goes into third-level sections
   (ie 1.1.1 Writing Pitches).
 
 
 * Do not include any real info in second-level sections (ie 1.1
   Pitches).  A first-level section may have introductory material,
   but other than that all material goes into third-level sections
   (ie 1.1.1 Writing Pitches).
 
 

+%%%%% CHECKING CROSS-REFERENCES
+
+Cross-references between different manuals are heavily used in the
+documentation, but they are not checked during compilation.  However,
+if you compile the documentation, a script called check_texi_refs can
+help you with checking and fixing these cross-references; for
+information on usage, cd into a source tree where documentation has
+been built, cd into Documentation and look for check-xrefs and
+fix-xrefs targets in 'make help' output.  Note that you have to find
+yourself the source files to fix cross-references in the generated
+documentation such as the Internals Reference; e.g. you can grep
+scm/ and lily/.
+
+

 %%%%% GENERAL WRITING
 
 * Do not forget to create @cindex entries for new sections of text.
 %%%%% GENERAL WRITING
 
 * Do not forget to create @cindex entries for new sections of text.


@@ -126,6 +172,11 @@ main docs
   is preferred.  (instead of `Time signature')   Only use capital
   letters for musical terms which demand them, like D.S. al Fine.
 
   is preferred.  (instead of `Time signature')   Only use capital
   letters for musical terms which demand them, like D.S. al Fine.
 

+  For scheme functions, only include the final part, ie
+    @funindex modern-voice-cautionary
+  and NOT
+    @funindex #(set-accidental-style modern-voice-cautionary)
+

 * Preferred terms:
     - in general, use the American spellings.  The internal
       lilypond property names use this spelling.
 * Preferred terms:
     - in general, use the American spellings.  The internal
       lilypond property names use this spelling.


@@ -135,6 +186,7 @@ simultaenous    NOT concurrent
 measure: the unit of music
 bar line: the symbol delimiting a measure   NOT barline
 note head   NOT notehead
 measure: the unit of music
 bar line: the symbol delimiting a measure   NOT barline
 note head   NOT notehead

+chord construct   NOT chord (when referring to <>)

 
 
 %%%%% TECHNICAL WRITING STYLE
 
 
 %%%%% TECHNICAL WRITING STYLE