]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/policy.txt
Update policy.
[lilypond.git] / Documentation / user / policy.txt
1 DOCUMENTATION POLICY
2 --------------------
3
4
5 %%%%% BOOKS
6
7 There are four parts to the documentation: the Learning Manual,
8 the Notation Reference, the Program Reference, and the Music
9 Glossary.
10
11 * Learning Manual: long, chatty, friendly explanations go here.
12   This is aimed at users learning something for the first time --
13   not necessarily just learning lilypond notation, but also things
14   like learning how to deal with projects, tweaking, preparing parts
15   for orchestras, etc.  Less formal language may be used here.
16
17 Users are encouraged to read the complete Learning Manual from
18 start-to-finish.
19
20
21 * Notation Reference: a (hopefully complete) description of
22   LilyPond input notation.  Some material from here may be
23   duplicated in the Learning Manual (for teaching).  The material is
24   presented in an approximate order of increasing difficulty, but
25   the goal is _not_ to provide a step-by-step learning environment.
26   For example, all material under "Pitches" should remain in that
27   section, even though microtonal accidentals may seem more advanced
28   than info about clefs or time signatures -- "Pitches" should be a
29   one-stop reference about the pitch portion of notes.  This section
30   is written in formal technical writing style.
31
32 Users are not expected to read this manual from start to finish.
33 However, they should be familiar with the material in the Learning
34 Manual (particularly ``Fundamental Concepts''), so do not repeat
35 that material in this book.  Also, you should assume that users
36 know what the notation means; explaining musical concepts happens
37 in the Music Glossary.
38
39
40 * Program Usage: information about using the program lilypond with
41   other programs (lilypond-book, operating systems, GUIs,
42   convert-ly, etc).  This section is written in formal technical
43   writing style.
44
45 Users are not expected to read this manual from start to finish.
46
47
48 * Music Glossary: information about the music notation itself.
49   Explainations and translations about notation terms go here.
50
51 Users are not expected to read this manual from start to finish.
52
53
54 %%%%% SECTION ORGANIZATION
55
56 The order of headings inside documentation sections should be:
57
58 main docs
59 @commonprop
60 @seealso
61 @refbugs
62
63 * You _must_ include a @seealso.  The order of items inside the
64   @seealso section is
65
66     Music glossary: @rgloss{foo}, @rgloss{bar}.
67
68     User manual: @ref{baz}, @ref{foozle}.
69
70     Snippets: @lsrdir{section}.
71
72     Program reference: @internalsref{fazzle}, @internalsref{booar}.
73
74   ("Snippets" is REQUIRED; the others are optional)
75
76 * @commonprop and @refbugs are optional.
77
78
79 %%%%% LILYPOND FORMATTING
80
81 * Use two spaces for indentation in lilypond examples.  (no tabs)
82
83 * If possible, only write one bar per line.  The notes on each
84   line should be an independent line.
85   Bad:
86     \override textscript #'padding = #3 c1^"hi"
87   Good:
88     \override textscript #'padding = #3
89     c1^"hi"
90
91 * LilyPond input should be produce via
92     @lilypond[verbatim,quote,ragged-right]
93   with `fragment' and `relative=2' optional.
94
95   Examples about page layout may alter the quote/ragged-right
96   options.  Omitting `verbatim' is not allowed.
97
98 * Inspirational headwords are produced with
99   @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
100   {pitches-headword.ly}
101
102 * Avoid long stretches of input code.  Noone is going to read them
103   in print.  Instead refer to an example input file with @lsr{}.
104
105
106 %%%%% TEXT FORMATTING
107
108 * Lines should be less than 72 characters long.  (I personally
109   recommend writing with 66-char lines, but don't bother modifying
110   existing material.)
111
112 * Do not use tabs.  They expand to nothing in DVI output.
113
114 * Do not use spaces at the beginning of a line (except in @example
115   or @verbatim environments), and do not use more than a single
116   space between words.  `makeinfo' copies the input lines verbatim
117   without removing those spaces.
118
119 * Use two spaces after a period.
120
121 * Variables or numbers which consist of a single character
122   (probably followed by a punctuation mark) should be tied
123   properly, either to the previous or the next word.  Example:
124
125       The variable@tie{}@var{a} ...
126
127 * To get consistent indentation in the DVI output it is better to
128   avoid the @verbatim environment.  Use the @example environment
129   instead if possible, but without extraneous indentation.  For
130   example, this
131
132     @example
133       foo {
134         bar
135       }
136     @end example
137
138   should be replaced with
139
140     @example
141     foo {
142       bar
143     }
144     @end example
145
146   where `@example' starts the line (without leading spaces).
147
148 * Do not compress the input vertically; this is, do not use
149
150     Beginning of logical unit
151     @example
152     ...
153     @end example
154     continuation of logical unit
155
156   but
157
158     Beginning of logical unit
159
160     @example
161     ...
162     @end example
163
164     @noindent
165     continuation of logical unit
166
167   This makes it easier to avoid forgetting the `@noindent'.  Only
168   use @noindent if the material is discussing the same material;
169   new material should simply begin without anything special on the
170   line above it.
171
172 * in @itemize use @item on a separate line like this:
173   @itemize
174   @item
175   Foo
176
177   @item
178   Bar
179
180   Do not use @itemize @bullet.
181
182 * Specially-marked text:
183
184     @code{}: actual lilypond code or property/context names.
185     @samp{}: ditto, for single-letter code.
186         @notation{}: refers to pieces of notation, such as
187           "@notation{crescendo} is often abbreviated as
188       @notation{cresc.}"  This should also be used to refer to
189       specific lyrics ("the @notation{A - men} is centered...")
190         @q{}: used for `vague' terms in English (and other natural
191       languages).
192         @qq{}: only for actual quotes -- i.e. "he said" or "she
193       wrote".
194
195 * @warning{} produces a "Note: " box.  Use for important messages.
196
197
198 %%%%% READABILITY
199
200 * Non-ASCII characters which are in utf-8 should be directly used;
201   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
202   all such characters appear in all output formats.
203
204 * Don't use a @ref{link to another section} in the middle of a
205   sentence.  It looks ok in HTML, moderately bad in PDF, and
206   utterly horrible in INFO.  Instead, reword the sentence so that
207   users are encouraged to see @ref{link to another section}.
208   (at the end of the sentence)
209
210 * Do not forget to create @cindex entries for new sections of text.
211   Enter commands with @funindex, i.e.
212     @cindex pitches, writing in different octaves
213     @funindex \relative
214   do not bother with the @code{} (they are added automatically).  These
215   items are added to both the command index and the unified index.
216
217 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
218
219 * Colon usage
220
221   1. To introduce lists
222   2. When beginning a quote: "So, he said,..."
223      This usage is rarer.  Americans often just use a comma.
224   3. When adding a defining example at the end of a sentence.
225
226
227 %%%%% TECHNICAL WRITING STYLE
228
229 * Do not refer to LilyPond in the text.  The reader knows what the
230   manual is about.  If you do, capitalization is LilyPond.
231
232 * If you explicitly refer to `lilypond' the program (or any other
233   command to be executed), say `@command{lilypond}'.
234
235 * Do not explicitly refer to the reader/user.  There is no one
236   else besides the reader and the writer.
237
238 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
239   comma after it:
240
241     blabla blabla, i.e., blabla blabla
242
243 * Avoid fluff (``Notice that,'' ``as you can see,''
244   ``Currently,'').
245
246 * The use of the word `illegal' is inappropriate in most cases.
247   Say `invalid' instead.
248
249
250