4 Current version of the manual: 2.11.10 ?
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). The
25 material is presented in an approximate order of increasing
26 difficulty, but the goal is _not_ to provide a step-by-step
27 learning environment. For example, all material under
28 "Notes" should remain in that section, even though microtonal
29 accidentals may seem more advanced than info about clefs or
30 time signatures -- "Notes" should be a one-stop reference
31 about, well, notes. This section is written in formal
32 technical writing style.
34 * Technical Details contains information about using
35 the program lilypond with other programs (lilypond-book,
36 operating systems, GUIs, convert-ly, etc). This section
37 is writtin in formal technical writing style.
43 * Do not forget to create @cindex entries for new sections of text.
44 Enter commands with @funindex, i.e.
46 do not bother with the @code{} (they are added automatically). These
47 items are added to both the command index and the unified index.
49 * The use of the word `illegal' is inappropriate in most cases. Say
52 * Avoid long stretches of input code. Noone is going to read them in
53 print. Instead refer to an example input file (@inputfileref), these
54 are clickable in HTML.
56 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
60 0. Do not use a colon to introduce examples, sentences just continue
62 in the display material.
65 2. When beginning a quote: "So, he said,..."
66 This usage is rarer. Americans often just use a comma.
67 3. When adding a defining example at the end of a sentence.
69 * To produce good looking texinfo output (for both TTY and DVI) some
70 additional formatting rules should be followed.
72 . Do not use tabs. They expand to nothing in DVI output.
74 . Do not use spaces at the beginning of a line (except in @example
75 or @verbatim environments), and do not use more than a single space
76 between words. `makeinfo' copies the input lines verbatim without
77 removing those spaces.
79 . Use two spaces after a priod.
81 . Variables or numbers which consist of a single character (probably
82 followed by a punctuation mark) should be tied properly, either to
83 the previous or the next word. Example:
85 The variable@tie{}@var{a} ...
87 . To get consistent indentation in the DVI output it is better to avoid
88 the @verbatim environment. Use the @example environment instead if
89 possible, but without extraneous indentation. For example, this
97 should be replaced with
105 where `@example' starts the line (without leading spaces).
107 . Use the `quote' option in @lilypond commands if possible.
109 . Do not compress the input vertically; this is, do not use
111 Beginning of logical unit
115 continuation of logical unit
119 Beginning of logical unit
126 continuation of logical unit
128 This makes it easier to not forget `@noindent'.
130 . Non-ASCII characters which are in utf-8 should be directly used;
131 this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
132 all such characters appear in all output formats.
134 * Lines should be less than 80 characters long.
136 * Use @q instead of `...' and @qq instead of ``...''. The latter macro
137 should be used with care since we use `...' as the default quoting
138 throughout the manual, except for things related to direct speech.
142 HINTS FOR TECHNICAL WRITING STYLE
144 * Do not refer to LilyPond in the text. The reader knows what the
145 manual is about. If you do, capitalization is LilyPond.
147 * If you explicitly refer to `lilypond', the program (or any other
148 command to be executed), say `@command{lilypond}'.
150 * Do not explicitly refer to the reader/user. There is no one else
151 besides the reader and the writer.
153 * Do not use abbreviations (don't, won't, etc.). If you do, use a
156 blabla blabla, i.e., blabla blabla
158 * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').