X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=2c24d26633ef8ecf24e93b022da46a3998986dcc;hb=c10e42d15b978acf35c75671b16c618215be8215;hp=fd2c895cbb6532c933278dc947640d3d7f39babc;hpb=7220607f3a1fb998d837adfa8532331f05461f70;p=lilypond.git

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index fd2c895cbb..2c24d26633 100644
--- 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:
-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
@@ -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.
 
@@ -88,22 +88,38 @@ 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}
+    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)
 
@@ -113,12 +129,28 @@ main docs
 * 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).
 
 
+%%%%% 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.
@@ -144,6 +176,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