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