X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=b4436a9085837cbb2c6a948fd9415b62165dcff0;hb=04b234b0dac3cb94cc0e291544ff7090903ad440;hp=aa496271841baf71837efca0c89f7ee71b07be88;hpb=b567811cb0fa5a805aabb9e8fb903763c13e8c29;p=lilypond.git

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index aa49627184..b4436a9085 100644
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -66,7 +66,7 @@ Users are not expected to read this manual from start to finish.
 
 
 * 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.
 
@@ -94,7 +94,7 @@ main docs
 
     Learning Manual:
     @rlearning{baz},
-    @rlearning{foozle}
+    @rlearning{foozle}.
 
     Notation Reference:
     @ruser{faazle},
@@ -106,13 +106,11 @@ main docs
     Installed Files:
     @file{path/to/dir/blahz}.
 
-    Snippets:
-    @lsrdir{section},
-    @lsr{specific/example-name.ly}.
+    Snippets: @rlsr{section}.
 
     Internals Reference:
-    @internalsref{fazzle},
-    @internalsref{booar}.
+    @rinternals{fazzle},
+    @rinternals{booar}.
 
       If there are multiple entries, separate them by commas
       but do not include an `and'.
@@ -131,7 +129,7 @@ main docs
 * To create links, use @ref{} if the link is within the same
   manual.
 
-* @predefined  is for commands in ly/property-init.ly
+* @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,
@@ -139,6 +137,20 @@ main docs
   (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.
@@ -155,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.
 
+  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.
@@ -164,6 +181,7 @@ simultaenous    NOT concurrent
 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