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).
  12
  13 \section{Notes and rests}
  14
  15 Rests.  Note that the dot of 8th, 16th and 32nd rests rest should be
  16 next to the top of the rest.  All rests except the whole rest are
  17 centered on the middle staff line.
  18
  19 \mudelafile{rest.fly}
  20
  21 Note head shapes are settable.  The stem endings should be adjusted
  22 per note head.  If you want different note head styles on one stem,
  23 you must create a special context called Thread.
  24
  25 \mudelafile{noteheadstyle.ly}
  26
  27 Noteheads can have dots, and ---although this is bad style--- rests
  28 can too.  Augmentation dots should never be printed on a staff line,
  29 but rather be shifted: down stem notes shift dots down, up stem up.
  30 In case of chords, all dots should be in a column.  The dots go along
  31 as  rests are shifted to avoid collisions.
  32
  33 \mudelafile{dots.fly}
  34
  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.
  39
  40 \mudelafile{multi-measure-rest.ly}
  41
  42 \section{Stems}
  43
  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.
  48
  49 \mudelafile{stem-tremolo.ly}
  50
  51 Beams, stems and noteheads often have communication troubles, since
  52 the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
  53 point) are mixed.
  54
  55 \section{Grace notes}
  56
  57 Grace notes are typeset as an encapsulated piece of music. You can
  58 have beams, notes, chords, stems etc. within a \verb|\grace| section.
  59 Slurs that start within a grace section, but aren't ended are attached
  60 to the next normal note.  Grace notes have zero duration.  If there
  61 are tuplets, the grace notes won't be under the brace.  Grace notes
  62 can have accidentals, but they are (currently) spaced at a fixed
  63 distance.
  64
  65
  66
  67 \mudelafile{grace.ly}
  68
  69
  70 \section{Beams, slurs and other spanners}
  71
  72 Beaming is generated automatically. Beams may cross bar lines. In that
  73 case, line breaks are forbidden.  Yet clef and key signatures are
  74 hidden just as with breakable bar lines.
  75
  76 \mudelafile{beaming.ly}
  77
  78 %Beams should not interfere with various items on the staff (amongst
  79 %others repeat signs)
  80 %
  81 % \mud elafile{beam-repeat.ly}
  82
  83 Beams should behave reasonably well, even under extreme circumstances.
  84 Stems may be short, but noteheads should never touch the beam.
  85
  86 \mudelafile{beam-extreme.ly}
  87
  88 Slurs should look nice and symmetric.  The curvature may increase
  89 only to avoid noteheads, and as little as possible.
  90
  91 \mudelafile{slur-symmetry.ly}
  92 \mudelafile{slur-symmetry-1.ly}
  93
  94 Ties are strictly horizontal.  They are placed in between note heads.
  95 The horizontal middle should not overlap with a staffline.
  96
  97 \mudelafile{tie.ly}
  98
  99 Beams can be typeset over fixed distance aligned staffs, beam
 100 beautification doesn't really work, but knees do. Beams should be
 101 behave well, wherever the switching point is.
 102
 103 \mudelafile{beam-interstaff.ly}
 104
 105 The same goes for slurs. They behave decently when broken across
 106 linebreak.
 107
 108 \mudelafile{slur-interstaff.ly}
 109
 110 Tuplets are indicated by a bracket with a number.  There should be no
 111 bracket if there is one beam that matches  the length of the tuplet.
 112 The bracket does not interfere with the stafflines, and the number is
 113 centered in the gap in the bracket.
 114
 115 \mudelafile{tup.ly}
 116
 117 \section{Repeats}
 118
 119 LilyPond has three modes for repeats: folded, unfolded and
 120 semi-unfolded.  Unfolded repeats are fully written out. Semi unfolded
 121 repeats have the body written and all alternatives sequentially.
 122 Folded repeats have the body written and all alternatives
 123 simultaneously.  If the number of alternatives is larger than the
 124 repeat count, the excess alternatives are ignored.  If the number of
 125 alternatives is smaller, the first alternative is multiplied to get to
 126 the number of repeats.
 127
 128 Unfolded behavior:
 129
 130 \mudelafile{repeat-unfold.ly}
 131
 132 Semi (un)folded behavior.  Voltas can start on non-barline moments.
 133 If they don't barlines should still be shown.
 134
 135 \mudelafile{repeat-semifold.ly}
 136
 137 Folded.  This doesn't make sense without alternatives, but it works.
 138
 139 \mudelafile{repeat-fold.ly}
 140
 141 \section{Multiple notes}
 142
 143 Rests should not collide with beams, stems and noteheads.  Rests may
 144 be under beams.  Rests should be move by integral number of spaces
 145 inside the staff, and by half spaces outside.  Notice that the half
 146 and whole rests just outside the staff get ledger lines in different
 147 cases.
 148
 149 \mudelafile{rest-collision.ly}
 150
 151 Normal collisions. We have support for four voice polyphony, where the
 152 middle voices are horizontally shifted in a limited number of cases.
 153
 154 \mudelafile{collisions.ly}
 155
 156 The number of stafflines of a staff can be set with the property
 157 numberOfStaffLines.  Ledger lines both on note heads and rests are
 158 adjusted.  Barlines also are adjusted.
 159
 160
 161 \mudelafile{number-staff-lines.fly}
 162
 163 \section{Spacing}
 164
 165 In a limited number of cases, LilyPond corrects for optical spacing
 166 effects.  In this example, space for opposite pointed stems is adjusted
 167
 168 \mudelafile{stem-spacing.sly}
 169
 170 \section{Global stuff}
 171
 172 Markings that are attached to (invisible) barlines are
 173 delicate: the are attached to the rest of the score without the score
 174 knowing it.  Consequently, they fall over  often.
 175
 176 \mudelafile{bar-scripts.ly}
 177
 178 Staff margins are also markings attached to barlines.  They should be
 179 left otf the staff, and be centered vertically wrt the staff.  They
 180 may be on normal staffs, but also on compound staffs, like the
 181 PianoStaff
 182
 183 \mudelafile{staff-margin.ly}
 184
 185 Breathing signs, also used for phrasing, do normally not influence
 186 global spacing -- only if space gets tight, notes are shifted to make
 187 room for the breathing sign. Breathing signs break beams running
 188 through their voice. In the following example, the notes in the first
 189 two measures all have the same distance from each other:
 190
 191 \mudelafile{breathing-sign.ly}
 192
 193
 194 \section{Clefs and Time Signatures}
 195
 196 The transparent clef should not occupy any space and with style
 197 \texttt{fullSizeChanges}, the changing clef should be typeset in full
 198 size. For octaviated clefs, the ``8'' should appear closely above or
 199 below the clef respectively.  The ``8'' is processed in a rather
 200 convoluted way, so this is fragile as well.
 201
 202 \mudelafile{clefs.ly}
 203
 204 By default, time signatures are written with two numbers. With style
 205 ``C'', 4/4 and 2/2 are written with their corresponding symbols and
 206 with style ``old'', 2/2, 3/2, 3/4, 4/4, 6/4, 9/4, 6/8 and 9/8 are
 207 typeset with symbols, all other signatures retain the default layout.
 208 The style ``1'', gives single number signatures for all signatures.
 209
 210 \mudelafile{time.fly}
 211
 212 \end{document}