7 There are four parts to the documentation: the Learning Manual,
8 the Notation Reference, the Program Reference, and the Music
12 The LM is written in a tutorial style which introduces the most
13 important concepts, structure and syntax of the elements of a
14 LilyPond score in a carefully graded sequence of steps.
15 Explanations of all musical concepts used in the Manual can be
16 found in the Music Glossary, and readers are assumed to have no
17 prior knowledge of LilyPond. The objective is to take readers to
18 a level where the Notation Reference can be understood and
19 employed to both adapt the templates in the Appendix to their
20 needs and to begin to construct their own scores. Commonly used
21 tweaks are introduced and explained. Examples are provided
22 throughout which, while being focussed on the topic being
23 introduced, are long enough to seem real in order to retain the
24 readers' interest. Each example builds on the previous material,
25 and comments are used liberally. Every new aspect is thoroughly
26 explained before it is used.
28 Users are encouraged to read the complete Learning Manual from
32 * Notation Reference: a (hopefully complete) description of
33 LilyPond input notation. Some material from here may be
34 duplicated in the Learning Manual (for teaching), but consider
35 the NR to be the "definitive" description of each notation
36 element, with the LM being an "extra". The goal is _not_ to
37 provide a step-by-step learning environment -- do not avoid
38 using notation that has not be introduced previously in the
39 NR (for example, use \break if appropriate). This section is
40 written in formal technical writing style.
42 Avoid duplication. Although users are not expected to read this
43 manual from start to finish, they should be familiar with the
44 material in the Learning Manual (particularly ``Fundamental
45 Concepts''), so do not repeat that material in each section of
46 this book. Also watch out for common constructs, like ^ - _ for
47 directions -- those are explained in NR 3. In NR 1, you can
49 DYNAMICS may be manually placed above or below the
50 staff, see @ref{Controlling direction and placement}.
52 Most tweaks should be added to LSR and not placed directly in the
53 .itely file. In some cases, tweaks may be placed in the main
54 text, but ask about this first.
56 Finally, you should assume that users know what the notation
57 means; explaining musical concepts happens in the Music Glossary.
60 * Application Usage: information about using the program lilypond
61 with other programs (lilypond-book, operating systems, GUIs,
62 convert-ly, etc). This section is written in formal technical
65 Users are not expected to read this manual from start to finish.
68 * Music Glossary: information about the music notation itself.
69 Explanations and translations about notation terms go here.
71 Users are not expected to read this manual from start to finish.
73 * Internals Reference: not really a documentation book, since it
74 is automagically generated from the source, but this is its
78 %%%%% SECTION ORGANIZATION
80 The order of headings inside documentation sections should be:
88 * You _must_ include a @seealso. The order of items inside the
107 @file{path/to/dir/blahz}.
109 Snippets: @rlsr{section}.
115 If there are multiple entries, separate them by commas
116 but do not include an `and'.
118 Always end with a period.
120 Place each link on a new line as above; this makes it much
121 easier to add or remove links. In the output, they
122 appear on a single line.
124 ("Snippets" is REQUIRED; the others are optional)
126 Any new concepts or links which require an explanation should go
127 as a full sentence(s) in the main text.
129 * To create links, use @ref{} if the link is within the same
132 * @predefined is for commands in ly/*-init.ly FIXME?
134 * Do not include any real info in second-level sections (ie 1.1
135 Pitches). A first-level section may have introductory material,
136 but other than that all material goes into third-level sections
137 (ie 1.1.1 Writing Pitches).
140 %%%%% CHECKING CROSS-REFERENCES
142 Cross-references between different manuals are heavily used in the
143 documentation, but they are not checked during compilation. However,
144 if you compile the documentation, a script called check_texi_refs can
145 help you with checking and fixing these cross-references; for
146 information on usage, cd into a source tree where documentation has
147 been built, cd into Documentation and look for check-xrefs and
148 fix-xrefs targets in 'make help' output. Note that you have to find
149 yourself the source files to fix cross-references in the generated
150 documentation such as the Internals Reference; e.g. you can grep
154 %%%%% GENERAL WRITING
156 * Do not forget to create @cindex entries for new sections of text.
157 Enter commands with @funindex, i.e.
158 @cindex pitches, writing in different octaves
160 do not bother with the @code{} (they are added automatically). These
161 items are added to both the command index and the unified index.
163 Both index commands should go in front of the actual material.
165 @cindex entries should not be capitalized, ie
166 @cindex time signature
167 is preferred. (instead of `Time signature') Only use capital
168 letters for musical terms which demand them, like D.S. al Fine.
171 - in general, use the American spellings. The internal
172 lilypond property names use this spelling.
173 - list of specific terms:
175 simultaenous NOT concurrent
176 measure: the unit of music
177 bar line: the symbol delimiting a measure NOT barline
178 note head NOT notehead
179 chord construct NOT chord (when referring to <>)
182 %%%%% TECHNICAL WRITING STYLE
184 * Do not refer to LilyPond in the text. The reader knows what the
185 manual is about. If you do, capitalization is LilyPond.
187 * If you explicitly refer to `lilypond' the program (or any other
188 command to be executed), say `@command{lilypond}'.
190 * Do not explicitly refer to the reader/user. There is no one
191 else besides the reader and the writer.
193 * Do not use abbreviations (don't, won't, etc.). If you do, use a
196 blabla blabla, i.e., blabla blabla
198 * Avoid fluff (``Notice that,'' ``as you can see,''
201 * The use of the word `illegal' is inappropriate in most cases.
202 Say `invalid' instead.