Documentation/user/writing-texinfo.txt

   1 DOCUMENTATION FORMATTING
   2 ------------------------
   3
   4 The language is called texinfo; you can see its manual here:
   5 http://www.gnu.org/software/texinfo/manual/texinfo/
   6
   7 However, you don't need to read those docs.  The most important
   8 thing to notice is that text is text.  If you see a mistake in the
   9 text, you can fix it.  If you want to change the order of
  10 something, you can cut-and-paste that stuff into a new location.
  11
  12
  13 %%%%% SECTIONING COMMANDS
  14
  15 Most of the manual operates at the
  16         @node Foo
  17         @subsubsection Foo
  18 level.  Sections are created with
  19         @node Foo
  20         @subsection Foo
  21 commands.
  22
  23 * Please leave two blank lines above a @node; this makes it easier
  24   to find sections in texinfo.
  25
  26 * sectioning commands (@node and @section) must not appear inside
  27   an @ignore.  Separate those commands with a space, ie @n ode.
  28
  29
  30
  31 %%%%% LILYPOND FORMATTING
  32
  33 * Use two spaces for indentation in lilypond examples.  (no tabs)
  34
  35 * All text strings should be prefaced with #.  LilyPond does not
  36   strictly require this, but it is helpful to get users accustomed
  37   to this scheme construct.  ie
  38     \set Staff.instrumentName = #"cello"
  39
  40 * All engravers should have double-quotes around them:
  41     \consists "Spans_arpeggio_engraver"
  42   Again, LilyPond does not strictly require this, but it is a
  43   useful standard to follow.
  44
  45 * Examples should end with a complete bar if possible.
  46
  47 * If possible, only write one bar per line.  The notes on each
  48   line should be an independent line -- tweaks should occur on
  49   their own line if possible.
  50   Bad:
  51     \override textscript #'padding = #3 c1^"hi"
  52   Good:
  53     \override textscript #'padding = #3
  54     c1^"hi"
  55
  56 * Most LilyPond input should be produced with:
  57     @lilypond[verbatim,quote,relative=2]
  58   or
  59     @lilypond[verbatim,quote,relative=1]
  60
  61   If you want to use \layout{} or define variables, use
  62     @lilypond[verbatim,quote]
  63
  64   In rare cases, other options may be used (or omitted), but ask first.
  65
  66 * Inspirational headwords are produced with
  67   @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
  68   {pitches-headword.ly}
  69
  70 * LSR snippets are linked with
  71   @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
  72   {filename.ly}
  73   excepted in Templates, where `doctitle' may be omitted.
  74
  75 * Avoid long stretches of input code.  Noone is going to read them
  76   in print.  Please create a smaller example.  (the smaller
  77   example does not need to be minimal, however)
  78
  79 * Specify durations for at least the first note of every bar.
  80
  81 * If possible, end with a complete bar.
  82
  83 * Comments should go on their own line, and be placed before the
  84   line(s) to which they refer.
  85
  86 * Add extra spaces around { } marks; ie
  87   not:          \chordmode {c e g}
  88   but instead:  \chordmode { c e g }
  89
  90 * If you only have one bar per line, omit bar checks.  If you
  91   put more than one bar per line (not recommended), then include
  92   bar checks.
  93
  94 * If you want to work on an example outside of the manual (for
  95   easier/faster processing), use this header:
  96
  97 \paper {
  98   #(define dump-extents #t)
  99   indent = 0\mm
 100   line-width = 160\mm - 2.0 * 0.4\in
 101   ragged-right = ##t
 102   force-assignment = #""
 103   line-width = #(- line-width (* mm  3.000000))
 104 }
 105
 106 \layout {
 107 }
 108
 109   You may not change any of these values.  If you are making an
 110   example demonstrating special \paper{} values, contact the
 111   Documentation Editor.
 112
 113
 114 %%%%% TEXT FORMATTING
 115
 116 * Lines should be less than 72 characters long.  (I personally
 117   recommend writing with 66-char lines, but don't bother modifying
 118   existing material.)
 119
 120 * Do not use tabs.
 121
 122 * Do not use spaces at the beginning of a line (except in @example
 123   or @verbatim environments), and do not use more than a single
 124   space between words.  `makeinfo' copies the input lines verbatim
 125   without removing those spaces.
 126
 127 * Use two spaces after a period.
 128
 129 * In examples of syntax, use @var{musicexpr} for a music
 130   expression.
 131
 132 * Don't use @rinternals{} in the main text.  If you're tempted to
 133   do so, you're probably getting too close to "talking through the
 134   code".  If you really want to refer to a context, use @code{} in
 135   the main text and @rinternals{} in the @seealso.
 136
 137 * Variables or numbers which consist of a single character
 138   (probably followed by a punctuation mark) should be tied
 139   properly, either to the previous or the next word.  Example:
 140
 141       The variable@tie{}@var{a} ...
 142
 143 * To get consistent indentation in the DVI output it is better to
 144   avoid the @verbatim environment.  Use the @example environment
 145   instead if possible, but without extraneous indentation.  For
 146   example, this
 147
 148     @example
 149       foo {
 150         bar
 151       }
 152     @end example
 153
 154   should be replaced with
 155
 156     @example
 157     foo {
 158       bar
 159     }
 160     @end example
 161
 162   where `@example' starts the line (without leading spaces).
 163
 164 * Do not compress the input vertically; this is, do not use
 165
 166     Beginning of logical unit
 167     @example
 168     ...
 169     @end example
 170     continuation of logical unit
 171
 172   but
 173
 174     Beginning of logical unit
 175
 176     @example
 177     ...
 178     @end example
 179
 180     @noindent
 181     continuation of logical unit
 182
 183   This makes it easier to avoid forgetting the `@noindent'.  Only
 184   use @noindent if the material is discussing the same material;
 185   new material should simply begin without anything special on the
 186   line above it.
 187
 188 * in @itemize use @item on a separate line like this:
 189   @itemize
 190   @item
 191   Foo
 192
 193   @item
 194   Bar
 195
 196   Do not use @itemize @bullet.
 197
 198 * To get LilyPond version, use @version{} (this does not work inside
 199   LilyPond snippets).  If you write "@version{}" (enclosed with
 200   quotes), or generally if @version{} is not followed by a space,
 201   enclose it with
 202
 203   @w{ ... }
 204
 205   e.g.
 206
 207   @w{"@version{}"}
 208
 209   to prevent an ugly line break in PDF output.
 210
 211
 212 %%%%% SYNTAX SURVEY
 213
 214 @c - single line comments
 215   "@c NOTE:" is a comment which should remain in the final
 216   version.  (gp only command ;)
 217 @ignore ... @end ignore - multi-line comment
 218
 219 @cindex - General index. Please add as many as you can.  Don't
 220   capitalize the first word.
 221 @funindex - is for a \lilycommand.
 222
 223 @example ... @end ignore - example text that should be set as a
 224   blockquote.  Any {} must be escaped with @{ }@
 225 @itemize @item A @item B ... @end itemize - for bulleted lists.
 226   Do not compress vertically like this.
 227
 228 @code{} - typeset in a tt-font. Use for actual lilypond code or
 229   property/context names.  If the name contains a space, wrap
 230   the entire thing inside @w{@code{  }}.
 231 @notation{} - refers to pieces of notation, e.g.
 232   "@notation{cres.}".  Also use to specific lyrics ("the
 233   @notation{A - men} is centered")
 234 @q{} - Single quotes. Used for `vague' terms.
 235 @qq{} - Double quotes.  Used for actual quotes ("he said") or for
 236   introducing special input modes.
 237
 238 @tie{} - Variables or numbers which consist of a single character
 239   (probably followed by a punctuation mark) should be tied
 240   properly, either to the previous or the next word.  Example:
 241     "The letter@tie{}@q{I} is skipped"
 242
 243 @var - Use for variables.
 244 @warning{} - produces a "Note: " box. Use for important messages.
 245
 246 @bs - Generates a backslash inside @warning.
 247     Any `\' used inside @warning (and @q or @qq) must be written as `@bs{}'
 248     (texinfo would also allow \\, but this breaks with PDF output).
 249
 250
 251
 252 %%%%% OTHER TEXT CONCERNS
 253
 254 * References must occur at the end of a sentence, for more
 255   information see @ref{the texinfo manual}.  Ideally this should
 256   also be the final sentence of a paragraph, but this is not
 257   required.  Any link in a doc section must be duplicated in the
 258   @seealso section at the bottom.
 259
 260 * Introducing examples must be done with
 261      . (ie finish the previous sentence/paragaph)
 262      : (ie `in this example:')
 263      , (ie `may add foo with the blah construct,')
 264   The old "sentence runs directly into the example" method is not
 265   allowed any more.
 266
 267 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 268
 269 * Colon usage
 270
 271   1. To introduce lists
 272   2. When beginning a quote: "So, he said,..."
 273      This usage is rarer.  Americans often just use a comma.
 274   3. When adding a defining example at the end of a sentence.
 275
 276 * Non-ASCII characters which are in utf-8 should be directly used;
 277   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 278   all such characters appear in all output formats.
 279