]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/regression-test.tely
e25c9789df10e418572f65947254252ff4c8015d
[lilypond.git] / Documentation / regression-test.tely
1 \input texinfo @c -*-texinfo-*-   vim:tw=72
2 @setfilename regression-test.info
3 @settitle LilyPond Regression test
4
5 @c fool ls-latex
6 @ignore
7 @author Han-Wen Nienhuys and Jan Nieuwenhuizen
8 @title LilyPond Regression test
9 @end ignore
10
11 @node Top, , ,
12
13 @section Introduction
14
15 This document tries give an brief overview of LilyPond features.  When
16 the text correspond with the shown notation, we consider LilyPond
17 Officially BugFree (tm).  This document is intended for finding bugs,
18 and documenting bugfixes.
19
20 @section Notes and rests
21
22 Rests.  Note that the dot of 8th, 16th and 32nd rests rest should be
23 next to the top of the rest.  All rests except the whole rest are
24 centered on the middle staff line.  
25
26 @mudelafile{rest.ly}
27
28 Note head shapes are settable.  The stem endings should be adjusted
29 per note head.  If you want different note head styles on one stem,
30 you must create a special context called Thread.
31
32 Harmonic notes have a different shape and different
33 dimensions. Nevertheless, noteheads in both styles can be combined, on
34 either up or down stems.
35
36 @mudelafile{noteheadstyle.ly}
37
38 Noteheads can have dots, and rests can too.  Augmentation dots should
39 never be printed on a staff line, but rather be shifted vertically. They
40 should go up, but in case of multiple parts, the down stems have down
41 shifted dots.  (Wanske p. 186) In case of chords, all dots should be in
42 a column.  The dots go along as rests are shifted to avoid collisions.
43
44 @mudelafile{dots.ly}
45
46 Accidentals worki: the second note does not get a sharp. The third and
47 fourth show forced and courtesy accidentals
48
49 @mudelafile{accidental.ly}
50
51 Multiple measure rests do not collide with barlines and clefs.  They
52 are not expanded when you set @code{Score.skipBars}.  Although the
53 multi-measure-rest is a Spanner, minimum distances are set to keep it
54 colliding from barlines. 
55
56
57 @mudelafile{multi-measure-rest.ly}
58
59 If @code{Score.skipBars} is set,
60 the signs for four, two, and one measure rest are combined to
61 produce the graphical representation of rests for up to 10 bars.
62 The number of bars will be written above the sign.
63
64 @mudelafile{mm-rests2.ly}
65
66 A sharp sign after a double sharp sign, as well as a flat sign
67 after a double flat sign is automatically prepended with a
68 natural sign.
69
70 @mudelafile{double-single-acc.ly}
71
72 @section Stems
73
74 Stem tremolos or rolls are tremolo signs that look like beam segments
75 crossing stems.  If the stem is in a beam, the tremolo must be parallel
76 to the beam.  If the stem is invisible (eg. on a whole note), the
77 tremolo must be centered on the note.
78
79 @mudelafile{stem-tremolo.ly}
80
81 Chord tremolos look like beams, but are a kind of repeat symbol.
82 To avoid confusion, chord tremolo beams do not reach the stems, but 
83 leave a gap.  Chord tremolo beams on half notes are not ambiguous,
84 as half notes cannot appear in a regular beam, and should reach the 
85 stems.
86   
87 @mudelafile{chord-tremolo.ly}
88
89 Beams, stems and noteheads often have communication troubles, since
90 the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
91 point) are mixed.
92
93 Stems, beams, ties and slurs should behave similarly, when placed
94 on the middle staff line. Of course stem-direction is down for high
95 notes, and up for low notes.
96
97 @mudelafile{stem-direction.ly}
98
99 Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}.
100
101 @mudelafile{stem-direction-down.ly}
102
103 @section Scripts
104
105 The staccato dot (and all scripts with follow-into-staff set), must
106 not be on staff lines.
107
108 @mudelafile{staccato-pos.ly}
109
110 Dynamics appear below or above the staff.  If multiple dynamics are
111 linked with (de)crescendi, they should be on the same line.
112
113 @mudelafile{dyn-line.ly}
114
115 @section Chord names
116
117 Chord names are generated from a list pitches, and are customisable
118 from guile.  For some unlogical names, guile customisation is used
119 by default.
120
121 @mudelafile{chord-names.ly}
122
123 @section Grace notes
124
125 Grace notes are typeset as an encapsulated piece of music. You can
126 have beams, notes, chords, stems etc. within a @code{\grace} section.
127 Slurs that start within a grace section, but aren't ended are attached
128 to the next normal note.  Grace notes have zero duration.  If there
129 are tuplets, the grace notes won't be under the brace.  Grace notes
130 can have accidentals, but they are (currently) spaced at a fixed
131 distance.  Grace notes (of course) come before the accidentals of the
132 main note.  Grace notes can also be positioned after the main note.
133
134 Grace notes without beams should have a slash, if @code{flagStyle} is
135 not set.  Main note scripts don't end up on the grace note.
136
137 @mudelafile{grace.ly}
138
139 @section Beams, slurs and other spanners
140
141 Beaming is generated automatically. Beams may cross bar lines. In that
142 case, line breaks are forbidden.  Yet clef and key signatures are
143 hidden just as with breakable bar lines.
144
145 @mudelafile{beaming.ly}
146
147 Beams should behave reasonably well, even under extreme circumstances.
148 Stems may be short, but noteheads should never touch the beam.
149
150 @mudelafile{beam-extreme.ly}
151
152 Beams should always reach the middle staff line.  The second beam
153 counting from the note head side, should never be lower than the
154 second staff line.  This does not hold for grace note beams.
155 Override with @code{noStemExtend}.
156
157 @mudelafile{beam-position.ly}
158
159 Slurs should look nice and symmetric.  The curvature may increase
160 only to avoid noteheads, and as little as possible.
161
162 @mudelafile{slur-symmetry.ly}
163 @mudelafile{slur-symmetry-1.ly}
164
165 Ties are strictly horizontal.  They are placed in between note heads.
166 The horizontal middle should not overlap with a staffline.
167
168 @mudelafile{tie.ly}
169
170 When tieing chords, the outer slurs point outwards, the inner slurs
171 point away from the center of the staff.  Override with
172 @code{tieVerticalDirection}.
173
174 @mudelafile{tie-chord.ly}
175
176 When tieing notes with accidentals across a bar boundary, the accidental
177 must not be drawn on the note in the new bar.  Instead, the next note of
178 the same pitch in this bar should always show the accidental (even if
179 it's natural).  Slurring a accidentaled note to a natural one across bar
180 boundaries should be explicit.
181
182 Pitches can be verified by printing them  with the @code{NoteNames} context.
183
184 @mudelafile{tie-accidental.ly}
185
186 Beams can be typeset over fixed distance aligned staffs, beam
187 beautification doesn't really work, but knees do. Beams should be
188 behave well, wherever the switching point is.
189
190 @mudelafile{beam-cross-staff.ly}
191
192 The same goes for slurs. They behave decently when broken across
193 linebreak.
194
195 @mudelafile{slur-cross-staff.ly}
196
197 Tuplets are indicated by a bracket with a number.  There should be no
198 bracket if there is one beam that matches  the length of the tuplet.
199 The bracket does not interfere with the stafflines, and the number is
200 centered in the gap in the bracket.
201
202 @mudelafile{tup.ly}
203
204 @section Property details
205
206 More specific settings take precendence over less specific settings. The
207 second slur has slurDirection set to down, overriding the stemup  setting.
208
209 @mudelafile{generic-property-override.ly}
210
211 Paper column supports a special output property that allows you to force
212 page breaks (among others).
213
214 @mudelafile{between-systems.ly}
215
216 @section Repeats
217
218 LilyPond has three modes for repeats: folded, unfolded and
219 semi-unfolded.  Unfolded repeats are fully written out. Semi unfolded
220 repeats have the body written and all alternatives sequentially.
221 Folded repeats have the body written and all alternatives
222 simultaneo.ly.  If the number of alternatives is larger than the
223 repeat count, the excess alternatives are ignored.  If the number of
224 alternatives is smaller, the first alternative is multiplied to get to
225 the number of repeats.
226
227 Unfolded behavior:
228
229 @mudelafile{repeat-unfold.ly}
230
231 Volta (Semi folded) behavior.  Voltas can start on non-barline moments.
232 If they don't barlines should still be shown.
233
234 @mudelafile{repeat-volta.ly}
235
236 Folded.  This doesn't make sense without alternatives, but it works.
237
238 @mudelafile{repeat-fold.ly}
239
240 Across linebreaks, the left edge of a first and second alternative
241 bracket should be equal
242
243 @mudelafile{repeat-line-break.ly}
244
245
246
247 @section Lyrics
248
249 Lyrics can be set to a melody automatically.  Excess lyrics will be
250 dumped.  Lyrics will not be set over rests.  You can have melismata
251 either by setting a property melismaBusy, or by setting
252 automaticMelismas (which will set melismas during slurs and ties).  If
253 you want a different order than first Music, then Lyrics, you must
254 precook a chord of staffs/lyrics and label those.  Of course
255 @code{\rhythm} ignores any other rhythms in the piece.  Hyphens and
256 extenders do not assume anything about lyric lengths, so they continue
257 to work.
258
259 @mudelafile{lyric-combine.ly}
260
261 @section Multiple notes
262
263 Rests should not collide with beams, stems and noteheads.  Rests may
264 be under beams.  Rests should be move by integral number of spaces
265 inside the staff, and by half spaces outside.  Notice that the half
266 and whole rests just outside the staff get ledger lines in different
267 cases.
268
269 @mudelafile{rest-collision.ly}
270
271 Normal collisions. We have support for polyphony, where the
272 middle voices are horizontally shifted.
273
274 @mudelafile{collisions.ly}
275
276 The number of stafflines of a staff can be set with the property
277 numberOfStaffLines.  Ledger lines both on note heads and rests are
278 adjusted.  Barlines also are adjusted.
279
280
281 @mudelafile{number-staff-lines.ly}
282
283 @section Spacing
284
285 In a limited number of cases, LilyPond corrects for optical spacing
286 effects.  In this example, space for opposite pointed stems is adjusted
287
288 @mudelafile{stem-spacing.ly}
289
290 If there are accidentals in the music, we add space, but the space
291 between note and accidentals is less than between the notes with the
292 same value.  Clef changes also get extra space, but not as much as
293 barlines.
294
295
296 Even if a line is very tightly spaced, there will still be room
297 between prefatory matter and the following notes.  The space after the
298 prefatory is very rigid.  In contrast, the space before the barline
299 must stretch like the space within the measure.
300
301 Tight:
302
303 @mudelafile{spacing-tight.ly}
304
305 Natural:
306
307 @mudelafile{spacing-natural.ly}
308
309 Loose:
310
311 @mudelafile{spacing-loose.ly}
312
313 Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that
314 lyrics don't collide with barlines.
315
316 @mudelafile{lyrics-bar.ly}
317
318 @section Global stuff
319
320 Breaks can be encouraged and discouraged using @code{\break} and
321 @code{\nobreak}.  They are abbrevs for @code{\penalty} commands.
322
323 @mudelafile{break.ly}
324
325
326 Markings that are attached to (invisible) barlines are 
327 delicate: the are attached to the rest of the score without the score
328 knowing it.  Consequently, they fall over  often.
329
330 @mudelafile{bar-scripts.ly}
331
332 Staff margins are also markings attached to barlines.  They should be
333 left of the staff, and be centered vertically wrt the staff.  They may
334 be on normal staffs, but also on compound staffs, like the PianoStaff
335
336 @mudelafile{staff-margin.ly}
337
338 Breathing signs, also used for phrasing, do normally not influence
339 global spacing -- only if space gets tight, notes are shifted to make
340 room for the breathing sign. Breathing signs break beams running
341 through their voice. In the following example, the notes in the first
342 two measures all have the same distance from each other:
343
344 @mudelafile{breathing-sign.ly}
345
346 Hara kiri staffs kill themselves if they are empty.  This example really
347 contains two staffs, but the second contains only spaces, and is
348 therefore removed. 
349
350 @mudelafile{hara-kiri-short.ly}
351
352
353 Fonts are  available in a default set of sizes: 11, 13, 16, 20, 23 and
354 26pt staffheight.  Sizes of the text fonts and symbol fonts are made
355 to match the staff dimensions.    
356
357 @mudelafile[nofly]{size11.ly}
358
359 @mudelafile[nofly]{size13.ly}
360
361 @mudelafile[nofly]{size16.ly}
362
363 @mudelafile[nofly]{size20.ly}
364
365 @mudelafile[nofly]{size23.ly}
366
367 @mudelafile[nofly]{size26.ly}
368
369
370 @section Clefs and Time Signatures
371
372 The transparent clef should not occupy any space and with style
373 @code{fullSizeChanges}, the changing clef should be typeset in full
374 size. For octaviated clefs, the ``8'' should appear closely above or
375 below the clef respectively.  The ``8'' is processed in a convoluted
376 way, so this is fragile as well.
377
378 @mudelafile{clefs.ly}
379
380
381 Key signatures appear on key  changes. They may also
382 appear without barlines.  The restoration accidentals are not printed at
383 the start of the line. If @code{createKeyOnClefChange} is set, they're
384 also created on a clef change.
385
386 @mudelafile{keys.ly}
387
388 @ignore
389 @c the input file is too long and does not test for specific bugs
390
391 By default, time signatures are written with two numbers. With style
392 ``C'', 4/4 and 2/2 are written with their corresponding symbols and
393 with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and
394 9/8 are typeset with symbols, all other signatures retain the default
395 layout. The style ``1'', gives single number signatures for all
396 signatures. 
397 %
398 \mu delafile{time.ly}
399 @end ignore
400
401
402
403 @section Hacks and Features
404
405 As a last resort, the placement of items can be adjusted manually, by
406 setting the @code{extra-offset} of an output object.
407
408 @mudelafile{generic-output-property.ly}
409
410 @bye
411