Move "new dynamic marks" into expressive.

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

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index bb377d392147511373a37572c7c489733ef3554a..4dac1c28f5fdd89f1752dbda586cb458f205792d 100644 (file)
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -8,11 +8,22 @@ There are four parts to the documentation: the Learning Manual,
 the Notation Reference, the Program Reference, and the Music
 Glossary.
 
 the Notation Reference, the Program Reference, and the Music
 Glossary.
 

-* Learning Manual: long, chatty, friendly explanations go here.
-  This is aimed at users learning something for the first time --
-  not necessarily just learning lilypond notation, but also things
-  like learning how to deal with projects, tweaking, preparing parts
-  for orchestras, etc.  Less formal language may be used here.
+* Learning Manual:
+  The LM is written in a tutorial style which introduces the most
+  important concepts, structure and syntax of the elements of a
+  LilyPond score in a carefully graded sequence of steps.
+  Explanations of all musical concepts used in the Manual can be
+  found in the Music Glossary, and readers are assumed to have no
+  prior knowledge of LilyPond.  The objective is to take readers to
+  a level where the Notation Reference can be understood and
+  employed to both adapt the templates in the Appendix to their
+  needs and to begin to construct their own scores.  Commonly used
+  tweaks are introduced and explained.  Examples are provided
+  throughout which, while being focussed on the topic being
+  introduced, are long enough to seem real in order to retain the
+  readers' interest.  Each example builds on the previous material,
+  and comments are used liberally.  Every new aspect is thoroughly
+  explained before it is used.

 
 Users are encouraged to read the complete Learning Manual from
 start-to-finish.
 
 Users are encouraged to read the complete Learning Manual from
 start-to-finish.


@@ -20,25 +31,34 @@ 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 this book.  Also, you should assume that users
-know what the notation means; explaining musical concepts happens
-in the Music Glossary.
-
-
-* Program Usage: information about using the program lilypond with
-  other programs (lilypond-book, operating systems, GUIs,
+  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
+  with other programs (lilypond-book, operating systems, GUIs,

   convert-ly, etc).  This section is written in formal technical
   writing style.
 
   convert-ly, etc).  This section is written in formal technical
   writing style.
 


@@ -50,187 +70,74 @@ Users are not expected to read this manual from start to finish.
 
 Users are not expected to read this manual from start to finish.
 
 
 Users are not expected to read this manual from start to finish.
 

+* Internals Reference: not really a documentation book, since it
+  is automagically generated from the source, but this is its
+  name.
+

 
 %%%%% SECTION ORGANIZATION
 
 The order of headings inside documentation sections should be:
 
 main docs
 
 %%%%% SECTION ORGANIZATION
 
 The order of headings inside documentation sections should be:
 
 main docs

-@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: @rgloss{foo}, @rgloss{bar}.
-
-    User manual: @ref{baz}, @ref{foozle}.
-
-    Snippets: @lsrdir{section}.
-
-    Program reference: @internalsref{fazzle}, @internalsref{booar}.
-
-  ("Snippets" is REQUIRED; the others are optional)
-
-* @commonprop and @refbugs are optional.
-
-
-%%%%% LILYPOND FORMATTING
-
-* Use two spaces for indentation in lilypond examples.  (no tabs)
-
-* If possible, only write one bar per line.  The notes on each
-  line should be an independent line.
-  Bad:
-    \override textscript #'padding = #3 c1^"hi"
-  Good:
-    \override textscript #'padding = #3
-    c1^"hi"
-
-* LilyPond input should be produce via
-    @lilypond[verbatim,quote,ragged-right]
-  with `fragment' and `relative=2' optional.
-
-  Examples about page layout may alter the quote/ragged-right
-  options.  Omitting `verbatim' is not allowed.
-
-* Inspirational headwords are produced with
-  @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
-  {pitches-headword.ly}
-
-* Avoid long stretches of input code.  Noone is going to read them
-  in print.  Instead refer to an example input file with @lsr{}.
-
-* If you want to work on an example outside of the manual (for
-  easier/faster processing), use this header:
-
-\paper {
-  #(define dump-extents #t)
-  indent = 0\mm
-  line-width = 160\mm - 2.0 * 0.4\in
-  ragged-right = ##t
-  force-assignment = #""
-  line-width = #(- line-width (* mm  3.000000))
-}
-
-\layout {
-}
+    Music Glossary:
+    @rglos{foo},
+    @rglos{bar}.

 
 

-  You may not change any of these values.  If you are making an
-  example demonstrating special \paper{} values, contact the
-  Documentation Editor.
+    Learning Manual:
+    @rlearning{baz},
+    @rlearning{foozle}

 
 

+    Notation Reference:
+    @ruser{faazle},
+    @ruser{boo}.

 
 

-%%%%% TEXT FORMATTING
+    Application Usage:
+    @rprogram{blah}.

 
 

-* Lines should be less than 72 characters long.  (I personally
-  recommend writing with 66-char lines, but don't bother modifying
-  existing material.)
+    Installed Files:
+    @file{path/to/dir/blahz}.

 
 

-* Do not use tabs.  They expand to nothing in DVI output.
+    Snippets:
+    @lsrdir{section},
+    @lsr{specific/example-name.ly}.

 
 

-* Do not use spaces at the beginning of a line (except in @example
-  or @verbatim environments), and do not use more than a single
-  space between words.  `makeinfo' copies the input lines verbatim
-  without removing those spaces.
+    Internals Reference:
+    @internalsref{fazzle},
+    @internalsref{booar}.

 
 

