Documentation/tex/lilypond-regtest.doc

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