* Documentation/topdocs/AUTHORS.texi, THANKS: add/modify my name and summary.
+ * Documentation/user/{first couple of chapters}: the big "Graham's moved to
+ a new city, his friends haven't arrived, and he has no internet access" patch.
+ Numerous editorial and stylistic changes to the manual.
+
2004-09-07 Han-Wen Nienhuys <hanwen@xs4all.nl>
* scm/framework-ps.scm (output-framework): handle landscape settings.
already set up for you. Just add notes, run LilyPond, and enjoy
beautiful printed scores!
-Note that all templates contain a @code{\version "x.y.z"} string. We
-highly recommend that you always include the @code{\version}, no matter
-how small your file is. Speaking from personal experience, it's
-quite frustrating to try to remember which version of LilyPond you were
-using a few years ago. @code{convert-ly} requires you to declare
-which version of LilyPond you used.
-
@menu
+* Suggestions for writing LilyPond files::
* Single staff::
* Piano templates::
* Small ensembles::
* Other templates::
@end menu
-@c more sections to come soon.
-@c make a note about the \score{} stuff? It might make more sense
-@c to note that in the tutorial, and reserve this section purely
-@c for templates. -GP
+@c TODO explain \score{} ? Maybe add a note to the tutorial?
+
+@node Suggestions for writing LilyPond files
+@section Suggestions for writing LilyPond files
+
+Now you're ready to begin writing bigger LilyPond files -- not just the
+little examples in the tutorial, but whole pieces. But how should you
+go about doing it?
+
+The best answer is ``however you want to do it''. As long as LilyPond
+can understand your files and produces the output that you want, it
+doesn't matter what your files look like. That said, sometimes we
+make mistakes when writing files. If LilyPond can't understand your
+files, or produces output that you don't like, how do you fix the
+problem?
+
+Here are a few suggestions that can help you in avoiding or fixing
+problems:
+@itemize @bullet
+@item Include @code{\version} numbers in every file. Note that all
+templates contain a @code{\version "x.y.z"} string. We
+highly recommend that you always include the @code{\version}, no matter
+how small your file is. Speaking from personal experience, it's
+quite frustrating to try to remember which version of LilyPond you were
+using a few years ago. @code{convert-ly} requires you to declare
+which version of LilyPond you used.
+
+@item Include checks: See @ref{Bar check} and @ref{Octave check}. If you
+include checks every so often, then if you make a mistake, you can pinpoint
+it quicker. How often is ``every so often''? It depends on the complexity
+of the music. For very simple music, perhaps just once or twice. For
+very complex music, every bar.
+
+@item One bar per line. If there's anything complicated, either in the music
+itself or in the output you desire, it's often good to write only one bar
+per line. Saving screen space by cramming eight bars per line just isn't
+worth it if you have to `debug' your files.
+
+@item Comment your files, with either bar numbers (every so often) or
+references to musical themes (``second theme in violins'', ``fourth
+variation''). You may not need it when you're writing the piece for
+the first time, but if you want to go back and change something two
+or three years later, you won't know how your file is structured if you
+don't comment the file.
+
+@end itemize
@node Single staff
@section Single staff
\version "2.3.11"
melody = \relative c' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a4 b c d
+ a4 b c d
}
\score{
- \new Staff \melody
- \paper { }
- \midi { \tempo 4=60 }
+ \new Staff \melody
+ \paper { }
+ \midi { \tempo 4=60 }
}
@end lilypond
\version "2.3.11"
melody = \relative c' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a4 b c d
+ a4 b c d
}
text = \lyrics {
- Aaa Bee Cee Dee
+ Aaa Bee Cee Dee
}
\score{
- <<
- \context Voice = one {
- \autoBeamOff
- \melody
+ <<
+ \context Voice = one {
+ \autoBeamOff
+ \melody
}
- \lyricsto "one" \new Lyrics \text
- >>
- \paper { }
- \midi { \tempo 4=60 }
+ \lyricsto "one" \new Lyrics \text
+ >>
+ \paper { }
+ \midi { \tempo 4=60 }
}
@end lilypond
\version "2.3.11"
melody = \relative c' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- f4 e8[ c] d4 g |
- a2 ~ a2 |
+ f4 e8[ c] d4 g |
+ a2 ~ a2 |
}
harmonies = \chords {
- c4:m f:min7 g:maj c:aug d2:dim b:sus
+ c4:m f:min7 g:maj c:aug d2:dim b:sus
}
\score {
<<
- \context ChordNames {
- \set chordChanges = ##t
- \harmonies
- }
- \context Staff = one \melody
- >>
+ \context ChordNames {
+ \set chordChanges = ##t
+ \harmonies
+ }
+ \context Staff = one \melody
+ >>
- \paper{ }
- \midi { \tempo 4=60}
+ \paper{ }
+ \midi { \tempo 4=60}
}
@end lilypond
\version "2.3.11"
melody = \relative c' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a b c d
+ a b c d
}
text = \lyrics {
- Aaa Bee Cee Dee
+ Aaa Bee Cee Dee
}
harmonies = \chords {
- a2 c2
+ a2 c2
}
\score {
- <<
- \context ChordNames {
- \set chordChanges = ##t
- \harmonies
- }
- \context Voice = one {
- \autoBeamOff
- \melody
- }
- \lyricsto "one" \new Lyrics \text
- >>
- \paper { }
- \midi { \tempo 4=60}
+ <<
+ \context ChordNames {
+ \set chordChanges = ##t
+ \harmonies
+ }
+ \context Voice = one {
+ \autoBeamOff
+ \melody
+ }
+ \lyricsto "one" \new Lyrics \text
+ >>
+ \paper { }
+ \midi { \tempo 4=60}
}
@end lilypond
\version "2.3.11"
upper = \relative c'' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a b c d
+ a b c d
}
lower = \relative c {
-\clef bass
-\key c \major
-\time 4/4
+ \clef bass
+ \key c \major
+ \time 4/4
- a2 c
+ a2 c
}
\score {
- \context PianoStaff <<
- \set PianoStaff.instrument = "Piano "
- \context Staff = upper \upper
- \context Staff = lower \lower
- >>
- \paper { }
- \midi { \tempo 4=60 }
+ \context PianoStaff <<
+ \set PianoStaff.instrument = "Piano "
+ \context Staff = upper \upper
+ \context Staff = lower \lower
+ >>
+ \paper { }
+ \midi { \tempo 4=60 }
}
@end lilypond
\version "2.3.11"
melody = \relative c'' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a b c d
+ a b c d
}
text = \lyrics {
- Aaa Bee Cee Dee
+ Aaa Bee Cee Dee
}
upper = \relative c'' {
-\clef treble
-\key c \major
-\time 4/4
+ \clef treble
+ \key c \major
+ \time 4/4
- a b c d
+ a b c d
}
lower = \relative c {
-\clef bass
-\key c \major
-\time 4/4
+ \clef bass
+ \key c \major
+ \time 4/4
- a2 c
+ a2 c
}
\score {
- <<
+ <<
\context Voice = mel {
- \autoBeamOff
- \melody
+ \autoBeamOff
+ \melody
}
\lyricsto mel \new Lyrics \text
\context PianoStaff <<
- \context Staff = upper \upper
- \context Staff = lower \lower
+ \context Staff = upper \upper
+ \context Staff = lower \lower
>>
- >>
- \paper {
+ >>
+ \paper {
\context { \RemoveEmptyStaffContext }
- }
- \midi { \tempo 4=60}
+ }
+ \midi { \tempo 4=60}
}
@end lilypond
\version "2.3.11"
global = {
-\key c \major
-\time 4/4
+ \key c \major
+ \time 4/4
}
sopMusic = \relative c'' {
-c4 c c8[( b)] c4
+ c4 c c8[( b)] c4
+}
+sopWords = \lyrics {
+ hi hi hi hi
}
-sopWords = \lyrics { hi4 hi hi hi }
altoMusic = \relative c' {
-e4 f d e
+ e4 f d e
+}
+altoWords =\lyrics {
+ ha ha ha ha
}
-altoWords =\lyrics { ha4 ha ha ha }
tenorMusic = \relative c' {
-g4 a f g
+ g4 a f g
+}
+tenorWords = \lyrics {
+ hu hu hu hu
}
-tenorWords = \lyrics { hu4 hu hu hu }
bassMusic = \relative c {
-c4 c g c
+ c4 c g c
+}
+bassWords = \lyrics {
+ ho ho ho ho
}
-bassWords = \lyrics { ho4 ho ho ho }
\score {
- \context ChoirStaff <<
- \context Lyrics = sopranos { s1 }
- \context Staff = women <<
- \context Voice = sopranos { \voiceOne << \global \sopMusic >> }
- \context Voice = altos { \voiceTwo << \global \altoMusic >> }
- >>
- \context Lyrics = altos { s1 }
- \context Lyrics = tenors { s1 }
- \context Staff = men <<
- \clef bass
- \context Voice = tenors { \voiceOne <<\global \tenorMusic >> }
- \context Voice = basses { \voiceTwo <<\global \bassMusic >> }
- >>
- \context Lyrics = basses { s1 }
-
-
- \context Lyrics = sopranos \lyricsto sopranos \sopWords
- \context Lyrics = altos \lyricsto altos \altoWords
- \context Lyrics = tenors \lyricsto tenors \tenorWords
- \context Lyrics = basses \lyricsto basses \bassWords
-
- >>
- \paper {
- \context {
-
- % a little smaller so lyrics can be closer to the staff.
- \Staff
- minimumVerticalExtent = #'(-3 . 3)
- }
- }
+ \context ChoirStaff <<
+ \context Lyrics = sopranos { s1 }
+ \context Staff = women <<
+ \context Voice = sopranos { \voiceOne << \global \sopMusic >> }
+ \context Voice = altos { \voiceTwo << \global \altoMusic >> }
+ >>
+ \context Lyrics = altos { s1 }
+ \context Lyrics = tenors { s1 }
+ \context Staff = men <<
+ \clef bass
+ \context Voice = tenors { \voiceOne <<\global \tenorMusic >> }
+ \context Voice = basses { \voiceTwo <<\global \bassMusic >> }
+ >>
+ \context Lyrics = basses { s1 }
+ \context Lyrics = sopranos \lyricsto sopranos \sopWords
+ \context Lyrics = altos \lyricsto altos \altoWords
+ \context Lyrics = tenors \lyricsto tenors \tenorWords
+ \context Lyrics = basses \lyricsto basses \bassWords
+ >>
+
+ \paper {
+ \context {
+ % a little smaller so lyrics can be closer to the staff.
+ \Staff minimumVerticalExtent = #'(-3 . 3)
+ }
+ }
}
@end lilypond
\version "2.3.11"
global = {
-\time 4/4
-\key c \major
+ \time 4/4
+ \key c \major
}
violinOne = \relative c''{
-\set Staff.instrument = "Violin 1 "
-c2 d
-e1
+ \set Staff.instrument = "Violin 1 "
+ c2 d
+ e1
}
violinTwo = \relative c''{
-\set Staff.instrument = "Violin 2 "
-g2 g
-g1
+ \set Staff.instrument = "Violin 2 "
+ g2 g
+ g1
}
viola = \relative c'{
-\set Staff.instrument = "Viola "
-\clef alto
-e2 d
-c1
+ \set Staff.instrument = "Viola "
+ \clef alto
+ e2 d
+ c1
}
cello = \relative c'{
-\set Staff.instrument = "Cello "
-\clef bass
-c2 g
-c,1
+ \set Staff.instrument = "Cello "
+ \clef bass
+ c2 g
+ c,1
}
\score {
- \new StaffGroup <<
- \new Staff << \global \violinOne >>
- \new Staff << \global \violinTwo >>
- \new Staff << \global \viola >>
- \new Staff << \global \cello >>
- >>
- \paper { }
- \midi { \tempo 4=60}
+ \new StaffGroup <<
+ \new Staff << \global \violinOne >>
+ \new Staff << \global \violinTwo >>
+ \new Staff << \global \viola >>
+ \new Staff << \global \cello >>
+ >>
+ \paper { }
+ \midi { \tempo 4=60}
}
@end lilypond
concert pitch; LilyPond will automatically transpose the key if the music
is within a @code{\transpose} section.
-@c TODO must clean up this example.
+@c TODO must clean up this jazz combo example
@c - transpositions stated in names (ie "trumpet in Bb" or whatever)
@c - one global section, instead of "global" (time) and "key"
@c - does it need those wierd macros? sl, nsl, etc.
\version "2.3.11"
\header {
- dedication = "dedication"
- title = "Title"
- subtitle = "Subtitle"
- subsubtitle = "Subsubtitle"
- composer = "Composer (xxxx-yyyy)"
- opus = "Opus 0"
- piece = "Piece I"
- instrument = "Instrument"
- arranger = "Arranger"
- poet = "Poet"
- texttranslator = "Translator"
- copyright = "public domain"
-
-% These are headers used by the Mutopia Project http://www.mutopiaproject.org/
- mutopiatitle = ""
- mutopiacomposer = ""
- mutopiapoet = ""
- mutopiainstrument = ""
- date = "composer's dates"
- source = "urtext "
- maintainer = "your name here"
- maintainerEmail = "your email here"
- maintainerWeb = "your home page"
- lastupdated = "2004/Aug/26"
+ dedication = "dedication"
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ composer = "Composer (xxxx-yyyy)"
+ opus = "Opus 0"
+ piece = "Piece I"
+ instrument = "Instrument"
+ arranger = "Arranger"
+ poet = "Poet"
+ texttranslator = "Translator"
+ copyright = "public domain"
+
+% These are headers used by the Mutopia Project http://www.mutopiaproject.org/
+ mutopiatitle = ""
+ mutopiacomposer = ""
+ mutopiapoet = ""
+ mutopiainstrument = ""
+ date = "composer's dates"
+ source = "urtext "
+ maintainer = "your name here"
+ maintainerEmail = "your email here"
+ maintainerWeb = "your home page"
+ lastupdated = "2004/Aug/26"
}
\score {
\header {
piece = "piece1"
opus = "opus1"
- }
- { c'4 }
+ }
+ { c'4 }
}
\score {
\header {
piece = "piece2"
opus = "opus2"
- }
- { c'4 }
+ }
+ { c'4 }
}
@end lilypond
quarter notes, and two types of barlines, a short one indicating a rest,
and a second one indicating a breath mark.
-
@lilypond[verbatim,raggedright]
-barOne = { \once \override Staff.BarLine #'bar-size = #2
- \bar "|" }
-barTwo = { \once \override Staff.BarLine #'extra-offset = #'(0 . 2)
- \once \override Staff.BarLine #'bar-size = #2
- \bar "|" }
+barOne = { \once \override Staff.BarLine #'bar-size = #2
+ \bar "|" }
+barTwo = { \once \override Staff.BarLine #'extra-offset = #'(0 . 2)
+ \once \override Staff.BarLine #'bar-size = #2
+ \bar "|" }
chant = \relative c' {
-\set Score.timing = ##f
-\override Staff.Stem #'transparent = ##t
+ \set Score.timing = ##f
+ \override Staff.Stem #'transparent = ##t
-f4 a2 \barTwo
-g4 a2 f2 \barOne
-g4( f) f( g) a2
+ f4 a2 \barTwo
+ g4 a2 f2 \barOne
+ g4( f) f( g) a2
}
\score {
- \chant
- \paper{ }
- \midi { \tempo 4=60 }
+ \chant
+ \paper{ }
+ \midi { \tempo 4=60 }
}
@end lilypond
completely. This template defines a large number of small segments
(@code{taor, grip, thrd,} etc), which can be reused easily.
+TODO - replace Bagpipe template with Andrew McNabb's work?
+
@lilypond[verbatim,raggedright]
taor = { \grace { g32[ d' g e'] } }
@end lilypond
-
-
-
stamping and cutting was completely done by hand. Making a correction
was cumbersome, if possible at all, so the engraving had to be perfect
in one go. Engraving was a highly specialized skill, a craftsman had
-to complete around five years of training before he could
+to complete around five years of training before she could
be a master engraver, and another five years of experience were
necessary to become truly skilled.
@cindex optical spacing
@lilypond[quote,noindent,fragment]
{
- \override Staff.NoteSpacing #'stem-spacing-correction = #0.6
- c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4 | \bar "||"
- \override Staff.NoteSpacing #'stem-spacing-correction = #0.0
- \override Staff.StaffSpacing #'stem-spacing-correction = #0.0
- \stemBoth c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4 |
+ \override Staff.NoteSpacing #'stem-spacing-correction = #0.6
+ c'4 e''4 e'4 b'4 |
+ \stemDown b'4 e''4 a'4 e''4 | \bar "||"
+ \override Staff.NoteSpacing #'stem-spacing-correction = #0.0
+ \override Staff.StaffSpacing #'stem-spacing-correction = #0.0
+ \stemBoth c'4 e''4 e'4 b'4 |
+ \stemDown b'4 e''4 a'4 e''4 |
}
@end lilypond
rhythms, spacing corrections lead to subtle variations in the layout
of every line, giving each one a distinct visual signature. Without
this signature all lines would look the same, and they become like a
-labyrinth. If the musician looks away once or has a lapse in his
-concentration, he will be lost on the page.
-@c he/she
+labyrinth. If the musician looks away once or has a lapse in her
+concentration, she will have lost her place on the page.
Similarly, the strong visual look of bold symbols on heavy staff lines
stands out better when music is far away from reader, for example, if
This is a common characteristic of typography. Layout should be
pretty, not only for its own sake, but especially because it helps the
-reader in his task. For performance material like sheet music, this is
+reader in her task. For performance material like sheet music, this is
of double importance: musicians have a limited amount of attention. The
less attention they need for reading, the more they can focus on
playing itself. In other words, better typography translates to better
@lilypond[quote,raggedright,relative=1,fragment]
\new Score \with {
- \override SpacingSpanner #'spacing-increment = #3
- \override TimeSignature #'transparent = ##t
- } {
- \stemDown <e g b>4_>-\arpeggio
- \override Arpeggio #'direction = #RIGHT
- \stemUp <e g b>4^>-\arpeggio
+ \override SpacingSpanner #'spacing-increment = #3
+ \override TimeSignature #'transparent = ##t
+} {
+ \stemDown <e g b>4_>-\arpeggio
+ \override Arpeggio #'direction = #RIGHT
+ \stemUp <e g b>4^>-\arpeggio
}
@end lilypond
@noindent
The process of formatting a score consists of reading and writing the
-variables of graphical objects.
-
-Some variables have a preset value. For example, the thickness of
-many lines---a characteristic of typographical style---are not fixed.
-They are variables, and altering them gives a different typographical
-impression.
+variables of graphical objects. Some variables have a preset value. For
+example, the thickness of many lines -- a characteristic of typographical
+style -- is a variable with a preset value. You are free to alter this
+value, giving your score a different typographical impression.
@lilypond[quote,raggedright]
-fragment = {
- \clef bass f8 as8
- c'4-~ c'16 as g f e16 g bes c' des'4
+fragment = {
+ \clef bass f8 as8
+ c'4-~ c'16 as g f e16 g bes c' des'4
}
-
- <<
- \new Staff \fragment
- \new Staff \with {
+<<
+ \new Staff \fragment
+ \new Staff \with {
\override Beam #'thickness = #0.3
\override Stem #'thickness = #0.5
\override Bar #'thickness = #3.6
\override Tie #'thickness = #2.2
\override StaffSymbol #'thickness = #3.0
\override Tie #'extra-offset = #'(0 . 0.3)
- } \fragment
- >>
+ }
+ \fragment
+>>
@end lilypond
Formatting rules are also preset variables: each object has variables
((-2) (make-smaller-markup (make-bold-markup "2")))
(else (make-simple-markup "bla")))))))))
- \context Voice \relative c' {
- \stemUp
- \set autoBeaming = ##f
- \time 2/4
- <d f g>4
- \once \override NoteHead #'print-function = #Note_head::brew_ez_stencil
- <d f g>
- \once \override NoteHead #'style = #'cross
- <d f g>
- \applyoutput #mc-squared
- <d f g>
- <<
+\new Voice \relative c' {
+ \stemUp
+ \set autoBeaming = ##f
+ \time 2/4
+ <d f g>4
+ \once \override NoteHead #'print-function = #Note_head::brew_ez_stencil
+ <d f g>
+ \once \override NoteHead #'style = #'cross
+ <d f g>
+ \applyoutput #mc-squared
+ <d f g>
+ <<
{ d8[ es-( fis^^ g] fis2-) }
\repeat unfold 5 { \applyoutput #mc-squared s8 }
- >>
- }
+ >>
+}
@end lilypond
\include "engraver-example.lyinc"
\score {
- \topVoice
- \paper {
- \context {
+ \topVoice
+ \paper {
+ \context {
\Voice
\remove "Stem_engraver"
\remove "Phrasing_slur_engraver"
\remove "Script_engraver"
\remove "Beam_engraver"
\remove "Auto_beam_engraver"
- }
- \context {
+ }
+ \context {
\Staff
\remove "Accidental_engraver"
\remove "Key_engraver"
\remove "Time_signature_engraver"
\remove "Staff_symbol_engraver"
\consists "Pitch_squash_engraver"
- }
- }
+ }
+}
}
@end lilypond
The @code{Stem_engraver} is notified of any note head coming along.
Every time one (or more, for a chord) note head is seen, a stem
-object is created and connected to the note head.
-By adding engravers for beams, slurs, accents, accidentals, bar lines,
+object is created and connected to the note head. By adding
+engravers for beams, slurs, accents, accidentals, bar lines,
time signature, and key signature, we get a complete piece of
notation.
@lilypond[quote,raggedright]
\include "engraver-example.lyinc"
-\context Staff << \topVoice \\ \botVoice >>
+\new Staff << \topVoice \\ \botVoice >>
@end lilypond
In this situation, the accidentals and staff are shared, but the
@lilypond[quote,raggedright]
\include "engraver-example.lyinc"
\score {
- <<
- \new Staff << \topVoice \\ \botVoice >>
- \new Staff << \pah \\ \hoom >>
- >>
+ <<
+ \new Staff << \topVoice \\ \botVoice >>
+ \new Staff << \pah \\ \hoom >>
+ >>
}
@end lilypond
@c < > is not a music expression,
@c so we use <<>> iso. <> to drive home the point of
-@c expressions. Don't change this back --hwn.
+@c expressions. Don't change this back --hwn.
@example
<<c4 d4 e4>>
@end example
By adding chord names and lyrics we obtain a lead sheet.
@lilypond[quote,raggedright]
- <<
- \context ChordNames \chords { c2 c f2 c }
- \new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
- \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 }
- >>
+<<
+ \new ChordNames \chords { c2 c f2 c }
+ \new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
+ \new Lyrics \lyrics { twin4 kle twin kle lit tle star2 }
+>>
@end lilypond
Polyphonic notation and piano music can also be printed. The following
The
@end ifhtml
@emph{@ref{Tutorial}}
-gives a gentle introduction to typesetting music.
-First time users should start here.
+gives a gentle introduction to typesetting music. First time
+users should start here.
@item
@ifhtml
The
@end ifhtml
@emph{@ref{Integrating text and music}}
-explains the details behind creating documents with in-line music
+explains the details behind creating documents with in-line music
examples (like this manual).
@item
@emph{@ref{Converting from other formats}}
explains how to run the conversion programs. These programs
are supplied with the LilyPond package, and convert a variety of music
-formats to the @code{.ly} format. In addition, this section explains
+formats to the @code{.ly} format. In addition, this section explains
how to upgrade input files from previous versions of LilyPond.
@item
@end ifhtml
@emph{@ref{Literature list}}
contains a set of useful reference books for those who wish to know
-more on notation and engraving.
+more on notation and engraving.
@end itemize
Once you are an experienced user, you can use the manual as reference:
initialization and example files. Throughout this manual, we refer to
input files relative to the top-directory of the source archive. For
example, @file{input/test/bla.ly} may refer to the file
-@file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
+@file{lilypond-2.3.14/input/test/bla.ly}. On binary packages for the
Unix platform, the documentation and examples can typically be found
somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
The @code{lilypond} may be called as follows from the command line.
@example
- lilypond [@var{option}]@dots{} @var{file}@dots{}
+ lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
When invoked with a filename that has no extension, the @file{.ly}
-extension is tried first. To read input from stdin, use a
+extension is tried first. To read input from stdin, use a
dash @code{-} for @var{file}.
When @file{filename.ly} is processed it will produce
@item --ps
Generate PostScript.
@item --dvi
- Generate DVI files. In this case, the @TeX{} backend should be
+ Generate DVI files. In this case, the @TeX{} backend should be
specified, i.e. @code{-f tex}.
@item --png
Generate pictures of each page, in PNG format. This implies @code{--ps}.
@item --pdf
- Generate PDF. This implies @code{--ps}.
+ Generate PDF. This implies @code{--ps}.
@item --preview
Generate an output file containing the titles and the first system
of the score.
@item -s,--safe
Do not trust the @code{.ly} input.
-When LilyPond formatting available through a web server, the
+When LilyPond formatting is available through a web server, the
@code{--safe} @b{MUST} be passed. This will prevent inline Scheme
code from wreaking havoc, for example
@end verbatim
The @code{--safe} option works by evaluating in-line Scheme
-expressions in a special safe module. This safe module is derived from
+expressions in a special safe module. This safe module is derived from
GUILE @file{safe-r5rs} module, but adds a number of functions of the
-LilyPond API. These functions are listed in @file{scm/safe-lily.scm}.
+LilyPond API. These functions are listed in @file{scm/safe-lily.scm}.
In addition, @code{--safe} disallows @code{\include} directives and
disables the use of backslashes in @TeX{} strings.
@item -v,--version
Show version information.
@item -V,--verbose
-Be verbose: show full paths of all files read, and give timing
+Be verbose: show full paths of all files read, and give timing
information.
@item -w,--warranty
@item @file{buildscripts/out/lilypond-login} (for C-shells)
@end itemize
-They should normally be sourced as part of the login process. If these
+They should normally be sourced as part of the login process. If these
scripts are not run from the system wide login process, then you must
run it yourself.
To make sure that @TeX{} and lilypond find data files (among
others @file{.tex}, @file{.mf} and @file{.tfm}),
you have to set @code{TEXMF} to point to the lilypond data
-file tree. A typical setting would be
+file tree. A typical setting would be
@example
@{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
@end example
@cindex TEXMF
@cindex printing postscript
-The binary itself recognizes the following environment variables:
+The binary itself recognizes the following environment variables:
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
-data files will be looked up by default. The directory should contain
+data files will be looked up by default. The directory should contain
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@item LANG
@cindex warning
@item Warning
- Something looks suspect. If you are requesting something out of the
+ Something looks suspect. If you are requesting something out of the
ordinary then you will understand the message, and can ignore it.
However, warnings usually indicate that something is wrong with the
input file.
@cindex error
@cindex fatal error
@item Fatal error
-Something is definitely wrong, and LilyPond cannot continue. This
-happens rarely. The most usual cause is misinstalled fonts.
+Something is definitely wrong, and LilyPond cannot continue. This
+happens rarely. The most usual cause is misinstalled fonts.
@cindex trace, Scheme
@cindex call trace
@cindex Scheme error
@item Scheme error
Errors that occur while executing Scheme code are caught by the Scheme
-interpreter. If running with the verbose option (@code{-V} or
+interpreter. If running with the verbose option (@code{-V} or
@code{--verbose}) then a call trace is printed of the offending
function call.
@cindex Programming error
@item Programming error
-There was some internal inconsistency. These error messages are
-intended to help the programmers and debuggers. Usually, they can be
-ignored. Sometimes, they come in such big quantities that they obscure
-other output. In this case, file a bug-report.
+There was some internal inconsistency. These error messages are
+intended to help the programmers and debuggers. Usually, they can be
+ignored. Sometimes, they come in such big quantities that they obscure
+other output. In this case, file a bug-report.
@item Aborted (core dumped)
This signals a serious programming error that caused the program to
-crash. Such errors are considered critical. If you stumble on one,
+crash. Such errors are considered critical. If you stumble on one,
send a bugreport.
@end example
A line-break is inserted in offending line to indicate the column
-where the error was found. For example,
+where the error was found. For example,
@example
test.ly:2:19: error: not a duration: 5:
g' @}
@end example
+These locations are LilyPond's best guess about where the warning or
+error occured, but (by their very nature) warning and errors occur
+when something unexpected happens. If you can't see an error in the
+indicated line of your input file, try checking one or two lines
+above the indicated position.
+
@node Reporting bugs
@section Reporting bugs
@cindex reporting bugs
If you have input that results in a crash or an erroneous output, then
-that is a bug. We try respond to bug-reports promptly, and fix them as
+that is a bug. We try respond to bug-reports promptly, and fix them as
soon as possible. Help us by sending a defective input file, so we can
-reproduce the problem. Make it small, so we can easily debug the
-problem. Don't forget to tell which version you use, and on which
+reproduce the problem. Make it small, so we can easily debug the
+problem. Don't forget to tell which version you use, and on which
platform you run it. Send the report to
@email{bug-lilypond@@gnu.org}.
+FIXME: devel bug reports go to...?
+
+@c yeah, normally these go in comments, but they'll be fixed -very- soon,
+@c and I wanted to make it clear to people reading the devel docs that
+@c these facts need clarification. -gp
+FIXME: does bug-lilypond get archived?
+
+@c TODO: make a link to the archive/search for html output
+When you've found a bug, do a few searches on the mailing list for
+the bug. Sometimes the bug will have already been reported and a fix
+or workaround is already known.
+
+@c I'm not going to mention the bug CVS. Newbies won't know how to
+@c use it, and it would only scare them. Besides, Erik says he doesn't
+@c mind getting multiple bug reports, so who cares if it makes more work
+@c for him? :) (in addition, multiple bug reports about the same
+@c thing could be useful in judging the severity of a problem) -gp
+
+Here's an example of a good bug report:
+
+@example
+% LilyPond 2.3.11, Mac OSX 10.3.4, fink package lilypond-unstable
+% slur does not look at accidentals
+\score @{
+\relative c''@{
+a1 a a a a
+a2. g16( b d fis)
+@}@}
+@end example
+
@node Editor support
@section Editor support
@cindex syntax coloring
@cindex coloring, syntax
-There is support from different editors for LilyPond.
+There is support from different editors for LilyPond.
@table @asis
@item Emacs
@ifnothtml
installation instructions.
@end ifnothtml
-for more information.
@item VIM
For @uref{http://www.vim.org,VIM}, a @file{vimrc} is supplied, along with
-syntax coloring tools. For more information, refer to the
+syntax coloring tools. For more information, refer to the
@ifhtml
@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
@end ifhtml
@item JEdit
-There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
+There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
information.
@end table
For both VIM and Emacs editors, there is also a facility to jump in
-the input file to the source of errors in the graphical output. See
+the input file to the source of errors in the graphical output. See
@ref{Point and click}.
Before LilyPond 3.0, the @code{lilypond} program only generated music
notation. Titles and page layout was done in a separate wrapper
-program. For compatibility with older files, this wrapper program has
-been retained as @code{lilypond-latex}. It uses the LilyPond program
+program. For compatibility with older files, this wrapper program has
+been retained as @code{lilypond-latex}. It uses the LilyPond program
and La@TeX{} to create a nicely titled piece of sheet music. Use of
this program is only necessary if the input file contains special
La@TeX{} options or formatting codes in markup texts.
@table @code
@item -k,--keep
Keep the temporary directory with all output
-files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
+files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
@item -h,--help
Print usage help.
@item -I,--include=@var{dir}
@item -s,--set=@var{key}=@var{val}
Add @var{key}= @var{val} to the settings, overriding those specified
-in the files. Possible keys: @code{language}, @code{latexheaders},
+in the files. Possible keys: @code{language}, @code{latexheaders},
@code{latexpackages}, @code{latexoptions}, @code{papersize},
@code{linewidth}, @code{orientation},
@code{textheight}.
@item -v,--version
Show version information.
@item -V,--verbose
-Be verbose. This prints out commands as they are executed, and more
+Be verbose. This prints out commands as they are executed, and more
information about the formatting process is printed.
@item --debug
-Print even more information. This is useful when generating bug reports.
+Print even more information. This is useful when generating bug reports.
@item -w,--warranty
Show the warranty with which GNU LilyPond comes. (It comes with
@strong{NO WARRANTY}!)
@subsection Additional parameters
The @code{lilypond} program responds to several parameters specified
-in a @code{\paper} section of the input file. They can be overridden
+in a @code{\paper} section of the input file. They can be overridden
by supplying a @code{--set} command line option.
@table @code
@item latexheaders
Specify additional La@TeX{} headers file.
- Normally read from the @code{\header} block. Default value: empty.
+ Normally read from the @code{\header} block. Default value: empty.
@item latexpackages
- Specify additional La@TeX{} packages file. This works cumulative,
+ Specify additional La@TeX{} packages file. This works cumulative,
so you can add multiple packages using multiple @code{-s=latexpackages} options.
- Normally read from the @code{\header} block. Default value:
+ Normally read from the @code{\header} block. Default value:
@code{geometry}.
@item latexoptions
Specify additional options for the La@TeX{}
-@code{\documentclass}. You can put any valid value here. This was
+@code{\documentclass}. You can put any valid value here. This was
designed to allow @code{lilypond} to produce output for double-sided
-paper, with balanced margins and page numbers on alternating sides. To
+paper, with balanced margins and page numbers on alternating sides. To
achieve this specify @code{twoside}.
@item orientation
- Set orientation. Choices are @code{portrait} or @code{landscape}. Is
+ Set orientation. Choices are @code{portrait} or @code{landscape}. Is
read from the @code{\paper} block, if set.
@item textheight
- The vertical extension of the music on the page. It is normally
+ The vertical extension of the music on the page. It is normally
calculated automatically, based on the paper size.
@item linewidth
- The music line width. It is normally read from the @code{\paper}
+ The music line width. It is normally read from the @code{\paper}
block.
@item papersize
- The paper size (as a name, e.g. @code{a4}). It is normally read from
+ The paper size (as a name, e.g. @code{a4}). It is normally read from
the @code{\paper} block.
@item fontenc
A form used frequently for single movements of the @aref{sonata},
@aref{symphony}, quartet, etc. A movement written in sonata form
falls into three sections called @emph{exposition}, @emph{development} and
-@emph{recapitulation}. In the exposition the composer introduces his musical
-ideas, consisting of a number of themes; in the development section he
-"develops" this material, and in the recapitulation he repeats the exposition,
-with certain modifications, however. The exposition contains a number of themes
+@emph{recapitulation}. In the exposition the composer introduces her musical
+ideas, consisting of a number of themes; in the development section she
+"develops" this material, and in the recapitulation she repeats the exposition,
+with certain modificationsr. The exposition contains a number of themes
which fall into two groups, often called first and second subject. Other
melodies occurring in each group are considered as continuations of these
two. The second theme is in another key, normally in the key of the
Utrecht/Eindhoven, The Netherlands, July 2002.
@menu
-* Notes to version 2.2::
+* Notes for version 3.0::
@end menu
-@node Notes to version 2.2
-@unnumberedsec Notes to version 3.0
+@node Notes for version 3.0
+@unnumberedsec Notes for version 3.0
-The most important developments in 3.0 are related. In LilyPond 3.0,
-@TeX{} is no longer strictly necessary to engrave music. This is
+The most important developments in 3.0 are related. In LilyPond 3.0,
+@TeX{} is no longer strictly necessary to engrave music. This is
because LilyPond can now also layout pages and determine page breaks.
Another notable feature is the syntax, which has been simplified even
further compared to previous versions.
@c
@c We don't have enough space to explain either VIM
@c or Emacs non-advanced users, and I fear that both editors will only
-@c confuse newbies. I vote for keeping the material in footnotes.
+@c confuse newbies. I vote for keeping the material in footnotes.
@c
@c --hwn
down
To use relative mode, add @code{\relative} before the piece of
-music. The first note is taken relative to the middle C
+music. The first note is taken relative to the middle C
@c no , for this sentence
(i.e. @code{c'})
There are two types of comments. The percent symbol @samp{%}
introduces a line comment; after @code{%} the rest of the line is
ignored. A block comments marks a whole section of music
-input. Anything that is enclosed in @code{%@{} and @code{%@}} is
+input. Anything that is enclosed in @code{%@{} and @code{%@}} is
ignored. The following fragment shows possible uses for comments
@example
@node An orchestral part
@section An orchestral part
-In orchestral music, all notes are printed twice. Once in a part for
+In orchestral music, all notes are printed twice. Once in a part for
the musicians, and once in a full score for the conductor. Identifiers can
-be used to avoid double work. The music is entered once, and stored in
+be used to avoid double work. The music is entered once, and stored in
a variable. The contents of that variable is then used to generate
both the part and the score.
substitutes the contents of @file{horn-music.ly} at this position in
the file, so @code{hornNotes} is defined afterwards. The command
@code{\transpose f@tie{}c'} indicates that the argument, being
-@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
+@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
@samp{f} is denoted by notated @code{c'}, which corresponds with
tuning of a normal French Horn in@tie{}F. The transposition can be seen
in the following output
projects / lilypond.git / commitdiff