-* Use two spaces after a period.
+      If there are multiple entries, separate them by commas
+      but do not include an `and'.

 
 

-* Variables or numbers which consist of a single character
-  (probably followed by a punctuation mark) should be tied
-  properly, either to the previous or the next word.  Example:
+      Always end with a period.

 
 

-      The variable@tie{}@var{a} ...
+      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.

 
 

-* To get consistent indentation in the DVI output it is better to
-  avoid the @verbatim environment.  Use the @example environment
-  instead if possible, but without extraneous indentation.  For
-  example, this
-
-    @example
-      foo {
-        bar
-      }
-    @end example
-
-  should be replaced with
-
-    @example
-    foo {
-      bar
-    }
-    @end example
-
-  where `@example' starts the line (without leading spaces).
-
-* Do not compress the input vertically; this is, do not use
-
-    Beginning of logical unit
-    @example
-    ...
-    @end example
-    continuation of logical unit
-
-  but
-
-    Beginning of logical unit
-
-    @example
-    ...
-    @end example
-
-    @noindent
-    continuation of logical unit
-
-  This makes it easier to avoid forgetting the `@noindent'.  Only
-  use @noindent if the material is discussing the same material;
-  new material should simply begin without anything special on the
-  line above it.
-
-* in @itemize use @item on a separate line like this:
-  @itemize
-  @item
-  Foo
-
-  @item
-  Bar
-
-  Do not use @itemize @bullet.
-
-* Specially-marked text:
-
-    @code{}: actual lilypond code or property/context names.
-    @samp{}: ditto, for single-letter code.
-
-
-      ** Any `\' used inside the commands below must be       **
-      ** written as `\\'.  Even if they are inside a @code{}. **
-            ( this should only affect @warning{} )
+  ("Snippets" is REQUIRED; the others are optional)

 
 

-       @notation{}: refers to pieces of notation, such as
-         "@notation{crescendo} is often abbreviated as
-      @notation{cresc.}"  This should also be used to refer to
-      specific lyrics ("the @notation{A - men} is centered...")
-       @q{}: used for `vague' terms in English (and other natural
-      languages).
-       @qq{}: only for actual quotes -- i.e. "he said" or "she
-      wrote".
-       @warning{}: produces a "Note: " box.  Use for important
-      messages.
+  Any new concepts or links which require an explanation should go
+  as a full sentence(s) in the main text.

 
 

+* To create links, use @ref{} if the link is within the same
+  manual.

 
 

-%%%%% READABILITY
+* 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).

 
 

-* Non-ASCII characters which are in utf-8 should be directly used;
-  this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
-  all such characters appear in all output formats.

 
 

-* Don't use a @ref{link to another section} in the middle of a
-  sentence.  It looks ok in HTML, moderately bad in PDF, and
-  utterly horrible in INFO.  Instead, reword the sentence so that
-  users are encouraged to see @ref{link to another section}.
-  (at the end of the sentence)
+%%%%% GENERAL WRITING

 
 * Do not forget to create @cindex entries for new sections of text.
   Enter commands with @funindex, i.e.
 
 * Do not forget to create @cindex entries for new sections of text.
   Enter commands with @funindex, i.e.


@@ -239,14 +146,22 @@ main docs
   do not bother with the @code{} (they are added automatically).  These
   items are added to both the command index and the unified index.
 
   do not bother with the @code{} (they are added automatically).  These
   items are added to both the command index and the unified index.
 

-* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
-
-* Colon usage
-
-  1. To introduce lists
-  2. When beginning a quote: "So, he said,..."
-     This usage is rarer.  Americans often just use a comma.
-  3. When adding a defining example at the end of a sentence.
+  Both index commands should go in front of the actual material.
+
+  @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.
+
+* Preferred terms:
+    - in general, use the American spellings.  The internal
+      lilypond property names use this spelling.
+    - list of specific terms:
+canceled
+simultaenous    NOT concurrent
+measure: the unit of music
+bar line: the symbol delimiting a measure   NOT barline
+note head   NOT notehead

 
 
 %%%%% TECHNICAL WRITING STYLE
 
 
 %%%%% TECHNICAL WRITING STYLE