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