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