[lilypond.git] / Documentation / tex / lilypond-regtest.doc

% -*-LaTeX-*-  vim:tw=72
\documentclass{article}

\title{LilyPond feature test}
\author{Han-Wen Nienhuys}
\begin{document}
\maketitle

This document tries give an brief overview of LilyPond features.  When
the text correspond with the shown notation, we consider LilyPond
Officially BugFree (tm).  This document is intended for finding bugs,
and documenting bugfixes.

\section{Notes and rests} 

Rests.  Note that the dot of 8th, 16th and 32nd rests rest should be
next to the top of the rest.  All rests except the whole rest are
centered on the middle staff line.  

\mudelafile{rest.fly}

Note head shapes are settable.  The stem endings should be adjusted
per note head.  If you want different note head styles on one stem,
you must create a special context called Thread.

\mudelafile{noteheadstyle.ly}

Noteheads can have dots, and ---although this is bad style in duple
meters--- rests can too.  Augmentation dots should never be printed on
a staff line, but rather be shifted: down stem notes shift dots down,
up stem up.  In case of chords, all dots should be in a column.  The
dots go along as rests are shifted to avoid collisions.

\mudelafile{dots.fly}

Multiple measure rests do not collide with barlines and clefs.  They
are not expanded when you set \verb+Score.SkipBars+.  Although the
multi-measure-rest is a Spanner, minimum distances are set to keep it
colliding from barlines. 

\mudelafile{multi-measure-rest.ly}

\section{Stems}

Stem tremolos (official naming?) or rolls are tremolo signs that look
like beam segments crossing stems.  If the stem is in a beam, the
tremolo must be parallel to the beam.  If the stem is invisible
(eg. on a whole note), the tremolo must be centered on the note.

\mudelafile{stem-tremolo.ly}

Chord tremolos look like beams, but are a kind of repeat symbol.
To avoid confusion, chord tremolo beams do not reach the stems, but 
leave a gap.  Chord tremolo beams on half notes are not ambiguous,
as half notes cannot appear in a regular beam, and should reach the 
stems.
  
\mudelafile{chord-tremolo.sly}

Beams, stems and noteheads often have communication troubles, since
the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
point) are mixed.

Stems, beams, ties and slurs should behave similarly, when placed
on the middle staff line. Of course stem-direction is down for high
notes, and up for low notes.

\mudelafile{stem-direction.sly}

Similarly, if \verb+stem_default_neutral_direction+ is set to \verb+-1+.

\mudelafile{stem-direction-down.ly}

\section{Grace notes}

Grace notes are typeset as an encapsulated piece of music. You can
have beams, notes, chords, stems etc. within a \verb|\grace| section.
Slurs that start within a grace section, but aren't ended are attached
to the next normal note.  Grace notes have zero duration.  If there
are tuplets, the grace notes won't be under the brace.  Grace notes
can have accidentals, but they are (currently) spaced at a fixed
distance.  Grace notes (of course) come before the accidentals of the
main note.  Grace notes can also be positioned after the main note.

\mudelafile{grace.ly}


\section{Beams, slurs and other spanners}

Beaming is generated automatically. Beams may cross bar lines. In that
case, line breaks are forbidden.  Yet clef and key signatures are
hidden just as with breakable bar lines.

\mudelafile{beaming.ly}

%Beams should not interfere with various items on the staff (amongst
%others repeat signs)
%
% \mud elafile{beam-repeat.ly}

Beams should behave reasonably well, even under extreme circumstances.
Stems may be short, but noteheads should never touch the beam.

\mudelafile{beam-extreme.ly}

Beams should always reach the middle staff line, the second beam
counting from the note head side, should never be lower than the
second staff line.  This does not hold for grace note beams.

\mudelafile{beam-position.sly}

Slurs should look nice and symmetric.  The curvature may increase
only to avoid noteheads, and as little as possible.

\mudelafile{slur-symmetry.ly}
\mudelafile{slur-symmetry-1.ly}

Ties are strictly horizontal.  They are placed in between note heads.
The horizontal middle should not overlap with a staffline.

\mudelafile{tie.ly}

Beams can be typeset over fixed distance aligned staffs, beam
beautification doesn't really work, but knees do. Beams should be
behave well, wherever the switching point is.

\mudelafile{beam-interstaff.ly}

The same goes for slurs. They behave decently when broken across
linebreak.

\mudelafile{slur-interstaff.ly}

Tuplets are indicated by a bracket with a number.  There should be no
bracket if there is one beam that matches  the length of the tuplet.
The bracket does not interfere with the stafflines, and the number is
centered in the gap in the bracket.

