4 Current version of the manual: 2.8.0
5 *** Please update this whenever you run convert-ly on the docs.
7 convert-ly --from=... --to=... --no-version *.itely
12 There are three parts to the documentation: the Learning Manual,
13 the Notation Reference, and the Technical Details.
15 * Long, wordy, chatty explanations go in the Learning Manual.
16 This is aimed at users learning something for the first
17 time -- not necessarily just learning lilypond notation, but
18 also things like learning how to deal with projects, tweaking,
19 preparing parts for orchestras, etc. Less formal language
22 * Notation Reference is a (hopefully complete) description of
23 LilyPond input notation. Some material from here may be
24 duplicated in the Learning Manual (for teaching). This
25 section is written in formal technical writing style.
27 * Technical Details contains information about using
28 the program lilypond with other programs (lilypond-book,
29 operating systems, GUIs, convert-ly, etc). This section
30 is writtin in formal technical writing style.
36 * Do not forget to create @cindex entries for new sections of text.
38 * The use of the word `illegal' is inappropriate in most cases. Say
41 * Avoid long stretches of input code. Noone is going to read them in
42 print. Instead refer to an example input file (@inputfileref), these
43 are clickable in HTML.
45 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
49 0. Do not use a colon to introduce examples, sentences just continue
51 in the display material.
54 2. When beginning a quote: "So, he said,..."
55 This usage is rarer. Americans often just use a comma.
56 3. When adding a defining example at the end of a sentence.
58 * To produce good looking texinfo output (for both TTY and DVI) some
59 additional formatting rules should be followed.
61 . Do not use tabs. They expand to nothing in DVI output.
63 . Do not use spaces at the beginning of a line (except in @example
64 or @verbatim environments), and do not use more than a single space
65 between words. `makeinfo' copies the input lines verbatim without
66 removing those spaces.
68 . Use two spaces after a priod.
70 . Variables or numbers which consist of a single character (probably
71 followed by a punctuation mark) should be tied properly, either to
72 the previous or the next word. Example:
74 The variable@tie{}@var{a} ...
76 . To get consistent indentation in the DVI output it is better to avoid
77 the @verbatim environment. Use the @example environment instead if
78 possible, but without extraneous indentation. For example, this
86 should be replaced with
94 where `@example' starts the line (without leading spaces).
96 . Use the `quote' option in @lilypond commands if possible.
98 . Do not compress the input vertically; this is, do not use
100 Beginning of logical unit
104 continuation of logical unit
108 Beginning of logical unit
115 continuation of logical unit
117 This makes it easier to not forget `@noindent'.
119 . Non-ASCII characters which are in utf-8 should be directly used;
120 this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
121 all such characters appear in all output formats.
123 * Lines should be less than 80 characters long.
127 HINTS FOR TECHNICAL WRITING STYLE
129 * Do not refer to LilyPond in the text. The reader knows what the
130 manual is about. If you do, capitalization is LilyPond.
132 * If you explicitly refer to `lilypond', the program (or any other
133 command to be executed), say `@command{lilypond}'.
135 * Do not explicitly refer to the reader/user. There is no one else
136 besides the reader and the writer.
138 * Do not use abbreviations (don't, won't, etc.). If you do, use a
141 blabla blabla, i.e., blabla blabla
143 * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').