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: @rgloss{foo}, @rgloss{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 * @commonprop and @refbugs are optional.
  77
  78
  79 %%%%% LILYPOND FORMATTING
  80
  81 * Use two spaces for indentation in lilypond examples.  (no tabs)
  82
  83 * If possible, only write one bar per line.  The notes on each
  84   line should be an independent line.
  85   Bad:
  86     \override textscript #'padding = #3 c1^"hi"
  87   Good:
  88     \override textscript #'padding = #3
  89     c1^"hi"
  90
  91 * LilyPond input should be produce via
  92     @lilypond[verbatim,quote,ragged-right]
  93   with `fragment' and `relative=2' optional.
  94
  95   Examples about page layout may alter the quote/ragged-right
  96   options.  Omitting `verbatim' is not allowed.
  97
  98 * Inspirational headwords are produced with
  99   @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
 100   {pitches-headword.ly}
 101
 102 * Avoid long stretches of input code.  Noone is going to read them
 103   in print.  Instead refer to an example input file with @lsr{}.
 104
 105 * If you want to work on an example outside of the manual (for
 106   easier/faster processing), use this header:
 107
 108 \paper {
 109   #(define dump-extents #t)
 110   indent = 0\mm
 111   line-width = 160\mm - 2.0 * 0.4\in
 112   ragged-right = ##t
 113   force-assignment = #""
 114   line-width = #(- line-width (* mm  3.000000))
 115 }
 116
 117 \layout {
 118 }
 119
 120   You may not change any of these values.  If you are making an
 121   example demonstrating special \paper{} values, contact the
 122   Documentation Editor.
 123
 124
 125 %%%%% TEXT FORMATTING
 126
 127 * Lines should be less than 72 characters long.  (I personally
 128   recommend writing with 66-char lines, but don't bother modifying
 129   existing material.)
 130
 131 * Do not use tabs.  They expand to nothing in DVI output.
 132
 133 * Do not use spaces at the beginning of a line (except in @example
 134   or @verbatim environments), and do not use more than a single
 135   space between words.  `makeinfo' copies the input lines verbatim
 136   without removing those spaces.
 137
 138 * Use two spaces after a period.
 139
 140 * Variables or numbers which consist of a single character
 141   (probably followed by a punctuation mark) should be tied
 142   properly, either to the previous or the next word.  Example:
 143
 144       The variable@tie{}@var{a} ...
 145
 146 * To get consistent indentation in the DVI output it is better to
 147   avoid the @verbatim environment.  Use the @example environment
 148   instead if possible, but without extraneous indentation.  For
 149   example, this
 150
 151     @example
 152       foo {
 153         bar
 154       }
 155     @end example
 156
 157   should be replaced with
 158
 159     @example
 160     foo {
 161       bar
 162     }
 163     @end example
 164
 165   where `@example' starts the line (without leading spaces).
 166
 167 * Do not compress the input vertically; this is, do not use
 168
 169     Beginning of logical unit
 170     @example
 171     ...
 172     @end example
 173     continuation of logical unit
 174
 175   but
 176
 177     Beginning of logical unit
 178
 179     @example
 180     ...
 181     @end example
 182
 183     @noindent
 184     continuation of logical unit
 185
 186   This makes it easier to avoid forgetting the `@noindent'.  Only
 187   use @noindent if the material is discussing the same material;
 188   new material should simply begin without anything special on the
 189   line above it.
 190
 191 * in @itemize use @item on a separate line like this:
 192   @itemize
 193   @item
 194   Foo
 195
 196   @item
 197   Bar
 198
 199   Do not use @itemize @bullet.
 200
 201 * Specially-marked text:
 202
 203     @code{}: actual lilypond code or property/context names.
 204     @samp{}: ditto, for single-letter code.
 205
 206
 207       ** Any `\' used inside the commands below must be       **
 208       ** written as `\\'.  Even if they are inside a @code{}. **
 209             ( this should only affect @warning{} )
 210
 211         @notation{}: refers to pieces of notation, such as
 212           "@notation{crescendo} is often abbreviated as
 213       @notation{cresc.}"  This should also be used to refer to
 214       specific lyrics ("the @notation{A - men} is centered...")
 215         @q{}: used for `vague' terms in English (and other natural
 216       languages).
 217         @qq{}: only for actual quotes -- i.e. "he said" or "she
 218       wrote".
 219         @warning{}: produces a "Note: " box.  Use for important
 220       messages.
 221
 222
 223 %%%%% READABILITY
 224
 225 * Non-ASCII characters which are in utf-8 should be directly used;
 226   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 227   all such characters appear in all output formats.
 228
 229 * Don't use a @ref{link to another section} in the middle of a
 230   sentence.  It looks ok in HTML, moderately bad in PDF, and
 231   utterly horrible in INFO.  Instead, reword the sentence so that
 232   users are encouraged to see @ref{link to another section}.
 233   (at the end of the sentence)
 234
 235 * Do not forget to create @cindex entries for new sections of text.
 236   Enter commands with @funindex, i.e.
 237     @cindex pitches, writing in different octaves
 238     @funindex \relative
 239   do not bother with the @code{} (they are added automatically).  These
 240   items are added to both the command index and the unified index.
 241
 242 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 243
 244 * Colon usage
 245
 246   1. To introduce lists
 247   2. When beginning a quote: "So, he said,..."
 248      This usage is rarer.  Americans often just use a comma.
 249   3. When adding a defining example at the end of a sentence.
 250
 251
 252 %%%%% TECHNICAL WRITING STYLE
 253
 254 * Do not refer to LilyPond in the text.  The reader knows what the
 255   manual is about.  If you do, capitalization is LilyPond.
 256
 257 * If you explicitly refer to `lilypond' the program (or any other
 258   command to be executed), say `@command{lilypond}'.
 259
 260 * Do not explicitly refer to the reader/user.  There is no one
 261   else besides the reader and the writer.
 262
 263 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 264   comma after it:
 265
 266     blabla blabla, i.e., blabla blabla
 267
 268 * Avoid fluff (``Notice that,'' ``as you can see,''
 269   ``Currently,'').
 270
 271 * The use of the word `illegal' is inappropriate in most cases.
 272   Say `invalid' instead.
 273
 274
 275