Documentation/user/policy.txt

   1 DOCUMENTATION POLICY
   2 --------------------
   3
   4
   5 %%%%% BOOKS
   6
   7 There are four parts to the documentation: the Learning Manual,
   8 the Notation Reference, the Program Reference, and the Music
   9 Glossary.
  10
  11 * Learning Manual: long, chatty, friendly explanations go here.
  12   This is aimed at users learning something for the first time --
  13   not necessarily just learning lilypond notation, but also things
  14   like learning how to deal with projects, tweaking, preparing parts
  15   for orchestras, etc.  Less formal language may be used here.
  16
  17 Users are encouraged to read the complete Learning Manual from
  18 start-to-finish.
  19
  20
  21 * Notation Reference: a (hopefully complete) description of
  22   LilyPond input notation.  Some material from here may be
  23   duplicated in the Learning Manual (for teaching).  The material is
  24   presented in an approximate order of increasing difficulty, but
  25   the goal is _not_ to provide a step-by-step learning environment.
  26   For example, all material under "Pitches" should remain in that
  27   section, even though microtonal accidentals may seem more advanced
  28   than info about clefs or time signatures -- "Pitches" should be a
  29   one-stop reference about the pitch portion of notes.  This section
  30   is written in formal technical writing style.
  31
  32 Users are not expected to read this manual from start to finish.
  33 However, they should be familiar with the material in the Learning
  34 Manual (particularly ``Fundamental Concepts''), so do not repeat
  35 that material in this book.  Also, you should assume that users
  36 know what the notation means; explaining musical concepts happens
  37 in the Music Glossary.
  38
  39
  40 * Program Usage: information about using the program lilypond with
  41   other programs (lilypond-book, operating systems, GUIs,
  42   convert-ly, etc).  This section is written in formal technical
  43   writing style.
  44
  45 Users are not expected to read this manual from start to finish.
  46
  47
  48 * Music Glossary: information about the music notation itself.
  49   Explainations and translations about notation terms go here.
  50
  51 Users are not expected to read this manual from start to finish.
  52
  53
  54 %%%%% SECTION ORGANIZATION
  55
  56 The order of headings inside documentation sections should be:
  57
  58 main docs
  59 @commonprop
  60 @seealso
  61 @refbugs
  62
  63 * You _must_ include a @seealso.  The order of items inside the
  64   @seealso section is
  65
  66     Music glossary: @rglos{foo}, @rglos{bar}.
  67
  68     User manual: @ref{baz}, @ref{foozle}.
  69
  70     Snippets: @lsrdir{section}.
  71
  72     Program reference: @internalsref{fazzle}, @internalsref{booar}.
  73
  74   ("Snippets" is REQUIRED; the others are optional)
  75
  76 * To create links, use @ref{} if the link is within the same
  77   manual.  If you are linking to another manual (say,
  78   learning->glossary or user->program usage), then use:
  79     @rlearning{}
  80     @ruser{}
  81     @rprogram{}
  82     @rglos{}
  83     @internalsref{}
  84
  85 * @commonprop and @refbugs are optional.
  86
  87
  88 %%%%% LILYPOND FORMATTING
  89
  90 * Use two spaces for indentation in lilypond examples.  (no tabs)
  91
  92 * If possible, only write one bar per line.  The notes on each
  93   line should be an independent line.
  94   Bad:
  95     \override textscript #'padding = #3 c1^"hi"
  96   Good:
  97     \override textscript #'padding = #3
  98     c1^"hi"
  99
 100 * LilyPond input should be produce via
 101     @lilypond[verbatim,quote,ragged-right]
 102   with `fragment' and `relative=2' optional.
 103
 104   Examples about page layout may alter the quote/ragged-right
 105   options.  Omitting `verbatim' is not allowed.
 106
 107 * Inspirational headwords are produced with
 108   @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
 109   {pitches-headword.ly}
 110
 111 * Avoid long stretches of input code.  Noone is going to read them
 112   in print.  Instead refer to an example input file with @lsr{}.
 113
 114 * If you want to work on an example outside of the manual (for
 115   easier/faster processing), use this header:
 116
 117 \paper {
 118   #(define dump-extents #t)
 119   indent = 0\mm
 120   line-width = 160\mm - 2.0 * 0.4\in
 121   ragged-right = ##t
 122   force-assignment = #""
 123   line-width = #(- line-width (* mm  3.000000))
 124 }
 125
 126 \layout {
 127 }
 128
 129   You may not change any of these values.  If you are making an
 130   example demonstrating special \paper{} values, contact the
 131   Documentation Editor.
 132
 133
 134 %%%%% TEXT FORMATTING
 135
 136 * Lines should be less than 72 characters long.  (I personally
 137   recommend writing with 66-char lines, but don't bother modifying
 138   existing material.)
 139
 140 * Do not use tabs.  They expand to nothing in DVI output.
 141
 142 * Do not use spaces at the beginning of a line (except in @example
 143   or @verbatim environments), and do not use more than a single
 144   space between words.  `makeinfo' copies the input lines verbatim
 145   without removing those spaces.
 146
 147 * Use two spaces after a period.
 148
 149 * Variables or numbers which consist of a single character
 150   (probably followed by a punctuation mark) should be tied
 151   properly, either to the previous or the next word.  Example:
 152
 153       The variable@tie{}@var{a} ...
 154
 155 * To get consistent indentation in the DVI output it is better to
 156   avoid the @verbatim environment.  Use the @example environment
 157   instead if possible, but without extraneous indentation.  For
 158   example, this
 159
 160     @example
 161       foo {
 162         bar
 163       }
 164     @end example
 165
 166   should be replaced with
 167
 168     @example
 169     foo {
 170       bar
 171     }
 172     @end example
 173
 174   where `@example' starts the line (without leading spaces).
 175
 176 * Do not compress the input vertically; this is, do not use
 177
 178     Beginning of logical unit
 179     @example
 180     ...
 181     @end example
 182     continuation of logical unit
 183
 184   but
 185
 186     Beginning of logical unit
 187
 188     @example
 189     ...
 190     @end example
 191
 192     @noindent
 193     continuation of logical unit
 194
 195   This makes it easier to avoid forgetting the `@noindent'.  Only
 196   use @noindent if the material is discussing the same material;
 197   new material should simply begin without anything special on the
 198   line above it.
 199
 200 * in @itemize use @item on a separate line like this:
 201   @itemize
 202   @item
 203   Foo
 204
 205   @item
 206   Bar
 207
 208   Do not use @itemize @bullet.
 209
 210 * Specially-marked text:
 211
 212     @code{}: actual lilypond code or property/context names.
 213     @samp{}: ditto, for single-letter code.
 214
 215
 216       ** Any `\' used inside the commands below must be       **
 217       ** written as `\\'.  Even if they are inside a @code{}. **
 218             ( this should only affect @warning{} )
 219
 220         @notation{}: refers to pieces of notation, such as
 221           "@notation{crescendo} is often abbreviated as
 222       @notation{cresc.}"  This should also be used to refer to
 223       specific lyrics ("the @notation{A - men} is centered...")
 224         @q{}: used for `vague' terms in English (and other natural
 225       languages).
 226         @qq{}: only for actual quotes -- i.e. "he said" or "she
 227       wrote".
 228         @warning{}: produces a "Note: " box.  Use for important
 229       messages.
 230
 231
 232 %%%%% READABILITY
 233
 234 * Non-ASCII characters which are in utf-8 should be directly used;
 235   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 236   all such characters appear in all output formats.
 237
 238 * Don't use a @ref{link to another section} in the middle of a
 239   sentence.  It looks ok in HTML, moderately bad in PDF, and
 240   utterly horrible in INFO.  Instead, reword the sentence so that
 241   users are encouraged to see @ref{link to another section}.
 242   (at the end of the sentence)
 243
 244 * Do not forget to create @cindex entries for new sections of text.
 245   Enter commands with @funindex, i.e.
 246     @cindex pitches, writing in different octaves
 247     @funindex \relative
 248   do not bother with the @code{} (they are added automatically).  These
 249   items are added to both the command index and the unified index.
 250
 251 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 252
 253 * Colon usage
 254
 255   1. To introduce lists
 256   2. When beginning a quote: "So, he said,..."
 257      This usage is rarer.  Americans often just use a comma.
 258   3. When adding a defining example at the end of a sentence.
 259
 260
 261 %%%%% TECHNICAL WRITING STYLE
 262
 263 * Do not refer to LilyPond in the text.  The reader knows what the
 264   manual is about.  If you do, capitalization is LilyPond.
 265
 266 * If you explicitly refer to `lilypond' the program (or any other
 267   command to be executed), say `@command{lilypond}'.
 268
 269 * Do not explicitly refer to the reader/user.  There is no one
 270   else besides the reader and the writer.
 271
 272 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 273   comma after it:
 274
 275     blabla blabla, i.e., blabla blabla
 276
 277 * Avoid fluff (``Notice that,'' ``as you can see,''
 278   ``Currently,'').
 279
 280 * The use of the word `illegal' is inappropriate in most cases.
 281   Say `invalid' instead.
 282
 283
 284