From: Han-Wen Nienhuys Date: Sun, 5 Nov 2006 13:40:14 +0000 (+0100) Subject: Merge branch 'cvs-head' of ssh+git://hanwen@repo.or.cz/srv/git/lilypond into master... X-Git-Tag: release/2.10.0-2~32^2~17 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=3b2883eac4e40ebab564cb47fd446c3d31063bff;hp=ca4b2e1b3c7302d2a007df931bab084ed6ff31da;p=lilypond.git Merge branch 'cvs-head' of ssh+git://hanwen@repo.or.cz/srv/git/lilypond into master-hanwen --- diff --git a/ChangeLog b/ChangeLog index 1c4af2d446..f4ac0c1d11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2006-11-04 Heikki Junes + + * po/fi.po: update Finnish translation. + +2006-11-03 Graham Percival + + * Documentation/user/ {various}: rename page->spacing, + global->non-music, invoking->running, example->templates. + 2006-11-03 Nicolas Sceaux * scm/display-lily.scm: add a parser argument to display methods, diff --git a/Documentation/user/examples.itely b/Documentation/user/examples.itely deleted file mode 100644 index 3e7845709c..0000000000 --- a/Documentation/user/examples.itely +++ /dev/null @@ -1,1422 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- -@node Example templates -@appendix Example templates - -This section of the manual contains templates with the LilyPond score -already set up for you. Just add notes, run LilyPond, and enjoy -beautiful printed scores! - -@c bad node name for ancient notation to avoid confict -@menu -* Single staff:: -* Piano templates:: -* String quartet:: -* Vocal ensembles:: -* Ancient notation templates:: -* Jazz combo:: -* Lilypond-book templates:: -@end menu - - -@node Single staff -@appendixsec Single staff -@appendixsubsec Notes only - -The first example gives you a staff with notes, suitable for a solo -instrument or a melodic fragment. Cut and paste this into a file, -add notes, and you're finished! - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -melody = \relative c' { - \clef treble - \key c \major - \time 4/4 - - a4 b c d -} - -\score { - \new Staff \melody - \layout { } - \midi {} -} -@end lilypond - -@appendixsubsec Notes and lyrics - -The next example demonstrates a simple melody with lyrics. Cut and -paste, add notes, then words for the lyrics. This example turns off -automatic beaming, which is common for vocal parts. If you want to use -automatic beaming, you'll have to change or comment out the relevant -line. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -melody = \relative c' { - \clef treble - \key c \major - \time 4/4 - - a4 b c d -} - -text = \lyricmode { - Aaa Bee Cee Dee -} - -\score{ - << - \new Voice = "one" { - \autoBeamOff - \melody - } - \new Lyrics \lyricsto "one" \text - >> - \layout { } - \midi { } -} -@end lilypond - -@appendixsubsec Notes and chords - -Want to prepare a lead sheet with a melody and chords? Look no further! - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -melody = \relative c' { - \clef treble - \key c \major - \time 4/4 - - f4 e8[ c] d4 g | - a2 ~ a2 | -} - -harmonies = \chordmode { - c4:m f:min7 g:maj c:aug d2:dim b:sus -} - -\score { - << - \new ChordNames { - \set chordChanges = ##t - \harmonies - } - \new Staff \melody - >> - - \layout{ } - \midi { } -} -@end lilypond - -@appendixsubsec Notes, lyrics, and chords. - -This template allows you to prepare a song with melody, words, and chords. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -melody = \relative c' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -text = \lyricmode { - Aaa Bee Cee Dee -} - -harmonies = \chordmode { - a2 c2 -} - -\score { - << - \new ChordNames { - \set chordChanges = ##t - \harmonies - } - \new Voice = "one" { - \autoBeamOff - \melody - } - \new Lyrics \lyricsto "one" \text - >> - \layout { } - \midi { } -} -@end lilypond - -@node Piano templates -@appendixsec Piano templates -@appendixsubsec Solo piano - -Here is a simple piano staff. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -upper = \relative c'' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -lower = \relative c { - \clef bass - \key c \major - \time 4/4 - - a2 c -} - -\score { - \new PianoStaff << - \set PianoStaff.instrumentName = "Piano " - \new Staff = "upper" \upper - \new Staff = "lower" \lower - >> - \layout { } - \midi { } -} -@end lilypond - -@appendixsubsec Piano and melody with lyrics - -Here is a typical song format: one staff with the melody and lyrics, with -piano accompaniment underneath. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -melody = \relative c'' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -text = \lyricmode { - Aaa Bee Cee Dee -} - -upper = \relative c'' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -lower = \relative c { - \clef bass - \key c \major - \time 4/4 - - a2 c -} - -\score { - << - \new Voice = "mel" { - \autoBeamOff - \melody - } - \new Lyrics \lyricsto mel \text - - \new PianoStaff << - \new Staff = "upper" \upper - \new Staff = "lower" \lower - >> - >> - \layout { - \context { \RemoveEmptyStaffContext } - } - \midi { } -} -@end lilypond - - -@appendixsubsec Piano centered lyrics - -Instead of having a full staff for the melody and lyrics, you can place -the lyrics between the piano staff (and omit the separate melody staff). - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -upper = \relative c'' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -lower = \relative c { - \clef bass - \key c \major - \time 4/4 - - a2 c -} - -text = \lyricmode { - Aaa Bee Cee Dee -} - -\score { - \new GrandStaff << - \new Staff = upper { \new Voice = "singer" \upper } - \new Lyrics \lyricsto "singer" \text - \new Staff = lower { - \clef bass - \lower - } - >> - \layout { - \context { \GrandStaff \accepts "Lyrics" } - \context { \Lyrics \consists "Bar_engraver" } - } - \midi { } -} -@end lilypond - - -@appendixsubsec Piano centered dynamics - -Many piano scores have the dynamics centered between the two -staffs. This requires a bit of tweaking to implement, but -since the template is right here, you don't have to do the -tweaking yourself. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -upper = \relative c'' { - \clef treble - \key c \major - \time 4/4 - - a b c d -} - -lower = \relative c { - \clef bass - \key c \major - \time 4/4 - - a2 c -} - -dynamics = { - s2\fff\> s4 - s\!\pp -} - -pedal = { - s2\sustainDown s2\sustainUp -} - -\score { - \new PianoStaff << - \new Staff = "upper" \upper - \new Dynamics = "dynamics" \dynamics - \new Staff = "lower" << - \clef bass - \lower - >> - \new Dynamics = "pedal" \pedal - >> - \layout { - \context { - \type "Engraver_group" - \name Dynamics - \alias Voice % So that \cresc works, for example. - \consists "Output_property_engraver" - - \override VerticalAxisGroup #'minimum-Y-extent = #'(-1 . 1) - pedalSustainStrings = #'("Ped." "*Ped." "*") - pedalUnaCordaStrings = #'("una corda" "" "tre corde") - - \consists "Piano_pedal_engraver" - \consists "Script_engraver" - \consists "Dynamic_engraver" - \consists "Text_engraver" - - \override TextScript #'font-size = #2 - \override TextScript #'font-shape = #'italic - \override DynamicText #'extra-offset = #'(0 . 2.5) - \override Hairpin #'extra-offset = #'(0 . 2.5) - - \consists "Skip_event_swallow_translator" - - \consists "Axis_group_engraver" - } - \context { - \PianoStaff - \accepts Dynamics - \override VerticalAlignment #'forced-distance = #7 - } - } -} -\score { - \new PianoStaff << - \new Staff = "upper" << \upper \dynamics >> - \new Staff = "lower" << \lower \dynamics >> - \new Dynamics = "pedal" \pedal - >> - \midi { - \context { - \type "Performer_group" - \name Dynamics - \consists "Piano_pedal_performer" - } - \context { - \PianoStaff - \accepts Dynamics - } - } -} -@end lilypond - - -@node String quartet -@appendixsec String quartet -@appendixsubsec String quartet - -This template demonstrates a string quartet. It also uses a @code{\global} -section for time and key signatures. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" - -global= { - \time 4/4 - \key c \major -} - -violinOne = \new Voice { \relative c''{ - \set Staff.instrumentName = "Violin 1 " - - c2 d e1 - -\bar "|." }} -violinTwo = \new Voice { \relative c''{ - \set Staff.instrumentName = "Violin 2 " - - g2 f e1 - -\bar "|." }} -viola = \new Voice { \relative c' { - \set Staff.instrumentName = "Viola " - \clef alto - - e2 d c1 - -\bar "|." }} -cello = \new Voice { \relative c' { - \set Staff.instrumentName = "Cello " - \clef bass - - c2 b a1 - -\bar "|."}} - -\score { - \new StaffGroup << - \new Staff << \global \violinOne >> - \new Staff << \global \violinTwo >> - \new Staff << \global \viola >> - \new Staff << \global \cello >> - >> - \layout { } - \midi { } -} -@end lilypond - -@appendixsubsec String quartet parts - -The previous example produces a nice string quartet, but what if you -needed to print parts? This template demonstrates how to use the -@code{\tag} feature to easily split a piece into individual parts. - -You need to split this template into separate files; the filenames -are contained in comments at the beginning of each file. @code{piece.ly} -contains all the music definitions. The other files -- @code{score.ly}, -@code{vn1.ly}, @code{vn2.ly}, @code{vla.ly}, and -@code{vlc.ly} -- produce the appropiate part. - -@verbatim -%%%%% piece.ly -\version "2.9.13" - -global= { - \time 4/4 - \key c \major -} - -Violinone = \new Voice { \relative c''{ - \set Staff.instrumentName = "Violin 1 " - - c2 d e1 - -\bar "|." }} %********************************* -Violintwo = \new Voice { \relative c''{ - \set Staff.instrumentName = "Violin 2 " - - g2 f e1 - -\bar "|." }} %********************************* -Viola = \new Voice { \relative c' { - \set Staff.instrumentName = "Viola " - \clef alto - - e2 d c1 - -\bar "|." }} %********************************* -Cello = \new Voice { \relative c' { - \set Staff.instrumentName = "Cello " - \clef bass - - c2 b a1 - -\bar "|."}} %********************************** - -music = { - << - \tag #'score \tag #'vn1 \new Staff { << \global \Violinone >> } - \tag #'score \tag #'vn2 \new Staff { << \global \Violintwo>> } - \tag #'score \tag #'vla \new Staff { << \global \Viola>> } - \tag #'score \tag #'vlc \new Staff { << \global \Cello>> } - >> -} - - - -%%%%% score.ly -\version "2.9.13" -\include "piece.ly" -#(set-global-staff-size 14) -\score { - \new StaffGroup \keepWithTag #'score \music - \layout { } - \midi { } -} - - -%%%%% vn1.ly -\version "2.9.13" -\include "piece.ly" -\score { - \keepWithTag #'vn1 \music - \layout { } -} - - -%%%%% vn2.ly -\version "2.9.13" -\include "piece.ly" -\score { - \keepWithTag #'vn2 \music - \layout { } -} - - -%%%%% vla.ly -\version "2.9.13" -\include "piece.ly" -\score { - \keepWithTag #'vla \music - \layout { } -} - - -%%%%% vlc.ly -\version "2.9.13" -\include "piece.ly" -\score { - \keepWithTag #'vlc \music - \layout { } -} -@end verbatim - - -@node Vocal ensembles -@appendixsec Vocal ensembles - -@appendixsubsec SATB vocal score - -Here is a standard four-part SATB vocal score. With larger ensembles, -it's often useful to include a section which is included in all -parts. For example, the time signature and key signatures are almost -always the same for all parts. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -global = { - \key c \major - \time 4/4 -} - -sopMusic = \relative c'' { - c4 c c8[( b)] c4 -} -sopWords = \lyricmode { - hi hi hi hi -} - -altoMusic = \relative c' { - e4 f d e -} -altoWords =\lyricmode { - ha ha ha ha -} - -tenorMusic = \relative c' { - g4 a f g -} -tenorWords = \lyricmode { - hu hu hu hu -} - -bassMusic = \relative c { - c4 c g c -} -bassWords = \lyricmode { - ho ho ho ho -} - -\score { - \new ChoirStaff << - \new Lyrics = sopranos { s1 } - \new Staff = women << - \new Voice = - "sopranos" { \voiceOne << \global \sopMusic >> } - \new Voice = - "altos" { \voiceTwo << \global \altoMusic >> } - >> - \new Lyrics = "altos" { s1 } - \new Lyrics = "tenors" { s1 } - \new Staff = men << - \clef bass - \new Voice = - "tenors" { \voiceOne <<\global \tenorMusic >> } - \new Voice = - "basses" { \voiceTwo <<\global \bassMusic >> } - >> - \new 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 - >> - - \layout { - \context { - % a little smaller so lyrics - % can be closer to the staff - \Staff - \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) - } - } -} -@end lilypond - - -@appendixsubsec SATB vocal score and automatic piano reduction - -This template adds an automatic piano reduction to the SATB vocal -score. This demonstrates one of the strengths of LilyPond -- you -can use a music definition more than once. If you make any changes -to the vocal notes (say, tenorMusic), then the changes will also -apply to the piano reduction. - -@lilypond[quote,verbatim,ragged-right] -\version "2.9.13" -global = { - \key c \major - \time 4/4 -} - -sopMusic = \relative c'' { - c4 c c8[( b)] c4 -} -sopWords = \lyricmode { - hi hi hi hi -} - -altoMusic = \relative c' { - e4 f d e -} -altoWords =\lyricmode { - ha ha ha ha -} - -tenorMusic = \relative c' { - g4 a f g -} -tenorWords = \lyricmode { - hu hu hu hu -} - -bassMusic = \relative c { - c4 c g c -} -bassWords = \lyricmode { - ho ho ho ho -} - -\score { - << - \new ChoirStaff << - \new Lyrics = sopranos { s1 } - \new Staff = women << - \new Voice = - "sopranos" { \voiceOne << \global \sopMusic >> } - \new Voice = - "altos" { \voiceTwo << \global \altoMusic >> } - >> - \new Lyrics = "altos" { s1 } - \new Lyrics = "tenors" { s1 } - \new Staff = men << - \clef bass - \new Voice = - "tenors" { \voiceOne <<\global \tenorMusic >> } - \new Voice = - "basses" { \voiceTwo <<\global \bassMusic >> } - >> - \new 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 - >> - \new PianoStaff << - \new Staff << - \set Staff.printPartCombineTexts = ##f - \partcombine - << \global \sopMusic >> - << \global \altoMusic >> - >> - \new Staff << - \clef bass - \set Staff.printPartCombineTexts = ##f - \partcombine - << \global \tenorMusic >> - << \global \bassMusic >> - >> - >> - >> - \layout { - \context { - % a little smaller so lyrics - % can be closer to the staff - \Staff - \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) - } - } -} -@end lilypond - - -@c bad node name to avoid node name confict -@node Ancient notation templates -@appendixsec Ancient notation templates - -@appendixsubsec Transcription of mensural music - -When transcribing mensural music, an incipit at the beginning of the -piece is useful to indicate the original key and tempo. While today -musicians are used to bar lines in order to faster recognize rhythmic -patterns, bar lines were not yet invented during the period of -mensural music; in fact, the meter often changed after every few -notes. As a compromise, bar lines are often printed between the -staves rather than on the staves. - -@lilypond[quote,verbatim,line-width=11.0\cm] -\version "2.9.13" - -global = { - \set Score.skipBars = ##t - - % incipit - \once \override Score.SystemStartBracket #'transparent = ##t - \override Score.SpacingSpanner #'spacing-increment = #1.0 % tight spacing - \key f \major - \time 2/2 - \once \override Staff.TimeSignature #'style = #'neomensural - \override Voice.NoteHead #'style = #'neomensural - \override Voice.Rest #'style = #'neomensural - \set Staff.printKeyCancellation = ##f - \cadenzaOn % turn off bar lines - \skip 1*10 - \once \override Staff.BarLine #'transparent = ##f - \bar "||" - \skip 1*1 % need this extra \skip such that clef change comes - % after bar line - \bar "" - - % main - \revert Score.SpacingSpanner #'spacing-increment % CHECK: no effect? - \cadenzaOff % turn bar lines on again - \once \override Staff.Clef #'full-size-change = ##t - \set Staff.forceClef = ##t - \key g \major - \time 4/4 - \override Voice.NoteHead #'style = #'default - \override Voice.Rest #'style = #'default - - % FIXME: setting printKeyCancellation back to #t must not - % occur in the first bar after the incipit. Dto. for forceClef. - % Therefore, we need an extra \skip. - \skip 1*1 - \set Staff.printKeyCancellation = ##t - \set Staff.forceClef = ##f - - \skip 1*7 % the actual music - - % let finis bar go through all staves - \override Staff.BarLine #'transparent = ##f - - % finis bar - \bar "|." -} - -discantusNotes = { - \transpose c' c'' { - \set Staff.instrumentName = "Discantus " - - % incipit - \clef "neomensural-c1" - c'1. s2 % two bars - \skip 1*8 % eight bars - \skip 1*1 % one bar - - % main - \clef "treble" - d'2. d'4 | - b e' d'2 | - c'4 e'4.( d'8 c' b | - a4) b a2 | - b4.( c'8 d'4) c'4 | - \once \override NoteHead #'transparent = ##t c'1 | - b\breve | - } -} - -discantusLyrics = \lyricmode { - % incipit - IV- - - % main - Ju -- bi -- | - la -- te De -- | - o, om -- - nis ter -- | - ra, __ om- | - "..." | - -us. | -} - -altusNotes = { - \transpose c' c'' { - \set Staff.instrumentName = "Altus " - - % incipit - \clef "neomensural-c3" - r1 % one bar - f1. s2 % two bars - \skip 1*7 % seven bars - \skip 1*1 % one bar - - % main - \clef "treble" - r2 g2. e4 fis g | % two bars - a2 g4 e | - fis g4.( fis16 e fis4) | - g1 | - \once \override NoteHead #'transparent = ##t g1 | - g\breve | - } -} - -altusLyrics = \lyricmode { - % incipit - IV- - - % main - Ju -- bi -- la -- te | % two bars - De -- o, om -- | - nis ter -- ra, | - "..." | - -us. | -} - -tenorNotes = { - \transpose c' c' { - \set Staff.instrumentName = "Tenor " - - % incipit - \clef "neomensural-c4" - r\longa % four bars - r\breve % two bars - r1 % one bar - c'1. s2 % two bars - \skip 1*1 % one bar - \skip 1*1 % one bar - - % main - \clef "treble_8" - R1 | - R1 | - R1 | - r2 d'2. d'4 b e' | % two bars - \once \override NoteHead #'transparent = ##t e'1 | - d'\breve | - } -} - -tenorLyrics = \lyricmode { - % incipit - IV- - - % main - Ju -- bi -- la -- te | % two bars - "..." | - -us. | -} - -bassusNotes = { - \transpose c' c' { - \set Staff.instrumentName = "Bassus " - - % incipit - \clef "bass" - r\maxima % eight bars - f1. s2 % two bars - \skip 1*1 % one bar - - % main - \clef "bass" - R1 | - R1 | - R1 | - R1 | - g2. e4 | - \once \override NoteHead #'transparent = ##t e1 | - g\breve | - } -} - -bassusLyrics = \lyricmode { - % incipit - IV- - - % main - Ju -- bi- | - "..." | - -us. | -} - -\score { - \new StaffGroup = choirStaff << - \new Voice = - "discantusNotes" << \global \discantusNotes >> - \new Lyrics = - "discantusLyrics" \lyricsto discantusNotes { \discantusLyrics } - \new Voice = - "altusNotes" << \global \altusNotes >> - \new Lyrics = - "altusLyrics" \lyricsto altusNotes { \altusLyrics } - \new Voice = - "tenorNotes" << \global \tenorNotes >> - \new Lyrics = - "tenorLyrics" \lyricsto tenorNotes { \tenorLyrics } - \new Voice = - "bassusNotes" << \global \bassusNotes >> - \new Lyrics = - "bassusLyrics" \lyricsto bassusNotes { \bassusLyrics } - >> - \layout { - \context { - \Score - - % no bars in staves - \override BarLine #'transparent = ##t - - % incipit should not start with a start delimiter - \remove "System_start_delimiter_engraver" - } - \context { - \Voice - - % no slurs - \override Slur #'transparent = ##t - - % Comment in the below "\remove" command to allow line - % breaking also at those barlines where a note overlaps - % into the next bar. The command is commented out in this - % short example score, but especially for large scores, you - % will typically yield better line breaking and thus improve - % overall spacing if you comment in the following command. - %\remove "Forbid_line_break_engraver" - } - } -} -@end lilypond - - -@appendixsubsec Gregorian transcription template - -This example demonstrates how to do modern transcription of Gregorian -music. Gregorian music has no measure, no stems; it uses only half and -quarter noteheads, and special marks, indicating rests of different length. - -@lilypond[quote,verbatim,ragged-right] -\include "gregorian-init.ly" -\version "2.9.13" - -chant = \relative c' { - \set Score.timing = ##f - f4 a2 \divisioMinima - g4 b a2 f2 \divisioMaior - g4( f) f( g) a2 \finalis -} - -verba = \lyricmode { - Lo -- rem ip -- sum do -- lor sit a -- met -} - -\score { - \new Staff << - \new Voice = "melody" { - \chant - } - \new Lyrics = "one" \lyricsto melody \verba - >> - - \layout { - \context { - \Staff - \remove "Time_signature_engraver" - \remove "Bar_engraver" - \override Stem #'transparent = ##t - } - \context { - \Voice - \override Stem #'length = #0 - } - \context { - \Score - barAlways = ##t - } - } -} -@end lilypond - - -@node Jazz combo -@appendixsec Jazz combo - -This is a much more complicated template, for a jazz ensemble. Note that all -instruments are notated in @code{\key c \major}. This refers to the key in -concert pitch; LilyPond will automatically transpose the key if the music -is within a @code{\transpose} section. - -@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. -@c - maybe ask Amelie Zapf to clean it up, or whether I should just -@c make whatever changes I feel like. - -@c FIXME: produces a warning ; key change merge. -@c The `line-width' argument is for the \header. - -@lilypond[quote,verbatim,ragged-right,line-width] -\version "2.9.13" -\header { - title = "Song" - subtitle = "(tune)" - composer = "Me" - meter = "moderato" - piece = "Swing" - tagline = \markup { - \column { - "LilyPond example file by Amelie Zapf," - "Berlin 07/07/2003" - } - } - texidoc = "Jazz tune for combo - (horns, guitar, piano, bass, drums)." -} - -#(set-global-staff-size 16) -\include "english.ly" - -%%%%%%%%%%%% Some macros %%%%%%%%%%%%%%%%%%% - -sl = { - \override NoteHead #'style = #'slash - \override Stem #'transparent = ##t -} -nsl = { - \revert NoteHead #'style - \revert Stem #'transparent -} -cr = \override NoteHead #'style = #'cross -ncr = \revert NoteHead #'style - -%% insert chord name style stuff here. - -jzchords = { } - - -%%%%%%%%%%%% Keys'n'thangs %%%%%%%%%%%%%%%%% - -global = { - \time 4/4 -} - -Key = { \key c \major } - -% ############ Horns ############ - -% ------ Trumpet ------ -trpt = \transpose c d \relative c'' { - \Key - c1 c c -} -trpharmony = \transpose c' d { - \jzchords -} -trumpet = { - \global - \set Staff.instrumentName = #"Trumpet" - \clef treble - << - \trpt - >> -} - -% ------ Alto Saxophone ------ -alto = \transpose c a \relative c' { - \Key - c1 c c -} -altoharmony = \transpose c' a { - \jzchords -} -altosax = { - \global - \set Staff.instrumentName = #"Alto Sax" - \clef treble - << - \alto - >> -} - -% ------ Baritone Saxophone ------ -bari = \transpose c a' \relative c { - \Key - c1 c \sl d4^"Solo" d d d \nsl -} -bariharmony = \transpose c' a \chordmode { - \jzchords s1 s d2:maj e:m7 -} -barisax = { - \global - \set Staff.instrumentName = #"Bari Sax" - \clef treble - << - \bari - >> -} - -% ------ Trombone ------ -tbone = \relative c { - \Key - c1 c c -} -tboneharmony = \chordmode { - \jzchords -} -trombone = { - \global - \set Staff.instrumentName = #"Trombone" - \clef bass - << - \tbone - >> -} - -% ############ Rhythm Section ############# - -% ------ Guitar ------ -gtr = \relative c'' { - \Key - c1 \sl b4 b b b \nsl c1 -} -gtrharmony = \chordmode { - \jzchords - s1 c2:min7+ d2:maj9 -} -guitar = { - \global - \set Staff.instrumentName = #"Guitar" - \clef treble - << - \gtr - >> -} - -%% ------ Piano ------ -rhUpper = \relative c'' { - \voiceOne - \Key - c1 c c -} -rhLower = \relative c' { - \voiceTwo - \Key - e1 e e -} - -lhUpper = \relative c' { - \voiceOne - \Key - g1 g g -} -lhLower = \relative c { - \voiceTwo - \Key - c1 c c -} - -PianoRH = { - \clef treble - \global - \set Staff.midiInstrument = "acoustic grand" - << - \new Voice = "one" \rhUpper - \new Voice = "two" \rhLower - >> -} -PianoLH = { - \clef bass - \global - \set Staff.midiInstrument = "acoustic grand" - << - \new Voice = "one" \lhUpper - \new Voice = "two" \lhLower - >> -} - -piano = { - << - \set PianoStaff.instrumentName = #"Piano" - \new Staff = "upper" \PianoRH - \new Staff = "lower" \PianoLH - >> -} - -% ------ Bass Guitar ------ -Bass = \relative c { - \Key - c1 c c -} -bass = { - \global - \set Staff.instrumentName = #"Bass" - \clef bass - << - \Bass - >> -} - -% ------ Drums ------ -up = \drummode { - hh4 4 hh hh 4 - hh4 4 - hh4 4 - hh4 4 -} - -down = \drummode { - bd4 s bd s bd s bd s bd s bd s -} - -drumContents = { - \global - << - \set DrumStaff.instrumentName = #"Drums" - \new DrumVoice { \voiceOne \up } - \new DrumVoice { \voiceTwo \down } - >> -} - -%%%%%%%%% It All Goes Together Here %%%%%%%%%%%%%%%%%%%%%% - -\score { - << - \new StaffGroup = "horns" << - \new Staff = "trumpet" \trumpet - \new Staff = "altosax" \altosax - \new ChordNames = "barichords" \bariharmony - \new Staff = "barisax" \barisax - \new Staff = "trombone" \trombone - >> - - \new StaffGroup = "rhythm" << - \new ChordNames = "chords" \gtrharmony - \new Staff = "guitar" \guitar - \new PianoStaff = "piano" \piano - \new Staff = "bass" \bass - \new DrumStaff { \drumContents } - >> - >> - - \layout { - \context { \RemoveEmptyStaffContext } - \context { - \Score - \override BarNumber #'padding = #3 - \override RehearsalMark #'padding = #2 - skipBars = ##t - } - } - - \midi { } -} -@end lilypond - -@ignore - -This isn't very useful, and only duplicates material in -"global issues". And if this info changes, this section often -gets forgotten. - -@no de Other templates -@se ction Other templates -@su bsection All headers - -This template displays all available headers. Some of them are only -used in the Mutopia project; they don't affect the printed output at -all. They are used if you want the piece to be listed with different -information in the Mutopia database than you wish to have printed on the -music. For example, Mutopia lists the composer of the famous D major -violin concerto as TchaikovskyPI, whereas perhaps you wish to print -"Petr Tchaikowski" on your music. - -@ The `line-width' is for \header. -@li lypond[quote,verbatim,ragged-right,line-width] -\version "2.9.13" -\header { - dedication = "dedication" - title = "Title" - subtitle = "Subtitle" - subsubtitle = "Subsubtitle" - composer = "Composer (xxxx-yyyy)" - opus = "Opus 0" - piece = "Piece I" - meter = "meter" - 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 { - { c'4 } - \header { - piece = "piece1" - opus = "opus1" - } -} - -\score { - { c'4 } - \header { - piece = "piece2" - opus = "opus2" - } -} -@end lilypond -@end ignore - - -@node Lilypond-book templates -@appendixsec Lilypond-book templates - -These templates are for use with @code{lilypond-book}. If you're not familiar -with this program, please refer to @ref{LilyPond-book}. - -@appendixsubsec LaTeX - -You can include LilyPond fragments in a LaTeX document. - -@example -\documentclass[]@{article@} - -\begin@{document@} - -Normal LaTeX text. - -\begin@{lilypond@} -\relative c'' @{ -a4 b c d -@} -\end@{lilypond@} - -More LaTeX text. - -\begin@{lilypond@} -\relative c'' @{ -d4 c b a -@} -\end@{lilypond@} -\end@{document@} -@end example - -@appendixsubsec Texinfo - -You can include LilyPond fragments in Texinfo; in fact, this entire manual -is written in Texinfo. - -@example -\input texinfo -@@node Top - -Texinfo text - -@@lilypond[verbatim,fragment,ragged-right] -a4 b c d -@@end lilypond - -More Texinfo text - -@@lilypond[verbatim,fragment,ragged-right] -d4 c b a -@@end lilypond - -@@bye -@end example diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely deleted file mode 100644 index bd2596410d..0000000000 --- a/Documentation/user/global.itely +++ /dev/null @@ -1,958 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- -@c This file is part of lilypond.tely - -@c A menu is needed before every deeper *section nesting of @node's; run -@c M-x texinfo-all-menus-update -@c to automatically fill in these menus before saving changes - -@node Non-musical notation -@chapter Non-musical notation - -This section deals with general lilypond issues, rather than -specific notation. - -@menu -* Input files:: -* Titles and headers:: -* MIDI output:: -* Displaying LilyPond notation:: -* Skipping corrected music:: -@end menu - - -@node Input files -@section Input files - -The main format of input for LilyPond are text files. By convention, -these files end with ``@code{.ly}''. - -@menu -* File structure (introduction):: -* Multiple scores in a book:: -* Extracting fragments of notation:: -* File structure:: -* A single music expression:: -* Including LilyPond files:: -* Text encoding:: -@end menu - - -@node File structure (introduction) -@subsection File structure (introduction) - -A basic example of a lilypond input file is - -@example -\version "2.9.13" -\score @{ - @{ @} % this is a single music expression; - % all the music goes in here. - \header @{ @} - \layout @{ @} - \midi @{ @} -@} -@end example - -@noindent -There are many variations of this basic pattern, but this -example serves as a useful starting place. - -The major part of this manual is concerned with entering various -forms of music in LilyPond. However, many music expressions are not -valid input on their own, for example, a @code{.ly} file containing -only a note -@example -c'4 -@end example - -@noindent -will result in a parsing error. Instead, music should be inside other -expressions, which may be put in a file by themselves. Such -expressions are called toplevel expressions. The next section enumerates -them all. - - -@node Multiple scores in a book -@subsection Multiple scores in a book - -@funindex \book -@cindex movements, multiple - -A document may contain multiple pieces of music and texts. Examples -of these are an etude book, or an orchestral part with multiple -movements. Each movement is entered with a @code{\score} block, - -@example -\score @{ - @var{..music..} -@} -@end example - -and texts are entered with a @code{\markup} block, - -@example -\markup @{ - @var{..text..} -@} -@end example - -@funindex \book - -The movements and texts are combined together in a @code{\book} block, -like - -@example -\book @{ - \score @{ - @var{..} - @} - \markup @{ - @var{..} - @} - \score @{ - @var{..} - @} -@} -@end example - - -The header for each piece of music can be put inside the @code{\score} -block. The @code{piece} name from the header will be printed before -each movement. The title for the entire book can be put inside the -@code{\book}, but if it is not present, the @code{\header} which is at -the top of the file is inserted. - -@example -\book @{ - \header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" - @} - \score @{ - @dots{} - \header @{ piece = "Romanze" @} - @} - \markup @{ - ..text of second verse.. - @} - \markup @{ - ..text of third verse.. - @} - \score @{ - @dots{} - \header @{ piece = "Menuetto" @} - @} -@} -@end example - -@node Extracting fragments of notation -@subsection Extracting fragments of notation - -It is possible to quote small fragments of a large score directly from -the output. This can be compared to clipping a piece of a paper score -with scissors. - -This is done by definining the measures that need to be cut out -separately. For example, including the following definition - - -@verbatim -\layout { - clip-regions - = #(list - (cons - (make-rhythmic-location 5 1 2) - (make-rhythmic-location 7 3 4))) -} -@end verbatim - -@noindent -will extract a fragment starting halfway the fifth measure, ending in -the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note -in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7. - -More clip regions can be defined by adding more pairs of -rhythmic-locations to the list. - -In order to use this feature, LilyPond must be invoked with -@code{-dclip-systems}. The clips are output as EPS files, and are -converted to PDF and PNG if these formats are switched on as well. - -For more information on output formats, see @ref{Invoking lilypond}. - -@seealso - -Examples: @inputfileref{input/regression/,clip-systems.ly} - - -@node File structure -@subsection File structure - -A @code{.ly} file contains any number of toplevel expressions, where a -toplevel expression is one of the following - -@itemize @bullet -@item -An output definition, such as @code{\paper}, @code{\midi}, and -@code{\layout}. Such a definition at the toplevel changes the default -settings for the block entered. - -@item -A direct scheme expression, such as -@code{#(set-default-paper-size "a7" 'landscape)} or -@code{#(ly:set-option 'point-and-click #f)}. - -@item -A @code{\header} block. This sets the global header block. This -is the block containing the definitions for book-wide settings, like -composer, title, etc. - -@item -A @code{\score} block. This score will be collected with other -toplevel scores, and combined as a single @code{\book}. - -This behavior can be changed by setting the variable -@code{toplevel-score-handler} at toplevel. The default handler is -defined in the init file @file{scm/@/lily@/.scm}. - -The @code{\score} must begin with a music expression, and may -contain only one music expression. - -@item -A @code{\book} block logically combines multiple movements -(i.e., multiple @code{\score} blocks) in one document. If there are -a number of @code{\scores}, a single output file will be created -in which all movements are concatenated. - -This behavior can be changed by setting the variable -@code{toplevel-book-handler} at toplevel. The default handler is -defined in the init file @file{scm/@/lily@/.scm}. - -@item -A compound music expression, such as -@example -@{ c'4 d' e'2 @} -@end example - -This will add the piece in a @code{\score} and format it in a -single book together with all other toplevel @code{\score}s and music -expressions. In other words, a file containing only the above -music expression will be translated into - -@example -\book @{ - \score @{ - \new Staff @{ - \new Voice @{ - @{ c'4 d' e'2 @} - @} - @} - @} - \layout @{ @} - \header @{ @} -@} -@end example - -This behavior can be changed by setting the variable -@code{toplevel-music-handler} at toplevel. The default handler is -defined in the init file @file{scm/@/lily@/.scm}. - -@item -A markup text, a verse for example -@example -\markup @{ - 2. The first line verse two. -@} -@end example - -Markup texts are rendered above, between or below the scores or music -expressions, wherever they appear. - -@item -An identifier, such as -@example -foo = @{ c4 d e d @} -@end example - -This can be used later on in the file by entering @code{\foo}. The -name of an identifier should have alphabetic characters only; no -numbers, underscores or dashes. - -@end itemize - -The following example shows three things that may be entered at -toplevel - -@example -\layout @{ - % movements are non-justified by default - ragged-right = ##t -@} - -\header @{ - title = "Do-re-mi" -@} - -@{ c'4 d' e2 @} -@end example - - -At any point in a file, any of the following lexical instructions can -be entered: - -@itemize @bullet -@item @code{\version} -@item @code{\include} -@item @code{\sourcefilename} -@item @code{\sourcefileline} - -@end itemize - - -@node A single music expression -@subsection A single music expression - -A @code{\score} must contain a single music expression. However, -this music expression may be of any size. Recall that music -expressions may be included inside other expressions to form -larger expressions. All of these examples are single music -expressions; note the curly braces @{ @} or angle brackets << ->> at the beginning and ending of the music. - -@example -@{ c'4 c' c' c' @} -@end example - -@lilypond[ragged-right,verbatim,quote] -{ - { c'4 c' c' c'} - { d'4 d' d' d'} -} -@end lilypond - -@lilypond[ragged-right,verbatim,quote] -<< - \new Staff { c'4 c' c' c' } - \new Staff { d'4 d' d' d' } ->> -@end lilypond - -@example -@{ - \new GrandStaff << - \new StaffGroup << - \new Staff @{ \flute @} - \new Staff @{ \oboe @} - >> - \new StaffGroup << - \new Staff @{ \violinI @} - \new Staff @{ \violinII @} - >> - >> -@} -@end example - - -@node Including LilyPond files -@subsection Including LilyPond files - -@funindex \include -@cindex including files - -A large project may be split up into separate files. To refer to another -file, use - -@example -\include "otherfile.ly" -@end example - -The line @code{\include "file.ly"} is equivalent to pasting the contents -of file.ly into the current file at the place where you have the -\include. For example, for a large project you might write separate files -for each instrument part and create a ``full score'' file which brings -together the individual instrument files. - -The initialization of LilyPond is done in a number of files that are -included by default when you start the program, normally transparent to the -user. Run lilypond --verbose to see a list of paths and files that Lily -finds. - -Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where -VERSION is in the form ``2.6.1'') are on the path and available to -@code{\include}. Files in the -current working directory are available to \include, but a file of the same -name in LilyPond's installation takes precedence. Files are -available to \include from directories in the search path specified as an -option when invoking @code{lilypond --include=DIR} which adds DIR to the -search path. - -The @code{\include} statement can use full path information, but with the Unix -convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example, -if @file{stuff.ly} is located one directory higher than the current working -directory, use - -@example -\include "../stuff.ly" -@end example - - -@node Text encoding -@subsection Text encoding - -LilyPond uses the Pango library to format multi-lingual texts, and -does not perform any input-encoding conversions. This means that any -text, be it title, lyric text, or musical instruction containing -non-ASCII characters, must be utf-8. The easiest way to enter such text is -by using a Unicode-aware editor and saving the file with utf-8 encoding. Most -popular modern editors have utf-8 support, for example, vim, Emacs, -jEdit, and GEdit do. - -@c Currently not working -@ignore -Depending on the fonts installed, the following fragment shows Hebrew -and Cyrillic lyrics, - -@cindex Cyrillic -@cindex Hebrew -@cindex ASCII, non - -@li lypondfile[fontload]{utf-8.ly} - -The @TeX{} backend does not handle encoding specially at all. Strings -in the input are put in the output as-is. Extents of text items in the -@TeX{} backend, are determined by reading a file created via the -@file{texstr} backend, - -@example -lilypond -b texstr input/les-nereides.ly -latex les-nereides.texstr -@end example - -The last command produces @file{les-nereides.textmetrics}, which is -read when you execute - -@example -lilypond -b tex input/les-nereides.ly -@end example - -Both @file{les-nereides.texstr} and @file{les-nereides.tex} need -suitable LaTeX wrappers to load appropriate La@TeX{} packages for -interpreting non-ASCII strings. - -@end ignore - -To use a Unicode escape sequence, use - -@example -#(ly:export (ly:wide-char->utf-8 #x2014)) -@end example - - -@seealso - -@inputfileref{input/regression,utf-8.ly} - - - -@node Titles and headers -@section Titles and headers - -Almost all printed music includes a title and the composer's name; -some pieces include a lot more information. - -@menu -* Creating titles:: -* Custom titles:: -@end menu - - -@node Creating titles -@subsection Creating titles - -Titles are created for each @code{\score} block, and over a -@code{\book}. - -The contents of the titles are taken from the @code{\header} blocks. -The header block for a book supports the following - - -@table @code -@funindex dedication -@item dedication -The dedicatee of the music, centered at the top of the first page. - -@funindex title -@item title -The title of the music, centered just below the dedication. - -@funindex subtitle -@item subtitle -Subtitle, centered below the title. - -@funindex subsubtitle -@item subsubtitle -Subsubtitle, centered below the subtitle. - -@funindex poet -@item poet -Name of the poet, flush-left below the subtitle. - -@funindex composer -@item composer -Name of the composer, flush-right below the subtitle. - -@funindex meter -@item meter -Meter string, flush-left below the poet. - -@funindex opus -@item opus -Name of the opus, flush-right below the composer. - -@funindex arranger -@item arranger -Name of the arranger, flush-right below the opus. - -@funindex instrument -@item instrument -Name of the instrument, centered below the arranger. Also -centered at the top of pages (other than the first page). - -@funindex piece -@item piece -Name of the piece, flush-left below the instrument. - -@cindex page breaks, forcing -@funindex breakbefore -@item breakbefore -This forces the title to start on a new page (set to ##t or ##f). - -@funindex copyright -@item copyright -Copyright notice, centered at the bottom of the first page. To -insert the copyright symbol, see @ref{Text encoding}. - -@funindex tagline -@item tagline -Centered at the bottom of the last page. - -@end table - -Here is a demonstration of the fields available. Note that you -may use any @ref{Text markup} commands in the header. - -@lilypond[quote,verbatim,line-width=11.0\cm] -\paper { - line-width = 9.0\cm - paper-height = 10.0\cm -} - -\book { - \header { - dedication = "dedicated to me" - title = \markup \center-align { "Title first line" "Title second line, -longer" } - subtitle = "the subtitle," - subsubtitle = #(string-append "subsubtitle LilyPond version " -(lilypond-version)) - poet = "Poet" - composer = \markup \center-align { "composer" \small "(1847-1973)" } - texttranslator = "Text Translator" - meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge -"r" } - arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize -#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" } - instrument = \markup \bold \italic "instrument" - piece = "Piece" - } - - \score { - { c'1 } - \header { - piece = "piece1" - opus = "opus1" - } - } - \markup { - and now... - } - \score { - { c'1 } - \header { - piece = "piece2" - opus = "opus2" - } - } -} -@end lilypond - -As demonstrated before, you can use multiple @code{\header} blocks. -When same fields appear in different blocks, the latter is used. -Here is a short example. - -@example -\header @{ - composer = "Composer" -@} -\header @{ - piece = "Piece" -@} -\score @{ - \new Staff @{ c'4 @} - \header @{ - piece = "New piece" % overwrite previous one - @} -@} -@end example - -If you define the @code{\header} inside the @code{\score} block, then -normally only the @code{piece} and @code{opus} headers will be printed. -Note that the music expression must come before the @code{\header}. - -@lilypond[quote,verbatim,line-width=11.0\cm] -\score { - { c'4 } - \header { - title = "title" % not printed - piece = "piece" - opus = "opus" - } -} -@end lilypond - -@funindex printallheaders -@noindent -You may change this behavior (and print all the headers when defining -@code{\header} inside @code{\score}) by using - -@example -\paper@{ - printallheaders=##t -@} -@end example - -@cindex copyright -@cindex tagline - -The default footer is empty, except for the first page, where the -@code{copyright} field from @code{\header} is inserted, and the last -page, where @code{tagline} from @code{\header} is added. The default -tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely -printed parts are good PR for us, so please leave the tagline if you -can.} - -Headers may be completely removed by setting them to false. - -@example -\header @{ - tagline = ##f - composer = ##f -@} -@end example - - -@node Custom titles -@subsection Custom titles - -A more advanced option is to change the definitions of the following -variables in the @code{\paper} block. The init file -@file{ly/titling-init.ly} lists the default layout. - -@table @code -@funindex bookTitleMarkup -@item bookTitleMarkup - This is the title put over an entire @code{\book} block. Typically, - it has the composer and the title of the piece - -@funindex scoreTitleMarkup -@item scoreTitleMarkup - This is the title put over a @code{\score} block within a -@code{\book}. Typically, it has the name of the movement (@code{piece} -field). - -@funindex oddHeaderMarkup -@item oddHeaderMarkup - This is the page header for odd-numbered pages. - -@funindex evenHeaderMarkup -@item evenHeaderMarkup - This is the page header for even-numbered pages. If unspecified, - the odd header is used instead. - - By default, headers are defined such that the page number is on the - outside edge, and the instrument is centered. - -@funindex oddFooterMarkup -@item oddFooterMarkup - This is the page footer for odd-numbered pages. - -@funindex evenFotterMarkup -@item evenFooterMarkup - This is the page footer for even-numbered pages. If unspecified, - the odd header is used instead. - - By default, the footer has the copyright notice on the first, and - the tagline on the last page. -@end table - - -@cindex \paper -@cindex header -@cindex footer -@cindex page layout -@cindex titles - -The following definition will put the title flush left, and the -composer flush right on a single line. - -@verbatim -\paper { - bookTitleMarkup = \markup { - \fill-line { - \fromproperty #'header:title - \fromproperty #'header:composer - } - } -} -@end verbatim - - - -@node MIDI output -@section MIDI output - -@cindex Sound -@cindex MIDI - -MIDI (Musical Instrument Digital Interface) is a standard for -connecting and controlling digital instruments. A MIDI file is a -series of notes in a number of tracks. It is not an actual -sound file; you need special software to translate between the -series of notes and actual sounds. - -Pieces of music can be converted to MIDI files, so you can listen to -what was entered. This is convenient for checking the music; octaves -that are off or accidentals that were mistyped stand out very much -when listening to the MIDI output. - -@refbugs - -Many musically interesting effects, such as swing, articulation, -slurring, etc., are not translated to midi. - -The midi output allocates a channel for each staff, and one for global -settings. Therefore the midi file should not have more than 15 staves -(or 14 if you do not use drums). Other staves will remain silent. - -Not all midi players correctly handle tempo changes in the midi -output. Players that are known to work include -@uref{http://@/timidity@/.sourceforge@/.net/,timidity}. - -@menu -* Creating MIDI files:: -* MIDI block:: -* MIDI instrument names:: -@end menu - -@node Creating MIDI files -@subsection Creating MIDI files - -To create a MIDI from a music piece of music, add a @code{\midi} block -to a score, for example, - -@example -\score @{ - @var{...music...} - \midi @{ @} -@} -@end example - -FIXME - -The tempo is specified using the @code{\tempo} command. In this -example the tempo of quarter notes is set to 72 beats per minute. - - -If there is a @code{\midi} command in a @code{\score}, only MIDI will -be produced. When notation is needed too, a @code{\layout} block must -be added - -@example -\score @{ - @var{...music...} - \midi @{ @} - \layout @{ @} -@} -@end example -@cindex layout block - - - -Ties, dynamics, and tempo changes are interpreted. Dynamic marks, -crescendi and decrescendi translate into MIDI volume levels. Dynamic -marks translate to a fixed fraction of the available MIDI volume -range, crescendi and decrescendi make the volume vary linearly between -their two extremes. The fractions can be adjusted by -@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. -For each type of MIDI instrument, a volume range can be defined. This -gives a basic equalizer control, which can enhance the quality of -the MIDI output remarkably. The equalizer can be controlled by -setting @code{instrumentEqualizer}, or by setting - -@example -\set Staff.midiMinimumVolume = #0.2 -\set Staff.midiMaximumVolume = #0.8 -@end example - -To remove dynamics from the MIDI output, insert the following lines -in the @code{\midi@{@}} section. - -@example -\midi @{ - ... - \context @{ - \Voice - \remove "Dynamic_performer" - \remove "Span_dynamic_performer" - @} -@} -@end example - - -@refbugs - -Unterminated (de)crescendos will not render properly in the midi file, -resulting in silent passages of music. The workaround is to explicitly -terminate the (de)crescendo. For example, - -@example -@{ a\< b c d\f @} -@end example - -@noindent -will not work properly but - -@example -@{ a\< b c d\!\f @} -@end example - -@noindent -will. - - -@node MIDI block -@subsection MIDI block -@cindex MIDI block - - -The MIDI block is analogous to the layout block, but it is somewhat -simpler. The @code{\midi} block is similar to @code{\layout}. It can contain -context definitions. - - -@cindex context definition - -Context definitions follow precisely the same syntax as within the -\layout block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}. - - -@node MIDI instrument names -@subsection MIDI instrument names - -@cindex instrument names -@funindex Staff.midiInstrument - -The MIDI instrument name is set by the @code{Staff.midiInstrument} -property. The instrument name should be chosen from the list in -@ref{MIDI instruments}. - -@example -\set Staff.midiInstrument = "glockenspiel" -@var{...notes...} -@end example - -If the selected instrument does not exactly match an instrument from -the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"}) -instrument is used. - - -@c Yes, this is a cop-out; this info doesn't belong in the Scheme -@c chapter, but I'm not certain where to stick it. -@c I think I'll eventually split this chapter into a "paper/layout" -@c chapter and a "misc issues" chapter. -gp -@node Displaying LilyPond notation -@section Displaying LilyPond notation - -@funindex \displayLilyMusc -Displaying a music expression in LilyPond notation can be -done using the music function @code{\displayLilyMusic}. For example, - -@example -@{ - \displayLilyMusic \transpose c a, @{ c e g a bes @} -@} -@end example - -will display - -@example -@{ a, cis e fis g @} -@end example - -By default, LilyPond will print these messages to the console along -with all the other messages. To split up these messages and save -the results of @code{\display@{STUFF@}}, redirect the output to -a file. - -@example -lilypond file.ly >display.txt -@end example - - -@node Skipping corrected music -@section Skipping corrected music - - -@funindex skipTypesetting -@funindex showLastLength - -When entering or copying music, usually only the music near the end (where -you -are adding notes) is interesting to view and correct. To speed up -this correction process, it is possible to skip typesetting of all but -the last few measures. This is achieved by putting - -@verbatim -showLastLength = R1*5 -\score { ... } -@end verbatim - -@noindent -in your source file. This will render only the last 5 measures -(assuming 4/4 time signature) of every @code{\score} in the input -file. For longer pieces, rendering only a small part is often an order -of magnitude quicker than rendering it completely - -Skipping parts of a score can be controlled in a more fine-grained -fashion with the property @code{Score.skipTypesetting}. When it is -set, no typesetting is performed at all. - -This property is also used to control output to the MIDI file. Note that -it skips all events, including tempo and instrument changes. You have -been warned. - -@lilypond[quote,fragment,ragged-right,verbatim] -\relative c'' { - c8 d - \set Score.skipTypesetting = ##t - e e e e e e e e - \set Score.skipTypesetting = ##f - c d b bes a g c2 } -@end lilypond - -In polyphonic music, @code{Score.skipTypesetting} will affect all -voices and staves, saving even more time. - - - diff --git a/Documentation/user/invoking.itely b/Documentation/user/invoking.itely deleted file mode 100644 index 81b6751d20..0000000000 --- a/Documentation/user/invoking.itely +++ /dev/null @@ -1,796 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- -@c This file is part of lilypond.tely - -@node Running LilyPond -@chapter Running LilyPond - -This chapter details the technicalities of running LilyPond. - -Some of these commands are run from the command-line. By -``command-line'', we mean the command -line in the operating system. Windows users -might be more familiar with the terms ``DOS shell'' or -``command shell''; OSX users might be more familiar with the -terms ``terminal'' or ``console''. OSX users should also -consult @ref{Notes for the MacOS X app}. - -Describing how to use -this part of an operating system is outside the scope of this -manual; please consult other documentation on this topic if -you are unfamiliar with the command-line. - -@menu -* Invoking lilypond:: -* Notes for the MacOS X app:: -* Updating files with convert-ly:: -* Reporting bugs:: -* Error messages:: -* Editor support:: -* Point and click:: -@end menu - -@node Invoking lilypond -@section Invoking lilypond -@cindex Invoking LilyPond -@cindex command line options -@cindex options, command line -@cindex switches - - -The @code{lilypond} executable may be called as follows from the command line. - -@example -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 -dash (@code{-}) for @var{file}. - -When @file{filename.ly} is processed it will produce -@file{filename.tex} as output (or @file{filename.ps} for PostScript -output). If @file{filename.ly} contains more than one @code{\score} -block, then the rest of the scores will be output in numbered files, -starting with @file{filename-1.tex}. Several files can be specified; -they will each be processed independently. @footnote{The status of -GUILE is not reset after processing a @code{.ly} file, so be careful -not to change any system defaults from within Scheme.} - - -@subsection Command line options - -The following options are supported: - -@table @code - -@item -e,--evaluate=@var{expr} -Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. -Multiple @code{-e} options may be given, they will be evaluated -sequentially. - -The expression will be evaluated in the @code{guile-user} module, so -if you want to use definitions in @var{expr}, use - -@example -lilypond -e '(define-public a 42)' -@end example - -@noindent -on the command-line, and include - -@example -#(use-modules (guile-user)) -@end example - -@noindent -at the top of the @code{.ly} file. - -@item -f,--format=@var{format} -which formats should be written. Choices are @code{svg}, @code{ps}, -@code{pdf}, @code{png}, @code{tex}, @code{dvi}. - -@item -b,--backend=@var{format} -the output format to use for the back-end. Choices are -@table @code -@item tex -for @TeX{} output, to be processed with La@TeX{}. If present, the file -@file{file.textmetrics} is read to determine text extents. -@item texstr -dump text strings to @file{.texstr} file, which can be run through -(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the -extents of strings of text. @strong{Warning:} this functionality is -currently missing due to heavy restructuring of the source code. -@item ps - for PostScript. -@cindex PostScript output - - Postscript files include TTF, Type1 and OTF fonts. No subsetting of - these fonts is done. When using oriental character sets, this can - lead to huge files. - -@item eps - for encapsulated PostScript. This dumps every page (system) as a separate -@file{EPS} file, without fonts, and as one collated @file{EPS} file with -all pages (systems) including fonts. - -This mode is used by default by lilypond-book. - -@item svg - for SVG (Scalable Vector Graphics). This dumps every page as a separate -@file{SVG} file, with embedded fonts. -@cindex SVG (Scalable Vector Graphics) - You need a SVG viewer which supports embedded fonts, or a SVG - viewer which is able to replace the embedded fonts with OTF fonts. - Under Unix, you may use @uref{http://www.inkscape.org,Inkscape} - (version 0.42 or later), after copying the OTF fonts in directory - @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}. -@item scm - for a dump of the raw, internal Scheme-based drawing commands. -@cindex Scheme dump -@end table - -@cindex output format, setting - -@item -d,--define-default=@var{var}=@var{val} -This sets the internal program option @var{var} to the Scheme value -@var{val}. If @var{val} is not supplied, then @var{#t} is used. To -switch off an option, @code{no-} may be prefixed to @var{var}, e.g. - -@cindex point and click, command line - -@example --dno-point-and-click -@end example - -@noindent -is the same as -@example --dpoint-and-click='#f' -@end example - -Another notable option is - -@example --dpaper-size=\"letter\" -@end example - -@noindent -Note that the string must be enclosed in escaped quotes ( @code{\"} ). - -Setting the @code{-dhelp} option will print a summary of the options -available, and exit. - -@item -h,--help -Show a summary of usage. - -@item -H,--header=FIELD -Dump a header field to file BASENAME.FIELD - -@item --include, -I=@var{directory} -Add @var{directory} to the search path for input files. -@cindex file searching -@cindex search path - -@item -i,--init=@var{file} -Set init file to @var{file} (default: @file{init.ly}). - -@item -o,--output=@var{FILE} -Set the default output file to @var{FILE}. The appropriate -suffix will be added (ie @code{.pdf} for pdf, @code{.tex} -for tex, etc). - -@item --ps -Generate PostScript. - -@item --dvi -Generate DVI files. In this case, the @TeX{} backend should be -specified, i.e., @code{-b tex}. - -@item --png -Generate pictures of each page, in PNG format. This implies -@code{--ps}. The resolution in DPI of the image may be set with -@example --dresolution=110 -@end example - -@item --pdf -Generate PDF. This implies @code{--ps}. - -@item --preview -Generate an output file containing the titles and the first system - -@item --no-pages -Do not generate the full pages. Useful in combination with -@code{--preview}. - -@item -s,--safe -Do not trust the @code{.ly} input. - -When LilyPond formatting is available through a web server, either the -@code{--safe} or the @code{--jail} option @b{MUST} be passed. The -@code{--safe} option will prevent inline Scheme code from wreaking -havoc, for example - -@quotation -@verbatim -#(system "rm -rf /") -{ - c4^#(ly:export (ly:gulp-file "/etc/passwd")) -} -@end verbatim -@end quotation - -The @code{--safe} option works by evaluating in-line Scheme -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}. - -In addition, @code{--safe} disallows @code{\include} directives and -disables the use of backslashes in @TeX{} strings. - -In @code{--safe} mode, it is not possible to import LilyPond variables -into Scheme. - -@code{--safe} does @emph{not} detect resource overuse. It is still -possible to make the program hang indefinitely, for example by feeding -cyclic data structures into the backend. Therefore, if using LilyPond -on a publicly accessible webserver, the process should be limited in -both CPU and memory usage. - -Note that @code{--safe} will prevent many useful LilyPond snippets from -being compiled. For a softer but secure alternative you can use the -@code{--jail} option. - - -@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} -Run LilyPond in a chroot jail. - -The @code{--jail} option provides a more flexible alternative to -@code{--safe} when LilyPond formatting is available through a web -server or whenever LilyPond executes externally provided -sources. - -The @code{--jail} option works by changing the root of LilyPond to -@var{jail} just before starting the actual compilation process. The user -and group are then changed to match those provided, and the current -directory is changed to @var{dir}. This setup guarantees that it is not -possible (at least in theory) to escape from the jail. Note that for -@code{--jail} to work LilyPond must be run as root, which is usually -accomplished in a safe way using @command{sudo}. - -Setting up a jail is a slightly delicate matter, as we must be sure that -LilyPond is able to find whatever it needs to compile the source -@emph{inside the jail}. A typical setup comprises the following items: - -@table @asis -@item Setting up a separate filesystem -A separate filesystem should be created for LilyPond, so that it can be -mounted with safe options such as @code{noexec}, @code{nodev}, and -@code{nosuid}. In this way, it is impossible to run executables or to -write directly to a device from LilyPond. If you do not want to create a -separate partition, just create a file of reasonable size and use it to -mount a loop device. A separate filesystem also guarantees that LilyPond -cannot write more space than it is allowed. - -@item Setting up a separate user -A separate user and group (say, @samp{lily}/@samp{lily}) with low -privileges should be used to run LilyPond inside the jail. There should -be a single directory writable by this user, which should be passed in -@var{dir}. - -@item Preparing the jail -LilyPond needs to read a number of files while running. All these files -are to be copied into the jail, under the same path they appear in the -real root filesystem. The entire content of the LilyPond installation -(e.g., @file{/usr/share/lilypond}) -should be copied. - -If problems arise, the simplest way to trace them down is to run -LilyPond using @command{strace}, which will allow you to determine which -files are missing. - -@item Running LilyPond -In a jail mounted with @code{noexec} it is impossible to execute any external -program. Therefore LilyPond must be run with a backend that does not -require any such program. As we already mentioned, it must be also run -with superuser privileges (which, of course, it will lose immediately), -possibly using @command{sudo}. It is a good idea to limit the number of -seconds of CPU time LilyPond can use (e.g., using @command{ulimit --t}), and, if your operating system supports it, the amount of memory -that can be allocated. -@end table - - -@item -v,--version -Show version information. - -@item -V,--verbose -Be verbose: show full paths of all files read, and give timing -information. - -@item -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with -@strong{NO WARRANTY}!) -@end table - - -@subsection Environment variables - - -@cindex LANG -@cindex LILYPONDPREFIX - -@code{Lilypond} 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 -subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. - -@item LANG -This selects the language for the warning messages. - -@item LILYPOND_GC_YIELD -With this variable the memory footprint and performance can be -adjusted. It is a percentage tunes memory management behavior. With -higher values, the program uses more memory, with smaller values, it -uses more CPU time. The default value is @code{70}. - -@end table - - -@node Notes for the MacOS X app -@section Notes for the MacOS X app - -The scripts (such as lilypond-book, convert-ly, abc2ly, and even -lilypond itself) are also -included inside MacOS X .app. They can be run from the command line by -invoking them directly, e.g. - -@example -@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond -@end example - -@noindent -The same is true of the other scripts in that directory, including -lilypond-book, convert-ly, abc2ly, etc. - -Alternatively, you may add this directory to your path. Modify (or create) -a file called @code{.profile} in your home directory such that it contains - -@example -export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin -@end example - -@noindent -This file should end with a blank line. - -Note that @var{path/to} will generally be @code{/Applications/}. - - -@node Updating files with convert-ly -@section Updating with @command{convert-ly} - -@cindex Updating a LilyPond file -@funindex convert-ly - -The LilyPond input syntax is routinely changed to simplify it or improve -it in different ways. As a side effect of this, the LilyPond interpreter -often is no longer compatible with older input files. To remedy this, -the program @command{convert-ly} can be used to deal with most of the -syntax changes between LilyPond versions. - -It uses @code{\version} statements in the input files to detect the -old version number. In most cases, to upgrade your input file it is -sufficient to run@footnote{MacOS X users may execute this command -under the menu entry @samp{Compile > Update syntax}.} - -@example -convert-ly -e myfile.ly -@end example - -If there are no changes to myfile.ly and file called myfile.ly.NEW -is created, then myfile.ly is already updated. - -@command{convert-ly} always converts up to the last syntax change handled by -it. This means that the @code{\version} number left in the file is -usually lower than the version of @command{convert-ly} itself. - -To upgrade LilyPond fragments in texinfo files, use - -@example -convert-ly --from=... --to=... --no-version *.itely -@end example - -To upgrade many files at once, combine @code{convert-ly} with -standard unix commands. This example will upgrade all @code{.ly} -files in the current directory - -@example -for f in *.ly; do convert-ly -e $f; done; -@end example - -In general, the program is invoked as follows: - -@example -convert-ly [@var{option}]@dots{} @var{file}@dots{} -@end example - - -The following options can be given: - -@table @code -@item -e,--edit -Do an inline edit of the input file. Overrides @code{--output}. - -@item -f,--from=@var{from-patchlevel} -Set the version to convert from. If this is not set, @command{convert-ly} -will guess this, on the basis of @code{\version} strings in the file. - -@item -n,--no-version -Normally, @command{convert-ly} adds a @code{\version} indicator -to the output. Specifying this option suppresses this. - -@item -s, --show-rules -Show all known conversions and exit. - -@item --to=@var{to-patchlevel} -Set the goal version of the conversion. It defaults to the latest -available version. - -@item -h, --help -Print usage help. -@end table - - -@refbugs - -Not all language changes are handled. Only one output option can be -specified. Automatically updating scheme and lilypond scheme -interfaces is quite unlikely; be prepared to tweak scheme code -manually. - - -@c We might want to make this a completely new section, along with more -@c info about how to upgrade old input files. -gp - -@ignore -Copy and paste from CVS, last updated -Aug 18, 2005 - -http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/ -convert-ly.txt?rev=HEAD&content-type=text/plain - -NEW: not exactly copied; this list has been modified. Since we're -changing the bug system, it doesn't make sense to copy from -the bug CVS any more. I'll figure out something else. -gp -@end ignore -@verbatim - -There are a few things that the convert-ly cannot handle. Here's a list of -limitations -that the community has complained about. - -This bug report structure has been chosen because convert-ly has a structure -that doesn't -allow to smoothly implement all needed changes. Thus this is just a wishlist, -placed -here for reference. - -1.6->2.0: - Doesn't always convert figured bass correctly, specifically things like {< ->}. Mats' comment on working around this: - To be able to run convert-ly - on it, I first replaced all occurencies of '{<' to some dummy like '{#' - and similarly I replaced '>}' with '&}'. After the conversion, I could - then change back from '{ #' to '{ <' and from '& }' to '> }'. - Doesn't convert all text markup correctly. In the old markup syntax, - it was possible to group a number of markup commands together within -parentheses, e.g. - -#'((bold italic) "string") - This will incorrectly be converted into - -\markup{{\bold italic} "string"} - instead of the correct - -\markup{\bold \italic "string"} -2.0->2.2: - Doesn't handle \partcombine - Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple -stanzas. -2.0->2.4: - \magnify isn't changed to \fontsize. - - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) - remove-tag isn't changed. - - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . - first-page-number isn't changed. - - first-page-number no => print-first-page-number = ##f - Line breaks in header strings aren't converted. - - \\\\ as line break in \header strings => \markup \center-align < - "First Line" "Second Line" > - Crescendo and decrescendo terminators aren't converted. - - \rced => \! - - \rc => \! -2.2->2.4: - \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly -converted. -2.4.2->2.5.9 - \markup{ \center-align <{ ... }> } should be converted to: - \markup{ \center-align {\line { ... }} } - but now, \line is missing. -2.4->2.6 - Special LaTeX characters such as $~$ in text are not converted to UTF8. -2.8 - \score{} must now begin with a music expression. Anything else - (particularly \header{}) must come after the music. -@end verbatim - - -@node Reporting bugs -@section Reporting bugs - -@cindex bugs -@cindex reporting bugs - -If you have input that results in a crash or an erroneous output, then -that is a bug. We try to 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. Send the report via: - -@example -@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs} -@end example - -A few tips: -@itemize @bullet - -@item Try to produce a very small input file which demonstrates the problem; -one or two bars is often sufficient to reproduce a bug. The smaller the -input file is, the easier it is for us to debug the problem. - -@item Don't forget to tell which version of LilyPond you use! - -@item If possible, use @code{ragged-right} in your example. This makes sure -that the bug can be reproduced in all paper sizes. -@end itemize - -@ignore -@c the bug database is not up to date enough. - -When you've found a bug, have a look at our -@uref{http://@/lilypond@/.org/@/bugs/@/v2.8/@/,bug database} to see if -it has already been reported. You could also try to 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. -@end ignore - -Here is an example of a good bug report: - -@verbatim -It seems that placement of accidentals is broken. In the -following example, the accidental touches the note head. - -Using Mac OSX 10.3.7, lilypond 2.7.32 - -\version "2.9.13" -\layout { ragged-right = ##t } -\relative c'' { - a4 b cis d -} -@end verbatim - -@lilypond[quote] -\layout { ragged-right = ##t } -\relative c''{ - \override Accidental #'extra-offset = #'(1.0 . 0) - a4 b cis d -} -@end lilypond - -@node Error messages -@section Error messages - -@cindex error messages -Different error messages can appear while compiling a file: - -@table @emph -@cindex warning - -@item Warning -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. - -@item Error -Something is definitely wrong. The current processing step (parsing, -interpreting, or formatting) will be finished, but the next step will -be skipped. - -@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. - -@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 -@code{--verbose}) then a call trace of the offending -function call is printed. - -@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. - -@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, -send a bug-report. - - -@end table - -@cindex errors, message format -If warnings and errors can -be linked to some part of the input file, then error messages have the -following form - -@example -@var{filename}:@var{lineno}:@var{columnno}: @var{message} -@var{offending input line} -@end example - -A line-break is inserted in the offending line to indicate the column -where the error was found. For example, - -@example -test.ly:2:19: error: not a duration: 5: - @{ c'4 e'5 - g' @} -@end example - -These locations are LilyPond's best guess about where the warning or -error occurred, but (by their very nature) warnings 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 Editor support -@section Editor support - -@cindex editors -@cindex vim -@cindex emacs -@cindex modes, editor -@cindex syntax coloring -@cindex coloring, syntax - -There is support from different editors for LilyPond. - -@table @asis -@item Emacs -Emacs has a @file{lilypond-mode}, which provides keyword -autocompletion, indentation, LilyPond specific parenthesis matching -and syntax coloring, handy compile short-cuts and reading LilyPond -manuals using Info. If @file{lilypond-mode} is not installed on your -platform, then read the -@ifhtml -@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. -@end ifhtml -@ifnothtml -installation instructions. -@end ifnothtml - -@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 -@ifhtml -@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. -@end ifhtml -@ifnothtml -installation instructions. -@end ifnothtml - - -@item JEdit - -The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin. -This plugin includes a DVI viewer, integrated help and viewing via -GhostScript. It can be installed by doing @key{Plugins > Plugin -Manager}, and selecting @code{LilyTool} from the @key{Install} tab. - -@end table - -All these editors can be made to jump into the input file to the source -of a symbol in the graphical output. See @ref{Point and click}. - - -@node Point and click -@section Point and click -@cindex point and click - - -Point and click lets you find notes in the input by clicking on them -in the PDF viewer. This makes it easier to find input that causes -some error in the sheet music. - -When this functionality is active, LilyPond adds hyperlinks to the PDF -file. These hyperlinks are sent to the web-browser, which opens a -text-editor with the cursor in the right place. - -To make this chain work, you should configure your PDF viewer to -follow hyperlinks using the @file{lilypond-invoke-editor} script -supplied with LilyPond. - -For Xpdf on Unix, the following should be present in -@file{xpdfrc}@footnote{On unix, this file is found either in -@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} - -@example -urlCommand "lilypond-invoke-editor %s" -@end example - -The program @file{lilypond-invoke-editor} is a small helper -program. It will invoke an editor for the special @code{textedit} -URIs, and run a web browser for others. It tests the environment -variable @code{EDITOR} for the following patterns, - -@table @code -@item emacs - this will invoke -@example -emacsclient --no-wait +@var{line}:@var{column} @var{file} -@end example -@item vim - this will invoke -@example -gvim --remote +:@var{line}:norm@var{char} @var{file} -@end example - -@item nedit -this will invoke -@example - nc -noask +@var{line} @var{file}' -@end example -@end table - -The environment variable @code{LYEDITOR} is used to override this. It -contains the command line to start the editor, where @code{%(file)s}, -@code{%(column)s}, @code{%(line)s} is replaced with the file, column -and line respectively. The setting - -@example -emacsclient --no-wait +%(line)s:%(column)s %(file)s -@end example - -@noindent -for @code{LYEDITOR} is equivalent to the standard emacsclient -invocation. - - -@cindex file size, output - -The point and click links enlarge the output files significantly. For -reducing the size of PDF and PS files, point and click may be switched -off by issuing - -@example -#(ly:set-option 'point-and-click #f) -@end example - -@noindent -in a @file{.ly} file. Alternately, you may pass this as an command-line -option - -@example -lilypond -dno-point-and-click file.ly -@end example - diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 32a875500d..bcdbc5682c 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -201,11 +201,11 @@ Appendices @include instrument-notation.itely @include advanced-notation.itely @include changing-defaults.itely -@include global.itely -@include page.itely +@include non-music.itely +@include spacing.itely @include programming-interface.itely -@include invoking.itely +@include running.itely @include lilypond-book.itely @include converters.itely @@ -213,7 +213,7 @@ Appendices @include literature.itely @include scheme-tutorial.itely @include notation-appendices.itely -@include examples.itely +@include templates.itely @include cheatsheet.itely @include fdl.itexi diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely new file mode 100644 index 0000000000..bd2596410d --- /dev/null +++ b/Documentation/user/non-music.itely @@ -0,0 +1,958 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely + +@c A menu is needed before every deeper *section nesting of @node's; run +@c M-x texinfo-all-menus-update +@c to automatically fill in these menus before saving changes + +@node Non-musical notation +@chapter Non-musical notation + +This section deals with general lilypond issues, rather than +specific notation. + +@menu +* Input files:: +* Titles and headers:: +* MIDI output:: +* Displaying LilyPond notation:: +* Skipping corrected music:: +@end menu + + +@node Input files +@section Input files + +The main format of input for LilyPond are text files. By convention, +these files end with ``@code{.ly}''. + +@menu +* File structure (introduction):: +* Multiple scores in a book:: +* Extracting fragments of notation:: +* File structure:: +* A single music expression:: +* Including LilyPond files:: +* Text encoding:: +@end menu + + +@node File structure (introduction) +@subsection File structure (introduction) + +A basic example of a lilypond input file is + +@example +\version "2.9.13" +\score @{ + @{ @} % this is a single music expression; + % all the music goes in here. + \header @{ @} + \layout @{ @} + \midi @{ @} +@} +@end example + +@noindent +There are many variations of this basic pattern, but this +example serves as a useful starting place. + +The major part of this manual is concerned with entering various +forms of music in LilyPond. However, many music expressions are not +valid input on their own, for example, a @code{.ly} file containing +only a note +@example +c'4 +@end example + +@noindent +will result in a parsing error. Instead, music should be inside other +expressions, which may be put in a file by themselves. Such +expressions are called toplevel expressions. The next section enumerates +them all. + + +@node Multiple scores in a book +@subsection Multiple scores in a book + +@funindex \book +@cindex movements, multiple + +A document may contain multiple pieces of music and texts. Examples +of these are an etude book, or an orchestral part with multiple +movements. Each movement is entered with a @code{\score} block, + +@example +\score @{ + @var{..music..} +@} +@end example + +and texts are entered with a @code{\markup} block, + +@example +\markup @{ + @var{..text..} +@} +@end example + +@funindex \book + +The movements and texts are combined together in a @code{\book} block, +like + +@example +\book @{ + \score @{ + @var{..} + @} + \markup @{ + @var{..} + @} + \score @{ + @var{..} + @} +@} +@end example + + +The header for each piece of music can be put inside the @code{\score} +block. The @code{piece} name from the header will be printed before +each movement. The title for the entire book can be put inside the +@code{\book}, but if it is not present, the @code{\header} which is at +the top of the file is inserted. + +@example +\book @{ + \header @{ + title = "Eight miniatures" + composer = "Igor Stravinsky" + @} + \score @{ + @dots{} + \header @{ piece = "Romanze" @} + @} + \markup @{ + ..text of second verse.. + @} + \markup @{ + ..text of third verse.. + @} + \score @{ + @dots{} + \header @{ piece = "Menuetto" @} + @} +@} +@end example + +@node Extracting fragments of notation +@subsection Extracting fragments of notation + +It is possible to quote small fragments of a large score directly from +the output. This can be compared to clipping a piece of a paper score +with scissors. + +This is done by definining the measures that need to be cut out +separately. For example, including the following definition + + +@verbatim +\layout { + clip-regions + = #(list + (cons + (make-rhythmic-location 5 1 2) + (make-rhythmic-location 7 3 4))) +} +@end verbatim + +@noindent +will extract a fragment starting halfway the fifth measure, ending in +the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note +in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7. + +More clip regions can be defined by adding more pairs of +rhythmic-locations to the list. + +In order to use this feature, LilyPond must be invoked with +@code{-dclip-systems}. The clips are output as EPS files, and are +converted to PDF and PNG if these formats are switched on as well. + +For more information on output formats, see @ref{Invoking lilypond}. + +@seealso + +Examples: @inputfileref{input/regression/,clip-systems.ly} + + +@node File structure +@subsection File structure + +A @code{.ly} file contains any number of toplevel expressions, where a +toplevel expression is one of the following + +@itemize @bullet +@item +An output definition, such as @code{\paper}, @code{\midi}, and +@code{\layout}. Such a definition at the toplevel changes the default +settings for the block entered. + +@item +A direct scheme expression, such as +@code{#(set-default-paper-size "a7" 'landscape)} or +@code{#(ly:set-option 'point-and-click #f)}. + +@item +A @code{\header} block. This sets the global header block. This +is the block containing the definitions for book-wide settings, like +composer, title, etc. + +@item +A @code{\score} block. This score will be collected with other +toplevel scores, and combined as a single @code{\book}. + +This behavior can be changed by setting the variable +@code{toplevel-score-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +The @code{\score} must begin with a music expression, and may +contain only one music expression. + +@item +A @code{\book} block logically combines multiple movements +(i.e., multiple @code{\score} blocks) in one document. If there are +a number of @code{\scores}, a single output file will be created +in which all movements are concatenated. + +This behavior can be changed by setting the variable +@code{toplevel-book-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +@item +A compound music expression, such as +@example +@{ c'4 d' e'2 @} +@end example + +This will add the piece in a @code{\score} and format it in a +single book together with all other toplevel @code{\score}s and music +expressions. In other words, a file containing only the above +music expression will be translated into + +@example +\book @{ + \score @{ + \new Staff @{ + \new Voice @{ + @{ c'4 d' e'2 @} + @} + @} + @} + \layout @{ @} + \header @{ @} +@} +@end example + +This behavior can be changed by setting the variable +@code{toplevel-music-handler} at toplevel. The default handler is +defined in the init file @file{scm/@/lily@/.scm}. + +@item +A markup text, a verse for example +@example +\markup @{ + 2. The first line verse two. +@} +@end example + +Markup texts are rendered above, between or below the scores or music +expressions, wherever they appear. + +@item +An identifier, such as +@example +foo = @{ c4 d e d @} +@end example + +This can be used later on in the file by entering @code{\foo}. The +name of an identifier should have alphabetic characters only; no +numbers, underscores or dashes. + +@end itemize + +The following example shows three things that may be entered at +toplevel + +@example +\layout @{ + % movements are non-justified by default + ragged-right = ##t +@} + +\header @{ + title = "Do-re-mi" +@} + +@{ c'4 d' e2 @} +@end example + + +At any point in a file, any of the following lexical instructions can +be entered: + +@itemize @bullet +@item @code{\version} +@item @code{\include} +@item @code{\sourcefilename} +@item @code{\sourcefileline} + +@end itemize + + +@node A single music expression +@subsection A single music expression + +A @code{\score} must contain a single music expression. However, +this music expression may be of any size. Recall that music +expressions may be included inside other expressions to form +larger expressions. All of these examples are single music +expressions; note the curly braces @{ @} or angle brackets << +>> at the beginning and ending of the music. + +@example +@{ c'4 c' c' c' @} +@end example + +@lilypond[ragged-right,verbatim,quote] +{ + { c'4 c' c' c'} + { d'4 d' d' d'} +} +@end lilypond + +@lilypond[ragged-right,verbatim,quote] +<< + \new Staff { c'4 c' c' c' } + \new Staff { d'4 d' d' d' } +>> +@end lilypond + +@example +@{ + \new GrandStaff << + \new StaffGroup << + \new Staff @{ \flute @} + \new Staff @{ \oboe @} + >> + \new StaffGroup << + \new Staff @{ \violinI @} + \new Staff @{ \violinII @} + >> + >> +@} +@end example + + +@node Including LilyPond files +@subsection Including LilyPond files + +@funindex \include +@cindex including files + +A large project may be split up into separate files. To refer to another +file, use + +@example +\include "otherfile.ly" +@end example + +The line @code{\include "file.ly"} is equivalent to pasting the contents +of file.ly into the current file at the place where you have the +\include. For example, for a large project you might write separate files +for each instrument part and create a ``full score'' file which brings +together the individual instrument files. + +The initialization of LilyPond is done in a number of files that are +included by default when you start the program, normally transparent to the +user. Run lilypond --verbose to see a list of paths and files that Lily +finds. + +Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where +VERSION is in the form ``2.6.1'') are on the path and available to +@code{\include}. Files in the +current working directory are available to \include, but a file of the same +name in LilyPond's installation takes precedence. Files are +available to \include from directories in the search path specified as an +option when invoking @code{lilypond --include=DIR} which adds DIR to the +search path. + +The @code{\include} statement can use full path information, but with the Unix +convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example, +if @file{stuff.ly} is located one directory higher than the current working +directory, use + +@example +\include "../stuff.ly" +@end example + + +@node Text encoding +@subsection Text encoding + +LilyPond uses the Pango library to format multi-lingual texts, and +does not perform any input-encoding conversions. This means that any +text, be it title, lyric text, or musical instruction containing +non-ASCII characters, must be utf-8. The easiest way to enter such text is +by using a Unicode-aware editor and saving the file with utf-8 encoding. Most +popular modern editors have utf-8 support, for example, vim, Emacs, +jEdit, and GEdit do. + +@c Currently not working +@ignore +Depending on the fonts installed, the following fragment shows Hebrew +and Cyrillic lyrics, + +@cindex Cyrillic +@cindex Hebrew +@cindex ASCII, non + +@li lypondfile[fontload]{utf-8.ly} + +The @TeX{} backend does not handle encoding specially at all. Strings +in the input are put in the output as-is. Extents of text items in the +@TeX{} backend, are determined by reading a file created via the +@file{texstr} backend, + +@example +lilypond -b texstr input/les-nereides.ly +latex les-nereides.texstr +@end example + +The last command produces @file{les-nereides.textmetrics}, which is +read when you execute + +@example +lilypond -b tex input/les-nereides.ly +@end example + +Both @file{les-nereides.texstr} and @file{les-nereides.tex} need +suitable LaTeX wrappers to load appropriate La@TeX{} packages for +interpreting non-ASCII strings. + +@end ignore + +To use a Unicode escape sequence, use + +@example +#(ly:export (ly:wide-char->utf-8 #x2014)) +@end example + + +@seealso + +@inputfileref{input/regression,utf-8.ly} + + + +@node Titles and headers +@section Titles and headers + +Almost all printed music includes a title and the composer's name; +some pieces include a lot more information. + +@menu +* Creating titles:: +* Custom titles:: +@end menu + + +@node Creating titles +@subsection Creating titles + +Titles are created for each @code{\score} block, and over a +@code{\book}. + +The contents of the titles are taken from the @code{\header} blocks. +The header block for a book supports the following + + +@table @code +@funindex dedication +@item dedication +The dedicatee of the music, centered at the top of the first page. + +@funindex title +@item title +The title of the music, centered just below the dedication. + +@funindex subtitle +@item subtitle +Subtitle, centered below the title. + +@funindex subsubtitle +@item subsubtitle +Subsubtitle, centered below the subtitle. + +@funindex poet +@item poet +Name of the poet, flush-left below the subtitle. + +@funindex composer +@item composer +Name of the composer, flush-right below the subtitle. + +@funindex meter +@item meter +Meter string, flush-left below the poet. + +@funindex opus +@item opus +Name of the opus, flush-right below the composer. + +@funindex arranger +@item arranger +Name of the arranger, flush-right below the opus. + +@funindex instrument +@item instrument +Name of the instrument, centered below the arranger. Also +centered at the top of pages (other than the first page). + +@funindex piece +@item piece +Name of the piece, flush-left below the instrument. + +@cindex page breaks, forcing +@funindex breakbefore +@item breakbefore +This forces the title to start on a new page (set to ##t or ##f). + +@funindex copyright +@item copyright +Copyright notice, centered at the bottom of the first page. To +insert the copyright symbol, see @ref{Text encoding}. + +@funindex tagline +@item tagline +Centered at the bottom of the last page. + +@end table + +Here is a demonstration of the fields available. Note that you +may use any @ref{Text markup} commands in the header. + +@lilypond[quote,verbatim,line-width=11.0\cm] +\paper { + line-width = 9.0\cm + paper-height = 10.0\cm +} + +\book { + \header { + dedication = "dedicated to me" + title = \markup \center-align { "Title first line" "Title second line, +longer" } + subtitle = "the subtitle," + subsubtitle = #(string-append "subsubtitle LilyPond version " +(lilypond-version)) + poet = "Poet" + composer = \markup \center-align { "composer" \small "(1847-1973)" } + texttranslator = "Text Translator" + meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge +"r" } + arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize +#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" } + instrument = \markup \bold \italic "instrument" + piece = "Piece" + } + + \score { + { c'1 } + \header { + piece = "piece1" + opus = "opus1" + } + } + \markup { + and now... + } + \score { + { c'1 } + \header { + piece = "piece2" + opus = "opus2" + } + } +} +@end lilypond + +As demonstrated before, you can use multiple @code{\header} blocks. +When same fields appear in different blocks, the latter is used. +Here is a short example. + +@example +\header @{ + composer = "Composer" +@} +\header @{ + piece = "Piece" +@} +\score @{ + \new Staff @{ c'4 @} + \header @{ + piece = "New piece" % overwrite previous one + @} +@} +@end example + +If you define the @code{\header} inside the @code{\score} block, then +normally only the @code{piece} and @code{opus} headers will be printed. +Note that the music expression must come before the @code{\header}. + +@lilypond[quote,verbatim,line-width=11.0\cm] +\score { + { c'4 } + \header { + title = "title" % not printed + piece = "piece" + opus = "opus" + } +} +@end lilypond + +@funindex printallheaders +@noindent +You may change this behavior (and print all the headers when defining +@code{\header} inside @code{\score}) by using + +@example +\paper@{ + printallheaders=##t +@} +@end example + +@cindex copyright +@cindex tagline + +The default footer is empty, except for the first page, where the +@code{copyright} field from @code{\header} is inserted, and the last +page, where @code{tagline} from @code{\header} is added. The default +tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely +printed parts are good PR for us, so please leave the tagline if you +can.} + +Headers may be completely removed by setting them to false. + +@example +\header @{ + tagline = ##f + composer = ##f +@} +@end example + + +@node Custom titles +@subsection Custom titles + +A more advanced option is to change the definitions of the following +variables in the @code{\paper} block. The init file +@file{ly/titling-init.ly} lists the default layout. + +@table @code +@funindex bookTitleMarkup +@item bookTitleMarkup + This is the title put over an entire @code{\book} block. Typically, + it has the composer and the title of the piece + +@funindex scoreTitleMarkup +@item scoreTitleMarkup + This is the title put over a @code{\score} block within a +@code{\book}. Typically, it has the name of the movement (@code{piece} +field). + +@funindex oddHeaderMarkup +@item oddHeaderMarkup + This is the page header for odd-numbered pages. + +@funindex evenHeaderMarkup +@item evenHeaderMarkup + This is the page header for even-numbered pages. If unspecified, + the odd header is used instead. + + By default, headers are defined such that the page number is on the + outside edge, and the instrument is centered. + +@funindex oddFooterMarkup +@item oddFooterMarkup + This is the page footer for odd-numbered pages. + +@funindex evenFotterMarkup +@item evenFooterMarkup + This is the page footer for even-numbered pages. If unspecified, + the odd header is used instead. + + By default, the footer has the copyright notice on the first, and + the tagline on the last page. +@end table + + +@cindex \paper +@cindex header +@cindex footer +@cindex page layout +@cindex titles + +The following definition will put the title flush left, and the +composer flush right on a single line. + +@verbatim +\paper { + bookTitleMarkup = \markup { + \fill-line { + \fromproperty #'header:title + \fromproperty #'header:composer + } + } +} +@end verbatim + + + +@node MIDI output +@section MIDI output + +@cindex Sound +@cindex MIDI + +MIDI (Musical Instrument Digital Interface) is a standard for +connecting and controlling digital instruments. A MIDI file is a +series of notes in a number of tracks. It is not an actual +sound file; you need special software to translate between the +series of notes and actual sounds. + +Pieces of music can be converted to MIDI files, so you can listen to +what was entered. This is convenient for checking the music; octaves +that are off or accidentals that were mistyped stand out very much +when listening to the MIDI output. + +@refbugs + +Many musically interesting effects, such as swing, articulation, +slurring, etc., are not translated to midi. + +The midi output allocates a channel for each staff, and one for global +settings. Therefore the midi file should not have more than 15 staves +(or 14 if you do not use drums). Other staves will remain silent. + +Not all midi players correctly handle tempo changes in the midi +output. Players that are known to work include +@uref{http://@/timidity@/.sourceforge@/.net/,timidity}. + +@menu +* Creating MIDI files:: +* MIDI block:: +* MIDI instrument names:: +@end menu + +@node Creating MIDI files +@subsection Creating MIDI files + +To create a MIDI from a music piece of music, add a @code{\midi} block +to a score, for example, + +@example +\score @{ + @var{...music...} + \midi @{ @} +@} +@end example + +FIXME + +The tempo is specified using the @code{\tempo} command. In this +example the tempo of quarter notes is set to 72 beats per minute. + + +If there is a @code{\midi} command in a @code{\score}, only MIDI will +be produced. When notation is needed too, a @code{\layout} block must +be added + +@example +\score @{ + @var{...music...} + \midi @{ @} + \layout @{ @} +@} +@end example +@cindex layout block + + + +Ties, dynamics, and tempo changes are interpreted. Dynamic marks, +crescendi and decrescendi translate into MIDI volume levels. Dynamic +marks translate to a fixed fraction of the available MIDI volume +range, crescendi and decrescendi make the volume vary linearly between +their two extremes. The fractions can be adjusted by +@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. +For each type of MIDI instrument, a volume range can be defined. This +gives a basic equalizer control, which can enhance the quality of +the MIDI output remarkably. The equalizer can be controlled by +setting @code{instrumentEqualizer}, or by setting + +@example +\set Staff.midiMinimumVolume = #0.2 +\set Staff.midiMaximumVolume = #0.8 +@end example + +To remove dynamics from the MIDI output, insert the following lines +in the @code{\midi@{@}} section. + +@example +\midi @{ + ... + \context @{ + \Voice + \remove "Dynamic_performer" + \remove "Span_dynamic_performer" + @} +@} +@end example + + +@refbugs + +Unterminated (de)crescendos will not render properly in the midi file, +resulting in silent passages of music. The workaround is to explicitly +terminate the (de)crescendo. For example, + +@example +@{ a\< b c d\f @} +@end example + +@noindent +will not work properly but + +@example +@{ a\< b c d\!\f @} +@end example + +@noindent +will. + + +@node MIDI block +@subsection MIDI block +@cindex MIDI block + + +The MIDI block is analogous to the layout block, but it is somewhat +simpler. The @code{\midi} block is similar to @code{\layout}. It can contain +context definitions. + + +@cindex context definition + +Context definitions follow precisely the same syntax as within the +\layout block. Translation modules for sound are called performers. +The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}. + + +@node MIDI instrument names +@subsection MIDI instrument names + +@cindex instrument names +@funindex Staff.midiInstrument + +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. + +@example +\set Staff.midiInstrument = "glockenspiel" +@var{...notes...} +@end example + +If the selected instrument does not exactly match an instrument from +the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"}) +instrument is used. + + +@c Yes, this is a cop-out; this info doesn't belong in the Scheme +@c chapter, but I'm not certain where to stick it. +@c I think I'll eventually split this chapter into a "paper/layout" +@c chapter and a "misc issues" chapter. -gp +@node Displaying LilyPond notation +@section Displaying LilyPond notation + +@funindex \displayLilyMusc +Displaying a music expression in LilyPond notation can be +done using the music function @code{\displayLilyMusic}. For example, + +@example +@{ + \displayLilyMusic \transpose c a, @{ c e g a bes @} +@} +@end example + +will display + +@example +@{ a, cis e fis g @} +@end example + +By default, LilyPond will print these messages to the console along +with all the other messages. To split up these messages and save +the results of @code{\display@{STUFF@}}, redirect the output to +a file. + +@example +lilypond file.ly >display.txt +@end example + + +@node Skipping corrected music +@section Skipping corrected music + + +@funindex skipTypesetting +@funindex showLastLength + +When entering or copying music, usually only the music near the end (where +you +are adding notes) is interesting to view and correct. To speed up +this correction process, it is possible to skip typesetting of all but +the last few measures. This is achieved by putting + +@verbatim +showLastLength = R1*5 +\score { ... } +@end verbatim + +@noindent +in your source file. This will render only the last 5 measures +(assuming 4/4 time signature) of every @code{\score} in the input +file. For longer pieces, rendering only a small part is often an order +of magnitude quicker than rendering it completely + +Skipping parts of a score can be controlled in a more fine-grained +fashion with the property @code{Score.skipTypesetting}. When it is +set, no typesetting is performed at all. + +This property is also used to control output to the MIDI file. Note that +it skips all events, including tempo and instrument changes. You have +been warned. + +@lilypond[quote,fragment,ragged-right,verbatim] +\relative c'' { + c8 d + \set Score.skipTypesetting = ##t + e e e e e e e e + \set Score.skipTypesetting = ##f + c d b bes a g c2 } +@end lilypond + +In polyphonic music, @code{Score.skipTypesetting} will affect all +voices and staves, saving even more time. + + + diff --git a/Documentation/user/page.itely b/Documentation/user/page.itely deleted file mode 100644 index aa4a6039b8..0000000000 --- a/Documentation/user/page.itely +++ /dev/null @@ -1,1172 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- -@c This file is part of lilypond.tely - -@c A menu is needed before every deeper *section nesting of @node's; run -@c M-x texinfo-all-menus-update -@c to automatically fill in these menus before saving changes - -@node Spacing issues -@chapter Spacing issues - -The global paper layout is determined by three factors: the page layout, the -line breaks, and the spacing. These all influence each other. The -choice of spacing determines how densely each system of music is set. -This influences where line breaks are chosen, and thus ultimately, how -many pages a piece of music takes. - -Globally speaking, this procedure happens in four steps: first, -flexible distances (``springs'') are chosen, based on durations. All -possible line breaking combinations are tried, and a ``badness'' score -is calculated for each. Then the height of each possible system is -estimated. Finally, a page breaking and line breaking combination is chosen -so that neither the horizontal nor the vertical spacing is too cramped -or stretched. - -@menu -* Paper and pages:: -* Music layout:: -* Vertical spacing:: -* Horizontal spacing:: -* Breaks:: -* Displaying spacing:: -@end menu - - -@node Paper and pages -@section Paper and pages - -This section deals with the boundaries that define the area -that music can be printed inside. - -@menu -* Paper size:: -* Page formatting:: -@end menu - - -@node Paper size -@subsection Paper size - -@cindex paper size -@cindex page size -@funindex papersize - -To change the paper size, there are two commands, -@example -#(set-default-paper-size "a4") -\paper @{ - #(set-paper-size "a4") -@} -@end example - -The first command sets the size of all pages. The second command sets the -size -of the pages that the @code{\paper} block applies to -- if the @code{\paper} -block is at the top of the file, then it will apply to all pages. If the -@code{\paper} block is inside a @code{\book}, then the paper size will only -apply to that book. - -Support for the following paper sizes are included by default, -@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter}, -@code{11x17} (also known as tabloid). - -Extra sizes may be added by editing the definition for -@code{paper-alist} in the initialization file @file{scm/paper.scm}. - -@cindex orientation -@cindex landscape - -If the symbol @code{landscape} is supplied as an argument to -@code{set-default-paper-size}, the pages will be rotated by 90 degrees, -and wider line widths will be set correspondingly. - -@example -#(set-default-paper-size "a6" 'landscape) -@end example - -Setting the paper size will adjust a number of @code{\paper} variables -(such as margins). To use a particular paper size with altered -@code{\paper} variables, set the paper size before setting the variables. - - -@node Page formatting -@subsection Page formatting - -@cindex page formatting -@cindex margins -@cindex header, page -@cindex footer, page - -LilyPond will do page layout, set margins, and add headers and -footers to each page. - -The default layout responds to the following settings in the -@code{\paper} block. - -@funindex \paper - -@quotation -@table @code -@funindex first-page-number -@item first-page-number -The value of the page number of the first page. Default is@tie{}1. - -@funindex printfirst-page-number -@item print-first-page-number -If set to true, will print the page number in the first page. Default is -false. - -@funindex print-page-number -@item print-page-number -If set to false, page numbers will not be printed. Default is true. - -@funindex paper-width -@item paper-width -The width of the page. The default is taken from the current paper size, -see @ref{Paper size}. - -@funindex paper-height -@item paper-height -The height of the page. The default is taken from the current paper size, -see @ref{Paper size}. - -@funindex top-margin -@item top-margin -Margin between header and top of the page. Default is@tie{}5mm. - -@funindex bottom-margin -@item bottom-margin -Margin between footer and bottom of the page. Default is@tie{}6mm. - -@funindex left-margin -@item left-margin -Margin between the left side of the page and the beginning of the -music. Unset by default, which means that the margins is determined -based on the @code{paper-width} and @code{line-width} to center the -score on the paper. - -@funindex line-width -@item line-width -The length of the systems. Default is @code{paper-width} minus @tie{}20mm. - -@funindex head-separation -@item head-separation -Distance between the top-most music system and the page header. Default -is@tie{}4mm. - -@funindex foot-separation -@item foot-separation -Distance between the bottom-most music system and the page -footer. Default is@tie{}4mm. - -@funindex page-top-space -@item page-top-space -Distance from the top of the printable area to the center of the first -staff. This only works for staves which are vertically small. Big staves -are set with the top of their bounding box aligned to the top of the -printable area. Default is@tie{}12mm. - -@funindex ragged-bottom -@item ragged-bottom -If set to true, systems will not be spread vertically across the page. This -does not affect the last page. Default is false. - -This should be set to true for pieces that have only two or three -systems per page, for example orchestral scores. - -@funindex ragged-last-bottom -@item ragged-last-bottom -If set to false, systems will be spread vertically to fill the last -page. Default is true. - -Pieces that amply fill two pages or more should have this set to -true. - -@funindex system-count -@item system-count -This variable, if set, specifies into how many lines a score should be -broken. Unset by default. - -@funindex between-system-space -@item between-system-space -This dimensions determines the distance between systems. It is the -ideal distance between the center of the bottom staff of one system -and the center of the top staff of the next system. Default is@tie{}20mm. - -Increasing this will provide a more even appearance of the page at the -cost of using more vertical space. - -@funindex between-system-padding -@item between-system-padding -This dimension is the minimum amount of white space that will always -be present between the bottom-most symbol of one system, and the -top-most of the next system. Default is@tie{}4mm. - -Increasing this will put systems whose bounding boxes almost touch -farther apart. - - -@funindex horizontal-shift -@item horizontal-shift -All systems (including titles and system separators) are shifted by -this amount to the right. Page markup, such as headers and footers are -not affected by this. The purpose of this variable is to make space -for instrument names at the left. Default is@tie{}0. - -@funindex after-title-space -@item after-title-space -Amount of space between the title and the first system. Default is@tie{}5mm. - -@funindex before-title-space -@item before-title-space -Amount of space between the last system of the previous piece and the -title of the next. Default is@tie{}10mm. - -@funindex between-title-space -@item between-title-space -Amount of space between consecutive titles (e.g., the title of the -book and the title of a piece). Default is@tie{}2mm. - -@funindex printallheaders -@item printallheaders -Setting this to #t will print all headers for each \score in a -\book. Normally only the piece and opus \headers are printed. - -@funindex systemSeparatorMarkup -@item systemSeparatorMarkup -This contains a markup object, which will be inserted between -systems. This is often used for orchestral scores. Unset by default. - -The markup command @code{\slashSeparator} is provided as a sensible -default, for example - -@lilypond[ragged-right] -#(set-default-paper-size "a6" 'landscape) -\book { - \score { - \relative { c1 \break c1 } - } - \paper { - systemSeparatorMarkup = \slashSeparator - } -} -@end lilypond - -@funindex blank-page-force -@item blank-page-force -The penalty for having a blank page in the middle of a -score. This is not used by @code{ly:optimal-breaking} since it will -never consider blank pages in the middle of a score. Default value -is 10. - -@funindex blank-last-page-force -@item blank-last-page-force -The penalty for ending the score on an odd-numbered page. -Default value is 0. - -@funindex page-spacing-weight -@item page-spacing-weight -The relative importance of page (vertical) spacing and line (horizontal) -spacing. High values will make page spacing more important. Default -value is 10. - -@funindex auto-first-page-number -@item auto-first-page-number -The page breaking algorithm is affected by the first page number being -odd or even. If this variable is set to #t, the page breaking algorithm -will decide whether to start with an odd or even number. This will -result in the first page number remaining as is or being increased by one. - -@end table -@end quotation - -Example: - -@example -\paper@{ - paper-width = 2\cm - top-margin = 3\cm - bottom-margin = 3\cm - ragged-last-bottom = ##t -@} -@end example - -You can also define these values in Scheme. In that case @code{mm}, -@code{in}, @code{pt}, and @code{cm} are variables defined in -@file{paper-defaults.ly} with values in millimeters. That is why the -value must be multiplied in the example - -@example -\paper @{ - #(define bottom-margin (* 2 cm)) -@} -@end example - -The header and footer are created by the functions @code{make-footer} -and @code{make-header}, defined in @code{\paper}. The default -implementations are in @file{ly/@/paper@/-defaults@/.ly} and -@file{ly/@/titling@/-init@/.ly}. - -The page layout itself is done by two functions in the -@code{\paper} block, @code{page-music-height} and -@code{page-make-stencil}. The former tells the line-breaking algorithm -how much space can be spent on a page, the latter creates the actual -page given the system to put on it. - - -@refbugs - -The option right-margin is defined but doesn't set the right margin -yet. The value for the right margin has to be defined adjusting the -values of @code{left-margin} and @code{line-width}. - -The default page header puts the page number and the @code{instrument} -field from the @code{\header} block on a line. - -The titles (from the @code{\header@{@}} section) are treated as a -system, so @code{ragged-bottom} and @code{ragged-last-bottom} will -add space between the titles and the first system of the score. - - -@node Music layout -@section Music layout - -@menu -* Setting global staff size:: -* Score layout:: -@end menu - - -@node Setting global staff size -@subsection Setting global staff size - -@cindex font size, setting -@cindex staff size, setting -@funindex layout file - -To set the global staff size, use @code{set-global-staff-size}. - -@example -#(set-global-staff-size 14) -@end example - -@noindent -This sets the global default size to 14pt staff height and scales all -fonts accordingly. - -The Feta font provides musical symbols at eight different -sizes. Each font is tuned for a different staff size: at a smaller size -the font becomes heavier, to match the relatively heavier staff lines. -The recommended font sizes are listed in the following table: - -@quotation -@multitable @columnfractions .15 .2 .22 .2 - -@item @b{font name} -@tab @b{staff height (pt)} -@tab @b{staff height (mm)} -@tab @b{use} - -@item feta11 -@tab 11.22 -@tab 3.9 -@tab pocket scores - -@item feta13 -@tab 12.60 -@tab 4.4 -@tab - -@item feta14 -@tab 14.14 -@tab 5.0 -@tab - -@item feta16 -@tab 15.87 -@tab 5.6 -@tab - -@item feta18 -@tab 17.82 -@tab 6.3 -@tab song books - -@item feta20 -@tab 20 -@tab 7.0 -@tab standard parts - -@item feta23 -@tab 22.45 -@tab 7.9 -@tab - -@item feta26 -@tab 25.2 -@tab 8.9 -@tab -@c modern rental material? - -@end multitable -@end quotation - -These fonts are available in any sizes. The context property -@code{fontSize} and the layout property @code{staff-space} (in -@internalsref{StaffSymbol}) can be used to tune the size for individual -staves. The sizes of individual staves are relative to the global size. - -@example - -@end example - -@seealso - -This manual: @ref{Selecting notation font size}. - - -@node Score layout -@subsection Score layout - -@funindex \layout - -While @code{\paper} contains settings that relate to the page formatting -of the whole document, @code{\layout} contains settings for score-specific -layout. - -@example -\layout @{ - indent = 2.0\cm - \context @{ \Staff - \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6) - @} - \context @{ \Voice - \override TextScript #'padding = #1.0 - \override Glissando #'thickness = #3 - @} -@} -@end example - - -@seealso - -This manual: @ref{Changing context default settings} - - -@node Vertical spacing -@section Vertical spacing - -@cindex vertical spacing -@cindex spacing, vertical - -Vertical spacing is controlled by three things: the amount of -space available (i.e., paper size and margins), the amount of -space between systems, and the amount of space between -staves inside a system. - -@menu -* Vertical spacing inside a system:: -* Vertical spacing of piano staves:: -* Vertical spacing between systems:: -* Controlling spacing of individual systems:: -* Two-pass vertical spacing:: -@end menu - - -@node Vertical spacing inside a system -@subsection Vertical spacing inside a system - -@cindex distance between staves -@cindex staff distance -@cindex space between staves -@cindex space inside systems - -The height of each system is determined automatically. To prevent -staves from bumping into each other, some minimum distances are set. -By changing these, you can put staves closer together. This -reduces the amount of space each system requires, and may result -in having more systems per page. - -Normally staves are stacked vertically. To make staves maintain a -distance, their vertical size is padded. This is done with the -property @code{minimum-Y-extent}. When applied to a -@internalsref{VerticalAxisGroup}, it controls the size of a horizontal -line, such as a staff or a line of lyrics. @code{minimum-Y-extent} -takes a pair of numbers, so -if you want to make it smaller than its default @code{#'(-4 . 4)} -then you could set - -@example -\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) -@end example - -@noindent -This sets the vertical size of the current staff to 3 staff spaces on -either side of the center staff line. The value @code{(-3 . 3)} is -interpreted as an interval, where the center line is the 0, so the -first number is generally negative. The numbers need not match; -for example, the staff can be made larger at the bottom by setting -it to @code{(-6 . 4)}. - - -@seealso - -Internals: Vertical alignment of staves is handled by the -@internalsref{VerticalAlignment} object. The context parameters -specifying the vertical extent are described in connection with -the @internalsref{Axis_group_engraver}. - -Example files: @inputfileref{input/regression/,page-spacing.ly}, -@inputfileref{input/regression/,alignment-vertical-spacing.ly}. - - -@node Vertical spacing of piano staves -@subsection Vertical spacing of piano staves - -The distance between staves of a @internalsref{PianoStaff} cannot be -computed during formatting. Rather, to make cross-staff beaming work -correctly, that distance has to be fixed beforehand. - -The distance of staves in a @code{PianoStaff} is set with the -@code{forced-distance} property of the -@internalsref{VerticalAlignment} object, created in -@internalsref{PianoStaff}. - -It can be adjusted as follows -@example -\new PianoStaff \with @{ - \override VerticalAlignment #'forced-distance = #7 -@} @{ - ... -@} -@end example - -@noindent -This would bring the staves together at a distance of 7 staff spaces, -measured from the center line of each staff. - -The difference is demonstrated in the following example, -@lilypond[quote,verbatim] -\relative c'' << - \new PianoStaff \with { - \override VerticalAlignment #'forced-distance = #7 - } << - \new Staff { c1 } - \new Staff { c } - >> - \new PianoStaff << - \new Staff { c } - \new Staff { c } - >> ->> -@end lilypond - - -@seealso - -Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}. - - -@node Vertical spacing between systems -@subsection Vertical spacing between systems - -Space between systems are controlled by four @code{\paper} variables, - -@example -\paper @{ - between-system-space = 1.5\cm - between-system-padding = #1 - ragged-bottom=##f - ragged-last-bottom=##f -@} -@end example - - -@node Controlling spacing of individual systems -@subsection Controlling spacing of individual systems - -It is also possible to change the distance between for each system -individually. This is done by including the command - -@example -\overrideProperty -#"Score.NonMusicalPaperColumn" -#'line-break-system-details -#'((fixed-alignment-extra-space . 15)) -@end example - -@noindent -at the line break before the system to be changed. The distance -@code{15} is distributed over all staves that have a fixed distance -alignment. For example, - -@lilypond[ragged-right, fragment, relative=2, staffsize=13] -\new PianoStaff << - \new Staff { - c1\break - - \overrideProperty - #"Score.NonMusicalPaperColumn" - #'line-break-system-details - #'((fixed-alignment-extra-space . 15)) - - c\break - } - \new Staff { c c } ->> -@end lilypond - -The distance for @code{fixed-alignment-extra-space} may also be -negative. - - -@node Two-pass vertical spacing -@subsection Two-pass vertical spacing - -In order to automatically stretch systems so that they should fill the -space left on a page, a two-pass technique can be used: - -@enumerate -@item In the first pass, the amount of vertical space used to increase -the height of each system is computed and dumped to a file. -@item In the second pass, spacing inside the systems are -stretched according to the data in the page layout file. -@end enumerate - -The @code{ragged-bottom} property adds space between systems, while -the two-pass technique adds space between staffs inside a system. - -To allow this behaviour, a @code{tweak-key} variable has to be set in -each score @code{\layout} block, and the tweaks included in each score -music, using the @code{\scoreTweak} music function. - -@quotation -@verbatim -%% include the generated page layout file: -\includePageLayoutFile - -\score { - \new StaffGroup << - \new Staff << - %% Include this score tweaks: - \scoreTweak "scoreA" - { \clef french c''1 \break c''1 } - >> - \new Staff { \clef soprano g'1 g'1 } - \new Staff { \clef mezzosoprano e'1 e'1 } - \new Staff { \clef alto g1 g1 } - \new Staff { \clef bass c1 c1 } - >> - \header { - piece = "Score with tweaks" - } - %% Define how to name the tweaks for this score: - \layout { #(define tweak-key "scoreA") } -} -@end verbatim -@end quotation - -For the first pass, the @code{dump-tweaks} option should be set to -generate the page layout file. - -@example -lilypond -b null -d dump-tweaks .ly -lilypond .ly -@end example - -@node Horizontal spacing -@section Horizontal Spacing - -@cindex horizontal spacing -@cindex spacing, horizontal - -@menu -* Horizontal spacing overview:: -* New spacing area:: -* Changing horizontal spacing:: -* Line length:: -@end menu - - -@node Horizontal spacing overview -@subsection Horizontal spacing overview - -The spacing engine translates differences in durations into stretchable -distances (``springs'') of differring lengths. Longer durations get -more space, shorter durations get less. The shortest durations get a -fixed amount of space (which is controlled by -@code{shortest-duration-space} in the @internalsref{SpacingSpanner} -object). The longer the duration, the more space it gets: doubling a -duration adds a fixed amount (this amount is controlled by -@code{spacing-increment}) of space to the note. - -For example, the following piece contains lots of half, quarter, and -8th notes; the eighth note is followed by 1 note head width (NHW). -The quarter note is followed by 2 NHW, the half by 3 NHW, etc. - -@lilypond[quote,fragment,verbatim,relative=1] -c2 c4. c8 c4. c8 c4. c8 c8 -c8 c4 c4 c4 -@end lilypond - -Normally, @code{spacing-increment} is set to 1.2 staff space, which is -approximately the width of a note head, and -@code{shortest-duration-space} is set to 2.0, meaning that the -shortest note gets 2.4 staff space (2.0 times the -@code{spacing-increment}) of horizontal space. This space is counted -from the left edge of the symbol, so the shortest notes are generally -followed by one NHW of space. - -If one would follow the above procedure exactly, then adding a single -32nd note to a score that uses 8th and 16th notes, would widen up the -entire score a lot. The shortest note is no longer a 16th, but a 32nd, -thus adding 1 NHW to every note. To prevent this, the shortest -duration for spacing is not the shortest note in the score, but rather -the one which occurs most frequently. - - -The most common shortest duration is determined as follows: in every -measure, the shortest duration is determined. The most common shortest -duration is taken as the basis for the spacing, with the stipulation -that this shortest duration should always be equal to or shorter than -an 8th note. The shortest duration is printed when you run -@code{lilypond} with the @code{--verbose} option. - -These durations may also be customized. If you set the -@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then -this sets the base duration for spacing. The maximum duration for this -base (normally an 8th), is set through @code{base-shortest-duration}. - -@funindex common-shortest-duration -@funindex base-shortest-duration -@funindex stem-spacing-correction -@funindex spacing - -Notes that are even shorter than the common shortest note are -followed by a space that is proportional to their duration relative to -the common shortest note. So if we were to add only a few 16th notes -to the example above, they would be followed by half a NHW: - -@lilypond[quote,fragment,verbatim,relative=2] -c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 -@end lilypond - - -In the introduction (see @ref{Engraving}), it was explained that stem -directions influence spacing. This is controlled with the -@code{stem-spacing-correction} property in the -@internalsref{NoteSpacing}, object. These are generated for every -@internalsref{Voice} context. The @code{StaffSpacing} object -(generated in @internalsref{Staff} context) contains the same property -for controlling the stem/bar line spacing. The following example shows -these corrections, once with default settings, and once with -exaggerated corrections: - -@lilypond[quote,ragged-right] -{ - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| - \override Staff.NoteSpacing #'stem-spacing-correction = #1.5 - \override Staff.StaffSpacing #'stem-spacing-correction = #1.5 - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| -} -@end lilypond - -Proportional notation is supported; see @ref{Proportional notation}. - - -@seealso - -Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, -@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and -@internalsref{SeparatingGroupSpanner}. - - -@refbugs - -There is no convenient mechanism to manually override spacing. The -following work-around may be used to insert extra space into a score. -@example - \once \override Score.SeparationItem #'padding = #1 -@end example - -No work-around exists for decreasing the amount of space. - - -@node New spacing area -@subsection New spacing area - -New sections with different spacing parameters can be started with -@code{newSpacingSection}. This is useful when there are -sections with a different notions of long and short notes. - -In the following example, the time signature change introduces a new -section, and hence the 16ths notes are spaced wider. - -@lilypond[relative,fragment,verbatim,quote] -\time 2/4 -c4 c8 c -c8 c c4 c16[ c c8] c4 -\newSpacingSection -\time 4/16 -c16[ c c8] -@end lilypond - - -@node Changing horizontal spacing -@subsection Changing horizontal spacing - -Horizontal spacing may be altered with the -@code{base-shortest-duration} property. Here -we compare the same music; once without altering -the property, and then altered. Larger values -of @code{ly:make-moment} will produce smaller -music. - -@lilypond[relative,verbatim,line-width=12\cm] -\score { - \relative c'' { - g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 | - g4 e e2 | f4 d d2 | c4 e g g | c,1 | - d4 d d d | d4 e f2 | e4 e e e | e4 f g2 | - g4 e e2 | f4 d d2 | c4 e g g | c,1 | - } -} -@end lilypond - -@lilypond[relative,verbatim,line-width=12\cm] -\score { - \relative c'' { - g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 | - g4 e e2 | f4 d d2 | c4 e g g | c,1 | - d4 d d d | d4 e f2 | e4 e e e | e4 f g2 | - g4 e e2 | f4 d d2 | c4 e g g | c,1 | - } - \layout { - \context { - \Score - \override SpacingSpanner - #'base-shortest-duration = #(ly:make-moment 1 4) - } - } -} -@end lilypond - - -@commonprop - -By default, spacing in tuplets depends on various non-duration -factors (such as accidentals, clef changes, etc). To disregard -such symbols and force uniform equal-duration spacing, use -@code{Score.SpacingSpanner #'uniform-stretching}. This -property can only be changed at the beginning of a score, - -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -\new Score \with { - \override SpacingSpanner #'uniform-stretching = ##t -} << - \new Staff{ - \times 4/5 { - c8 c8 c8 c8 c8 - } - c8 c8 c8 c8 - } - \new Staff{ - c8 c8 c8 c8 - \times 4/5 { - c8 c8 c8 c8 c8 - } - } ->> -@end lilypond - - -When @code{strict-note-spacing} is set, notes are spaced without -regard for clefs, bar lines, and grace notes, - -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -\override Score.SpacingSpanner #'strict-note-spacing = ##t -\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] } -@end lilypond - - -@node Line length -@subsection Line length - -@cindex page breaks -@cindex breaking pages - -@funindex indent -@funindex line-width -@funindex ragged-right -@funindex ragged-last - -@c Although line-width can be set in \layout, it should be set in paper -@c block, to get page layout right. -@c Setting indent in \paper block makes not much sense, but it works. - -@c Bit verbose and vague, use examples? -The most basic settings influencing the spacing are @code{indent} and -@code{line-width}. They are set in the @code{\layout} block. They -control the indentation of the first line of music, and the lengths of -the lines. - -If @code{ragged-right} is set to true in the @code{\layout} block, then -systems ends at their natural horizontal length, instead of being spread -horizontally to fill the whole line. This is useful for -short fragments, and for checking how tight the natural spacing is. - -@cindex page layout -@cindex vertical spacing - -The option @code{ragged-last} is similar to @code{ragged-right}, but -only affects the last line of the piece. No restrictions are put on -that line. The result is similar to formatting text paragraphs. In a -paragraph, the last line simply takes its natural horizontal length. -@c Note that for text there are several options for the last line. -@c While Knuth TeX uses natural length, lead typesetters use the same -@c stretch as the previous line. eTeX uses \lastlinefit to -@c interpolate between both these solutions. - -@example -\layout @{ - indent = #0 - line-width = #150 - ragged-last = ##t -@} -@end example - - -@node Breaks -@section Breaks - -@menu -* Line breaking:: -* Page breaking:: -* Optimal page breaking:: -* Optimal page turning:: -@end menu - -@node Line breaking -@subsection Line breaking - -@cindex line breaks -@cindex breaking lines - -Line breaks are normally computed automatically. They are chosen so -that lines look neither cramped nor loose, and that consecutive lines -have similar density. - -Occasionally you might want to override the automatic breaks; you can -do this by specifying @code{\break}. This will force a line break at -this point. Line breaks can only occur at places where there are bar -lines. If you want to have a line break where there is no bar line, -you can force an invisible bar line by entering @code{\bar -""}. Similarly, @code{\noBreak} forbids a line break at a -point. - - -@cindex regular line breaks -@cindex four bar music. - -For line breaks at regular intervals use @code{\break} separated by -skips and repeated with @code{\repeat}: -@example -<< \repeat unfold 7 @{ - s1 \noBreak s1 \noBreak - s1 \noBreak s1 \break @} - @emph{the real music} ->> -@end example - -@noindent -This makes the following 28 measures (assuming 4/4 time) be broken every -4 measures, and only there. - -@refcommands - -@code{\break}, and @code{\noBreak}. -@funindex \break -@funindex \noBreak - -@seealso - -Internals: @internalsref{LineBreakEvent}. - -A linebreaking configuration can now be saved as a @code{.ly} file -automatically. This allows vertical alignments to be stretched to -fit pages in a second formatting run. This is fairly new and -complicated; see @inputfileref{input/regression/,page-layout-twopass.ly} -for details. - -@refbugs - -Line breaks can only occur if there is a ``proper'' bar line. A note -which is hanging over a bar line is not proper, such as - -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -c4 c2 c2 \break % this does nothing -c2 c4 | % a break here would work -c4 c2 c4 ~ \break % as does this break -c4 c2 c4 -@end lilypond - -To allow line breaks on such bar lines, the -@code{Forbid_line_break_engraver} can be removed from @code{Voice} -context, like so - - -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -\new Voice \with { - \remove "Forbid_line_break_engraver" -} { - c4 c2 c2 \break % now the break is allowed - c2 c4 -} -@end lilypond - - - -@node Page breaking -@subsection Page breaking - -The default page breaking may be overriden by inserting -@code{\pageBreak} or @code{\noPageBreak} commands. These commands are -analogous to @code{\break} and @code{\noBreak}. They should be -inserted at a bar line. These commands force and forbid a page-break -from happening. Of course, the @code{\pageBreak} command also forces -a line break. - -Page breaks are computed by the @code{page-breaking} function. -LilyPond provides two algorithms for computing page -breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The -default is @code{ly:optimal-breaking}, but the value can be changed in -the @code{\paper} block: - -@example -\paper@{ - #(define page-breaking ly:page-turn-breaking) -@} -@end example - -The old page breaking algorithm is called -@code{optimal-page-breaks}. If you are having trouble with the new page -breakers, you can enable the old one as a workaround. - -@refcommands - -@funindex \pageBreak -@code{\pageBreak} -@funindex \noPageBreak -@code{\noPageBreak} - - -@node Optimal page breaking -@subsection Optimal page breaking - -@funindex ly:optimal-breaking - -The @code{ly:optimal-breaking} function is LilyPond's default method of -determining page breaks. It attempts to find a page breaking that minimizes -cramping and stretching, both horizontally and vertically. Unlike -@code{ly:page-turn-breaking}, it has no concept of page turns. - - -@node Optimal page turning -@subsection Optimal page turning - -@funindex ly:page-turn-breaking - -Often it is necessary to find a page breaking configuration so that there is -a rest at the end of every second page. This way, the musician can turn the -page without having to miss notes. The @code{ly:page-turn-breaking} function -attempts to find a page breaking minimizing cramping and stretching, but with -the additional restriction that it is only allowed to introduce page turns -in specified places. - -There are two steps to using this page breaking function. First, you must -enable it in the @code{\paper} block. Then, you must tell the function -where you would like to allow page breaks. - -There are two ways to achieve the second step. First, you can specify each -potential page turn manually, by inserting @code{\allowPageTurn} into your -input file at the appropriate places. - -If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or -Voice context. The @code{Page_turn_engraver} will scan the context for -sections without notes (note that it does not scan for rests; it scans for -the absence of notes. This is so that single-staff polyphony with rests in one -of the parts does not throw off the @code{Page_turn_engraver}). When it finds -a sufficiently long section without notes, the @code{Page_turn_engraver} will -insert an @code{\allowPageTurn} at the final barline in that section, unless -there is a ``special'' barline (such as a double bar), in which case the -@code{\allowPageTurn} will be inserted at the final ``special'' barline in -the section. - -@funindex minimumPageTurnLength -The @code{Page_turn_engraver} reads the context property -@code{minimumPageTurnLength} to determine how long a note-free section must -be before a page turn is considered. The default value for -@code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}. If you want -to disable page turns, you can set it to something very large. - -@example -\new Staff \with @{ \consists "Page_turn_engraver" @} -@{ - a4 b c d | - R1 | % a page turn will be allowed here - a4 b c d | - \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2) - R1 | % a page turn will not be allowed here - a4 b r2 | - R1*2 | % a page turn will be allowed here - a1 -@} -@end example - -@funindex minimumRepeatLengthForPageTurn -The @code{Page_turn_engraver} detects volta repeats. It will only allow a page -turn during the repeat if there is enough time at the beginning and end of the -repeat to turn the page back. The @code{Page_turn_engraver} can also disable -page turns if the repeat is very short. If you set the context property -@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will -only allow turns in repeats whose duration is longer than this value. - -@refbugs - -There should only be one @code{Page_turn_engraver} in a score. If there is more -than one, they will interfere with each other. - - -@node Displaying spacing -@section Displaying spacing - -@funindex annotate-spacing -@cindex Spacing, display of properties - -To graphically display the dimensions of vertical properties that may -be altered for page formatting, set @code{annotate-spacing} in the -@code{\paper} block, like this - - -@lilypond[verbatim] -#(set-default-paper-size "a6" 'landscape) - -\book { - \score { { c4 } } - \paper { annotate-spacing = ##t } -} -@end lilypond - -@c need to have \book{} otherwise we get the separate systems. -hwn - -@noindent -@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp -Some unit dimensions are measured in staff spaces, while others -are measured in millimeters. -The pairs -(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and -@var{b} the upper edge of the interval. - - diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely new file mode 100644 index 0000000000..81b6751d20 --- /dev/null +++ b/Documentation/user/running.itely @@ -0,0 +1,796 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely + +@node Running LilyPond +@chapter Running LilyPond + +This chapter details the technicalities of running LilyPond. + +Some of these commands are run from the command-line. By +``command-line'', we mean the command +line in the operating system. Windows users +might be more familiar with the terms ``DOS shell'' or +``command shell''; OSX users might be more familiar with the +terms ``terminal'' or ``console''. OSX users should also +consult @ref{Notes for the MacOS X app}. + +Describing how to use +this part of an operating system is outside the scope of this +manual; please consult other documentation on this topic if +you are unfamiliar with the command-line. + +@menu +* Invoking lilypond:: +* Notes for the MacOS X app:: +* Updating files with convert-ly:: +* Reporting bugs:: +* Error messages:: +* Editor support:: +* Point and click:: +@end menu + +@node Invoking lilypond +@section Invoking lilypond +@cindex Invoking LilyPond +@cindex command line options +@cindex options, command line +@cindex switches + + +The @code{lilypond} executable may be called as follows from the command line. + +@example +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 +dash (@code{-}) for @var{file}. + +When @file{filename.ly} is processed it will produce +@file{filename.tex} as output (or @file{filename.ps} for PostScript +output). If @file{filename.ly} contains more than one @code{\score} +block, then the rest of the scores will be output in numbered files, +starting with @file{filename-1.tex}. Several files can be specified; +they will each be processed independently. @footnote{The status of +GUILE is not reset after processing a @code{.ly} file, so be careful +not to change any system defaults from within Scheme.} + + +@subsection Command line options + +The following options are supported: + +@table @code + +@item -e,--evaluate=@var{expr} +Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. +Multiple @code{-e} options may be given, they will be evaluated +sequentially. + +The expression will be evaluated in the @code{guile-user} module, so +if you want to use definitions in @var{expr}, use + +@example +lilypond -e '(define-public a 42)' +@end example + +@noindent +on the command-line, and include + +@example +#(use-modules (guile-user)) +@end example + +@noindent +at the top of the @code{.ly} file. + +@item -f,--format=@var{format} +which formats should be written. Choices are @code{svg}, @code{ps}, +@code{pdf}, @code{png}, @code{tex}, @code{dvi}. + +@item -b,--backend=@var{format} +the output format to use for the back-end. Choices are +@table @code +@item tex +for @TeX{} output, to be processed with La@TeX{}. If present, the file +@file{file.textmetrics} is read to determine text extents. +@item texstr +dump text strings to @file{.texstr} file, which can be run through +(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the +extents of strings of text. @strong{Warning:} this functionality is +currently missing due to heavy restructuring of the source code. +@item ps + for PostScript. +@cindex PostScript output + + Postscript files include TTF, Type1 and OTF fonts. No subsetting of + these fonts is done. When using oriental character sets, this can + lead to huge files. + +@item eps + for encapsulated PostScript. This dumps every page (system) as a separate +@file{EPS} file, without fonts, and as one collated @file{EPS} file with +all pages (systems) including fonts. + +This mode is used by default by lilypond-book. + +@item svg + for SVG (Scalable Vector Graphics). This dumps every page as a separate +@file{SVG} file, with embedded fonts. +@cindex SVG (Scalable Vector Graphics) + You need a SVG viewer which supports embedded fonts, or a SVG + viewer which is able to replace the embedded fonts with OTF fonts. + Under Unix, you may use @uref{http://www.inkscape.org,Inkscape} + (version 0.42 or later), after copying the OTF fonts in directory + @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}. +@item scm + for a dump of the raw, internal Scheme-based drawing commands. +@cindex Scheme dump +@end table + +@cindex output format, setting + +@item -d,--define-default=@var{var}=@var{val} +This sets the internal program option @var{var} to the Scheme value +@var{val}. If @var{val} is not supplied, then @var{#t} is used. To +switch off an option, @code{no-} may be prefixed to @var{var}, e.g. + +@cindex point and click, command line + +@example +-dno-point-and-click +@end example + +@noindent +is the same as +@example +-dpoint-and-click='#f' +@end example + +Another notable option is + +@example +-dpaper-size=\"letter\" +@end example + +@noindent +Note that the string must be enclosed in escaped quotes ( @code{\"} ). + +Setting the @code{-dhelp} option will print a summary of the options +available, and exit. + +@item -h,--help +Show a summary of usage. + +@item -H,--header=FIELD +Dump a header field to file BASENAME.FIELD + +@item --include, -I=@var{directory} +Add @var{directory} to the search path for input files. +@cindex file searching +@cindex search path + +@item -i,--init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). + +@item -o,--output=@var{FILE} +Set the default output file to @var{FILE}. The appropriate +suffix will be added (ie @code{.pdf} for pdf, @code{.tex} +for tex, etc). + +@item --ps +Generate PostScript. + +@item --dvi +Generate DVI files. In this case, the @TeX{} backend should be +specified, i.e., @code{-b tex}. + +@item --png +Generate pictures of each page, in PNG format. This implies +@code{--ps}. The resolution in DPI of the image may be set with +@example +-dresolution=110 +@end example + +@item --pdf +Generate PDF. This implies @code{--ps}. + +@item --preview +Generate an output file containing the titles and the first system + +@item --no-pages +Do not generate the full pages. Useful in combination with +@code{--preview}. + +@item -s,--safe +Do not trust the @code{.ly} input. + +When LilyPond formatting is available through a web server, either the +@code{--safe} or the @code{--jail} option @b{MUST} be passed. The +@code{--safe} option will prevent inline Scheme code from wreaking +havoc, for example + +@quotation +@verbatim +#(system "rm -rf /") +{ + c4^#(ly:export (ly:gulp-file "/etc/passwd")) +} +@end verbatim +@end quotation + +The @code{--safe} option works by evaluating in-line Scheme +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}. + +In addition, @code{--safe} disallows @code{\include} directives and +disables the use of backslashes in @TeX{} strings. + +In @code{--safe} mode, it is not possible to import LilyPond variables +into Scheme. + +@code{--safe} does @emph{not} detect resource overuse. It is still +possible to make the program hang indefinitely, for example by feeding +cyclic data structures into the backend. Therefore, if using LilyPond +on a publicly accessible webserver, the process should be limited in +both CPU and memory usage. + +Note that @code{--safe} will prevent many useful LilyPond snippets from +being compiled. For a softer but secure alternative you can use the +@code{--jail} option. + + +@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} +Run LilyPond in a chroot jail. + +The @code{--jail} option provides a more flexible alternative to +@code{--safe} when LilyPond formatting is available through a web +server or whenever LilyPond executes externally provided +sources. + +The @code{--jail} option works by changing the root of LilyPond to +@var{jail} just before starting the actual compilation process. The user +and group are then changed to match those provided, and the current +directory is changed to @var{dir}. This setup guarantees that it is not +possible (at least in theory) to escape from the jail. Note that for +@code{--jail} to work LilyPond must be run as root, which is usually +accomplished in a safe way using @command{sudo}. + +Setting up a jail is a slightly delicate matter, as we must be sure that +LilyPond is able to find whatever it needs to compile the source +@emph{inside the jail}. A typical setup comprises the following items: + +@table @asis +@item Setting up a separate filesystem +A separate filesystem should be created for LilyPond, so that it can be +mounted with safe options such as @code{noexec}, @code{nodev}, and +@code{nosuid}. In this way, it is impossible to run executables or to +write directly to a device from LilyPond. If you do not want to create a +separate partition, just create a file of reasonable size and use it to +mount a loop device. A separate filesystem also guarantees that LilyPond +cannot write more space than it is allowed. + +@item Setting up a separate user +A separate user and group (say, @samp{lily}/@samp{lily}) with low +privileges should be used to run LilyPond inside the jail. There should +be a single directory writable by this user, which should be passed in +@var{dir}. + +@item Preparing the jail +LilyPond needs to read a number of files while running. All these files +are to be copied into the jail, under the same path they appear in the +real root filesystem. The entire content of the LilyPond installation +(e.g., @file{/usr/share/lilypond}) +should be copied. + +If problems arise, the simplest way to trace them down is to run +LilyPond using @command{strace}, which will allow you to determine which +files are missing. + +@item Running LilyPond +In a jail mounted with @code{noexec} it is impossible to execute any external +program. Therefore LilyPond must be run with a backend that does not +require any such program. As we already mentioned, it must be also run +with superuser privileges (which, of course, it will lose immediately), +possibly using @command{sudo}. It is a good idea to limit the number of +seconds of CPU time LilyPond can use (e.g., using @command{ulimit +-t}), and, if your operating system supports it, the amount of memory +that can be allocated. +@end table + + +@item -v,--version +Show version information. + +@item -V,--verbose +Be verbose: show full paths of all files read, and give timing +information. + +@item -w,--warranty +Show the warranty with which GNU LilyPond comes. (It comes with +@strong{NO WARRANTY}!) +@end table + + +@subsection Environment variables + + +@cindex LANG +@cindex LILYPONDPREFIX + +@code{Lilypond} 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 +subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. + +@item LANG +This selects the language for the warning messages. + +@item LILYPOND_GC_YIELD +With this variable the memory footprint and performance can be +adjusted. It is a percentage tunes memory management behavior. With +higher values, the program uses more memory, with smaller values, it +uses more CPU time. The default value is @code{70}. + +@end table + + +@node Notes for the MacOS X app +@section Notes for the MacOS X app + +The scripts (such as lilypond-book, convert-ly, abc2ly, and even +lilypond itself) are also +included inside MacOS X .app. They can be run from the command line by +invoking them directly, e.g. + +@example +@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond +@end example + +@noindent +The same is true of the other scripts in that directory, including +lilypond-book, convert-ly, abc2ly, etc. + +Alternatively, you may add this directory to your path. Modify (or create) +a file called @code{.profile} in your home directory such that it contains + +@example +export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin +@end example + +@noindent +This file should end with a blank line. + +Note that @var{path/to} will generally be @code{/Applications/}. + + +@node Updating files with convert-ly +@section Updating with @command{convert-ly} + +@cindex Updating a LilyPond file +@funindex convert-ly + +The LilyPond input syntax is routinely changed to simplify it or improve +it in different ways. As a side effect of this, the LilyPond interpreter +often is no longer compatible with older input files. To remedy this, +the program @command{convert-ly} can be used to deal with most of the +syntax changes between LilyPond versions. + +It uses @code{\version} statements in the input files to detect the +old version number. In most cases, to upgrade your input file it is +sufficient to run@footnote{MacOS X users may execute this command +under the menu entry @samp{Compile > Update syntax}.} + +@example +convert-ly -e myfile.ly +@end example + +If there are no changes to myfile.ly and file called myfile.ly.NEW +is created, then myfile.ly is already updated. + +@command{convert-ly} always converts up to the last syntax change handled by +it. This means that the @code{\version} number left in the file is +usually lower than the version of @command{convert-ly} itself. + +To upgrade LilyPond fragments in texinfo files, use + +@example +convert-ly --from=... --to=... --no-version *.itely +@end example + +To upgrade many files at once, combine @code{convert-ly} with +standard unix commands. This example will upgrade all @code{.ly} +files in the current directory + +@example +for f in *.ly; do convert-ly -e $f; done; +@end example + +In general, the program is invoked as follows: + +@example +convert-ly [@var{option}]@dots{} @var{file}@dots{} +@end example + + +The following options can be given: + +@table @code +@item -e,--edit +Do an inline edit of the input file. Overrides @code{--output}. + +@item -f,--from=@var{from-patchlevel} +Set the version to convert from. If this is not set, @command{convert-ly} +will guess this, on the basis of @code{\version} strings in the file. + +@item -n,--no-version +Normally, @command{convert-ly} adds a @code{\version} indicator +to the output. Specifying this option suppresses this. + +@item -s, --show-rules +Show all known conversions and exit. + +@item --to=@var{to-patchlevel} +Set the goal version of the conversion. It defaults to the latest +available version. + +@item -h, --help +Print usage help. +@end table + + +@refbugs + +Not all language changes are handled. Only one output option can be +specified. Automatically updating scheme and lilypond scheme +interfaces is quite unlikely; be prepared to tweak scheme code +manually. + + +@c We might want to make this a completely new section, along with more +@c info about how to upgrade old input files. -gp + +@ignore +Copy and paste from CVS, last updated +Aug 18, 2005 + +http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/ +convert-ly.txt?rev=HEAD&content-type=text/plain + +NEW: not exactly copied; this list has been modified. Since we're +changing the bug system, it doesn't make sense to copy from +the bug CVS any more. I'll figure out something else. -gp +@end ignore +@verbatim + +There are a few things that the convert-ly cannot handle. Here's a list of +limitations +that the community has complained about. + +This bug report structure has been chosen because convert-ly has a structure +that doesn't +allow to smoothly implement all needed changes. Thus this is just a wishlist, +placed +here for reference. + +1.6->2.0: + Doesn't always convert figured bass correctly, specifically things like {< +>}. Mats' comment on working around this: + To be able to run convert-ly + on it, I first replaced all occurencies of '{<' to some dummy like '{#' + and similarly I replaced '>}' with '&}'. After the conversion, I could + then change back from '{ #' to '{ <' and from '& }' to '> }'. + Doesn't convert all text markup correctly. In the old markup syntax, + it was possible to group a number of markup commands together within +parentheses, e.g. + -#'((bold italic) "string") + This will incorrectly be converted into + -\markup{{\bold italic} "string"} + instead of the correct + -\markup{\bold \italic "string"} +2.0->2.2: + Doesn't handle \partcombine + Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple +stanzas. +2.0->2.4: + \magnify isn't changed to \fontsize. + - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) + remove-tag isn't changed. + - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . + first-page-number isn't changed. + - first-page-number no => print-first-page-number = ##f + Line breaks in header strings aren't converted. + - \\\\ as line break in \header strings => \markup \center-align < + "First Line" "Second Line" > + Crescendo and decrescendo terminators aren't converted. + - \rced => \! + - \rc => \! +2.2->2.4: + \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly +converted. +2.4.2->2.5.9 + \markup{ \center-align <{ ... }> } should be converted to: + \markup{ \center-align {\line { ... }} } + but now, \line is missing. +2.4->2.6 + Special LaTeX characters such as $~$ in text are not converted to UTF8. +2.8 + \score{} must now begin with a music expression. Anything else + (particularly \header{}) must come after the music. +@end verbatim + + +@node Reporting bugs +@section Reporting bugs + +@cindex bugs +@cindex reporting bugs + +If you have input that results in a crash or an erroneous output, then +that is a bug. We try to 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. Send the report via: + +@example +@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs} +@end example + +A few tips: +@itemize @bullet + +@item Try to produce a very small input file which demonstrates the problem; +one or two bars is often sufficient to reproduce a bug. The smaller the +input file is, the easier it is for us to debug the problem. + +@item Don't forget to tell which version of LilyPond you use! + +@item If possible, use @code{ragged-right} in your example. This makes sure +that the bug can be reproduced in all paper sizes. +@end itemize + +@ignore +@c the bug database is not up to date enough. + +When you've found a bug, have a look at our +@uref{http://@/lilypond@/.org/@/bugs/@/v2.8/@/,bug database} to see if +it has already been reported. You could also try to 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. +@end ignore + +Here is an example of a good bug report: + +@verbatim +It seems that placement of accidentals is broken. In the +following example, the accidental touches the note head. + +Using Mac OSX 10.3.7, lilypond 2.7.32 + +\version "2.9.13" +\layout { ragged-right = ##t } +\relative c'' { + a4 b cis d +} +@end verbatim + +@lilypond[quote] +\layout { ragged-right = ##t } +\relative c''{ + \override Accidental #'extra-offset = #'(1.0 . 0) + a4 b cis d +} +@end lilypond + +@node Error messages +@section Error messages + +@cindex error messages +Different error messages can appear while compiling a file: + +@table @emph +@cindex warning + +@item Warning +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. + +@item Error +Something is definitely wrong. The current processing step (parsing, +interpreting, or formatting) will be finished, but the next step will +be skipped. + +@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. + +@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 +@code{--verbose}) then a call trace of the offending +function call is printed. + +@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. + +@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, +send a bug-report. + + +@end table + +@cindex errors, message format +If warnings and errors can +be linked to some part of the input file, then error messages have the +following form + +@example +@var{filename}:@var{lineno}:@var{columnno}: @var{message} +@var{offending input line} +@end example + +A line-break is inserted in the offending line to indicate the column +where the error was found. For example, + +@example +test.ly:2:19: error: not a duration: 5: + @{ c'4 e'5 + g' @} +@end example + +These locations are LilyPond's best guess about where the warning or +error occurred, but (by their very nature) warnings 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 Editor support +@section Editor support + +@cindex editors +@cindex vim +@cindex emacs +@cindex modes, editor +@cindex syntax coloring +@cindex coloring, syntax + +There is support from different editors for LilyPond. + +@table @asis +@item Emacs +Emacs has a @file{lilypond-mode}, which provides keyword +autocompletion, indentation, LilyPond specific parenthesis matching +and syntax coloring, handy compile short-cuts and reading LilyPond +manuals using Info. If @file{lilypond-mode} is not installed on your +platform, then read the +@ifhtml +@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. +@end ifhtml +@ifnothtml +installation instructions. +@end ifnothtml + +@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 +@ifhtml +@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. +@end ifhtml +@ifnothtml +installation instructions. +@end ifnothtml + + +@item JEdit + +The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin. +This plugin includes a DVI viewer, integrated help and viewing via +GhostScript. It can be installed by doing @key{Plugins > Plugin +Manager}, and selecting @code{LilyTool} from the @key{Install} tab. + +@end table + +All these editors can be made to jump into the input file to the source +of a symbol in the graphical output. See @ref{Point and click}. + + +@node Point and click +@section Point and click +@cindex point and click + + +Point and click lets you find notes in the input by clicking on them +in the PDF viewer. This makes it easier to find input that causes +some error in the sheet music. + +When this functionality is active, LilyPond adds hyperlinks to the PDF +file. These hyperlinks are sent to the web-browser, which opens a +text-editor with the cursor in the right place. + +To make this chain work, you should configure your PDF viewer to +follow hyperlinks using the @file{lilypond-invoke-editor} script +supplied with LilyPond. + +For Xpdf on Unix, the following should be present in +@file{xpdfrc}@footnote{On unix, this file is found either in +@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} + +@example +urlCommand "lilypond-invoke-editor %s" +@end example + +The program @file{lilypond-invoke-editor} is a small helper +program. It will invoke an editor for the special @code{textedit} +URIs, and run a web browser for others. It tests the environment +variable @code{EDITOR} for the following patterns, + +@table @code +@item emacs + this will invoke +@example +emacsclient --no-wait +@var{line}:@var{column} @var{file} +@end example +@item vim + this will invoke +@example +gvim --remote +:@var{line}:norm@var{char} @var{file} +@end example + +@item nedit +this will invoke +@example + nc -noask +@var{line} @var{file}' +@end example +@end table + +The environment variable @code{LYEDITOR} is used to override this. It +contains the command line to start the editor, where @code{%(file)s}, +@code{%(column)s}, @code{%(line)s} is replaced with the file, column +and line respectively. The setting + +@example +emacsclient --no-wait +%(line)s:%(column)s %(file)s +@end example + +@noindent +for @code{LYEDITOR} is equivalent to the standard emacsclient +invocation. + + +@cindex file size, output + +The point and click links enlarge the output files significantly. For +reducing the size of PDF and PS files, point and click may be switched +off by issuing + +@example +#(ly:set-option 'point-and-click #f) +@end example + +@noindent +in a @file{.ly} file. Alternately, you may pass this as an command-line +option + +@example +lilypond -dno-point-and-click file.ly +@end example + diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely new file mode 100644 index 0000000000..aa4a6039b8 --- /dev/null +++ b/Documentation/user/spacing.itely @@ -0,0 +1,1172 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely + +@c A menu is needed before every deeper *section nesting of @node's; run +@c M-x texinfo-all-menus-update +@c to automatically fill in these menus before saving changes + +@node Spacing issues +@chapter Spacing issues + +The global paper layout is determined by three factors: the page layout, the +line breaks, and the spacing. These all influence each other. The +choice of spacing determines how densely each system of music is set. +This influences where line breaks are chosen, and thus ultimately, how +many pages a piece of music takes. + +Globally speaking, this procedure happens in four steps: first, +flexible distances (``springs'') are chosen, based on durations. All +possible line breaking combinations are tried, and a ``badness'' score +is calculated for each. Then the height of each possible system is +estimated. Finally, a page breaking and line breaking combination is chosen +so that neither the horizontal nor the vertical spacing is too cramped +or stretched. + +@menu +* Paper and pages:: +* Music layout:: +* Vertical spacing:: +* Horizontal spacing:: +* Breaks:: +* Displaying spacing:: +@end menu + + +@node Paper and pages +@section Paper and pages + +This section deals with the boundaries that define the area +that music can be printed inside. + +@menu +* Paper size:: +* Page formatting:: +@end menu + + +@node Paper size +@subsection Paper size + +@cindex paper size +@cindex page size +@funindex papersize + +To change the paper size, there are two commands, +@example +#(set-default-paper-size "a4") +\paper @{ + #(set-paper-size "a4") +@} +@end example + +The first command sets the size of all pages. The second command sets the +size +of the pages that the @code{\paper} block applies to -- if the @code{\paper} +block is at the top of the file, then it will apply to all pages. If the +@code{\paper} block is inside a @code{\book}, then the paper size will only +apply to that book. + +Support for the following paper sizes are included by default, +@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter}, +@code{11x17} (also known as tabloid). + +Extra sizes may be added by editing the definition for +@code{paper-alist} in the initialization file @file{scm/paper.scm}. + +@cindex orientation +@cindex landscape + +If the symbol @code{landscape} is supplied as an argument to +@code{set-default-paper-size}, the pages will be rotated by 90 degrees, +and wider line widths will be set correspondingly. + +@example +#(set-default-paper-size "a6" 'landscape) +@end example + +Setting the paper size will adjust a number of @code{\paper} variables +(such as margins). To use a particular paper size with altered +@code{\paper} variables, set the paper size before setting the variables. + + +@node Page formatting +@subsection Page formatting + +@cindex page formatting +@cindex margins +@cindex header, page +@cindex footer, page + +LilyPond will do page layout, set margins, and add headers and +footers to each page. + +The default layout responds to the following settings in the +@code{\paper} block. + +@funindex \paper + +@quotation +@table @code +@funindex first-page-number +@item first-page-number +The value of the page number of the first page. Default is@tie{}1. + +@funindex printfirst-page-number +@item print-first-page-number +If set to true, will print the page number in the first page. Default is +false. + +@funindex print-page-number +@item print-page-number +If set to false, page numbers will not be printed. Default is true. + +@funindex paper-width +@item paper-width +The width of the page. The default is taken from the current paper size, +see @ref{Paper size}. + +@funindex paper-height +@item paper-height +The height of the page. The default is taken from the current paper size, +see @ref{Paper size}. + +@funindex top-margin +@item top-margin +Margin between header and top of the page. Default is@tie{}5mm. + +@funindex bottom-margin +@item bottom-margin +Margin between footer and bottom of the page. Default is@tie{}6mm. + +@funindex left-margin +@item left-margin +Margin between the left side of the page and the beginning of the +music. Unset by default, which means that the margins is determined +based on the @code{paper-width} and @code{line-width} to center the +score on the paper. + +@funindex line-width +@item line-width +The length of the systems. Default is @code{paper-width} minus @tie{}20mm. + +@funindex head-separation +@item head-separation +Distance between the top-most music system and the page header. Default +is@tie{}4mm. + +@funindex foot-separation +@item foot-separation +Distance between the bottom-most music system and the page +footer. Default is@tie{}4mm. + +@funindex page-top-space +@item page-top-space +Distance from the top of the printable area to the center of the first +staff. This only works for staves which are vertically small. Big staves +are set with the top of their bounding box aligned to the top of the +printable area. Default is@tie{}12mm. + +@funindex ragged-bottom +@item ragged-bottom +If set to true, systems will not be spread vertically across the page. This +does not affect the last page. Default is false. + +This should be set to true for pieces that have only two or three +systems per page, for example orchestral scores. + +@funindex ragged-last-bottom +@item ragged-last-bottom +If set to false, systems will be spread vertically to fill the last +page. Default is true. + +Pieces that amply fill two pages or more should have this set to +true. + +@funindex system-count +@item system-count +This variable, if set, specifies into how many lines a score should be +broken. Unset by default. + +@funindex between-system-space +@item between-system-space +This dimensions determines the distance between systems. It is the +ideal distance between the center of the bottom staff of one system +and the center of the top staff of the next system. Default is@tie{}20mm. + +Increasing this will provide a more even appearance of the page at the +cost of using more vertical space. + +@funindex between-system-padding +@item between-system-padding +This dimension is the minimum amount of white space that will always +be present between the bottom-most symbol of one system, and the +top-most of the next system. Default is@tie{}4mm. + +Increasing this will put systems whose bounding boxes almost touch +farther apart. + + +@funindex horizontal-shift +@item horizontal-shift +All systems (including titles and system separators) are shifted by +this amount to the right. Page markup, such as headers and footers are +not affected by this. The purpose of this variable is to make space +for instrument names at the left. Default is@tie{}0. + +@funindex after-title-space +@item after-title-space +Amount of space between the title and the first system. Default is@tie{}5mm. + +@funindex before-title-space +@item before-title-space +Amount of space between the last system of the previous piece and the +title of the next. Default is@tie{}10mm. + +@funindex between-title-space +@item between-title-space +Amount of space between consecutive titles (e.g., the title of the +book and the title of a piece). Default is@tie{}2mm. + +@funindex printallheaders +@item printallheaders +Setting this to #t will print all headers for each \score in a +\book. Normally only the piece and opus \headers are printed. + +@funindex systemSeparatorMarkup +@item systemSeparatorMarkup +This contains a markup object, which will be inserted between +systems. This is often used for orchestral scores. Unset by default. + +The markup command @code{\slashSeparator} is provided as a sensible +default, for example + +@lilypond[ragged-right] +#(set-default-paper-size "a6" 'landscape) +\book { + \score { + \relative { c1 \break c1 } + } + \paper { + systemSeparatorMarkup = \slashSeparator + } +} +@end lilypond + +@funindex blank-page-force +@item blank-page-force +The penalty for having a blank page in the middle of a +score. This is not used by @code{ly:optimal-breaking} since it will +never consider blank pages in the middle of a score. Default value +is 10. + +@funindex blank-last-page-force +@item blank-last-page-force +The penalty for ending the score on an odd-numbered page. +Default value is 0. + +@funindex page-spacing-weight +@item page-spacing-weight +The relative importance of page (vertical) spacing and line (horizontal) +spacing. High values will make page spacing more important. Default +value is 10. + +@funindex auto-first-page-number +@item auto-first-page-number +The page breaking algorithm is affected by the first page number being +odd or even. If this variable is set to #t, the page breaking algorithm +will decide whether to start with an odd or even number. This will +result in the first page number remaining as is or being increased by one. + +@end table +@end quotation + +Example: + +@example +\paper@{ + paper-width = 2\cm + top-margin = 3\cm + bottom-margin = 3\cm + ragged-last-bottom = ##t +@} +@end example + +You can also define these values in Scheme. In that case @code{mm}, +@code{in}, @code{pt}, and @code{cm} are variables defined in +@file{paper-defaults.ly} with values in millimeters. That is why the +value must be multiplied in the example + +@example +\paper @{ + #(define bottom-margin (* 2 cm)) +@} +@end example + +The header and footer are created by the functions @code{make-footer} +and @code{make-header}, defined in @code{\paper}. The default +implementations are in @file{ly/@/paper@/-defaults@/.ly} and +@file{ly/@/titling@/-init@/.ly}. + +The page layout itself is done by two functions in the +@code{\paper} block, @code{page-music-height} and +@code{page-make-stencil}. The former tells the line-breaking algorithm +how much space can be spent on a page, the latter creates the actual +page given the system to put on it. + + +@refbugs + +The option right-margin is defined but doesn't set the right margin +yet. The value for the right margin has to be defined adjusting the +values of @code{left-margin} and @code{line-width}. + +The default page header puts the page number and the @code{instrument} +field from the @code{\header} block on a line. + +The titles (from the @code{\header@{@}} section) are treated as a +system, so @code{ragged-bottom} and @code{ragged-last-bottom} will +add space between the titles and the first system of the score. + + +@node Music layout +@section Music layout + +@menu +* Setting global staff size:: +* Score layout:: +@end menu + + +@node Setting global staff size +@subsection Setting global staff size + +@cindex font size, setting +@cindex staff size, setting +@funindex layout file + +To set the global staff size, use @code{set-global-staff-size}. + +@example +#(set-global-staff-size 14) +@end example + +@noindent +This sets the global default size to 14pt staff height and scales all +fonts accordingly. + +The Feta font provides musical symbols at eight different +sizes. Each font is tuned for a different staff size: at a smaller size +the font becomes heavier, to match the relatively heavier staff lines. +The recommended font sizes are listed in the following table: + +@quotation +@multitable @columnfractions .15 .2 .22 .2 + +@item @b{font name} +@tab @b{staff height (pt)} +@tab @b{staff height (mm)} +@tab @b{use} + +@item feta11 +@tab 11.22 +@tab 3.9 +@tab pocket scores + +@item feta13 +@tab 12.60 +@tab 4.4 +@tab + +@item feta14 +@tab 14.14 +@tab 5.0 +@tab + +@item feta16 +@tab 15.87 +@tab 5.6 +@tab + +@item feta18 +@tab 17.82 +@tab 6.3 +@tab song books + +@item feta20 +@tab 20 +@tab 7.0 +@tab standard parts + +@item feta23 +@tab 22.45 +@tab 7.9 +@tab + +@item feta26 +@tab 25.2 +@tab 8.9 +@tab +@c modern rental material? + +@end multitable +@end quotation + +These fonts are available in any sizes. The context property +@code{fontSize} and the layout property @code{staff-space} (in +@internalsref{StaffSymbol}) can be used to tune the size for individual +staves. The sizes of individual staves are relative to the global size. + +@example + +@end example + +@seealso + +This manual: @ref{Selecting notation font size}. + + +@node Score layout +@subsection Score layout + +@funindex \layout + +While @code{\paper} contains settings that relate to the page formatting +of the whole document, @code{\layout} contains settings for score-specific +layout. + +@example +\layout @{ + indent = 2.0\cm + \context @{ \Staff + \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6) + @} + \context @{ \Voice + \override TextScript #'padding = #1.0 + \override Glissando #'thickness = #3 + @} +@} +@end example + + +@seealso + +This manual: @ref{Changing context default settings} + + +@node Vertical spacing +@section Vertical spacing + +@cindex vertical spacing +@cindex spacing, vertical + +Vertical spacing is controlled by three things: the amount of +space available (i.e., paper size and margins), the amount of +space between systems, and the amount of space between +staves inside a system. + +@menu +* Vertical spacing inside a system:: +* Vertical spacing of piano staves:: +* Vertical spacing between systems:: +* Controlling spacing of individual systems:: +* Two-pass vertical spacing:: +@end menu + + +@node Vertical spacing inside a system +@subsection Vertical spacing inside a system + +@cindex distance between staves +@cindex staff distance +@cindex space between staves +@cindex space inside systems + +The height of each system is determined automatically. To prevent +staves from bumping into each other, some minimum distances are set. +By changing these, you can put staves closer together. This +reduces the amount of space each system requires, and may result +in having more systems per page. + +Normally staves are stacked vertically. To make staves maintain a +distance, their vertical size is padded. This is done with the +property @code{minimum-Y-extent}. When applied to a +@internalsref{VerticalAxisGroup}, it controls the size of a horizontal +line, such as a staff or a line of lyrics. @code{minimum-Y-extent} +takes a pair of numbers, so +if you want to make it smaller than its default @code{#'(-4 . 4)} +then you could set + +@example +\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) +@end example + +@noindent +This sets the vertical size of the current staff to 3 staff spaces on +either side of the center staff line. The value @code{(-3 . 3)} is +interpreted as an interval, where the center line is the 0, so the +first number is generally negative. The numbers need not match; +for example, the staff can be made larger at the bottom by setting +it to @code{(-6 . 4)}. + + +@seealso + +Internals: Vertical alignment of staves is handled by the +@internalsref{VerticalAlignment} object. The context parameters +specifying the vertical extent are described in connection with +the @internalsref{Axis_group_engraver}. + +Example files: @inputfileref{input/regression/,page-spacing.ly}, +@inputfileref{input/regression/,alignment-vertical-spacing.ly}. + + +@node Vertical spacing of piano staves +@subsection Vertical spacing of piano staves + +The distance between staves of a @internalsref{PianoStaff} cannot be +computed during formatting. Rather, to make cross-staff beaming work +correctly, that distance has to be fixed beforehand. + +The distance of staves in a @code{PianoStaff} is set with the +@code{forced-distance} property of the +@internalsref{VerticalAlignment} object, created in +@internalsref{PianoStaff}. + +It can be adjusted as follows +@example +\new PianoStaff \with @{ + \override VerticalAlignment #'forced-distance = #7 +@} @{ + ... +@} +@end example + +@noindent +This would bring the staves together at a distance of 7 staff spaces, +measured from the center line of each staff. + +The difference is demonstrated in the following example, +@lilypond[quote,verbatim] +\relative c'' << + \new PianoStaff \with { + \override VerticalAlignment #'forced-distance = #7 + } << + \new Staff { c1 } + \new Staff { c } + >> + \new PianoStaff << + \new Staff { c } + \new Staff { c } + >> +>> +@end lilypond + + +@seealso + +Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}. + + +@node Vertical spacing between systems +@subsection Vertical spacing between systems + +Space between systems are controlled by four @code{\paper} variables, + +@example +\paper @{ + between-system-space = 1.5\cm + between-system-padding = #1 + ragged-bottom=##f + ragged-last-bottom=##f +@} +@end example + + +@node Controlling spacing of individual systems +@subsection Controlling spacing of individual systems + +It is also possible to change the distance between for each system +individually. This is done by including the command + +@example +\overrideProperty +#"Score.NonMusicalPaperColumn" +#'line-break-system-details +#'((fixed-alignment-extra-space . 15)) +@end example + +@noindent +at the line break before the system to be changed. The distance +@code{15} is distributed over all staves that have a fixed distance +alignment. For example, + +@lilypond[ragged-right, fragment, relative=2, staffsize=13] +\new PianoStaff << + \new Staff { + c1\break + + \overrideProperty + #"Score.NonMusicalPaperColumn" + #'line-break-system-details + #'((fixed-alignment-extra-space . 15)) + + c\break + } + \new Staff { c c } +>> +@end lilypond + +The distance for @code{fixed-alignment-extra-space} may also be +negative. + + +@node Two-pass vertical spacing +@subsection Two-pass vertical spacing + +In order to automatically stretch systems so that they should fill the +space left on a page, a two-pass technique can be used: + +@enumerate +@item In the first pass, the amount of vertical space used to increase +the height of each system is computed and dumped to a file. +@item In the second pass, spacing inside the systems are +stretched according to the data in the page layout file. +@end enumerate + +The @code{ragged-bottom} property adds space between systems, while +the two-pass technique adds space between staffs inside a system. + +To allow this behaviour, a @code{tweak-key} variable has to be set in +each score @code{\layout} block, and the tweaks included in each score +music, using the @code{\scoreTweak} music function. + +@quotation +@verbatim +%% include the generated page layout file: +\includePageLayoutFile + +\score { + \new StaffGroup << + \new Staff << + %% Include this score tweaks: + \scoreTweak "scoreA" + { \clef french c''1 \break c''1 } + >> + \new Staff { \clef soprano g'1 g'1 } + \new Staff { \clef mezzosoprano e'1 e'1 } + \new Staff { \clef alto g1 g1 } + \new Staff { \clef bass c1 c1 } + >> + \header { + piece = "Score with tweaks" + } + %% Define how to name the tweaks for this score: + \layout { #(define tweak-key "scoreA") } +} +@end verbatim +@end quotation + +For the first pass, the @code{dump-tweaks} option should be set to +generate the page layout file. + +@example +lilypond -b null -d dump-tweaks .ly +lilypond .ly +@end example + +@node Horizontal spacing +@section Horizontal Spacing + +@cindex horizontal spacing +@cindex spacing, horizontal + +@menu +* Horizontal spacing overview:: +* New spacing area:: +* Changing horizontal spacing:: +* Line length:: +@end menu + + +@node Horizontal spacing overview +@subsection Horizontal spacing overview + +The spacing engine translates differences in durations into stretchable +distances (``springs'') of differring lengths. Longer durations get +more space, shorter durations get less. The shortest durations get a +fixed amount of space (which is controlled by +@code{shortest-duration-space} in the @internalsref{SpacingSpanner} +object). The longer the duration, the more space it gets: doubling a +duration adds a fixed amount (this amount is controlled by +@code{spacing-increment}) of space to the note. + +For example, the following piece contains lots of half, quarter, and +8th notes; the eighth note is followed by 1 note head width (NHW). +The quarter note is followed by 2 NHW, the half by 3 NHW, etc. + +@lilypond[quote,fragment,verbatim,relative=1] +c2 c4. c8 c4. c8 c4. c8 c8 +c8 c4 c4 c4 +@end lilypond + +Normally, @code{spacing-increment} is set to 1.2 staff space, which is +approximately the width of a note head, and +@code{shortest-duration-space} is set to 2.0, meaning that the +shortest note gets 2.4 staff space (2.0 times the +@code{spacing-increment}) of horizontal space. This space is counted +from the left edge of the symbol, so the shortest notes are generally +followed by one NHW of space. + +If one would follow the above procedure exactly, then adding a single +32nd note to a score that uses 8th and 16th notes, would widen up the +entire score a lot. The shortest note is no longer a 16th, but a 32nd, +thus adding 1 NHW to every note. To prevent this, the shortest +duration for spacing is not the shortest note in the score, but rather +the one which occurs most frequently. + + +The most common shortest duration is determined as follows: in every +measure, the shortest duration is determined. The most common shortest +duration is taken as the basis for the spacing, with the stipulation +that this shortest duration should always be equal to or shorter than +an 8th note. The shortest duration is printed when you run +@code{lilypond} with the @code{--verbose} option. + +These durations may also be customized. If you set the +@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then +this sets the base duration for spacing. The maximum duration for this +base (normally an 8th), is set through @code{base-shortest-duration}. + +@funindex common-shortest-duration +@funindex base-shortest-duration +@funindex stem-spacing-correction +@funindex spacing + +Notes that are even shorter than the common shortest note are +followed by a space that is proportional to their duration relative to +the common shortest note. So if we were to add only a few 16th notes +to the example above, they would be followed by half a NHW: + +@lilypond[quote,fragment,verbatim,relative=2] +c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 +@end lilypond + + +In the introduction (see @ref{Engraving}), it was explained that stem +directions influence spacing. This is controlled with the +@code{stem-spacing-correction} property in the +@internalsref{NoteSpacing}, object. These are generated for every +@internalsref{Voice} context. The @code{StaffSpacing} object +(generated in @internalsref{Staff} context) contains the same property +for controlling the stem/bar line spacing. The following example shows +these corrections, once with default settings, and once with +exaggerated corrections: + +@lilypond[quote,ragged-right] +{ + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + \override Staff.NoteSpacing #'stem-spacing-correction = #1.5 + \override Staff.StaffSpacing #'stem-spacing-correction = #1.5 + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| +} +@end lilypond + +Proportional notation is supported; see @ref{Proportional notation}. + + +@seealso + +Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, +@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and +@internalsref{SeparatingGroupSpanner}. + + +@refbugs + +There is no convenient mechanism to manually override spacing. The +following work-around may be used to insert extra space into a score. +@example + \once \override Score.SeparationItem #'padding = #1 +@end example + +No work-around exists for decreasing the amount of space. + + +@node New spacing area +@subsection New spacing area + +New sections with different spacing parameters can be started with +@code{newSpacingSection}. This is useful when there are +sections with a different notions of long and short notes. + +In the following example, the time signature change introduces a new +section, and hence the 16ths notes are spaced wider. + +@lilypond[relative,fragment,verbatim,quote] +\time 2/4 +c4 c8 c +c8 c c4 c16[ c c8] c4 +\newSpacingSection +\time 4/16 +c16[ c c8] +@end lilypond + + +@node Changing horizontal spacing +@subsection Changing horizontal spacing + +Horizontal spacing may be altered with the +@code{base-shortest-duration} property. Here +we compare the same music; once without altering +the property, and then altered. Larger values +of @code{ly:make-moment} will produce smaller +music. + +@lilypond[relative,verbatim,line-width=12\cm] +\score { + \relative c'' { + g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 | + g4 e e2 | f4 d d2 | c4 e g g | c,1 | + d4 d d d | d4 e f2 | e4 e e e | e4 f g2 | + g4 e e2 | f4 d d2 | c4 e g g | c,1 | + } +} +@end lilypond + +@lilypond[relative,verbatim,line-width=12\cm] +\score { + \relative c'' { + g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 | + g4 e e2 | f4 d d2 | c4 e g g | c,1 | + d4 d d d | d4 e f2 | e4 e e e | e4 f g2 | + g4 e e2 | f4 d d2 | c4 e g g | c,1 | + } + \layout { + \context { + \Score + \override SpacingSpanner + #'base-shortest-duration = #(ly:make-moment 1 4) + } + } +} +@end lilypond + + +@commonprop + +By default, spacing in tuplets depends on various non-duration +factors (such as accidentals, clef changes, etc). To disregard +such symbols and force uniform equal-duration spacing, use +@code{Score.SpacingSpanner #'uniform-stretching}. This +property can only be changed at the beginning of a score, + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +\new Score \with { + \override SpacingSpanner #'uniform-stretching = ##t +} << + \new Staff{ + \times 4/5 { + c8 c8 c8 c8 c8 + } + c8 c8 c8 c8 + } + \new Staff{ + c8 c8 c8 c8 + \times 4/5 { + c8 c8 c8 c8 c8 + } + } +>> +@end lilypond + + +When @code{strict-note-spacing} is set, notes are spaced without +regard for clefs, bar lines, and grace notes, + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +\override Score.SpacingSpanner #'strict-note-spacing = ##t +\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] } +@end lilypond + + +@node Line length +@subsection Line length + +@cindex page breaks +@cindex breaking pages + +@funindex indent +@funindex line-width +@funindex ragged-right +@funindex ragged-last + +@c Although line-width can be set in \layout, it should be set in paper +@c block, to get page layout right. +@c Setting indent in \paper block makes not much sense, but it works. + +@c Bit verbose and vague, use examples? +The most basic settings influencing the spacing are @code{indent} and +@code{line-width}. They are set in the @code{\layout} block. They +control the indentation of the first line of music, and the lengths of +the lines. + +If @code{ragged-right} is set to true in the @code{\layout} block, then +systems ends at their natural horizontal length, instead of being spread +horizontally to fill the whole line. This is useful for +short fragments, and for checking how tight the natural spacing is. + +@cindex page layout +@cindex vertical spacing + +The option @code{ragged-last} is similar to @code{ragged-right}, but +only affects the last line of the piece. No restrictions are put on +that line. The result is similar to formatting text paragraphs. In a +paragraph, the last line simply takes its natural horizontal length. +@c Note that for text there are several options for the last line. +@c While Knuth TeX uses natural length, lead typesetters use the same +@c stretch as the previous line. eTeX uses \lastlinefit to +@c interpolate between both these solutions. + +@example +\layout @{ + indent = #0 + line-width = #150 + ragged-last = ##t +@} +@end example + + +@node Breaks +@section Breaks + +@menu +* Line breaking:: +* Page breaking:: +* Optimal page breaking:: +* Optimal page turning:: +@end menu + +@node Line breaking +@subsection Line breaking + +@cindex line breaks +@cindex breaking lines + +Line breaks are normally computed automatically. They are chosen so +that lines look neither cramped nor loose, and that consecutive lines +have similar density. + +Occasionally you might want to override the automatic breaks; you can +do this by specifying @code{\break}. This will force a line break at +this point. Line breaks can only occur at places where there are bar +lines. If you want to have a line break where there is no bar line, +you can force an invisible bar line by entering @code{\bar +""}. Similarly, @code{\noBreak} forbids a line break at a +point. + + +@cindex regular line breaks +@cindex four bar music. + +For line breaks at regular intervals use @code{\break} separated by +skips and repeated with @code{\repeat}: +@example +<< \repeat unfold 7 @{ + s1 \noBreak s1 \noBreak + s1 \noBreak s1 \break @} + @emph{the real music} +>> +@end example + +@noindent +This makes the following 28 measures (assuming 4/4 time) be broken every +4 measures, and only there. + +@refcommands + +@code{\break}, and @code{\noBreak}. +@funindex \break +@funindex \noBreak + +@seealso + +Internals: @internalsref{LineBreakEvent}. + +A linebreaking configuration can now be saved as a @code{.ly} file +automatically. This allows vertical alignments to be stretched to +fit pages in a second formatting run. This is fairly new and +complicated; see @inputfileref{input/regression/,page-layout-twopass.ly} +for details. + +@refbugs + +Line breaks can only occur if there is a ``proper'' bar line. A note +which is hanging over a bar line is not proper, such as + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +c4 c2 c2 \break % this does nothing +c2 c4 | % a break here would work +c4 c2 c4 ~ \break % as does this break +c4 c2 c4 +@end lilypond + +To allow line breaks on such bar lines, the +@code{Forbid_line_break_engraver} can be removed from @code{Voice} +context, like so + + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +\new Voice \with { + \remove "Forbid_line_break_engraver" +} { + c4 c2 c2 \break % now the break is allowed + c2 c4 +} +@end lilypond + + + +@node Page breaking +@subsection Page breaking + +The default page breaking may be overriden by inserting +@code{\pageBreak} or @code{\noPageBreak} commands. These commands are +analogous to @code{\break} and @code{\noBreak}. They should be +inserted at a bar line. These commands force and forbid a page-break +from happening. Of course, the @code{\pageBreak} command also forces +a line break. + +Page breaks are computed by the @code{page-breaking} function. +LilyPond provides two algorithms for computing page +breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The +default is @code{ly:optimal-breaking}, but the value can be changed in +the @code{\paper} block: + +@example +\paper@{ + #(define page-breaking ly:page-turn-breaking) +@} +@end example + +The old page breaking algorithm is called +@code{optimal-page-breaks}. If you are having trouble with the new page +breakers, you can enable the old one as a workaround. + +@refcommands + +@funindex \pageBreak +@code{\pageBreak} +@funindex \noPageBreak +@code{\noPageBreak} + + +@node Optimal page breaking +@subsection Optimal page breaking + +@funindex ly:optimal-breaking + +The @code{ly:optimal-breaking} function is LilyPond's default method of +determining page breaks. It attempts to find a page breaking that minimizes +cramping and stretching, both horizontally and vertically. Unlike +@code{ly:page-turn-breaking}, it has no concept of page turns. + + +@node Optimal page turning +@subsection Optimal page turning + +@funindex ly:page-turn-breaking + +Often it is necessary to find a page breaking configuration so that there is +a rest at the end of every second page. This way, the musician can turn the +page without having to miss notes. The @code{ly:page-turn-breaking} function +attempts to find a page breaking minimizing cramping and stretching, but with +the additional restriction that it is only allowed to introduce page turns +in specified places. + +There are two steps to using this page breaking function. First, you must +enable it in the @code{\paper} block. Then, you must tell the function +where you would like to allow page breaks. + +There are two ways to achieve the second step. First, you can specify each +potential page turn manually, by inserting @code{\allowPageTurn} into your +input file at the appropriate places. + +If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or +Voice context. The @code{Page_turn_engraver} will scan the context for +sections without notes (note that it does not scan for rests; it scans for +the absence of notes. This is so that single-staff polyphony with rests in one +of the parts does not throw off the @code{Page_turn_engraver}). When it finds +a sufficiently long section without notes, the @code{Page_turn_engraver} will +insert an @code{\allowPageTurn} at the final barline in that section, unless +there is a ``special'' barline (such as a double bar), in which case the +@code{\allowPageTurn} will be inserted at the final ``special'' barline in +the section. + +@funindex minimumPageTurnLength +The @code{Page_turn_engraver} reads the context property +@code{minimumPageTurnLength} to determine how long a note-free section must +be before a page turn is considered. The default value for +@code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}. If you want +to disable page turns, you can set it to something very large. + +@example +\new Staff \with @{ \consists "Page_turn_engraver" @} +@{ + a4 b c d | + R1 | % a page turn will be allowed here + a4 b c d | + \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2) + R1 | % a page turn will not be allowed here + a4 b r2 | + R1*2 | % a page turn will be allowed here + a1 +@} +@end example + +@funindex minimumRepeatLengthForPageTurn +The @code{Page_turn_engraver} detects volta repeats. It will only allow a page +turn during the repeat if there is enough time at the beginning and end of the +repeat to turn the page back. The @code{Page_turn_engraver} can also disable +page turns if the repeat is very short. If you set the context property +@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will +only allow turns in repeats whose duration is longer than this value. + +@refbugs + +There should only be one @code{Page_turn_engraver} in a score. If there is more +than one, they will interfere with each other. + + +@node Displaying spacing +@section Displaying spacing + +@funindex annotate-spacing +@cindex Spacing, display of properties + +To graphically display the dimensions of vertical properties that may +be altered for page formatting, set @code{annotate-spacing} in the +@code{\paper} block, like this + + +@lilypond[verbatim] +#(set-default-paper-size "a6" 'landscape) + +\book { + \score { { c4 } } + \paper { annotate-spacing = ##t } +} +@end lilypond + +@c need to have \book{} otherwise we get the separate systems. -hwn + +@noindent +@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp +Some unit dimensions are measured in staff spaces, while others +are measured in millimeters. +The pairs +(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and +@var{b} the upper edge of the interval. + + diff --git a/Documentation/user/templates.itely b/Documentation/user/templates.itely new file mode 100644 index 0000000000..3e7845709c --- /dev/null +++ b/Documentation/user/templates.itely @@ -0,0 +1,1422 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@node Example templates +@appendix Example templates + +This section of the manual contains templates with the LilyPond score +already set up for you. Just add notes, run LilyPond, and enjoy +beautiful printed scores! + +@c bad node name for ancient notation to avoid confict +@menu +* Single staff:: +* Piano templates:: +* String quartet:: +* Vocal ensembles:: +* Ancient notation templates:: +* Jazz combo:: +* Lilypond-book templates:: +@end menu + + +@node Single staff +@appendixsec Single staff +@appendixsubsec Notes only + +The first example gives you a staff with notes, suitable for a solo +instrument or a melodic fragment. Cut and paste this into a file, +add notes, and you're finished! + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +melody = \relative c' { + \clef treble + \key c \major + \time 4/4 + + a4 b c d +} + +\score { + \new Staff \melody + \layout { } + \midi {} +} +@end lilypond + +@appendixsubsec Notes and lyrics + +The next example demonstrates a simple melody with lyrics. Cut and +paste, add notes, then words for the lyrics. This example turns off +automatic beaming, which is common for vocal parts. If you want to use +automatic beaming, you'll have to change or comment out the relevant +line. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +melody = \relative c' { + \clef treble + \key c \major + \time 4/4 + + a4 b c d +} + +text = \lyricmode { + Aaa Bee Cee Dee +} + +\score{ + << + \new Voice = "one" { + \autoBeamOff + \melody + } + \new Lyrics \lyricsto "one" \text + >> + \layout { } + \midi { } +} +@end lilypond + +@appendixsubsec Notes and chords + +Want to prepare a lead sheet with a melody and chords? Look no further! + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +melody = \relative c' { + \clef treble + \key c \major + \time 4/4 + + f4 e8[ c] d4 g | + a2 ~ a2 | +} + +harmonies = \chordmode { + c4:m f:min7 g:maj c:aug d2:dim b:sus +} + +\score { + << + \new ChordNames { + \set chordChanges = ##t + \harmonies + } + \new Staff \melody + >> + + \layout{ } + \midi { } +} +@end lilypond + +@appendixsubsec Notes, lyrics, and chords. + +This template allows you to prepare a song with melody, words, and chords. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +melody = \relative c' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +text = \lyricmode { + Aaa Bee Cee Dee +} + +harmonies = \chordmode { + a2 c2 +} + +\score { + << + \new ChordNames { + \set chordChanges = ##t + \harmonies + } + \new Voice = "one" { + \autoBeamOff + \melody + } + \new Lyrics \lyricsto "one" \text + >> + \layout { } + \midi { } +} +@end lilypond + +@node Piano templates +@appendixsec Piano templates +@appendixsubsec Solo piano + +Here is a simple piano staff. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +upper = \relative c'' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +lower = \relative c { + \clef bass + \key c \major + \time 4/4 + + a2 c +} + +\score { + \new PianoStaff << + \set PianoStaff.instrumentName = "Piano " + \new Staff = "upper" \upper + \new Staff = "lower" \lower + >> + \layout { } + \midi { } +} +@end lilypond + +@appendixsubsec Piano and melody with lyrics + +Here is a typical song format: one staff with the melody and lyrics, with +piano accompaniment underneath. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +melody = \relative c'' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +text = \lyricmode { + Aaa Bee Cee Dee +} + +upper = \relative c'' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +lower = \relative c { + \clef bass + \key c \major + \time 4/4 + + a2 c +} + +\score { + << + \new Voice = "mel" { + \autoBeamOff + \melody + } + \new Lyrics \lyricsto mel \text + + \new PianoStaff << + \new Staff = "upper" \upper + \new Staff = "lower" \lower + >> + >> + \layout { + \context { \RemoveEmptyStaffContext } + } + \midi { } +} +@end lilypond + + +@appendixsubsec Piano centered lyrics + +Instead of having a full staff for the melody and lyrics, you can place +the lyrics between the piano staff (and omit the separate melody staff). + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +upper = \relative c'' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +lower = \relative c { + \clef bass + \key c \major + \time 4/4 + + a2 c +} + +text = \lyricmode { + Aaa Bee Cee Dee +} + +\score { + \new GrandStaff << + \new Staff = upper { \new Voice = "singer" \upper } + \new Lyrics \lyricsto "singer" \text + \new Staff = lower { + \clef bass + \lower + } + >> + \layout { + \context { \GrandStaff \accepts "Lyrics" } + \context { \Lyrics \consists "Bar_engraver" } + } + \midi { } +} +@end lilypond + + +@appendixsubsec Piano centered dynamics + +Many piano scores have the dynamics centered between the two +staffs. This requires a bit of tweaking to implement, but +since the template is right here, you don't have to do the +tweaking yourself. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +upper = \relative c'' { + \clef treble + \key c \major + \time 4/4 + + a b c d +} + +lower = \relative c { + \clef bass + \key c \major + \time 4/4 + + a2 c +} + +dynamics = { + s2\fff\> s4 + s\!\pp +} + +pedal = { + s2\sustainDown s2\sustainUp +} + +\score { + \new PianoStaff << + \new Staff = "upper" \upper + \new Dynamics = "dynamics" \dynamics + \new Staff = "lower" << + \clef bass + \lower + >> + \new Dynamics = "pedal" \pedal + >> + \layout { + \context { + \type "Engraver_group" + \name Dynamics + \alias Voice % So that \cresc works, for example. + \consists "Output_property_engraver" + + \override VerticalAxisGroup #'minimum-Y-extent = #'(-1 . 1) + pedalSustainStrings = #'("Ped." "*Ped." "*") + pedalUnaCordaStrings = #'("una corda" "" "tre corde") + + \consists "Piano_pedal_engraver" + \consists "Script_engraver" + \consists "Dynamic_engraver" + \consists "Text_engraver" + + \override TextScript #'font-size = #2 + \override TextScript #'font-shape = #'italic + \override DynamicText #'extra-offset = #'(0 . 2.5) + \override Hairpin #'extra-offset = #'(0 . 2.5) + + \consists "Skip_event_swallow_translator" + + \consists "Axis_group_engraver" + } + \context { + \PianoStaff + \accepts Dynamics + \override VerticalAlignment #'forced-distance = #7 + } + } +} +\score { + \new PianoStaff << + \new Staff = "upper" << \upper \dynamics >> + \new Staff = "lower" << \lower \dynamics >> + \new Dynamics = "pedal" \pedal + >> + \midi { + \context { + \type "Performer_group" + \name Dynamics + \consists "Piano_pedal_performer" + } + \context { + \PianoStaff + \accepts Dynamics + } + } +} +@end lilypond + + +@node String quartet +@appendixsec String quartet +@appendixsubsec String quartet + +This template demonstrates a string quartet. It also uses a @code{\global} +section for time and key signatures. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" + +global= { + \time 4/4 + \key c \major +} + +violinOne = \new Voice { \relative c''{ + \set Staff.instrumentName = "Violin 1 " + + c2 d e1 + +\bar "|." }} +violinTwo = \new Voice { \relative c''{ + \set Staff.instrumentName = "Violin 2 " + + g2 f e1 + +\bar "|." }} +viola = \new Voice { \relative c' { + \set Staff.instrumentName = "Viola " + \clef alto + + e2 d c1 + +\bar "|." }} +cello = \new Voice { \relative c' { + \set Staff.instrumentName = "Cello " + \clef bass + + c2 b a1 + +\bar "|."}} + +\score { + \new StaffGroup << + \new Staff << \global \violinOne >> + \new Staff << \global \violinTwo >> + \new Staff << \global \viola >> + \new Staff << \global \cello >> + >> + \layout { } + \midi { } +} +@end lilypond + +@appendixsubsec String quartet parts + +The previous example produces a nice string quartet, but what if you +needed to print parts? This template demonstrates how to use the +@code{\tag} feature to easily split a piece into individual parts. + +You need to split this template into separate files; the filenames +are contained in comments at the beginning of each file. @code{piece.ly} +contains all the music definitions. The other files -- @code{score.ly}, +@code{vn1.ly}, @code{vn2.ly}, @code{vla.ly}, and +@code{vlc.ly} -- produce the appropiate part. + +@verbatim +%%%%% piece.ly +\version "2.9.13" + +global= { + \time 4/4 + \key c \major +} + +Violinone = \new Voice { \relative c''{ + \set Staff.instrumentName = "Violin 1 " + + c2 d e1 + +\bar "|." }} %********************************* +Violintwo = \new Voice { \relative c''{ + \set Staff.instrumentName = "Violin 2 " + + g2 f e1 + +\bar "|." }} %********************************* +Viola = \new Voice { \relative c' { + \set Staff.instrumentName = "Viola " + \clef alto + + e2 d c1 + +\bar "|." }} %********************************* +Cello = \new Voice { \relative c' { + \set Staff.instrumentName = "Cello " + \clef bass + + c2 b a1 + +\bar "|."}} %********************************** + +music = { + << + \tag #'score \tag #'vn1 \new Staff { << \global \Violinone >> } + \tag #'score \tag #'vn2 \new Staff { << \global \Violintwo>> } + \tag #'score \tag #'vla \new Staff { << \global \Viola>> } + \tag #'score \tag #'vlc \new Staff { << \global \Cello>> } + >> +} + + + +%%%%% score.ly +\version "2.9.13" +\include "piece.ly" +#(set-global-staff-size 14) +\score { + \new StaffGroup \keepWithTag #'score \music + \layout { } + \midi { } +} + + +%%%%% vn1.ly +\version "2.9.13" +\include "piece.ly" +\score { + \keepWithTag #'vn1 \music + \layout { } +} + + +%%%%% vn2.ly +\version "2.9.13" +\include "piece.ly" +\score { + \keepWithTag #'vn2 \music + \layout { } +} + + +%%%%% vla.ly +\version "2.9.13" +\include "piece.ly" +\score { + \keepWithTag #'vla \music + \layout { } +} + + +%%%%% vlc.ly +\version "2.9.13" +\include "piece.ly" +\score { + \keepWithTag #'vlc \music + \layout { } +} +@end verbatim + + +@node Vocal ensembles +@appendixsec Vocal ensembles + +@appendixsubsec SATB vocal score + +Here is a standard four-part SATB vocal score. With larger ensembles, +it's often useful to include a section which is included in all +parts. For example, the time signature and key signatures are almost +always the same for all parts. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +global = { + \key c \major + \time 4/4 +} + +sopMusic = \relative c'' { + c4 c c8[( b)] c4 +} +sopWords = \lyricmode { + hi hi hi hi +} + +altoMusic = \relative c' { + e4 f d e +} +altoWords =\lyricmode { + ha ha ha ha +} + +tenorMusic = \relative c' { + g4 a f g +} +tenorWords = \lyricmode { + hu hu hu hu +} + +bassMusic = \relative c { + c4 c g c +} +bassWords = \lyricmode { + ho ho ho ho +} + +\score { + \new ChoirStaff << + \new Lyrics = sopranos { s1 } + \new Staff = women << + \new Voice = + "sopranos" { \voiceOne << \global \sopMusic >> } + \new Voice = + "altos" { \voiceTwo << \global \altoMusic >> } + >> + \new Lyrics = "altos" { s1 } + \new Lyrics = "tenors" { s1 } + \new Staff = men << + \clef bass + \new Voice = + "tenors" { \voiceOne <<\global \tenorMusic >> } + \new Voice = + "basses" { \voiceTwo <<\global \bassMusic >> } + >> + \new 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 + >> + + \layout { + \context { + % a little smaller so lyrics + % can be closer to the staff + \Staff + \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) + } + } +} +@end lilypond + + +@appendixsubsec SATB vocal score and automatic piano reduction + +This template adds an automatic piano reduction to the SATB vocal +score. This demonstrates one of the strengths of LilyPond -- you +can use a music definition more than once. If you make any changes +to the vocal notes (say, tenorMusic), then the changes will also +apply to the piano reduction. + +@lilypond[quote,verbatim,ragged-right] +\version "2.9.13" +global = { + \key c \major + \time 4/4 +} + +sopMusic = \relative c'' { + c4 c c8[( b)] c4 +} +sopWords = \lyricmode { + hi hi hi hi +} + +altoMusic = \relative c' { + e4 f d e +} +altoWords =\lyricmode { + ha ha ha ha +} + +tenorMusic = \relative c' { + g4 a f g +} +tenorWords = \lyricmode { + hu hu hu hu +} + +bassMusic = \relative c { + c4 c g c +} +bassWords = \lyricmode { + ho ho ho ho +} + +\score { + << + \new ChoirStaff << + \new Lyrics = sopranos { s1 } + \new Staff = women << + \new Voice = + "sopranos" { \voiceOne << \global \sopMusic >> } + \new Voice = + "altos" { \voiceTwo << \global \altoMusic >> } + >> + \new Lyrics = "altos" { s1 } + \new Lyrics = "tenors" { s1 } + \new Staff = men << + \clef bass + \new Voice = + "tenors" { \voiceOne <<\global \tenorMusic >> } + \new Voice = + "basses" { \voiceTwo <<\global \bassMusic >> } + >> + \new 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 + >> + \new PianoStaff << + \new Staff << + \set Staff.printPartCombineTexts = ##f + \partcombine + << \global \sopMusic >> + << \global \altoMusic >> + >> + \new Staff << + \clef bass + \set Staff.printPartCombineTexts = ##f + \partcombine + << \global \tenorMusic >> + << \global \bassMusic >> + >> + >> + >> + \layout { + \context { + % a little smaller so lyrics + % can be closer to the staff + \Staff + \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3) + } + } +} +@end lilypond + + +@c bad node name to avoid node name confict +@node Ancient notation templates +@appendixsec Ancient notation templates + +@appendixsubsec Transcription of mensural music + +When transcribing mensural music, an incipit at the beginning of the +piece is useful to indicate the original key and tempo. While today +musicians are used to bar lines in order to faster recognize rhythmic +patterns, bar lines were not yet invented during the period of +mensural music; in fact, the meter often changed after every few +notes. As a compromise, bar lines are often printed between the +staves rather than on the staves. + +@lilypond[quote,verbatim,line-width=11.0\cm] +\version "2.9.13" + +global = { + \set Score.skipBars = ##t + + % incipit + \once \override Score.SystemStartBracket #'transparent = ##t + \override Score.SpacingSpanner #'spacing-increment = #1.0 % tight spacing + \key f \major + \time 2/2 + \once \override Staff.TimeSignature #'style = #'neomensural + \override Voice.NoteHead #'style = #'neomensural + \override Voice.Rest #'style = #'neomensural + \set Staff.printKeyCancellation = ##f + \cadenzaOn % turn off bar lines + \skip 1*10 + \once \override Staff.BarLine #'transparent = ##f + \bar "||" + \skip 1*1 % need this extra \skip such that clef change comes + % after bar line + \bar "" + + % main + \revert Score.SpacingSpanner #'spacing-increment % CHECK: no effect? + \cadenzaOff % turn bar lines on again + \once \override Staff.Clef #'full-size-change = ##t + \set Staff.forceClef = ##t + \key g \major + \time 4/4 + \override Voice.NoteHead #'style = #'default + \override Voice.Rest #'style = #'default + + % FIXME: setting printKeyCancellation back to #t must not + % occur in the first bar after the incipit. Dto. for forceClef. + % Therefore, we need an extra \skip. + \skip 1*1 + \set Staff.printKeyCancellation = ##t + \set Staff.forceClef = ##f + + \skip 1*7 % the actual music + + % let finis bar go through all staves + \override Staff.BarLine #'transparent = ##f + + % finis bar + \bar "|." +} + +discantusNotes = { + \transpose c' c'' { + \set Staff.instrumentName = "Discantus " + + % incipit + \clef "neomensural-c1" + c'1. s2 % two bars + \skip 1*8 % eight bars + \skip 1*1 % one bar + + % main + \clef "treble" + d'2. d'4 | + b e' d'2 | + c'4 e'4.( d'8 c' b | + a4) b a2 | + b4.( c'8 d'4) c'4 | + \once \override NoteHead #'transparent = ##t c'1 | + b\breve | + } +} + +discantusLyrics = \lyricmode { + % incipit + IV- + + % main + Ju -- bi -- | + la -- te De -- | + o, om -- + nis ter -- | + ra, __ om- | + "..." | + -us. | +} + +altusNotes = { + \transpose c' c'' { + \set Staff.instrumentName = "Altus " + + % incipit + \clef "neomensural-c3" + r1 % one bar + f1. s2 % two bars + \skip 1*7 % seven bars + \skip 1*1 % one bar + + % main + \clef "treble" + r2 g2. e4 fis g | % two bars + a2 g4 e | + fis g4.( fis16 e fis4) | + g1 | + \once \override NoteHead #'transparent = ##t g1 | + g\breve | + } +} + +altusLyrics = \lyricmode { + % incipit + IV- + + % main + Ju -- bi -- la -- te | % two bars + De -- o, om -- | + nis ter -- ra, | + "..." | + -us. | +} + +tenorNotes = { + \transpose c' c' { + \set Staff.instrumentName = "Tenor " + + % incipit + \clef "neomensural-c4" + r\longa % four bars + r\breve % two bars + r1 % one bar + c'1. s2 % two bars + \skip 1*1 % one bar + \skip 1*1 % one bar + + % main + \clef "treble_8" + R1 | + R1 | + R1 | + r2 d'2. d'4 b e' | % two bars + \once \override NoteHead #'transparent = ##t e'1 | + d'\breve | + } +} + +tenorLyrics = \lyricmode { + % incipit + IV- + + % main + Ju -- bi -- la -- te | % two bars + "..." | + -us. | +} + +bassusNotes = { + \transpose c' c' { + \set Staff.instrumentName = "Bassus " + + % incipit + \clef "bass" + r\maxima % eight bars + f1. s2 % two bars + \skip 1*1 % one bar + + % main + \clef "bass" + R1 | + R1 | + R1 | + R1 | + g2. e4 | + \once \override NoteHead #'transparent = ##t e1 | + g\breve | + } +} + +bassusLyrics = \lyricmode { + % incipit + IV- + + % main + Ju -- bi- | + "..." | + -us. | +} + +\score { + \new StaffGroup = choirStaff << + \new Voice = + "discantusNotes" << \global \discantusNotes >> + \new Lyrics = + "discantusLyrics" \lyricsto discantusNotes { \discantusLyrics } + \new Voice = + "altusNotes" << \global \altusNotes >> + \new Lyrics = + "altusLyrics" \lyricsto altusNotes { \altusLyrics } + \new Voice = + "tenorNotes" << \global \tenorNotes >> + \new Lyrics = + "tenorLyrics" \lyricsto tenorNotes { \tenorLyrics } + \new Voice = + "bassusNotes" << \global \bassusNotes >> + \new Lyrics = + "bassusLyrics" \lyricsto bassusNotes { \bassusLyrics } + >> + \layout { + \context { + \Score + + % no bars in staves + \override BarLine #'transparent = ##t + + % incipit should not start with a start delimiter + \remove "System_start_delimiter_engraver" + } + \context { + \Voice + + % no slurs + \override Slur #'transparent = ##t + + % Comment in the below "\remove" command to allow line + % breaking also at those barlines where a note overlaps + % into the next bar. The command is commented out in this + % short example score, but especially for large scores, you + % will typically yield better line breaking and thus improve + % overall spacing if you comment in the following command. + %\remove "Forbid_line_break_engraver" + } + } +} +@end lilypond + + +@appendixsubsec Gregorian transcription template + +This example demonstrates how to do modern transcription of Gregorian +music. Gregorian music has no measure, no stems; it uses only half and +quarter noteheads, and special marks, indicating rests of different length. + +@lilypond[quote,verbatim,ragged-right] +\include "gregorian-init.ly" +\version "2.9.13" + +chant = \relative c' { + \set Score.timing = ##f + f4 a2 \divisioMinima + g4 b a2 f2 \divisioMaior + g4( f) f( g) a2 \finalis +} + +verba = \lyricmode { + Lo -- rem ip -- sum do -- lor sit a -- met +} + +\score { + \new Staff << + \new Voice = "melody" { + \chant + } + \new Lyrics = "one" \lyricsto melody \verba + >> + + \layout { + \context { + \Staff + \remove "Time_signature_engraver" + \remove "Bar_engraver" + \override Stem #'transparent = ##t + } + \context { + \Voice + \override Stem #'length = #0 + } + \context { + \Score + barAlways = ##t + } + } +} +@end lilypond + + +@node Jazz combo +@appendixsec Jazz combo + +This is a much more complicated template, for a jazz ensemble. Note that all +instruments are notated in @code{\key c \major}. This refers to the key in +concert pitch; LilyPond will automatically transpose the key if the music +is within a @code{\transpose} section. + +@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. +@c - maybe ask Amelie Zapf to clean it up, or whether I should just +@c make whatever changes I feel like. + +@c FIXME: produces a warning ; key change merge. +@c The `line-width' argument is for the \header. + +@lilypond[quote,verbatim,ragged-right,line-width] +\version "2.9.13" +\header { + title = "Song" + subtitle = "(tune)" + composer = "Me" + meter = "moderato" + piece = "Swing" + tagline = \markup { + \column { + "LilyPond example file by Amelie Zapf," + "Berlin 07/07/2003" + } + } + texidoc = "Jazz tune for combo + (horns, guitar, piano, bass, drums)." +} + +#(set-global-staff-size 16) +\include "english.ly" + +%%%%%%%%%%%% Some macros %%%%%%%%%%%%%%%%%%% + +sl = { + \override NoteHead #'style = #'slash + \override Stem #'transparent = ##t +} +nsl = { + \revert NoteHead #'style + \revert Stem #'transparent +} +cr = \override NoteHead #'style = #'cross +ncr = \revert NoteHead #'style + +%% insert chord name style stuff here. + +jzchords = { } + + +%%%%%%%%%%%% Keys'n'thangs %%%%%%%%%%%%%%%%% + +global = { + \time 4/4 +} + +Key = { \key c \major } + +% ############ Horns ############ + +% ------ Trumpet ------ +trpt = \transpose c d \relative c'' { + \Key + c1 c c +} +trpharmony = \transpose c' d { + \jzchords +} +trumpet = { + \global + \set Staff.instrumentName = #"Trumpet" + \clef treble + << + \trpt + >> +} + +% ------ Alto Saxophone ------ +alto = \transpose c a \relative c' { + \Key + c1 c c +} +altoharmony = \transpose c' a { + \jzchords +} +altosax = { + \global + \set Staff.instrumentName = #"Alto Sax" + \clef treble + << + \alto + >> +} + +% ------ Baritone Saxophone ------ +bari = \transpose c a' \relative c { + \Key + c1 c \sl d4^"Solo" d d d \nsl +} +bariharmony = \transpose c' a \chordmode { + \jzchords s1 s d2:maj e:m7 +} +barisax = { + \global + \set Staff.instrumentName = #"Bari Sax" + \clef treble + << + \bari + >> +} + +% ------ Trombone ------ +tbone = \relative c { + \Key + c1 c c +} +tboneharmony = \chordmode { + \jzchords +} +trombone = { + \global + \set Staff.instrumentName = #"Trombone" + \clef bass + << + \tbone + >> +} + +% ############ Rhythm Section ############# + +% ------ Guitar ------ +gtr = \relative c'' { + \Key + c1 \sl b4 b b b \nsl c1 +} +gtrharmony = \chordmode { + \jzchords + s1 c2:min7+ d2:maj9 +} +guitar = { + \global + \set Staff.instrumentName = #"Guitar" + \clef treble + << + \gtr + >> +} + +%% ------ Piano ------ +rhUpper = \relative c'' { + \voiceOne + \Key + c1 c c +} +rhLower = \relative c' { + \voiceTwo + \Key + e1 e e +} + +lhUpper = \relative c' { + \voiceOne + \Key + g1 g g +} +lhLower = \relative c { + \voiceTwo + \Key + c1 c c +} + +PianoRH = { + \clef treble + \global + \set Staff.midiInstrument = "acoustic grand" + << + \new Voice = "one" \rhUpper + \new Voice = "two" \rhLower + >> +} +PianoLH = { + \clef bass + \global + \set Staff.midiInstrument = "acoustic grand" + << + \new Voice = "one" \lhUpper + \new Voice = "two" \lhLower + >> +} + +piano = { + << + \set PianoStaff.instrumentName = #"Piano" + \new Staff = "upper" \PianoRH + \new Staff = "lower" \PianoLH + >> +} + +% ------ Bass Guitar ------ +Bass = \relative c { + \Key + c1 c c +} +bass = { + \global + \set Staff.instrumentName = #"Bass" + \clef bass + << + \Bass + >> +} + +% ------ Drums ------ +up = \drummode { + hh4 4 hh hh 4 + hh4 4 + hh4 4 + hh4 4 +} + +down = \drummode { + bd4 s bd s bd s bd s bd s bd s +} + +drumContents = { + \global + << + \set DrumStaff.instrumentName = #"Drums" + \new DrumVoice { \voiceOne \up } + \new DrumVoice { \voiceTwo \down } + >> +} + +%%%%%%%%% It All Goes Together Here %%%%%%%%%%%%%%%%%%%%%% + +\score { + << + \new StaffGroup = "horns" << + \new Staff = "trumpet" \trumpet + \new Staff = "altosax" \altosax + \new ChordNames = "barichords" \bariharmony + \new Staff = "barisax" \barisax + \new Staff = "trombone" \trombone + >> + + \new StaffGroup = "rhythm" << + \new ChordNames = "chords" \gtrharmony + \new Staff = "guitar" \guitar + \new PianoStaff = "piano" \piano + \new Staff = "bass" \bass + \new DrumStaff { \drumContents } + >> + >> + + \layout { + \context { \RemoveEmptyStaffContext } + \context { + \Score + \override BarNumber #'padding = #3 + \override RehearsalMark #'padding = #2 + skipBars = ##t + } + } + + \midi { } +} +@end lilypond + +@ignore + +This isn't very useful, and only duplicates material in +"global issues". And if this info changes, this section often +gets forgotten. + +@no de Other templates +@se ction Other templates +@su bsection All headers + +This template displays all available headers. Some of them are only +used in the Mutopia project; they don't affect the printed output at +all. They are used if you want the piece to be listed with different +information in the Mutopia database than you wish to have printed on the +music. For example, Mutopia lists the composer of the famous D major +violin concerto as TchaikovskyPI, whereas perhaps you wish to print +"Petr Tchaikowski" on your music. + +@ The `line-width' is for \header. +@li lypond[quote,verbatim,ragged-right,line-width] +\version "2.9.13" +\header { + dedication = "dedication" + title = "Title" + subtitle = "Subtitle" + subsubtitle = "Subsubtitle" + composer = "Composer (xxxx-yyyy)" + opus = "Opus 0" + piece = "Piece I" + meter = "meter" + 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 { + { c'4 } + \header { + piece = "piece1" + opus = "opus1" + } +} + +\score { + { c'4 } + \header { + piece = "piece2" + opus = "opus2" + } +} +@end lilypond +@end ignore + + +@node Lilypond-book templates +@appendixsec Lilypond-book templates + +These templates are for use with @code{lilypond-book}. If you're not familiar +with this program, please refer to @ref{LilyPond-book}. + +@appendixsubsec LaTeX + +You can include LilyPond fragments in a LaTeX document. + +@example +\documentclass[]@{article@} + +\begin@{document@} + +Normal LaTeX text. + +\begin@{lilypond@} +\relative c'' @{ +a4 b c d +@} +\end@{lilypond@} + +More LaTeX text. + +\begin@{lilypond@} +\relative c'' @{ +d4 c b a +@} +\end@{lilypond@} +\end@{document@} +@end example + +@appendixsubsec Texinfo + +You can include LilyPond fragments in Texinfo; in fact, this entire manual +is written in Texinfo. + +@example +\input texinfo +@@node Top + +Texinfo text + +@@lilypond[verbatim,fragment,ragged-right] +a4 b c d +@@end lilypond + +More Texinfo text + +@@lilypond[verbatim,fragment,ragged-right] +d4 c b a +@@end lilypond + +@@bye +@end example diff --git a/THANKS b/THANKS index ddca7b2708..5519d5bb0e 100644 --- a/THANKS +++ b/THANKS @@ -68,6 +68,7 @@ Francisco Vila Harald Wellmann Henrik Frisk Johannes Schindelin +John Williams J. Leung Karim Haddad Karl Hammar diff --git a/po/fi.po b/po/fi.po index 25d9be70f1..39bc41a695 100644 --- a/po/fi.po +++ b/po/fi.po @@ -9,8 +9,8 @@ msgid "" msgstr "" "Project-Id-Version: fi\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2006-10-18 01:06+0300\n" -"PO-Revision-Date: 2006-10-18 01:10+0300\n" +"POT-Creation-Date: 2006-11-04 02:13+0200\n" +"PO-Revision-Date: 2006-11-04 02:19+0200\n" "Last-Translator: hjunes\n" "Language-Team: \n" "MIME-Version: 1.0\n" @@ -210,7 +210,8 @@ msgstr "näytä takuusitoumus" #: lilypond-book.py:70 msgid "" -"Process LilyPond snippets in hybrid HTML, LaTeX, or texinfo document.\n" +"Process LilyPond snippets in hybrid HTML, LaTeX, texinfo or DocBook " +"document.\n" "\n" "Example usage:\n" "\n" @@ -218,8 +219,8 @@ msgid "" " lilypond-book --filter=\"convert-ly --no-version --from=2.0.0 -\" BOOK\n" " lilypond-book --process='lilypond -I include' BOOK\n" msgstr "" -"Käsittele HTML, LaTeX, tai texinfo -documenttiin sisällytetyt LilyPond " -"palaset.\n" +"Käsittele HTML, LaTeX, texinfo tai DocBook -documenttiin sisällytetyt " +"LilyPond palaset.\n" "Käyttöesimerkkejä:\n" "\n" " lilypond-book --filter=\"tr '[a-z]' '[A-Z]'\" BOOK\n" @@ -245,8 +246,8 @@ msgid "pipe snippets through FILTER [convert-ly -n -]" msgstr "putkita palaset kohteen FILTER läpi [convert-ly -n -]" #: lilypond-book.py:135 -msgid "use output format FORMAT (texi [default], texi-html, latex, html)" -msgstr "käytä tulostusmuotona formaattia FMT (texi [oletus], texi-html, latex, html)" +msgid "use output format FORMAT (texi [default], texi-html, latex, html, docbook)" +msgstr "käytä tulostusmuotona formaattia FMT (texi [oletus], texi-html, latex, html, docbook)" #: lilypond-book.py:138 msgid "add DIR to include path" @@ -266,11 +267,11 @@ msgstr "prosessoi ly_tiedostot käyttäen komentoa COMMAND FILE..." #: lilypond-book.py:159 msgid "" -"extract all PostScript fonts into INPUT.psfonts for LaTeXmust use this with " -"dvips -h INPUT.psfonts" +"extract all PostScript fonts into INPUT.psfonts for LaTeX\n" +"must use this with dvips -h INPUT.psfonts" msgstr "" -"poimi kaikki PostScript fontit tiedostoon INPUT.psfonts LaTeX:ia varten\n" -"\t tätä täytyy käyttää dvips -h INPUT.psfonts :in kanssa" +"poimi kaikki PostScript-fontit tiedostoon INPUT.psfonts LaTeX:ia varten\n" +"tätä täytyy käyttää dvips -h INPUT.psfonts :in kanssa" #: lilypond-book.py:162 midi2ly.py:896 main.cc:183 msgid "be verbose" @@ -280,123 +281,123 @@ msgstr "tulosta runsaasti käsittelytietoa" msgid "show warranty and copyright" msgstr "näytä takuu ja copyright" -#: lilypond-book.py:721 +#: lilypond-book.py:778 #, python-format msgid "file not found: %s" msgstr "tiedostoa %s ei löydy" -#: lilypond-book.py:952 +#: lilypond-book.py:1009 #, python-format msgid "deprecated ly-option used: %s=%s" msgstr "vanhentunut ly-optio käytössä: %s=%s" -#: lilypond-book.py:955 +#: lilypond-book.py:1012 #, python-format msgid "compatibility mode translation: %s=%s" msgstr "yhteensopivuusmuodon käännös: %s=%s" -#: lilypond-book.py:959 +#: lilypond-book.py:1016 #, python-format msgid "deprecated ly-option used: %s" msgstr "vanhentunut ly-optio käytössä: %s" -#: lilypond-book.py:962 +#: lilypond-book.py:1019 #, python-format msgid "compatibility mode translation: %s" msgstr "yhteensopivuusmuodon käännös: %s" -#: lilypond-book.py:981 +#: lilypond-book.py:1038 #, python-format msgid "ignoring unknown ly option: %s" msgstr "sivuutetaan tuntematon ly -optio: %s" -#: lilypond-book.py:1318 +#: lilypond-book.py:1391 #, python-format msgid "Opening filter `%s'" msgstr "Avataan filtteri `%s'" -#: lilypond-book.py:1335 +#: lilypond-book.py:1408 #, python-format msgid "`%s' failed (%d)" msgstr "`%s' epäonnistui (%d)" -#: lilypond-book.py:1336 +#: lilypond-book.py:1409 msgid "The error log is as follows:" msgstr "Virheloki on seuraava:" -#: lilypond-book.py:1405 +#: lilypond-book.py:1479 msgid "Can't find \\begin{document} in LaTeX document" msgstr "Ei voitu löytää \\begin{document} LaTeX-documentista" -#: lilypond-book.py:1513 +#: lilypond-book.py:1589 msgid "Writing snippets..." msgstr "Kirjoitetaan palasia..." -#: lilypond-book.py:1518 +#: lilypond-book.py:1594 msgid "Processing..." msgstr "Prosessoidaan..." -#: lilypond-book.py:1522 +#: lilypond-book.py:1598 msgid "All snippets are up to date..." msgstr "Kaikki palaset on päivitetty..." -#: lilypond-book.py:1532 +#: lilypond-book.py:1608 #, python-format msgid "can't determine format for: %s" msgstr "ei löytynyt formaattia: %s" -#: lilypond-book.py:1543 +#: lilypond-book.py:1619 #, python-format msgid "%s is up to date." msgstr "%s on päivitetty." -#: lilypond-book.py:1549 +#: lilypond-book.py:1625 #, python-format msgid "Writing `%s'..." msgstr "Kirjoitetaan `%s'..." -#: lilypond-book.py:1604 +#: lilypond-book.py:1680 msgid "Output would overwrite input file; use --output." msgstr "Tuloste kirjautuisi syötetiedoston päälle; käytä --output." -#: lilypond-book.py:1608 +#: lilypond-book.py:1684 #, python-format msgid "Reading %s..." msgstr "Luetaan %s..." -#: lilypond-book.py:1627 +#: lilypond-book.py:1703 msgid "Dissecting..." msgstr "Analysoidaan..." -#: lilypond-book.py:1643 +#: lilypond-book.py:1719 #, python-format msgid "Compiling %s..." msgstr "Kootaan %s..." -#: lilypond-book.py:1652 +#: lilypond-book.py:1728 #, python-format msgid "Processing include: %s" msgstr "Prosessoidaan sisällytetävä: %s" -#: lilypond-book.py:1666 +#: lilypond-book.py:1742 #, python-format msgid "Removing `%s'" msgstr "Poistetaan `%s'" -#: lilypond-book.py:1743 +#: lilypond-book.py:1819 #, python-format msgid "Writing fonts to %s..." msgstr "Kirjoitetaan fontteja hakemistoon %s..." -#: lilypond-book.py:1758 +#: lilypond-book.py:1834 msgid "option --psfonts not used" msgstr "optiota --psfonts=FILE ei käytetty" -#: lilypond-book.py:1759 +#: lilypond-book.py:1835 msgid "processing with dvips will have no fonts" msgstr "prosessointi dvips:illä ei sisällä fontteja" -#: lilypond-book.py:1762 +#: lilypond-book.py:1838 msgid "DVIPS usage:" msgstr "DVIPS käyttö:" @@ -491,7 +492,7 @@ msgstr "tunnistamaton optio: `%s'" msgid "invalid argument `%s' to option `%s'" msgstr "epäkelpo argumentti `%s' optiolle `%s'" -#: warn.cc:68 grob.cc:556 input.cc:82 +#: warn.cc:68 grob.cc:557 input.cc:82 #, c-format msgid "programming error: %s" msgstr "ohjelmointivirhe: %s" @@ -564,15 +565,15 @@ msgstr "\\applycontext vaatii funktioargumentin" msgid "can't change, already in translator: %s" msgstr "ei voitu vaihtaa, oli jo tulkitsijassa: %s" -#: axis-group-engraver.cc:82 +#: axis-group-engraver.cc:78 msgid "Axis_group_engraver: vertical group already has a parent" msgstr "Axis_group_engraver: vertikaaliryhmällä on jo vanhempi" -#: axis-group-engraver.cc:83 +#: axis-group-engraver.cc:79 msgid "are there two Axis_group_engravers?" msgstr "onko käytössä kaksi Axis_group_engraver:ia?" -#: axis-group-engraver.cc:84 +#: axis-group-engraver.cc:80 msgid "removing this vertical group" msgstr "poistetaan tämä vertikaaliryhmä" @@ -593,15 +594,15 @@ msgstr "palkki löytyi jo" msgid "unterminated beam" msgstr "päättämätön palkki" -#: beam-engraver.cc:237 chord-tremolo-engraver.cc:134 +#: beam-engraver.cc:238 chord-tremolo-engraver.cc:134 msgid "stem must have Rhythmic structure" msgstr "varrella on oltava Rhytmic -rakenne" -#: beam-engraver.cc:245 +#: beam-engraver.cc:246 msgid "stem doesn't fit in beam" msgstr "varsi ei sovi palkkiin" -#: beam-engraver.cc:246 +#: beam-engraver.cc:247 msgid "beam was started here" msgstr "palkki aloitettiin täältä" @@ -684,7 +685,7 @@ msgstr "Coherent_ligature_engraver: asetetaan `spacing-increment=0.01': ptr=%ul" msgid "couldn't find line breaking that satisfies constraints" msgstr "ei löytynyt rivinkatkaisukohtaa joka täyttäisi ehdot" -#: context-def.cc:128 +#: context-def.cc:130 #, c-format msgid "program has no such type: `%s'" msgstr "ohjelmalla ei ole tyyppiä: `%s'" @@ -870,7 +871,7 @@ msgstr "päättämätön tavuviiva" msgid "include files are not allowed in safe mode" msgstr "sisällytettävät tiedostot eivät ole sallittuja turvatilassa" -#: includable-lexer.cc:60 lily-guile.cc:96 lily-parser-scheme.cc:115 +#: includable-lexer.cc:60 lily-guile.cc:96 lily-parser-scheme.cc:117 #, c-format msgid "can't find file: `%s'" msgstr "tiedostoa ei löydy: `%s'" @@ -930,12 +931,12 @@ msgstr "suoritetaan tehtävä joka tapauksessa" msgid "type check for `%s' failed; value `%s' must be of type `%s'" msgstr "tyypin `%s' tarkistus epäonnistui; arvon `%s' on oltava tyyppiä `%s'" -#: lily-lexer.cc:222 +#: lily-lexer.cc:233 #, c-format msgid "identifier name is a keyword: `%s'" msgstr "tunnistenimi on avainsana: `%s'" -#: lily-lexer.cc:237 +#: lily-lexer.cc:248 #, c-format msgid "error at EOF: %s" msgstr "virhe tiedoston lopussa (EOF): %s" @@ -955,7 +956,7 @@ msgstr "Vaihdetaan työhakemistoksi `%s'" msgid "can't find init file: `%s'" msgstr "tiedostoa ei löydy: `%s'" -#: lily-parser-scheme.cc:125 +#: lily-parser-scheme.cc:126 #, c-format msgid "Processing `%s'" msgstr "Prosessoidaan `%s'" @@ -964,7 +965,7 @@ msgstr "Prosessoidaan `%s'" msgid "Parsing..." msgstr "Jäsennetään..." -#: lily-parser.cc:126 +#: lily-parser.cc:125 msgid "braces don't match" msgstr "aaltosulkumerkit eivät täsmää" @@ -1388,8 +1389,8 @@ msgstr "tuntematon virhe: %d lukee fonttitiedostoa: %s" #: open-type-font.cc:171 open-type-font.cc:295 #, c-format -msgid "FT_Get_Glyph_Name() returned error: %d" -msgstr "FT_Get_Glyph_Name() palautti virheen: %d" +msgid "FT_Get_Glyph_Name() returned error: %u" +msgstr "FT_Get_Glyph_Name() palautti virheen: %u" #: page-turn-page-breaking.cc:227 msgid "" @@ -1408,7 +1409,7 @@ msgstr "Lasketaan sivujen ja rivien katkaisuja (%d mahdollista sivunkatkaisua).. msgid "Drawing systems..." msgstr "Piirretään tahteja..." -#: pango-font.cc:184 +#: pango-font.cc:194 #, c-format msgid "" "Glyph has no name, but font supports glyph naming.\n" @@ -1417,12 +1418,12 @@ msgstr "" "Ladokkeella ei ole nimea, mutta kirjasin tukee ladokkeen nimeämistä.\n" "Sivuutetaan ladoke U+%0X, tiedostossa %s" -#: pango-font.cc:217 +#: pango-font.cc:237 #, c-format msgid "no PostScript font name for font `%s'" msgstr "ei PostScript fonttinimeä fontille `%s'" -#: pango-font.cc:265 +#: pango-font.cc:285 msgid "FreeType face has no PostScript font name" msgstr "FreeType muodolla ei ollut PostScript fonttinimeä" @@ -1473,23 +1474,23 @@ msgstr "Tehdään MIDI-tuloste `%s'..." msgid "unterminated phrasing slur" msgstr "päättämätön fraaseerauskaari" -#: piano-pedal-engraver.cc:304 +#: piano-pedal-engraver.cc:283 #, c-format msgid "expect 3 strings for piano pedals, found: %ld" msgstr "odotettiin 3 merkkijonoa pianopedaalille, löytyi: %ld" -#: piano-pedal-engraver.cc:319 piano-pedal-engraver.cc:330 +#: piano-pedal-engraver.cc:298 piano-pedal-engraver.cc:309 #: piano-pedal-performer.cc:93 #, c-format msgid "can't find start of piano pedal: `%s'" msgstr "ei löydetty alkua pianopedaalille: `%s'" -#: piano-pedal-engraver.cc:377 +#: piano-pedal-engraver.cc:344 #, c-format msgid "can't find start of piano pedal bracket: `%s'" msgstr "ei löydetty alkua pianopedaalimerkinnälle: `%s'" -#: program-option.cc:195 +#: program-option.cc:199 #, c-format msgid "no such internal option: %s" msgstr "tuntematon sisäinen optio: %s" @@ -1722,12 +1723,12 @@ msgstr "tuntematon tulkitsija: `%s'" msgid "can't find: `%s'" msgstr "ei löytynyt `%s'" -#: translator.cc:331 +#: translator.cc:332 #, c-format msgid "Two simultaneous %s events, junking this one" msgstr "Kaksi samanaikaista %s-tapahtumaa, hylätään tämä" -#: translator.cc:332 +#: translator.cc:333 #, c-format msgid "Previous %s event here" msgstr "Edellinen %s-tapahtuma täällä" @@ -1744,7 +1745,7 @@ msgstr "trilliladoke löytyi jo" msgid "invalid direction of tuplet-span-event" msgstr "tuntematon tuplettiväli-tapahtuman suunta" -#: vaticana-ligature-engraver.cc:382 +#: vaticana-ligature-engraver.cc:388 #, c-format msgid "" "ignored prefix (es) `%s' of this head according to restrictions of the " @@ -1753,7 +1754,7 @@ msgstr "" "sivuutetaan prefiksi (t) `%s' tälle nuottipäälle valitun ligatuurityylin " "mukaisesti" -#: vaticana-ligature-engraver.cc:708 +#: vaticana-ligature-engraver.cc:714 #, c-format msgid "Vaticana_ligature_engraver: setting `spacing-increment = %f': ptr =%ul" msgstr "Vaticana_ligature_engraver: asetetaan `spacing-increment = %f': ptr=%ul" @@ -1783,119 +1784,114 @@ msgstr "löytyi ja volta-ladoke, lopetetaan se ennenaikaisesti" msgid "also already have an ended spanner" msgstr "myös tekstileike päätettiin jo" -#: parser.yy:704 parser.yy:710 +#: parser.yy:703 msgid "\\paper cannot be used in \\score, use \\layout instead" msgstr "\\paper ei voi olla käytössä \\score:ssa, käytä \\layout sen sijaan" -#: parser.yy:728 parser.yy:734 +#: parser.yy:727 msgid "need \\paper for paper block" msgstr "tarvitaan \\paper paperiryhmälle" -#: parser.yy:1174 parser.yy:1204 +#: parser.yy:1173 msgid "Grob name should be alphanumeric" msgstr "Graafiseen objectiin täytyy olla kirjain tai numero" -#: parser.yy:1477 parser.yy:1497 +#: parser.yy:1476 msgid "second argument must be pitch list" msgstr "toisen argumentin on oltava äänenkorkeuslista" -#: parser.yy:1504 parser.yy:1509 parser.yy:1974 parser.yy:1524 parser.yy:1529 -#: parser.yy:2004 +#: parser.yy:1503 parser.yy:1508 parser.yy:1973 msgid "have to be in Lyric mode for lyrics" msgstr "täytyy olla Lyrics -moodissa lyriikkaa varten" -#: parser.yy:1606 parser.yy:1628 +#: parser.yy:1605 msgid "expecting string as script definition" msgstr "oletetaan merkkijonon olevan skriptimäärittely" -#: parser.yy:1761 parser.yy:1811 parser.yy:1786 parser.yy:1836 +#: parser.yy:1760 parser.yy:1810 #, c-format msgid "not a duration: %d" msgstr "ei ole kesto: %d" -#: parser.yy:1928 parser.yy:1956 +#: parser.yy:1927 msgid "have to be in Note mode for notes" msgstr "täytyy olla Note -moodissa nuotteja varten" -#: parser.yy:1989 parser.yy:2020 +#: parser.yy:1988 msgid "have to be in Chord mode for chords" msgstr "täytyy olla Chord -moodissa sointuja varten" -#: lexer.ll:177 lexer.ll:159 +#: lexer.ll:176 msgid "stray UTF-8 BOM encountered" msgstr "satunnainen UTF-8 BOM (osaluettelo) havaittu" -#: lexer.ll:181 lexer.ll:163 +#: lexer.ll:180 msgid "Skipping UTF-8 BOM" msgstr "Sivuutetaan UTF-8 BOM (osaluettelo)" -#: lexer.ll:236 lexer.ll:218 +#: lexer.ll:235 #, c-format msgid "Renaming input to: `%s'" msgstr "Avataan syöte: `%s'" -#: lexer.ll:254 lexer.ll:236 +#: lexer.ll:252 msgid "quoted string expected after \\version" msgstr "lainausmerkittyä merkkijonoa ei löytynyt kohteen \\version jälkeen" -#: lexer.ll:258 lexer.ll:240 +#: lexer.ll:256 msgid "quoted string expected after \\sourcefilename" msgstr "odotettiin lainausmerkittyä merkkijonoa \\sourcefilename:n jälkeen" -#: lexer.ll:262 lexer.ll:244 +#: lexer.ll:260 msgid "integer expected after \\sourcefileline" msgstr "odotettiin kokonaislukua \\sourcefilename:n jälkeen" -#: lexer.ll:275 lexer.ll:257 +#: lexer.ll:273 msgid "EOF found inside a comment" msgstr "EOF löytyi kommentin sisältä" -#: lexer.ll:290 lexer.ll:272 +#: lexer.ll:288 msgid "\\maininput not allowed outside init files" msgstr "\\maininput ei ole sallittu init-alustustiedoston ulkopuolella" -#: lexer.ll:314 lexer.ll:296 +#: lexer.ll:312 #, c-format msgid "wrong or undefined identifier: `%s'" msgstr "väärä tai määrittämätön tunniste: `%s'" #. backup rule -#: lexer.ll:323 lexer.ll:305 +#: lexer.ll:321 msgid "end quote missing" msgstr "jälkimmäinen lainaismerkki puuttuu" -#: lexer.ll:468 lexer.ll:450 +#: lexer.ll:466 msgid "Brace found at end of lyric. Did you forget a space?" msgstr "Sulkumerkki löytyi lyriikan lopussa. Unohditko välilyönnin?" -#: lexer.ll:561 lexer.ll:543 +#: lexer.ll:559 msgid "Brace found at end of markup. Did you forget a space?" msgstr "Sulkumerkki löytyi lyriikan lopussa. Unohditko välilyönnin?" -#: lexer.ll:661 lexer.ll:643 +#: lexer.ll:659 #, c-format msgid "invalid character: `%c'" msgstr "epäkelpo merkki: `%c'" -#: lexer.ll:776 lexer.ll:731 +#: lexer.ll:774 lexer.ll:775 #, c-format msgid "unknown escaped string: `\\%s'" msgstr "tuntematon koodinvaihtomerkillinen merkkijono: `\\\\%s'" -#: lexer.ll:882 lexer.ll:828 +#: lexer.ll:880 lexer.ll:881 #, c-format msgid "Incorrect lilypond version: %s (%s, %s)" msgstr "Epäkelpo lilypond versio: %s (%s, %s)" -#: lexer.ll:883 lexer.ll:829 +#: lexer.ll:881 lexer.ll:882 msgid "Consider updating the input with the convert-ly script" msgstr "Harkitse syötteen päivittämistä convert-ly scriptillä" -#: lexer.ll:931 -msgid "can't find signature for music function" -msgstr "ei löytynyt aikamerkintää musiikkifunktiolle" - -#: backend-library.scm:19 lily.scm:485 ps-to-png.scm:88 +#: backend-library.scm:19 lily.scm:494 ps-to-png.scm:88 #, lisp-format msgid "Invoking `~a'..." msgstr "Kutsutaan `~a'..." @@ -1941,7 +1937,7 @@ msgstr "kääntäjä kuuntelee olematonta tapahtumaluokkaa ~A" msgid "no systems found in \\score markup, does it have a \\layout block?" msgstr "systeemejä ei löytynyt \\score merkinnässä, onko siinä \\layout blokkia?" -#: define-markup-commands.scm:1281 +#: define-markup-commands.scm:1284 #, lisp-format msgid "not a valid duration string: ~a" msgstr "ei ole sallittu keston merkkijono: ~a" @@ -2080,22 +2076,22 @@ msgstr "" msgid "old relative compatibility not used" msgstr "vanhaa relative -yhteensopivuutta ei käytetty" -#: lily.scm:135 +#: lily.scm:142 #, lisp-format msgid "Can't find ~A" msgstr "Ei löydetty ~A" -#: lily.scm:200 +#: lily.scm:207 #, lisp-format msgid "wrong type for argument ~a. Expecting ~a, found ~s" msgstr "väärä tyyppi argumentille ~a. Odotettiin ~a, löytyi ~s" -#: lily.scm:414 lily.scm:475 +#: lily.scm:423 lily.scm:484 #, lisp-format msgid "failed files: ~S" msgstr "epäonniset tiedostot: ~S" -#: lily.scm:465 +#: lily.scm:474 #, lisp-format msgid "Redirecting output to ~a..." msgstr "Ohjataan tulosteet paikkaan ~a..."