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). The material is
35 presented in an approximate order of increasing difficulty, but
36 the goal is _not_ to provide a step-by-step learning environment.
37 For example, all material under "Pitches" should remain in that
38 section, even though microtonal accidentals may seem more advanced
39 than info about clefs or time signatures -- "Pitches" should be a
40 one-stop reference about the pitch portion of notes. This section
41 is written in formal technical writing style.
43 Users are not expected to read this manual from start to finish.
44 However, they should be familiar with the material in the Learning
45 Manual (particularly ``Fundamental Concepts''), so do not repeat
46 that material in each section of this book. Also, you should
47 assume that users know what the notation means; explaining musical
48 concepts happens in the Music Glossary.
51 * Application Usage: information about using the program lilypond
52 with other programs (lilypond-book, operating systems, GUIs,
53 convert-ly, etc). This section is written in formal technical
56 Users are not expected to read this manual from start to finish.
59 * Music Glossary: information about the music notation itself.
60 Explainations and translations about notation terms go here.
62 Users are not expected to read this manual from start to finish.
64 * Internals Reference: not really a documentation book, since it
65 is automagically generated from the source, but this is its
69 %%%%% SECTION ORGANIZATION
71 The order of headings inside documentation sections should be:
79 * You _must_ include a @seealso. The order of items inside the
82 Music Glossary: @rglos{foo}, @rglos{bar}.
84 Learning Manual: @rlearning{baz}, @rlearning{foozle}
86 Notation Reference: @ruser{faazle}, @ruser{boo}.
88 Application Usage: @rprogram{blah}.
90 Installed Files: @file{path/to/dir/blahz}.
92 Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
93 (if there is only one entry, omit a final period. If there
94 are multiple entries, separate them by commas, do not
95 include an `and', and end with a period.)
97 Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
99 ("Snippets" is REQUIRED; the others are optional)
101 Any new concepts or links which require an explanation should go
102 as a full sentence(s) in the main text.
104 * To create links, use @ref{} if the link is within the same
107 * Do not include any real info in second-level sections (ie 1.1
108 Pitches). A first-level section may have introductory material,
109 but other than that all material goes into third-level sections
110 (ie 1.1.1 Writing Pitches).
113 %%%%% GENERAL WRITING
115 * Do not forget to create @cindex entries for new sections of text.
116 Enter commands with @funindex, i.e.
117 @cindex pitches, writing in different octaves
119 do not bother with the @code{} (they are added automatically). These
120 items are added to both the command index and the unified index.
122 Both index commands should go in front of the actual material.
124 @cindex entries should not be capitalized, ie
125 @cindex time signature
126 is preferred. (instead of `Time signature') Only use capital
127 letters for musical terms which demand them, like D.S. al Fine.
130 - in general, use the American spellings. The internal
131 lilypond property names use this spelling.
132 - list of specific terms:
134 simultaenous NOT concurrent
135 measure: the unit of music
136 bar line: the symbol delimiting a measure NOT barline
137 note head NOT notehead
140 %%%%% TECHNICAL WRITING STYLE
142 * Do not refer to LilyPond in the text. The reader knows what the
143 manual is about. If you do, capitalization is LilyPond.
145 * If you explicitly refer to `lilypond' the program (or any other
146 command to be executed), say `@command{lilypond}'.
148 * Do not explicitly refer to the reader/user. There is no one
149 else besides the reader and the writer.
151 * Do not use abbreviations (don't, won't, etc.). If you do, use a
154 blabla blabla, i.e., blabla blabla
156 * Avoid fluff (``Notice that,'' ``as you can see,''
159 * The use of the word `illegal' is inappropriate in most cases.
160 Say `invalid' instead.