Merge commit 'origin/dev/jneeman' into systems-per-page

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 481394249972e99f936dffd7f963e70e4017a89f..0460e7ad3b4bff11187deb9b2a64481f05b678b1 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -45,8 +45,9 @@ 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
 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

-mention that "dynamics (or whatever) may be placed above or below
-the staff, for details see @ref{Up and down}".
+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
 
 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


@@ -65,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.
 


@@ -79,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: @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.)
+    Snippets: @rlsr{section}.

 
 

-    Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
+    Internals Reference:
+    @rinternals{fazzle},
+    @rinternals{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.


@@ -134,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.


@@ -143,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