@section Introduction
-This document tries give a 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.
-
-[TODO: revise and completize this. ]
-
-[TODO: should generate out of header fields using ly2dvi?]
-
-
+This document presents a 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.
-
-@lilypondfile{rest.ly}
-
-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.
-
-Harmonic notes have a different shape and different
-dimensions. Nevertheless, noteheads in both styles can be combined, on
-either up or down stems.
-
-@lilypondfile{noteheadstyle.ly}
-
-Noteheads can have dots, and rests can too. Augmentation dots should
-never be printed on a staff line, but rather be shifted vertically. They
-should go up, but in case of multiple parts, the down stems have down
-shifted dots. (Wanske p. 186) In case of chords, all dots should be in
-a column. The dots go along as rests are shifted to avoid collisions.
+@lilypondfile[printfilename]{rest.ly}
-@lilypondfile{dots.ly}
+@lilypondfile[printfilename]{rest-ledger.ly}
-Accidentals work: the second note does not get a sharp. The third and
-fourth show forced and courtesy accidentals
+@lilypondfile[printfilename]{note-head-style.ly}
-@lilypondfile{accidental.ly}
+@lilypondfile[printfilename]{mensural.ly}
-Multiple measure rests do not collide with barlines and clefs. They
-are not expanded when you set @code{Score.skipBars}. Although the
-multi-measure-rest is a Spanner, minimum distances are set to keep it
-colliding from barlines.
+@lilypondfile[printfilename]{easy-notation.ly}
+@lilypondfile[printfilename]{dots.ly}
-@lilypondfile{multi-measure-rest.ly}
+@lilypondfile[printfilename]{accidental.ly}
-If @code{Score.skipBars} is set,
-the signs for four, two, and one measure rest are combined to
-produce the graphical representation of rests for up to 10 bars.
-The number of bars will be written above the sign.
+@lilypondfile[printfilename]{multi-measure-rest.ly}
-@lilypondfile{mm-rests2.ly}
+@lilypondfile[printfilename]{mm-rests2.ly}
-A sharp sign after a double sharp sign, as well as a flat sign
-after a double flat sign is automatically prepended with a
-natural sign.
+@lilypondfile[printfilename]{accidental-single-double.ly}
-@lilypondfile{accidental-single-double.ly}
@section Stems
-Stem tremolos 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.
+@lilypondfile[printfilename]{stem-tremolo.ly}
-@lilypondfile{stem-tremolo.ly}
+@lilypondfile[printfilename]{chord-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.
-
-@lilypondfile{chord-tremolo.ly}
+@lilypondfile[printfilename]{stem-direction.ly}
-Beams, stems and noteheads often have communication troubles, since
-the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
-point) are mixed.
+@lilypondfile[printfilename]{stem-direction-down.ly}
-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.
-@lilypondfile{stem-direction.ly}
-
-Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}.
-
-@lilypondfile{stem-direction-down.ly}
@section Scripts
-The staccato dot (and all scripts with follow-into-staff set), must
-not be on staff lines.
+@lilypondfile[printfilename]{staccato-pos.ly}
-@lilypondfile{staccato-pos.ly}
+@lilypondfile[printfilename]{arpeggio.ly}
-Dynamics appear below or above the staff. If multiple dynamics are
-linked with (de)crescendi, they should be on the same line.
+@lilypondfile[printfilename]{glissando.ly}
-@lilypondfile{dyn-line.ly}
+@section Dynamics
+@lilypondfile[printfilename]{dynamics-line.ly}
-Arpeggios are supported, both cross-staff and one-staff.
-
-@lilypondfile{arpeggio.ly}
+@lilypondfile[printfilename]{hairpin-ending.ly}
+@lilypondfile[printfilename]{dynamics-broken-hairpin.ly}
+@lilypondfile[printfilename]{dynamics-unbound-hairpin.ly}
@section Chord names
-Chord names are generated from a list pitches, and are customisable
-from guile. For some unlogical names, guile customisation is used
-by default.
+@lilypondfile[printfilename]{chord-names.ly}
+@lilypondfile[printfilename]{chord-changes.ly}
-@lilypondfile{chord-names.ly}
-@section Grace notes
-Grace notes are typeset as an encapsulated piece of music. You can
-have beams, notes, chords, stems etc. within a @code{\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.
+@section Grace notes
-Grace notes without beams should have a slash, if @code{flagStyle} is
-not set. Main note scripts don't end up on the grace note.
+Grace note do weird things with timing. Fragile.
-@lilypondfile{grace.ly}
-@section Beams, slurs and other spanners
+@lilypondfile[printfilename]{grace.ly}
-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.
+@lilypondfile[printfilename]{grace-bar-line.ly}
-@lilypondfile{beaming.ly}
+@lilypondfile[printfilename]{grace-nest2.ly}
-Beams should behave reasonably well, even under extreme circumstances.
-Stems may be short, but noteheads should never touch the beam.
+@lilypondfile[printfilename]{grace-nest3.ly}
-@lilypondfile{beam-extreme.ly}
+@lilypondfile[printfilename]{grace-nest4.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.
-Override with @code{noStemExtend}.
+@lilypondfile[printfilename]{grace-nest5.ly}
+@lilypondfile[printfilename]{grace-nest1.ly}
-@lilypondfile{beam-position.ly}
+@lilypondfile[printfilename]{grace-start.ly}
-Slurs should look nice and symmetric. The curvature may increase
-only to avoid noteheads, and as little as possible. Slurs never
-run through noteheads or stems.
+@lilypondfile[printfilename]{grace-sync.ly}
-@lilypondfile{slur-nice.ly}
-@lilypondfile{slur-symmetry.ly}
-@lilypondfile{slur-symmetry-1.ly}
-Across line breaks, slurs behave nicely. On the left, they extend to
-just after the preferatory matter, and on the right to the end of the
-staff. A slur should follow the same vertical direction it would have
-in unbroken state.
+@section Beams
-@lilypondfile{slur-broken-trend.ly}
+@lilypondfile[printfilename]{beaming.ly}
-Ties are strictly horizontal. They are placed in between note heads.
-The horizontal middle should not overlap with a staffline.
+@lilypondfile[printfilename]{beam-extreme.ly}
-@lilypondfile{tie.ly}
+@lilypondfile[printfilename]{beam-position.ly}
-When tieing chords, the outer slurs point outwards, the inner slurs
-point away from the center of the staff. Override with
-@code{tieVerticalDirection}.
+@lilypondfile[printfilename]{auto-beam-bar.ly}
-@lilypondfile{tie-chord.ly}
+@lilypondfile[printfilename]{beam-rest.ly}
-When tieing notes with accidentals across a bar boundary, the accidental
-must not be drawn on the note in the new bar. Instead, the next note of
-the same pitch in this bar should always show the accidental (even if
-it's natural). Slurring a accidentaled note to a natural one across bar
-boundaries should be explicit.
+@lilypondfile[printfilename]{beam-length.ly}
-Pitches can be verified by printing them with the @code{NoteNames} context.
+@lilypondfile[printfilename]{beam-dir-function.ly}
-@lilypondfile{tie-accidental.ly}
+@lilypondfile[printfilename]{auto-knee.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.
+@lilypondfile[printfilename]{auto-isknee.ly}
-@lilypondfile{beam-cross-staff.ly}
+@lilypondfile[printfilename]{triplets.ly}
-The same goes for slurs. They behave decently when broken across
-linebreak.
-@lilypondfile{slur-cross-staff.ly}
+@section Slurs
-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.
+@lilypondfile[printfilename]{slur-nice.ly}
-@lilypondfile{tup.ly}
+@lilypondfile[printfilename]{slur-symmetry.ly}
-@section Property details
+@lilypondfile[printfilename]{slur-symmetry-1.ly}
-More specific settings take precendence over less specific settings. The
-second slur has slurDirection set to down, overriding the stemup setting.
+@lilypondfile[printfilename]{slur-broken-trend.ly}
-@lilypondfile{generic-property-override.ly}
+@lilypondfile[printfilename]{slur-attachment.ly}
-@section Repeats
+@lilypondfile[printfilename]{slur-attachment-override.ly}
-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
-simultaneo.ly. 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.
+@lilypondfile[printfilename]{slur-stem-broken.ly}
-Unfolded behavior:
+@lilypondfile[printfilename]{drarn-slurs.ly}
-@lilypondfile{repeat-unfold.ly}
+@lilypondfile[printfilename]{phrasing-slur.ly}
-Volta (Semi folded) behavior. Voltas can start on non-barline moments.
-If they don't barlines should still be shown.
+@lilypondfile[printfilename]{slur-staccato.ly}
-@lilypondfile{repeat-volta.ly}
-Folded. This doesn't make sense without alternatives, but it works.
+@section Ties
-@lilypondfile{repeat-fold.ly}
+@lilypondfile[printfilename]{tie.ly}
-Across linebreaks, the left edge of a first and second alternative
-bracket should be equal
+@lilypondfile[printfilename]{tie-chord.ly}
-@lilypondfile{repeat-line-break.ly}
+@lilypondfile[printfilename]{tie-accidental.ly}
-Auto change piano staff switches voices between up and down staffs
-automatically; rests are switched along with the coming note.
+@lilypondfile[printfilename]{tup.ly}
-@lilypondfile{auto-change.ly}
+@lilypondfile[printfilename]{tuplet-beam.ly}
-@section Lyrics
+@lilypondfile[printfilename]{tuplet-staffline-collision.ly}
-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
-@code{\rhythm} ignores any other rhythms in the piece. Hyphens and
-extenders do not assume anything about lyric lengths, so they continue
-to work.
+@lilypondfile[printfilename]{tuplet-nest.ly}
-@lilypondfile{lyric-combine.ly}
-Multiple stanzas
+@section Property details
-@lilypondfile{lyrics-multi-stanza.ly}
+@lilypondfile[printfilename]{generic-property-override.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.
-@lilypondfile{rest-collision.ly}
+@section Repeats
-Normal collisions. We have support for polyphony, where the
-middle voices are horizontally shifted.
+@lilypondfile[printfilename]{repeat-unfold.ly}
-@lilypondfile{collisions.ly}
+@lilypondfile[printfilename]{repeat-volta.ly}
-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.
+@lilypondfile[printfilename]{repeat-fold.ly}
+@lilypondfile[printfilename]{repeat-line-break.ly}
-@lilypondfile{number-staff-lines.ly}
+@lilypondfile[printfilename]{volta-broken-left-edge.ly}
-@section Spacing
+@section Lyrics
-In a limited number of cases, LilyPond corrects for optical spacing
-effects. In this example, space for opposite pointed stems is adjusted
+@lilypondfile[printfilename]{lyric-combine.ly}
-@lilypondfile{stem-spacing.ly}
+@lilypondfile[printfilename]{lyrics-multi-stanza.ly}
-If there are accidentals in the music, we add space, but the space
-between note and accidentals is less than between the notes with the
-same value. Clef changes also get extra space, but not as much as
-barlines.
+@lilypondfile[printfilename]{lyric-phrasing.ly}
-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:
-@lilypondfile{spacing-tight.ly}
+@section Multiple notes
-Natural:
+@lilypondfile[printfilename]{rest-collision.ly}
-@lilypondfile{spacing-natural.ly}
+@lilypondfile[printfilename]{collisions.ly}
-Loose:
+@lilypondfile[printfilename]{collision-dots.ly}
-@lilypondfile{spacing-loose.ly}
+@lilypondfile[printfilename]{collision-mesh.ly}
-Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that
-lyrics don't collide with barlines.
+@lilypondfile[printfilename]{number-staff-lines.ly}
-@lilypondfile{lyrics-bar.ly}
-Text is set with empty horizontal dimensions. The boolean property
-textNonEmpty is used to respect the horizontal size of text.
-@lilypondfile{non-empty-text.ly}
+@section Spacing
+@lilypondfile[printfilename]{stem-spacing.ly}
+@lilypondfile[printfilename]{spacing-tight.ly}
+@lilypondfile[printfilename]{spacing-natural.ly}
-@section PianoStaff
+@lilypondfile[printfilename]{spacing-loose.ly}
+@lilypondfile[printfilename]{spacing-accidental.ly}
+@lilypondfile[printfilename]{spacing-accidental-staffs.ly}
-@section Global stuff
+@lilypondfile[printfilename]{lyrics-bar.ly}
-Breaks can be encouraged and discouraged using @code{\break} and
-@code{\nobreak}. They are abbrevs for @code{\penalty} commands.
+@lilypondfile[printfilename]{non-empty-text.ly}
-@lilypondfile{break.ly}
-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.
-@lilypondfile{bar-scripts.ly}
+@section PianoStaff
-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
+@lilypondfile[printfilename]{beam-cross-staff.ly}
-@lilypondfile{staff-margin.ly}
+@lilypondfile[printfilename]{slur-cross-staff.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:
+@lilypondfile[printfilename]{percent-repeat.ly}
-@lilypondfile{breathing-sign.ly}
+@lilypondfile[printfilename]{auto-change.ly}
-Hara kiri staffs kill themselves if they are empty. This example really
-contains two staffs, but the second contains only spaces, and is
-therefore removed.
+@lilypondfile[printfilename]{follow-thread.ly}
-@lilypondfile{hara-kiri-short.ly}
-In orchestral scores and hymns, voices are traditionally combined onto
-one staff. LilyPond has a part combiner, that combines or separates two
-voices according to actual rhythm and pitch. User-defined texts such as
-``solo'' and ``@`a2'' are typeset automagically, as appropriate.
-@lilypondfile{part-combine.ly}
+@section Global stuff
+@lilypondfile[printfilename]{break.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.
+@lilypondfile[printfilename]{bar-number.ly}
-@lilypondfile[nonfragment]{size11.ly}
+@lilypondfile[printfilename]{span-bar.ly}
-@lilypondfile[nonfragment]{size13.ly}
+@lilypondfile[printfilename]{bar-scripts.ly}
-@lilypondfile[nonfragment]{size16.ly}
+@lilypondfile[printfilename]{staff-margin.ly}
-@lilypondfile[nonfragment]{size20.ly}
+@lilypondfile[printfilename]{breathing-sign.ly}
-@lilypondfile[nonfragment]{size23.ly}
+@lilypondfile[printfilename]{hara-kiri-short.ly}
-@lilypondfile[nonfragment]{size26.ly}
+@lilypondfile[printfilename]{part-combine.ly}
-@section Clefs and Time Signatures
+@lilypondfile[printfilename,nofragment]{size11.ly}
-The transparent clef should not occupy any space and with style
-@code{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.
+@lilypondfile[printfilename,nofragment]{size13.ly}
-@lilypondfile{clefs.ly}
+@lilypondfile[printfilename,nofragment]{size16.ly}
+@lilypondfile[printfilename,nofragment]{size20.ly}
-Key signatures appear on key changes. They may also
-appear without barlines. The restoration accidentals are not printed at
-the start of the line. If @code{createKeyOnClefChange} is set, they're
-also created on a clef change.
+@lilypondfile[printfilename,nofragment]{size23.ly}
-@lilypondfile{keys.ly}
+@lilypondfile[printfilename,nofragment]{size26.ly}
+@section Clefs and Time Signatures
-@ignore
-@c 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.ly}
-@end ignore
+@lilypondfile[printfilename]{clefs.ly}
+@lilypondfile[printfilename]{keys.ly}
+@lilypondfile[printfilename]{key-signature-scordatura.ly}
@section Hacks and Features
-As a last resort, the placement of items can be adjusted manually, by
-setting the @code{extra-offset} of an output object.
-
-@lilypondfile{generic-output-property.ly}
+@lilypondfile[printfilename]{generic-output-property.ly}
-The same mechanism can be used to force pagebreaks.
+@lilypondfile[printfilename]{between-systems.ly}
-@lilypondfile{between-systems.ly}
+@lilypondfile{molecule-hacking.ly}
@bye
projects / lilypond.git / blobdiff