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