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 * sectioning commands (@node and @section) must not appear inside
  24   an @ignore.  Separate those commands with a space, ie @n ode.
  25
  26
  27
  28 %%%%% LILYPOND FORMATTING
  29
  30 * Use two spaces for indentation in lilypond examples.  (no tabs)
  31
  32 * All text strings should be prefaced with #.  LilyPond does not
  33   strictly require this, but it is helpful to get users accustomed
  34   to this scheme construct.  ie
  35     \set Staff.instrumentName = #"cello"
  36
  37 * Examples should end with a complete bar if possible.
  38
  39 * If possible, only write one bar per line.  The notes on each
  40   line should be an independent line -- tweaks should occur on
  41   their own line if possible.
  42   Bad:
  43     \override textscript #'padding = #3 c1^"hi"
  44   Good:
  45     \override textscript #'padding = #3
  46     c1^"hi"
  47
  48 * LilyPond input should be produced via
  49     @lilypond[verbatim,quote,ragged-right]
  50   with `fragment' and `relative=2' optional.
  51
  52   Examples about page layout may alter the quote/ragged-right
  53   options.  Omitting `verbatim' is not allowed except for special
  54   circumstances.
  55
  56 * Inspirational headwords are produced with
  57   @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
  58   {pitches-headword.ly}
  59
  60 * LSR snippets are linked with
  61   @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
  62   {filename.ly}
  63
  64 * Avoid long stretches of input code.  Noone is going to read them
  65   in print.  Please create a smaller example.  (the smaller
  66   example does not need to be minimal, however)
  67
  68 * If you want to work on an example outside of the manual (for
  69   easier/faster processing), use this header:
  70
  71 \paper {
  72   #(define dump-extents #t)
  73   indent = 0\mm
  74   line-width = 160\mm - 2.0 * 0.4\in
  75   ragged-right = ##t
  76   force-assignment = #""
  77   line-width = #(- line-width (* mm  3.000000))
  78 }
  79
  80 \layout {
  81 }
  82
  83   You may not change any of these values.  If you are making an
  84   example demonstrating special \paper{} values, contact the
  85   Documentation Editor.
  86
  87
  88 %%%%% TEXT FORMATTING
  89
  90 * Lines should be less than 72 characters long.  (I personally
  91   recommend writing with 66-char lines, but don't bother modifying
  92   existing material.)
  93
  94 * Do not use tabs.
  95
  96 * Do not use spaces at the beginning of a line (except in @example
  97   or @verbatim environments), and do not use more than a single
  98   space between words.  `makeinfo' copies the input lines verbatim
  99   without removing those spaces.
 100
 101 * Use two spaces after a period.
 102
 103 * Variables or numbers which consist of a single character
 104   (probably followed by a punctuation mark) should be tied
 105   properly, either to the previous or the next word.  Example:
 106
 107       The variable@tie{}@var{a} ...
 108
 109 * To get consistent indentation in the DVI output it is better to
 110   avoid the @verbatim environment.  Use the @example environment
 111   instead if possible, but without extraneous indentation.  For
 112   example, this
 113
 114     @example
 115       foo {
 116         bar
 117       }
 118     @end example
 119
 120   should be replaced with
 121
 122     @example
 123     foo {
 124       bar
 125     }
 126     @end example
 127
 128   where `@example' starts the line (without leading spaces).
 129
 130 * Do not compress the input vertically; this is, do not use
 131
 132     Beginning of logical unit
 133     @example
 134     ...
 135     @end example
 136     continuation of logical unit
 137
 138   but
 139
 140     Beginning of logical unit
 141
 142     @example
 143     ...
 144     @end example
 145
 146     @noindent
 147     continuation of logical unit
 148
 149   This makes it easier to avoid forgetting the `@noindent'.  Only
 150   use @noindent if the material is discussing the same material;
 151   new material should simply begin without anything special on the
 152   line above it.
 153
 154 * in @itemize use @item on a separate line like this:
 155   @itemize
 156   @item
 157   Foo
 158
 159   @item
 160   Bar
 161
 162   Do not use @itemize @bullet.
 163
 164 * To get LilyPond version, use @version{} (this does not work inside
 165   LilyPond snippets).  If you write "@version{}" (enclosed with
 166   quotes), or generally if @version{} is not followed by a space,
 167   enclose it with
 168
 169   @w{ ... }
 170
 171   e.g.
 172
 173   @w{"@version{}"}
 174
 175   to prevent an ugly line break in PDF output.
 176
 177
 178 %%%%% SYNTAX SURVEY
 179
 180 @c - single line comments
 181   "@c NOTE:" is a comment which should remain in the final
 182   version.  (gp only command ;)
 183 @ignore ... @end ignore - multi-line comment
 184
 185 @cindex - General index. Please add as many as you can.  Don't
 186   capitalize the first word.
 187 @funindex - is for a \lilycommand.
 188
 189 @example ... @end ignore - example text that should be set as a
 190   blockquote.  Any {} must be escaped with @{ }@
 191 @itemize @item A @item B ... @end itemize - for bulleted lists.
 192   Do not compress vertically like this.
 193
 194 @code{} - typeset in a tt-font. Use for actual lilypond code or
 195   property/context names.
 196 @notation{} - refers to pieces of notation, e.g.
 197   "@notation{cres.}".  Also use to specific lyrics ("the
 198   @notation{A - men} is centered")
 199 @q{} - Single quotes. Used for `vague' terms.
 200 @qq{} - Double quotes.  Used for actual quotes ("he said").
 201
 202 @warning{}: produces a "Note: " box.  Use for important
 203       messages.
 204
 205 @tie{} - Variables or numbers which consist of a single character
 206   (probably followed by a punctuation mark) should be tied
 207   properly, either to the previous or the next word.  Example:
 208     "The letter@tie{}@q{I} is skipped"
 209
 210 @var - Use for variables.
 211 @warning{} - produces a "Note: " box.
 212   Any `\' used inside this must be written as `\\'.
 213
 214
 215
 216 %%%%% OTHER TEXT CONCERNS
 217
 218 * References must occur at the end of a sentence, for more
 219   information see @ref{the texinfo manual}.  Ideally this should
 220   also be the final sentence of a paragraph, but this is not
 221   required.  Any link in a doc section must be duplicated in the
 222   @seealso section at the bottom.
 223
 224 * Introducing examples must be done with
 225      . (ie finish the previous sentence/paragaph)
 226      : (ie `in this example:')
 227      , (ie `may add foo with the blah construct,')
 228   The old "sentence runs directly into the example" method is not
 229   allowed any more.
 230
 231 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 232
 233 * Colon usage
 234
 235   1. To introduce lists
 236   2. When beginning a quote: "So, he said,..."
 237      This usage is rarer.  Americans often just use a comma.
 238   3. When adding a defining example at the end of a sentence.
 239
 240 * Non-ASCII characters which are in utf-8 should be directly used;
 241   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 242   all such characters appear in all output formats.
 243