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