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