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 * sectioning commands (@node and @section) must not appear inside
24 an @ignore. Separate those commands with a space, ie @n ode.
28 %%%%% LILYPOND FORMATTING
30 * Use two spaces for indentation in lilypond examples. (no tabs)
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"
37 * Examples should end with a complete bar if possible.
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.
43 \override textscript #'padding = #3 c1^"hi"
45 \override textscript #'padding = #3
48 * LilyPond input should be produced via
49 @lilypond[verbatim,quote,ragged-right]
50 with `fragment' and `relative=2' optional.
52 Examples about page layout may alter the quote/ragged-right
53 options. Omitting `verbatim' is not allowed except for special
56 * Inspirational headwords are produced with
57 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
60 * LSR snippets are linked with
61 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
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)
68 * If you want to work on an example outside of the manual (for
69 easier/faster processing), use this header:
72 #(define dump-extents #t)
74 line-width = 160\mm - 2.0 * 0.4\in
76 force-assignment = #""
77 line-width = #(- line-width (* mm 3.000000))
83 You may not change any of these values. If you are making an
84 example demonstrating special \paper{} values, contact the
90 * Lines should be less than 72 characters long. (I personally
91 recommend writing with 66-char lines, but don't bother modifying
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.
101 * Use two spaces after a period.
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:
107 The variable@tie{}@var{a} ...
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
120 should be replaced with
128 where `@example' starts the line (without leading spaces).
130 * Do not compress the input vertically; this is, do not use
132 Beginning of logical unit
136 continuation of logical unit
140 Beginning of logical unit
147 continuation of logical unit
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
154 * in @itemize use @item on a separate line like this:
162 Do not use @itemize @bullet.
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,
175 to prevent an ugly line break in PDF output.
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
185 @cindex - General index. Please add as many as you can. Don't
186 capitalize the first word.
187 @funindex - is for a \lilycommand.
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.
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").
202 @warning{}: produces a "Note: " box. Use for important
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"
210 @var - Use for variables.
211 @warning{} - produces a "Note: " box.
212 Any `\' used inside this must be written as `\\'.
216 %%%%% OTHER TEXT CONCERNS
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.
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
231 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
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.
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.