1 \input texinfo @c -*-texinfo-*- vim:tw=72
2 @setfilename regression-test.info
3 @settitle LilyPond Regression test
7 This document tries give an brief overview of LilyPond features. When
8 the text correspond with the shown notation, we consider LilyPond
9 Officially BugFree (tm). This document is intended for finding bugs,
10 and documenting bugfixes.
12 @section Notes and rests
14 Rests. Note that the dot of 8th, 16th and 32nd rests rest should be
15 next to the top of the rest. All rests except the whole rest are
16 centered on the middle staff line.
20 Note head shapes are settable. The stem endings should be adjusted
21 per note head. If you want different note head styles on one stem,
22 you must create a special context called Thread.
24 @mudelafile{noteheadstyle.ly}
26 Noteheads can have dots, and ---although this is bad style in duple
27 meters--- rests can too. Augmentation dots should never be printed on
28 a staff line, but rather be shifted vertically. They should go up, but
29 in case of multiple parts, the down stems have down shifted dots.
30 (Wanske p. 186) In case of chords, all dots should be in a column.
31 The dots go along as rests are shifted to avoid collisions.
35 Multiple measure rests do not collide with barlines and clefs. They
36 are not expanded when you set \verb+Score.SkipBars+. Although the
37 multi-measure-rest is a Spanner, minimum distances are set to keep it
38 colliding from barlines.
40 @mudelafile{multi-measure-rest.ly}
44 Stem tremolos (official naming?) or rolls are tremolo signs that look
45 like beam segments crossing stems. If the stem is in a beam, the
46 tremolo must be parallel to the beam. If the stem is invisible
47 (eg. on a whole note), the tremolo must be centered on the note.
49 @mudelafile{stem-tremolo.ly}
51 Chord tremolos look like beams, but are a kind of repeat symbol.
52 To avoid confusion, chord tremolo beams do not reach the stems, but
53 leave a gap. Chord tremolo beams on half notes are not ambiguous,
54 as half notes cannot appear in a regular beam, and should reach the
57 @mudelafile{chord-tremolo.sly}
59 Beams, stems and noteheads often have communication troubles, since
60 the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
63 Stems, beams, ties and slurs should behave similarly, when placed
64 on the middle staff line. Of course stem-direction is down for high
65 notes, and up for low notes.
67 @mudelafile{stem-direction.sly}
69 Similarly, if \verb+stem_default_neutral_direction+ is set to \verb+-1+.
71 @mudelafile{stem-direction-down.ly}
75 The staccato dot (and all scripts with follow-into-staff set), must
76 not be on staff lines.
78 @mudelafile{staccato-pos.sly}
82 Grace notes are typeset as an encapsulated piece of music. You can
83 have beams, notes, chords, stems etc. within a \verb|\grace| section.
84 Slurs that start within a grace section, but aren't ended are attached
85 to the next normal note. Grace notes have zero duration. If there
86 are tuplets, the grace notes won't be under the brace. Grace notes
87 can have accidentals, but they are (currently) spaced at a fixed
88 distance. Grace notes (of course) come before the accidentals of the
89 main note. Grace notes can also be positioned after the main note.
94 @section Beams, slurs and other spanners
96 Beaming is generated automatically. Beams may cross bar lines. In that
97 case, line breaks are forbidden. Yet clef and key signatures are
98 hidden just as with breakable bar lines.
100 @mudelafile{beaming.ly}
102 Beams should behave reasonably well, even under extreme circumstances.
103 Stems may be short, but noteheads should never touch the beam.
105 @mudelafile{beam-extreme.ly}
107 Beams should always reach the middle staff line, the second beam
108 counting from the note head side, should never be lower than the
109 second staff line. This does not hold for grace note beams.
111 @mudelafile{beam-position.sly}
113 Slurs should look nice and symmetric. The curvature may increase
114 only to avoid noteheads, and as little as possible.
116 @mudelafile{slur-symmetry.ly}
117 @mudelafile{slur-symmetry-1.ly}
119 Ties are strictly horizontal. They are placed in between note heads.
120 The horizontal middle should not overlap with a staffline.
124 Beams can be typeset over fixed distance aligned staffs, beam
125 beautification doesn't really work, but knees do. Beams should be
126 behave well, wherever the switching point is.
128 @mudelafile{beam-interstaff.ly}
130 The same goes for slurs. They behave decently when broken across
133 @mudelafile{slur-interstaff.ly}
135 Tuplets are indicated by a bracket with a number. There should be no
136 bracket if there is one beam that matches the length of the tuplet.
137 The bracket does not interfere with the stafflines, and the number is
138 centered in the gap in the bracket.
144 LilyPond has three modes for repeats: folded, unfolded and
145 semi-unfolded. Unfolded repeats are fully written out. Semi unfolded
146 repeats have the body written and all alternatives sequentially.
147 Folded repeats have the body written and all alternatives
148 simultaneously. If the number of alternatives is larger than the
149 repeat count, the excess alternatives are ignored. If the number of
150 alternatives is smaller, the first alternative is multiplied to get to
151 the number of repeats.
155 @mudelafile{repeat-unfold.ly}
157 Semi (un)folded behavior. Voltas can start on non-barline moments.
158 If they don't barlines should still be shown.
160 @mudelafile{repeat-semifold.ly}
162 Folded. This doesn't make sense without alternatives, but it works.
164 @mudelafile{repeat-fold.ly}
168 Lyrics can be set to a melody automatically. Excess lyrics will be
169 dumped. Lyrics will not be set over rests. You can have melismata
170 either by setting a property melismaBusy, or by setting
171 automaticMelismas (which will set melismas during slurs and ties). If
172 you want a different order than first Music, then Lyrics, you must
173 precook a chord of staffs/lyrics and label those. Of course
174 @code{\rhythm} ignores any other rhythms in the piece. Hyphens and
175 extenders do not assume anything about lyric lengths, so they continue
178 @mudelafile{lyric-combine.ly}
180 @section Multiple notes
182 Rests should not collide with beams, stems and noteheads. Rests may
183 be under beams. Rests should be move by integral number of spaces
184 inside the staff, and by half spaces outside. Notice that the half
185 and whole rests just outside the staff get ledger lines in different
188 @mudelafile{rest-collision.ly}
190 Normal collisions. We have support for polyphony, where the
191 middle voices are horizontally shifted.
193 @mudelafile{collisions.ly}
195 The number of stafflines of a staff can be set with the property
196 numberOfStaffLines. Ledger lines both on note heads and rests are
197 adjusted. Barlines also are adjusted.
200 @mudelafile{number-staff-lines.fly}
204 In a limited number of cases, LilyPond corrects for optical spacing
205 effects. In this example, space for opposite pointed stems is adjusted
207 @mudelafile{stem-spacing.sly}
209 If there are accidentals in the music, we add space, but the space
210 between note and accidentals is less than between the notes with the
211 same value. Clef changes also get extra space, but not as much as
215 Even if a line is very tightly spaced, there will still be room
216 between prefatory matter and the following notes. The space after the
217 prefatory is very rigid. In contrast, the space before the barline
218 must stretch like the space within the measure.
222 @mudelafile{spacing-tight.ly}
226 @mudelafile{spacing-natural.ly}
230 @mudelafile{spacing-loose.ly}
233 @section Global stuff
235 Markings that are attached to (invisible) barlines are
236 delicate: the are attached to the rest of the score without the score
237 knowing it. Consequently, they fall over often.
239 @mudelafile{bar-scripts.ly}
241 Staff margins are also markings attached to barlines. They should be
242 left of the staff, and be centered vertically wrt the staff. They may
243 be on normal staffs, but also on compound staffs, like the PianoStaff
245 @mudelafile{staff-margin.ly}
247 Breathing signs, also used for phrasing, do normally not influence
248 global spacing -- only if space gets tight, notes are shifted to make
249 room for the breathing sign. Breathing signs break beams running
250 through their voice. In the following example, the notes in the first
251 two measures all have the same distance from each other:
253 @mudelafile{breathing-sign.ly}
255 Fonts are available in a default set of sizes: 11, 13, 16, 20, 23 and
256 26pt staffheight. Sizes of the text fonts and symbol fonts are made
257 to match the staff dimensions.
259 @mudelafile[nofly]{size11.ly}
261 @mudelafile[nofly]{size13.ly}
263 @mudelafile[nofly]{size16.ly}
265 @mudelafile[nofly]{size20.ly}
267 @mudelafile[nofly]{size23.ly}
269 @mudelafile[nofly]{size26.ly}
272 @section Clefs and Time Signatures
274 The transparent clef should not occupy any space and with style
275 @code{fullSizeChanges}, the changing clef should be typeset in full
276 size. For octaviated clefs, the ``8'' should appear closely above or
277 below the clef respectively. The ``8'' is processed in a convoluted
278 way, so this is fragile as well.
280 @mudelafile{clefs.ly}
283 @c the input file is too long and does not test for specific bugs
284 By default, time signatures are written with two numbers. With style
285 ``C'', 4/4 and 2/2 are written with their corresponding symbols and
286 with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and
287 9/8 are typeset with symbols, all other signatures retain the default
288 layout. The style ``1'', gives single number signatures for all
291 \mu delafile{time.fly}