Indentation nit: use 4 instead of 8 spaces.

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index fd2c895cbb6532c933278dc947640d3d7f39babc..b4436a9085837cbb2c6a948fd9415b62165dcff0 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -46,8 +46,8 @@ 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:
 this book.  Also watch out for common constructs, like ^ - _ for
 directions -- those are explained in NR 3.  In NR 1, you can
 write:

-Dynamics (or whatever) may be manually placed above or below the
-staff, for details see @ref{Controlling direction and placement}".
+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


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


@@ -88,22 +88,38 @@ main docs
 * 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)
 
 
   ("Snippets" is REQUIRED; the others are optional)
 


@@ -113,12 +129,28 @@ main docs
 * 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  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.


@@ -135,6 +167,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.


@@ -144,6 +181,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