6 There are four parts to the documentation: the Learning Manual,
7 the Notation Reference, the Program Reference, and the Music
10 * Learning Manual: long, chatty, friendly explanations go here.
11 This is aimed at users learning something for the first time --
12 not necessarily just learning lilypond notation, but also things
13 like learning how to deal with projects, tweaking, preparing parts
14 for orchestras, etc. Less formal language may be used here.
16 Users are encouraged to read the complete Learning Manual from
20 * Notation Reference: a (hopefully complete) description of
21 LilyPond input notation. Some material from here may be
22 duplicated in the Learning Manual (for teaching). The material is
23 presented in an approximate order of increasing difficulty, but
24 the goal is _not_ to provide a step-by-step learning environment.
25 For example, all material under "Pitches" should remain in that
26 section, even though microtonal accidentals may seem more advanced
27 than info about clefs or time signatures -- "Pitches" should be a
28 one-stop reference about the pitch portion of notes. This section
29 is written in formal technical writing style.
31 Users are not expected to read this manual from start to finish.
32 However, they should be familiar with the material in the Learning
33 Manual (particularly ``Fundamental Concepts''), so do not repeat
34 that material in this book. Also, you should assume that users
35 know what the notation means; explaining musical concepts happens
36 in the Music Glossary.
39 * Program Usage: information about using the program lilypond with
40 other programs (lilypond-book, operating systems, GUIs,
41 convert-ly, etc). This section is written in formal technical
44 Users are not expected to read this manual from start to finish.
47 * Music Glossary: information about the music notation itself.
48 Explainations and translations about notation terms go here.
50 Users are not expected to read this manual from start to finish.
53 %%%%% SECTION ORGANIZATION
55 The order of headings inside documentation sections should be:
62 * You must include a @seealso with at least one link to @lsrdir{}.
64 * @commonprop and @refbugs are optional.
67 %%%%% LILYPOND FORMATTING
69 * Use two spaces for indentation in lilypond examples. (no tabs)
71 * If possible, only write one bar per line. The notes on each
72 line should be an independent line.
74 \override textscript #'padding = #3 c1^"hi"
76 \override textscript #'padding = #3
79 * LilyPond input should be produce via
80 @lilypond[verbatim,quote,ragged-right]
81 with `fragment' and `relative=2' optional.
83 Examples about page layout may alter the quote/ragged-right
84 options. Omitting `verbatim' is not allowed.
86 * Inspirational headwords are produced with
87 @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
90 * Avoid long stretches of input code. Noone is going to read them
91 in print. Instead refer to an example input file with @lsr{}.
96 * Lines should be less than 72 characters long. (I personally
97 recommend writing with 66-char lines, but don't bother modifying
100 * Do not use tabs. They expand to nothing in DVI output.
102 * Do not use spaces at the beginning of a line (except in @example
103 or @verbatim environments), and do not use more than a single
104 space between words. `makeinfo' copies the input lines verbatim
105 without removing those spaces.
107 * Use two spaces after a period.
109 * Variables or numbers which consist of a single character
110 (probably followed by a punctuation mark) should be tied
111 properly, either to the previous or the next word. Example:
113 The variable@tie{}@var{a} ...
115 * To get consistent indentation in the DVI output it is better to
116 avoid the @verbatim environment. Use the @example environment
117 instead if possible, but without extraneous indentation. For
126 should be replaced with
134 where `@example' starts the line (without leading spaces).
136 * Do not compress the input vertically; this is, do not use
138 Beginning of logical unit
142 continuation of logical unit
146 Beginning of logical unit
153 continuation of logical unit
155 This makes it easier to avoid forgetting the `@noindent'.
157 * in @itemize use @item on a separate line like this:
165 Do not use @itemize @bullet.
167 * Use @q instead of `...' and @qq instead of ``...''. The latter macro
168 should be used with care since we use `...' as the default quoting
169 throughout the manual, except for things related to direct speech.
171 In most cases, you should use @code{} or @samp{} instead.
176 * Non-ASCII characters which are in utf-8 should be directly used;
177 this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
178 all such characters appear in all output formats.
180 * Don't use a @ref{link to another section} in the middle of a
181 sentence. It looks ok in HTML, moderately bad in PDF, and
182 utterly horrible in INFO. Instead, reword the sentence so that
183 users are encouraged to see @ref{link to another section}.
184 (at the end of the sentence)
186 * Do not forget to create @cindex entries for new sections of text.
187 Enter commands with @funindex, i.e.
188 @cindex pitches, writing in different octaves
190 do not bother with the @code{} (they are added automatically). These
191 items are added to both the command index and the unified index.
193 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
197 1. To introduce lists
198 2. When beginning a quote: "So, he said,..."
199 This usage is rarer. Americans often just use a comma.
200 3. When adding a defining example at the end of a sentence.
203 %%%%% TECHNICAL WRITING STYLE
205 * Do not refer to LilyPond in the text. The reader knows what the
206 manual is about. If you do, capitalization is LilyPond.
208 * If you explicitly refer to `lilypond' the program (or any other
209 command to be executed), say `@command{lilypond}'.
211 * Do not explicitly refer to the reader/user. There is no one
212 else besides the reader and the writer.
214 * Do not use abbreviations (don't, won't, etc.). If you do, use a
217 blabla blabla, i.e., blabla blabla
219 * Avoid fluff (``Notice that,'' ``as you can see,''
222 * The use of the word `illegal' is inappropriate in most cases.
223 Say `invalid' instead.
227 convert-ly -e --from=... --to=... --no-version *.itely
229 % to find the current version number,
230 grep "version \"" tutorial.itely
232 % (nobody ever remembers to update this file, so I've stopped
233 % trying to record it here)