\mudelafile{tup.ly}

\section{Repeats}

LilyPond has three modes for repeats: folded, unfolded and
semi-unfolded.  Unfolded repeats are fully written out. Semi unfolded
repeats have the body written and all alternatives sequentially.
Folded repeats have the body written and all alternatives
simultaneously.  If the number of alternatives is larger than the
repeat count, the excess alternatives are ignored.  If the number of
alternatives is smaller, the first alternative is multiplied to get to
the number of repeats.

Unfolded behavior:

\mudelafile{repeat-unfold.ly}

Semi (un)folded behavior.  Voltas can start on non-barline moments.
If they don't barlines should still be shown.

\mudelafile{repeat-semifold.ly}

Folded.  This doesn't make sense without alternatives, but it works.

\mudelafile{repeat-fold.ly}

\section{Lyrics}

Lyrics can be set to a melody automatically.  Excess lyrics will be
dumped.  Lyrics will not be set over rests.  You can have melismata
either by setting a property melismaBusy, or by setting
automaticMelismas (which will set melismas during slurs and ties).  If
you want a different order than first Music, then Lyrics, you must
precook a chord of staffs/lyrics and label those.  Of course
\verb+\rhythm+ ignores any other rhythms in the piece.  Hyphens and
extenders do not assume anything about lyric lengths, so they continue
to work.

\mudelafile{lyric-combine.ly}

\section{Multiple notes}

Rests should not collide with beams, stems and noteheads.  Rests may
be under beams.  Rests should be move by integral number of spaces
inside the staff, and by half spaces outside.  Notice that the half
and whole rests just outside the staff get ledger lines in different
cases.

% \m udelafile{rest-collision.ly}

Normal collisions. We have support for four voice polyphony, where the
middle voices are horizontally shifted in a limited number of cases.

\mudelafile{collisions.ly}

In some cases, collisions may be hairy to resolve, or the typesetter
may have special whishes.  For those special cases, note shifts can be 
set by hand.

\mudelafile{note-shift.sly}

The number of stafflines of a staff can be set with the property
numberOfStaffLines.  Ledger lines both on note heads and rests are
adjusted.  Barlines also are adjusted.


\mudelafile{number-staff-lines.fly}

\section{Spacing}

In a limited number of cases, LilyPond corrects for optical spacing
effects.  In this example, space for opposite pointed stems is adjusted

\mudelafile{stem-spacing.sly}

Even if a line is very tightly spaced, there will still be room
between prefatory matter and the following notes.  The space after the
prefatory is very rigid.  In contrast, the space before the barline
must stretch like the space within the measure.

Tight:

\mudelafile{spacing-tight.ly}

Natural:

\mudelafile{spacing-natural.ly}

Loose:

\mudelafile{spacing-loose.ly}


\section{Global stuff}

Markings that are attached to (invisible) barlines are 
delicate: the are attached to the rest of the score without the score
knowing it.  Consequently, they fall over  often.

\mudelafile{bar-scripts.ly}

Staff margins are also markings attached to barlines.  They should be
left of the staff, and be centered vertically wrt the staff.  They may
be on normal staffs, but also on compound staffs, like the PianoStaff

\mudelafile{staff-margin.ly}

Breathing signs, also used for phrasing, do normally not influence
global spacing -- only if space gets tight, notes are shifted to make
room for the breathing sign. Breathing signs break beams running
through their voice. In the following example, the notes in the first
two measures all have the same distance from each other:

\mudelafile{breathing-sign.ly}

Fonts are  available in a default set of sizes: 11, 13, 16, 20, 23 and
26pt staffheight.  Sizes of the text fonts and symbol fonts are made
to match the staff dimensions.    

\mudelafile{size11.ly}

\mudelafile{size13.ly}

\mudelafile{size16.ly}

\mudelafile{size20.ly}

\mudelafile{size23.ly}

\mudelafile{size26.ly}


\section{Clefs and Time Signatures}

The transparent clef should not occupy any space and with style
\texttt{fullSizeChanges}, the changing clef should be typeset in full
size. For octaviated clefs, the ``8'' should appear closely above or
below the clef respectively.  The ``8'' is processed in a convoluted
way, so this is fragile as well.

\mudelafile{clefs.ly}

\def\bla#1{%the input file is too long and does not test for specific bugs
By default, time signatures are written with two numbers. With style
``C'', 4/4 and 2/2 are written with their corresponding symbols and
with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and
9/8 are typeset with symbols, all other signatures retain the default
layout. The style ``1'', gives single number signatures for all
signatures. 
%
\mu delafile{time.fly}
}
\end{document}