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