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
17 @unnumberedsubsubsec Foo
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 * If possible, only write one bar per line. The notes on each
33 line should be an independent line.
35 \override textscript #'padding = #3 c1^"hi"
37 \override textscript #'padding = #3
40 * LilyPond input should be produced via
41 @lilypond[verbatim,quote,ragged-right]
42 with `fragment' and `relative=2' optional.
44 Examples about page layout may alter the quote/ragged-right
45 options. Omitting `verbatim' is not allowed except for special
48 * Inspirational headwords are produced with
49 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
52 * LSR snippets are linked with
53 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
56 * Avoid long stretches of input code. Noone is going to read them
57 in print. Please create a smaller example. (the smaller
58 example does not need to be minimal, however)
60 * If you want to work on an example outside of the manual (for
61 easier/faster processing), use this header:
64 #(define dump-extents #t)
66 line-width = 160\mm - 2.0 * 0.4\in
68 force-assignment = #""
69 line-width = #(- line-width (* mm 3.000000))
75 You may not change any of these values. If you are making an
76 example demonstrating special \paper{} values, contact the
82 * Lines should be less than 72 characters long. (I personally
83 recommend writing with 66-char lines, but don't bother modifying
88 * Do not use spaces at the beginning of a line (except in @example
89 or @verbatim environments), and do not use more than a single
90 space between words. `makeinfo' copies the input lines verbatim
91 without removing those spaces.
93 * Use two spaces after a period.
95 * Variables or numbers which consist of a single character
96 (probably followed by a punctuation mark) should be tied
97 properly, either to the previous or the next word. Example:
99 The variable@tie{}@var{a} ...
101 * To get consistent indentation in the DVI output it is better to
102 avoid the @verbatim environment. Use the @example environment
103 instead if possible, but without extraneous indentation. For
112 should be replaced with
120 where `@example' starts the line (without leading spaces).
122 * Do not compress the input vertically; this is, do not use
124 Beginning of logical unit
128 continuation of logical unit
132 Beginning of logical unit
139 continuation of logical unit
141 This makes it easier to avoid forgetting the `@noindent'. Only
142 use @noindent if the material is discussing the same material;
143 new material should simply begin without anything special on the
146 * in @itemize use @item on a separate line like this:
154 Do not use @itemize @bullet.
159 @c - single line comments
160 @ignore ... @end ignore - multi-line comment
162 @cindex - General index. Please add as many as you can. Don't
163 capitalize the first word.
164 @funindex - is for a \lilycommand.
166 @example ... @end ignore - example text that should be set as a
167 blockquote. Any {} must be escaped with @{ }@
168 @itemize @item A @item B ... @end itemize - for bulleted lists.
169 Do not compress vertically like this.
171 @code{} - typeset in a tt-font. Use for actual lilypond code or
172 property/context names.
173 @notation{} - refers to pieces of notation, e.g.
174 "@notation{cres.}". Also use to specific lyrics ("the
175 @notation{A - men} is centered")
176 @q{} - Single quotes. Used for `vague' terms.
177 @qq{} - Double quotes. Used for actual quotes ("he said").
179 @warning{}: produces a "Note: " box. Use for important
182 @tie{} - Variables or numbers which consist of a single character
183 (probably followed by a punctuation mark) should be tied
184 properly, either to the previous or the next word. Example:
185 "The letter@tie{}@q{I} is skipped"
187 @var - Use for variables.
188 @warning{} - produces a "Note: " box.
189 Any `\' used inside this must be written as `\\'.
193 %%%%% OTHER TEXT CONCERNS
195 * References must occur at the end of a sentence, for more
196 information see @ref{the texinfo manual}. Ideally this should
197 also be the final sentence of a paragraph, but this is not
198 required. Any link in a doc section must be duplicated in the
199 @seealso section at the bottom.
201 * Introducing examples may be done with
202 . (ie finish the previous sentence/paragaph)
203 : (ie `in this example:')
204 , (ie `may add foo with the blah construct,')
206 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
210 1. To introduce lists
211 2. When beginning a quote: "So, he said,..."
212 This usage is rarer. Americans often just use a comma.
213 3. When adding a defining example at the end of a sentence.
215 * Non-ASCII characters which are in utf-8 should be directly used;
216 this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
217 all such characters appear in all output formats.
219 * Don't use a @ref{link to another section} in the middle of a
220 sentence. It looks ok in HTML, moderately bad in PDF, and
221 utterly horrible in INFO. Instead, reword the sentence so that
222 users are encouraged to see @ref{link to another section}.
223 (at the end of the sentence)