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 with at least one link to @lsrdir{}.
  64   The order of items inside the @seealso section is
  65
  66     Music glossary: @rgloss{foo}, @rgloss{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 * @commonprop and @refbugs are optional.
  77
  78
  79 %%%%% LILYPOND FORMATTING
  80
  81 * Use two spaces for indentation in lilypond examples.  (no tabs)
  82
  83 * If possible, only write one bar per line.  The notes on each
  84   line should be an independent line.
  85   Bad:
  86     \override textscript #'padding = #3 c1^"hi"
  87   Good:
  88     \override textscript #'padding = #3
  89     c1^"hi"
  90
  91 * LilyPond input should be produce via
  92     @lilypond[verbatim,quote,ragged-right]
  93   with `fragment' and `relative=2' optional.
  94
  95   Examples about page layout may alter the quote/ragged-right
  96   options.  Omitting `verbatim' is not allowed.
  97
  98 * Inspirational headwords are produced with
  99   @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
 100   {pitches-headword.ly}
 101
 102 * Avoid long stretches of input code.  Noone is going to read them
 103   in print.  Instead refer to an example input file with @lsr{}.
 104
 105
 106 %%%%% TEXT FORMATTING
 107
 108 * Lines should be less than 72 characters long.  (I personally
 109   recommend writing with 66-char lines, but don't bother modifying
 110   existing material.)
 111
 112 * Do not use tabs.  They expand to nothing in DVI output.
 113
 114 * Do not use spaces at the beginning of a line (except in @example
 115   or @verbatim environments), and do not use more than a single
 116   space between words.  `makeinfo' copies the input lines verbatim
 117   without removing those spaces.
 118
 119 * Use two spaces after a period.
 120
 121 * Variables or numbers which consist of a single character
 122   (probably followed by a punctuation mark) should be tied
 123   properly, either to the previous or the next word.  Example:
 124
 125       The variable@tie{}@var{a} ...
 126
 127 * To get consistent indentation in the DVI output it is better to
 128   avoid the @verbatim environment.  Use the @example environment
 129   instead if possible, but without extraneous indentation.  For
 130   example, this
 131
 132     @example
 133       foo {
 134         bar
 135       }
 136     @end example
 137
 138   should be replaced with
 139
 140     @example
 141     foo {
 142       bar
 143     }
 144     @end example
 145
 146   where `@example' starts the line (without leading spaces).
 147
 148 * Do not compress the input vertically; this is, do not use
 149
 150     Beginning of logical unit
 151     @example
 152     ...
 153     @end example
 154     continuation of logical unit
 155
 156   but
 157
 158     Beginning of logical unit
 159
 160     @example
 161     ...
 162     @end example
 163
 164     @noindent
 165     continuation of logical unit
 166
 167   This makes it easier to avoid forgetting the `@noindent'.  Only
 168   use @noindent if the material is discussing the same material;
 169   new material should simply begin without anything special on the
 170   line above it.
 171
 172 * in @itemize use @item on a separate line like this:
 173   @itemize
 174   @item
 175   Foo
 176
 177   @item
 178   Bar
 179
 180   Do not use @itemize @bullet.
 181
 182 * Use @q instead of `...' and @qq instead of ``...''.  The latter macro
 183   should be used with care since we use `...' as the default quoting
 184   throughout the manual, except for things related to direct speech.
 185
 186   In most cases, you should use @code{} or @samp{} instead.
 187
 188
 189 %%%%% READABILITY
 190
 191 * Non-ASCII characters which are in utf-8 should be directly used;
 192   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 193   all such characters appear in all output formats.
 194
 195 * Don't use a @ref{link to another section} in the middle of a
 196   sentence.  It looks ok in HTML, moderately bad in PDF, and
 197   utterly horrible in INFO.  Instead, reword the sentence so that
 198   users are encouraged to see @ref{link to another section}.
 199   (at the end of the sentence)
 200
 201 * Do not forget to create @cindex entries for new sections of text.
 202   Enter commands with @funindex, i.e.
 203     @cindex pitches, writing in different octaves
 204     @funindex \relative
 205   do not bother with the @code{} (they are added automatically).  These
 206   items are added to both the command index and the unified index.
 207
 208 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 209
 210 * Colon usage
 211
 212   1. To introduce lists
 213   2. When beginning a quote: "So, he said,..."
 214      This usage is rarer.  Americans often just use a comma.
 215   3. When adding a defining example at the end of a sentence.
 216
 217
 218 %%%%% TECHNICAL WRITING STYLE
 219
 220 * Do not refer to LilyPond in the text.  The reader knows what the
 221   manual is about.  If you do, capitalization is LilyPond.
 222
 223 * If you explicitly refer to `lilypond' the program (or any other
 224   command to be executed), say `@command{lilypond}'.
 225
 226 * Do not explicitly refer to the reader/user.  There is no one
 227   else besides the reader and the writer.
 228
 229 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 230   comma after it:
 231
 232     blabla blabla, i.e., blabla blabla
 233
 234 * Avoid fluff (``Notice that,'' ``as you can see,''
 235   ``Currently,'').
 236
 237 * The use of the word `illegal' is inappropriate in most cases.
 238   Say `invalid' instead.
 239
 240
 241