1 DOCUMENTATION FORMATTING
2 ------------------------
4 The language is called texinfo; you can see its manual here:
5 http://www.gnu.org/software/texinfo/manual/texinfo/
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.
13 %%%%% SECTIONING COMMANDS
15 Most of the manual operates at the
18 level. Sections are created with
23 * Please leave two blank lines above a @node; this makes it easier
24 to find sections in texinfo.
26 * sectioning commands (@node and @section) must not appear inside
27 an @ignore. Separate those commands with a space, ie @n ode.
31 %%%%% LILYPOND FORMATTING
33 * Use two spaces for indentation in lilypond examples. (no tabs)
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"
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.
45 * Examples should end with a complete bar if possible.
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.
51 \override textscript #'padding = #3 c1^"hi"
53 \override textscript #'padding = #3
56 * LilyPond input should be produced via
57 @lilypond[verbatim,quote,ragged-right]
58 with `fragment' and `relative=2' optional.
60 Examples about page layout may alter the quote/ragged-right
61 options. Omitting `verbatim' is not allowed except for special
64 * Inspirational headwords are produced with
65 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
68 * LSR snippets are linked with
69 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
72 * Avoid long stretches of input code. Noone is going to read them
73 in print. Please create a smaller example. (the smaller
74 example does not need to be minimal, however)
76 * Specify durations for at least the first note of every bar.
78 * If possible, end with a complete bar.
80 * Comments should go on their own line, and be placed before the
81 line(s) to which they refer.
83 * Add extra spaces around { } marks; ie
84 not: \chordmode {c e g}
85 but instead: \chordmode { c e g }
87 * If you only have one bar per line, omit bar checks. If you
88 put more than one bar per line (not recommended), then include
91 * If you want to work on an example outside of the manual (for
92 easier/faster processing), use this header:
95 #(define dump-extents #t)
97 line-width = 160\mm - 2.0 * 0.4\in
99 force-assignment = #""
100 line-width = #(- line-width (* mm 3.000000))
106 You may not change any of these values. If you are making an
107 example demonstrating special \paper{} values, contact the
108 Documentation Editor.
111 %%%%% TEXT FORMATTING
113 * Lines should be less than 72 characters long. (I personally
114 recommend writing with 66-char lines, but don't bother modifying
119 * Do not use spaces at the beginning of a line (except in @example
120 or @verbatim environments), and do not use more than a single
121 space between words. `makeinfo' copies the input lines verbatim
122 without removing those spaces.
124 * Use two spaces after a period.
126 * In examples of syntax, use @var{musicexpr} for a music
129 * Don't use @rinternals{} in the main text. If you're tempted to
130 do so, you're probably getting too close to "talking through the
131 code". If you really want to refer to a context, use @code{} in
132 the main text and @rinternals{} in the @seealso.
134 * Variables or numbers which consist of a single character
135 (probably followed by a punctuation mark) should be tied
136 properly, either to the previous or the next word. Example:
138 The variable@tie{}@var{a} ...
140 * To get consistent indentation in the DVI output it is better to
141 avoid the @verbatim environment. Use the @example environment
142 instead if possible, but without extraneous indentation. For
151 should be replaced with
159 where `@example' starts the line (without leading spaces).
161 * Do not compress the input vertically; this is, do not use
163 Beginning of logical unit
167 continuation of logical unit
171 Beginning of logical unit
178 continuation of logical unit
180 This makes it easier to avoid forgetting the `@noindent'. Only
181 use @noindent if the material is discussing the same material;
182 new material should simply begin without anything special on the
185 * in @itemize use @item on a separate line like this:
193 Do not use @itemize @bullet.
195 * To get LilyPond version, use @version{} (this does not work inside
196 LilyPond snippets). If you write "@version{}" (enclosed with
197 quotes), or generally if @version{} is not followed by a space,
206 to prevent an ugly line break in PDF output.
211 @c - single line comments
212 "@c NOTE:" is a comment which should remain in the final
213 version. (gp only command ;)
214 @ignore ... @end ignore - multi-line comment
216 @cindex - General index. Please add as many as you can. Don't
217 capitalize the first word.
218 @funindex - is for a \lilycommand.
220 @example ... @end ignore - example text that should be set as a
221 blockquote. Any {} must be escaped with @{ }@
222 @itemize @item A @item B ... @end itemize - for bulleted lists.
223 Do not compress vertically like this.
225 @code{} - typeset in a tt-font. Use for actual lilypond code or
226 property/context names. If the name contains a space, wrap
227 the entire thing inside @w{@code{ }}.
228 @notation{} - refers to pieces of notation, e.g.
229 "@notation{cres.}". Also use to specific lyrics ("the
230 @notation{A - men} is centered")
231 @q{} - Single quotes. Used for `vague' terms.
232 @qq{} - Double quotes. Used for actual quotes ("he said").
234 @tie{} - Variables or numbers which consist of a single character
235 (probably followed by a punctuation mark) should be tied
236 properly, either to the previous or the next word. Example:
237 "The letter@tie{}@q{I} is skipped"
239 @var - Use for variables.
240 @warning{} - produces a "Note: " box. Use for important messages.
242 @bs - Generates a backslash inside @warning.
243 Any `\' used inside @warning (and @q or @qq) must be written as `@bs{}'
244 (texinfo would also allow \\, but this breaks with PDF output).
248 %%%%% OTHER TEXT CONCERNS
250 * References must occur at the end of a sentence, for more
251 information see @ref{the texinfo manual}. Ideally this should
252 also be the final sentence of a paragraph, but this is not
253 required. Any link in a doc section must be duplicated in the
254 @seealso section at the bottom.
256 * Introducing examples must be done with
257 . (ie finish the previous sentence/paragaph)
258 : (ie `in this example:')
259 , (ie `may add foo with the blah construct,')
260 The old "sentence runs directly into the example" method is not
263 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
267 1. To introduce lists
268 2. When beginning a quote: "So, he said,..."
269 This usage is rarer. Americans often just use a comma.
270 3. When adding a defining example at the end of a sentence.
272 * Non-ASCII characters which are in utf-8 should be directly used;
273 this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
274 all such characters appear in all output formats.