1 \input texinfo @c -*-texinfo-*- vim:tw=72
2 @setfilename regression-test.info
3 @settitle LilyPond Regression test
7 @author Han-Wen Nienhuys and Jan Nieuwenhuizen
8 @title LilyPond Regression test
15 This document tries give a 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.
20 [TODO: revise and completize this. ]
22 [TODO: should generate out of header fields using ly2dvi?]
26 @section Notes and rests
28 Rests. Note that the dot of 8th, 16th and 32nd rests rest should be
29 next to the top of the rest. All rests except the whole rest are
30 centered on the middle staff line.
34 Note head shapes are settable. The stem endings should be adjusted
35 per note head. If you want different note head styles on one stem,
36 you must create a special context called Thread.
38 Harmonic notes have a different shape and different
39 dimensions. Nevertheless, noteheads in both styles can be combined, on
40 either up or down stems.
42 @mudelafile{noteheadstyle.ly}
44 Noteheads can have dots, and rests can too. Augmentation dots should
45 never be printed on a staff line, but rather be shifted vertically. They
46 should go up, but in case of multiple parts, the down stems have down
47 shifted dots. (Wanske p. 186) In case of chords, all dots should be in
48 a column. The dots go along as rests are shifted to avoid collisions.
52 Accidentals work: the second note does not get a sharp. The third and
53 fourth show forced and courtesy accidentals
55 @mudelafile{accidental.ly}
57 Multiple measure rests do not collide with barlines and clefs. They
58 are not expanded when you set @code{Score.skipBars}. Although the
59 multi-measure-rest is a Spanner, minimum distances are set to keep it
60 colliding from barlines.
63 @mudelafile{multi-measure-rest.ly}
65 If @code{Score.skipBars} is set,
66 the signs for four, two, and one measure rest are combined to
67 produce the graphical representation of rests for up to 10 bars.
68 The number of bars will be written above the sign.
70 @mudelafile{mm-rests2.ly}
72 A sharp sign after a double sharp sign, as well as a flat sign
73 after a double flat sign is automatically prepended with a
76 @mudelafile{accidental-single-double.ly}
80 Stem tremolos or rolls are tremolo signs that look like beam segments
81 crossing stems. If the stem is in a beam, the tremolo must be parallel
82 to the beam. If the stem is invisible (eg. on a whole note), the
83 tremolo must be centered on the note.
85 @mudelafile{stem-tremolo.ly}
87 Chord tremolos look like beams, but are a kind of repeat symbol.
88 To avoid confusion, chord tremolo beams do not reach the stems, but
89 leave a gap. Chord tremolo beams on half notes are not ambiguous,
90 as half notes cannot appear in a regular beam, and should reach the
93 @mudelafile{chord-tremolo.ly}
95 Beams, stems and noteheads often have communication troubles, since
96 the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
99 Stems, beams, ties and slurs should behave similarly, when placed
100 on the middle staff line. Of course stem-direction is down for high
101 notes, and up for low notes.
103 @mudelafile{stem-direction.ly}
105 Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}.
107 @mudelafile{stem-direction-down.ly}
111 The staccato dot (and all scripts with follow-into-staff set), must
112 not be on staff lines.
114 @mudelafile{staccato-pos.ly}
116 Dynamics appear below or above the staff. If multiple dynamics are
117 linked with (de)crescendi, they should be on the same line.
119 @mudelafile{dyn-line.ly}
122 Arpeggios are supported, both cross-staff and one-staff.
124 @mudelafile{arpeggio.ly}
130 Chord names are generated from a list pitches, and are customisable
131 from guile. For some unlogical names, guile customisation is used
134 @mudelafile{chord-names.ly}
138 Grace notes are typeset as an encapsulated piece of music. You can
139 have beams, notes, chords, stems etc. within a @code{\grace} section.
140 Slurs that start within a grace section, but aren't ended are attached
141 to the next normal note. Grace notes have zero duration. If there
142 are tuplets, the grace notes won't be under the brace. Grace notes
143 can have accidentals, but they are (currently) spaced at a fixed
144 distance. Grace notes (of course) come before the accidentals of the
145 main note. Grace notes can also be positioned after the main note.
147 Grace notes without beams should have a slash, if @code{flagStyle} is
148 not set. Main note scripts don't end up on the grace note.
150 @mudelafile{grace.ly}
152 @section Beams, slurs and other spanners
154 Beaming is generated automatically. Beams may cross bar lines. In that
155 case, line breaks are forbidden. Yet clef and key signatures are
156 hidden just as with breakable bar lines.
158 @mudelafile{beaming.ly}
160 Beams should behave reasonably well, even under extreme circumstances.
161 Stems may be short, but noteheads should never touch the beam.
163 @mudelafile{beam-extreme.ly}
165 Beams should always reach the middle staff line. The second beam
166 counting from the note head side, should never be lower than the
167 second staff line. This does not hold for grace note beams.
168 Override with @code{noStemExtend}.
170 @mudelafile{beam-position.ly}
172 Slurs should look nice and symmetric. The curvature may increase
173 only to avoid noteheads, and as little as possible. Slurs never
174 run through noteheads or stems.
176 @mudelafile{slur-nice.ly}
177 @mudelafile{slur-symmetry.ly}
178 @mudelafile{slur-symmetry-1.ly}
180 Across line breaks, slurs behave nicely. On the left, they extend to
181 just after the preferatory matter, and on the right to the end of the
182 staff. A slur should follow the same vertical direction it would have
185 @mudelafile{slur-broken-trend.ly}
187 Ties are strictly horizontal. They are placed in between note heads.
188 The horizontal middle should not overlap with a staffline.
192 When tieing chords, the outer slurs point outwards, the inner slurs
193 point away from the center of the staff. Override with
194 @code{tieVerticalDirection}.
196 @mudelafile{tie-chord.ly}
198 When tieing notes with accidentals across a bar boundary, the accidental
199 must not be drawn on the note in the new bar. Instead, the next note of
200 the same pitch in this bar should always show the accidental (even if
201 it's natural). Slurring a accidentaled note to a natural one across bar
202 boundaries should be explicit.
204 Pitches can be verified by printing them with the @code{NoteNames} context.
206 @mudelafile{tie-accidental.ly}
208 Beams can be typeset over fixed distance aligned staffs, beam
209 beautification doesn't really work, but knees do. Beams should be
210 behave well, wherever the switching point is.
212 @mudelafile{beam-cross-staff.ly}
214 The same goes for slurs. They behave decently when broken across
217 @mudelafile{slur-cross-staff.ly}
219 Tuplets are indicated by a bracket with a number. There should be no
220 bracket if there is one beam that matches the length of the tuplet.
221 The bracket does not interfere with the stafflines, and the number is
222 centered in the gap in the bracket.
226 @section Property details
228 More specific settings take precendence over less specific settings. The
229 second slur has slurDirection set to down, overriding the stemup setting.
231 @mudelafile{generic-property-override.ly}
235 LilyPond has three modes for repeats: folded, unfolded and
236 semi-unfolded. Unfolded repeats are fully written out. Semi unfolded
237 repeats have the body written and all alternatives sequentially.
238 Folded repeats have the body written and all alternatives
239 simultaneo.ly. If the number of alternatives is larger than the
240 repeat count, the excess alternatives are ignored. If the number of
241 alternatives is smaller, the first alternative is multiplied to get to
242 the number of repeats.
246 @mudelafile{repeat-unfold.ly}
248 Volta (Semi folded) behavior. Voltas can start on non-barline moments.
249 If they don't barlines should still be shown.
251 @mudelafile{repeat-volta.ly}
253 Folded. This doesn't make sense without alternatives, but it works.
255 @mudelafile{repeat-fold.ly}
257 Across linebreaks, the left edge of a first and second alternative
258 bracket should be equal
260 @mudelafile{repeat-line-break.ly}
262 Auto change piano staff switches voices between up and down staffs
263 automatically; rests are switched along with the coming note.
265 @mudelafile{auto-change.ly}
269 Lyrics can be set to a melody automatically. Excess lyrics will be
270 dumped. Lyrics will not be set over rests. You can have melismata
271 either by setting a property melismaBusy, or by setting
272 automaticMelismas (which will set melismas during slurs and ties). If
273 you want a different order than first Music, then Lyrics, you must
274 precook a chord of staffs/lyrics and label those. Of course
275 @code{\rhythm} ignores any other rhythms in the piece. Hyphens and
276 extenders do not assume anything about lyric lengths, so they continue
279 @mudelafile{lyric-combine.ly}
283 @mudelafile{lyrics-multi-stanza.ly}
285 @section Multiple notes
287 Rests should not collide with beams, stems and noteheads. Rests may
288 be under beams. Rests should be move by integral number of spaces
289 inside the staff, and by half spaces outside. Notice that the half
290 and whole rests just outside the staff get ledger lines in different
293 @mudelafile{rest-collision.ly}
295 Normal collisions. We have support for polyphony, where the
296 middle voices are horizontally shifted.
298 @mudelafile{collisions.ly}
300 The number of stafflines of a staff can be set with the property
301 numberOfStaffLines. Ledger lines both on note heads and rests are
302 adjusted. Barlines also are adjusted.
305 @mudelafile{number-staff-lines.ly}
309 In a limited number of cases, LilyPond corrects for optical spacing
310 effects. In this example, space for opposite pointed stems is adjusted
312 @mudelafile{stem-spacing.ly}
314 If there are accidentals in the music, we add space, but the space
315 between note and accidentals is less than between the notes with the
316 same value. Clef changes also get extra space, but not as much as
319 Even if a line is very tightly spaced, there will still be room
320 between prefatory matter and the following notes. The space after the
321 prefatory is very rigid. In contrast, the space before the barline
322 must stretch like the space within the measure.
326 @mudelafile{spacing-tight.ly}
330 @mudelafile{spacing-natural.ly}
334 @mudelafile{spacing-loose.ly}
336 Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that
337 lyrics don't collide with barlines.
339 @mudelafile{lyrics-bar.ly}
341 Text is set with empty horizontal dimensions. The boolean property
342 textNonEmpty is used to respect the horizontal size of text.
344 @mudelafile{non-empty-text.ly}
353 @section Global stuff
355 Breaks can be encouraged and discouraged using @code{\break} and
356 @code{\nobreak}. They are abbrevs for @code{\penalty} commands.
358 @mudelafile{break.ly}
360 Markings that are attached to (invisible) barlines are
361 delicate: the are attached to the rest of the score without the score
362 knowing it. Consequently, they fall over often.
364 @mudelafile{bar-scripts.ly}
366 Staff margins are also markings attached to barlines. They should be
367 left of the staff, and be centered vertically wrt the staff. They may
368 be on normal staffs, but also on compound staffs, like the PianoStaff
370 @mudelafile{staff-margin.ly}
372 Breathing signs, also used for phrasing, do normally not influence
373 global spacing -- only if space gets tight, notes are shifted to make
374 room for the breathing sign. Breathing signs break beams running
375 through their voice. In the following example, the notes in the first
376 two measures all have the same distance from each other:
378 @mudelafile{breathing-sign.ly}
380 Hara kiri staffs kill themselves if they are empty. This example really
381 contains two staffs, but the second contains only spaces, and is
384 @mudelafile{hara-kiri-short.ly}
386 In orchestral scores and hymns, voices are traditionally combined onto
387 one staff. LilyPond has a part combiner, that combines or separates two
388 voices according to actual rhythm and pitch. User-defined texts such as
389 ``solo'' and ``@`a2'' are typeset automagically, as appropriate.
391 @mudelafile{part-combine.ly}
394 Fonts are available in a default set of sizes: 11, 13, 16, 20, 23 and
395 26pt staffheight. Sizes of the text fonts and symbol fonts are made
396 to match the staff dimensions.
398 @mudelafile[nonfragment]{size11.ly}
400 @mudelafile[nonfragment]{size13.ly}
402 @mudelafile[nonfragment]{size16.ly}
404 @mudelafile[nonfragment]{size20.ly}
406 @mudelafile[nonfragment]{size23.ly}
408 @mudelafile[nonfragment]{size26.ly}
411 @section Clefs and Time Signatures
413 The transparent clef should not occupy any space and with style
414 @code{fullSizeChanges}, the changing clef should be typeset in full
415 size. For octaviated clefs, the ``8'' should appear closely above or
416 below the clef respectively. The ``8'' is processed in a convoluted
417 way, so this is fragile as well.
419 @mudelafile{clefs.ly}
422 Key signatures appear on key changes. They may also
423 appear without barlines. The restoration accidentals are not printed at
424 the start of the line. If @code{createKeyOnClefChange} is set, they're
425 also created on a clef change.
433 @c the input file is too long and does not test for specific bugs
435 By default, time signatures are written with two numbers. With style
436 ``C'', 4/4 and 2/2 are written with their corresponding symbols and
437 with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and
438 9/8 are typeset with symbols, all other signatures retain the default
439 layout. The style ``1'', gives single number signatures for all
442 \mu delafile{time.ly}
447 @section Hacks and Features
449 As a last resort, the placement of items can be adjusted manually, by
450 setting the @code{extra-offset} of an output object.
452 @mudelafile{generic-output-property.ly}
454 The same mechanism can be used to force pagebreaks.
456 @mudelafile{between-systems.ly}