Doc-de: update of editorial and linkage

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 4f0367fd8d7d3c277e60afb81aae2877ffc0bcbe..b4436a9085837cbb2c6a948fd9415b62165dcff0 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,30 +80,46 @@ 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
+@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)
 
 
   ("Snippets" is REQUIRED; the others are optional)
 


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


@@ -121,7 +162,15 @@ main docs
 
   Both index commands should go in front of the actual material.
 
 
   Both index commands should go in front of the actual material.
 

-  @cindex should not be capitalized.
+  @cindex entries should not be capitalized, ie
+    @cindex time signature
+  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
 
 * Preferred terms:
     - in general, use the American spellings.  The internal


@@ -130,8 +179,9 @@ main docs
 canceled
 simultaenous    NOT concurrent
 measure: the unit of music
 canceled
 simultaenous    NOT concurrent
 measure: the unit of music

-bar line: the symbol delimiting a measure
-
+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