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