Documentation/tex/lilypond-regtest.doc

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