X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=0490cf34683ad7ea9fc6e09720c63d0c5bcc9991;hb=ab22598a9ec73d62e28760eb54439f8bf87fd4af;hp=4ac0a5679fe040c268372dc7a8c7ae9fb58032b8;hpb=1ab20317f9aaac1ffb949169c98e0cc948a8f715;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 4ac0a5679f..0490cf3468 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,157 +1,121 @@ @c -*-texinfo-*- -@c TODO: LilyPond LilyPond LilyPond - +@c TODO: +@c * LilyPond Lilypond lilypond (sometimes: the program) +@c * more details about running lilypond; error messages, +@c compiling/viewing (emacs?) +@c * where to go from First steps+More basics? @node Tutorial @chapter Tutorial - + +@html + +@end html + @menu * First steps:: Music language of LilyPond -* Simple legend:: Small table of music language symbols * Running LilyPond:: Printing music -* The first real tune:: The first real tune -* Lyrics and chords:: Lyrics and chords +* More basics:: +* Printing lyrics:: +* A melody with chords :: +* More stanzas:: * More movements :: Joining separate pieces of music * A piano excerpt:: Piano music +* Fine tuning a piece:: * An orchestral score:: Conductor's score and individual parts -* Other ways to run LilyPond:: Other ways to run LilyPond * Integrating text and music:: Integrating text and music -* End of tutorial:: The end @end menu - -The music is described in a text file, using a simple music language. -LilyPond reads that text file and generates music that you can print or -view. - -Therefore, creating music notation with LilyPond is done in two steps. -Using a text editor, you write down the notes to print. Then, you run -LilyPond to get your printed output. +Operating lilypond is done through text files: To print a piece of +music, you enter the music in a file. When you run lilypond (normally +using the program @code{ly2dvi}) on that file, the program produces +another file which contains sheet music that you can print or view. This tutorial starts with a small introduction to the LilyPond music language. After this first contact, we will show you how to run LilyPond to produce printed output; you should then be able to create -your first sheets of music. - -The tutorial continues with a slightly more elaborate example of real music. -This piece introduces and explains some finer details of LilyPond. -Then, a number of more complex examples follow, that will help you to -produce most complex music with LilyPond. - +your first sheets of music. The tutorial continues with more and more +complex examples. -@c title? @node First steps @section First steps -@c @node Music language of LilyPond -@c @section Music language of LilyPond +We start off by showing how very simple music is entered in LilyPond: +you get a note simply by typing its @htmlref{note name}, from @samp{a} +through @samp{g}. So if you enter -This section shows how easy writing music with LilyPond actually is. If -you have not seen LilyPond input source before, this section is for you. - -The next section has a table (see @ref{Simple legend}) of all symbols -that are introduced here, you may want to keep an eye on that. - -Writing music with LilyPond is explained below by a number of small -examples. Each example has a small piece of text; the LilyPond input -that you should type, with the resulting music printed below it. - -You get a simple note by typing its note name, from @code{a} through -@code{g}: - -@quotation @example c d e f g a b @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\transpose c'' { c d e f g a b } +@noindent +then the result looks like this: + +@c ? +@c \transpose c c' { c d e f g a b } +@c @lily pond[notime] +@c \property Score.timing = ##f +@lilypond[notime, relative=2] +c d e f g a b @end lilypond -@end quotation -@separate -The length of a note is specified by adding a number, ``@code{1}'' for a -whole note, ``@code{2}'' for a half note, and so on: +We will continue with this format: First we show a snippet of input, +then the resulting output. + +The length of a note is specified by adding a number, @samp{1} for a +@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on: -@quotation @example a1 a2 a4 a16 a32 @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t -%\property Staff.Clef = \turnOff -\transpose c'' { a1 a2 a4 a16 a32 } -s16_" " +\property Staff.autoBeaming = ##f +\transpose c c' { a1 a2 a4 a16 a32 s16_" " } @end lilypond -@end quotation -@separate -If you don't specify a duration, the previous duration is used: +If you do not specify a @rglos{duration}, the previous one is used: -@quotation @example -a a a2 a +a4 a a2 a @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -%\property Staff.Clef = \turnOff -\transpose c'' { a a a2 a } -s16_" " +\transpose c c' { a a a2 a s16_" " } @end lilypond -@end quotation -@separate -A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat -(@texiflat{}) by adding ``@code{es}'': +A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a +@rglos{flat} (@texiflat{}) by adding @samp{es}. As you would expect, +a @rglos{double sharp} or @rglos{double flat} is made by adding +@samp{isis} or @samp{eses}: -@quotation @example cis1 ees fisis aeses @end example -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\transpose c'' { cis1 ees fisis aeses } -s16_" " +\transpose c c' { cis1 ees fisis aeses s16_" " } @end lilypond -@end quotation -@separate -Add a dot ``@code{.}'' after the duration to get a dotted note: -@quotation +Add a dot @samp{.} after the duration to get a @rglos{dotted note}: + @example a2. a4 a8. a16 @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -%\property Staff.Clef = \turnOff -\transpose c'' { a2. a4 a8. a16 } -s16_" " +\transpose c c' { a2. a4 a8. a16 s16_" " } @end lilypond -@end quotation -@separate -The meter (or time signature) can be set with the ``@code{\time}'' command: +The @rglos{meter} (or @rglos{time signature}) can be set with the +@code{\time} command: -@quotation @example \time 3/4 \time 6/8 @@ -159,8 +123,8 @@ The meter (or time signature) can be set with the ``@code{\time}'' command: @end example @c a clef here may lead to confusion -@lilypond[fragment] -\property Staff.Clef = \turnOff +@lilypond +\property Staff.Clef \set #'transparent = ##t \time 3/4 s4_" " \time 6/8 @@ -168,24 +132,21 @@ s4_" " \time 4/4 s16_" " @end lilypond -@end quotation -@separate -The clef can be set using the ``@code{\clef}'' command: +The @rglos{clef} can be set using the @code{\clef} command: @c what is more common name treble or violin? @c in Dutch, its violin. -@quotation +@c in English its definitely treble. @example -\clef violin +\clef treble \clef bass \clef alto \clef tenor @end example -@lilypond[fragment] +@lilypond[notime] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff \clef violin s4_" " \clef bass @@ -195,48 +156,41 @@ s4_" " \clef tenor s16_" " @end lilypond -@end quotation -@separate -From these commands and notes, a piece of music can be formed. A piece -of music is made by enclosing it in ``@code{\notes @{ ... @}}''. -LilyPond then knows that music follows (and not lyrics, for example): +When you enter these commands in a file, you must to enclose them in +@code{\notes @{@dots{}@}}. This lets LilyPond know that music (as +opposed to @rglos{lyrics}) follows: -@quotation @example \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. + \time 3/4 + \clef bass + c2 e4 g2. + f4 e d c2. @} @end example -@end quotation -@separate - -At this point, the piece of music is ready to be printed. This is done -by combining the music with a printing command. +Now the piece of music is almost ready to be printed. The final step is to +combine the music with a printing command. -The printing command is the so-called ``@code{\paper}'' block. You will -see later that the \paper block is necessary to customize all kinds of -printing specifics. The music and the \paper block are combined by -enclosing them in ``@code{\score @{ ... @}}''. This is what a full +The printing command is the so-called @code{\paper} block. Later on +you will see that the @code{\paper} block is used to customize +printing specifics. The music and the @code{\paper} block are combined by +enclosing them in @code{\score @{ ... @}}. This is what a full LilyPond source file looks like: -@quotation @example \score @{ \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. + \time 3/4 + \clef bass + c2 e4 g2. + f4 e d c2. @} \paper @{ @} @} @end example -@lilypond +@lilypond[noindent] \score { \notes { \time 3/4 @@ -244,18 +198,205 @@ LilyPond source file looks like: c2 e4 g2. f4 e d c2. } - \paper { linewidth = 60 * \staffspace } + \paper { + linewidth = 55 * \staffspace + } } @end lilypond + + +@node Running LilyPond +@section Running LilyPond + +In the last section we explained what kind of things you could enter +in a lilypond file. In this section we explain how to run LilyPond +and how to view or print the output. If you have not used LilyPond +before, want to test your setup of LilyPond, or want to run an example +file yourself, read this section. The instructions that follow +are for running LilyPond on Unix-like systems. Some additional +instructions for running LilyPond on Windows are given at the end of +this section. + +Begin by opening a terminal window and starting a text editor. +For example, you could open an xterm and execute @code{joe}. In your +text editor, enter the following input and save the file as +@file{test.ly}: + +@quotation +@example +\score @{ + \notes @{ c'4 e' g' @} +@} +@end example @end quotation -@separate +@cindex ly2dvi + +@c now this is weird, running ly2dvi to run LilyPond +@c (therefore name change proposal) + +LilyPond is the program that computes the sheet music. All other +things, such as adding titles, page breaking and other page layout, +are done by a small wrapper program called +@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and +then adds the titling and page layout instructions. To process +@file{test.ly} with @code{ly2dvi}, proceed as follows: + +@quotation +@example +ly2dvi -p test.ly +@end example +@end quotation + +You will see the following on your screen: + +@quotation +@example +GNU LilyPond 1.7.16 +Now processing: `/home/fred/ly/test.ly' +Parsing... +Interpreting music...[1] + @emph{ ... more interesting stuff ... } +PDF output to `test.pdf'... +DVI output to `test.dvi'... +@end example +@end quotation +@cindex DVI file +@cindex Viewing music +@cindex xdvi + +The results of the ly2dvi run are two files, @file{test.dvi} and +@file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can +print or view. For example, viewing PDF can be done with ghostview. +If a version of ghostview is installed on your system, one of these +commands will produce a window with some music notation on your +screen: +@c eeek +@quotation +@example + gv test.pdf + ghostview test.pdf + ggv test.pdf + kghostview test.pdf +@end example +@end quotation +If the music on your screen looks good, you can print it by clicking +File/Print inside ghostview. + +The DVI file (@file{test.dvi}) contains the same sheet music in a +different format. DVI files are more easily processed by the computer, +so viewing them usually is quicker. You can run @code{xdvi test.dvi} or +@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons +activate magnifying glasses. Unfortunately, variable symbols (such as +beams and slurs) are not displayed in the magnifying glasses. + + +@cindex Ghostscript +@cindex @code{lpr} +@cindex Printing output +@cindex PostScript +@cindex PDF + +If you are familiar with @TeX{}, be warned: do not use other DVI +drivers like @code{dvilj}. The @TeX{} coming out of LilyPond uses +embedded PostScript code and will not render correctly if you use +anything other than @code{dvips}. + +@cindex dvips +@cindex dvilj +@cindex DVI driver + +@unnumberedsubsec Windows users +Windows users can start the terminal by clicking on the LilyPond or +Cygwin icon. You can use any text editor (such as NotePad, Emacs or +Vim) to edit the LilyPond file. If you install the Cygwin's +@code{XFree86} X11 window system, @code{tetex-x11} and +@code{ghostscript-x11} packages too, you can view the @code{dvi} +output doing @code{xdvi test.dvi} as described above. If you have +installed a PostScript/PDF viewer, such as @code{GSView} from +@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done +with: +@quotation +@example +@code{gsview32 test.pdf} +@end example +@end quotation +You can also print from the command line by executing: +@quotation +@example +@code{gsview32 /s test.pdf} +@end example +@end quotation + + +@strong{SUMMARY} + +To run LilyPond, input a text file, then run the command @code{ly2dvi} on +that file. The resulting files are either DVI or PostScript, and can +be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows) +respectively. The following table summarizes the constructs that were +discussed in the previous two sections. + +@multitable @columnfractions .3 .3 .4 + +@item @b{Syntax} +@tab @b{Description} +@tab @b{Example} + +@item @code{1 2 8 16} +@tab durations +@tab +@lilypond[relative 1, notime] +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +c1 c2 c8 c16 +@end lilypond + +@item @code{. ..} +@tab augmentation dots +@tab +@lilypond[relative 1, notime] +\property Staff.Clef = \turnOff +c4. c4.. +@end lilypond + +@item @code{c d e f g a b } +@tab scale +@tab +@lilypond[relative 1, notime] +\property Staff.Clef = \turnOff +c d e f g a b +@end lilypond + +@item @code{\clef treble \clef bass } +@tab clefs +@tab +@lilypond[notime] +\clef treble +s4_" " +\clef bass +s4_" " +@end lilypond + +@item @code{\time 3/4 \time 4/4 } +@tab time signature +@tab +@lilypond +\property Staff.Clef \set #'transparent = ##t +\time 3/4 +s4_" " +\time 4/4 +s16_" " +@end lilypond + +@end multitable -We continue with the introduction of the remaining musical constructs. -@c maybe legend here? +@node More basics +@section More basics -Rests are entered just like notes with the name ``@code{r}'': +We continue with the introduction of the remaining musical constructs. +Normal rests are entered just like notes with the name ``@code{r}'': @quotation @example @@ -272,7 +413,7 @@ s16_" " @end quotation @separate -@c Tim wants to move this quotes example just before the: quotes-don't-work +@c Tim wants to move this quotes example just before the: quotes-do not-work @c score, but we'd need to remove quotes from the other two (key and @c tie) examples... @@ -280,7 +421,7 @@ s16_" " @c but we'd need to remove the ', from \key and tie To raise a note by an octave, add a high quote @code{'} (apostrophe) to the note name, to lower a note one octave, add a ``low quote'' @code{,} -(a comma). The central C is @code{c'}: +(a comma). Middle C is @code{c'}: @quotation @example @@ -295,18 +436,26 @@ c'4 c'' c''' \clef bass c c, @end quotation @separate -A tie is created by entering a tilde ``@code{~}'' between the notes to -be tied. A tie between two notes means that the second note must not be -played separately, but just makes the first note sound longer: - +A tie is created by adding a tilde ``@code{~}'' to the first note +being tied. @quotation @lilypond[fragment,verbatim] -g'4 ~ g' a'2 ~ a'4 +g'4-~ g' a'2-~ a'4 @end lilypond @end quotation @separate +A tie is different from a slur. A tie simply makes the first note +sound longer, and can only be used on pairs of notes with the same +pitch. Slurs indicate the articulations of notes, and can be used on +larger groups of notes. Slurs and ties are also nested in practice: +@lilypond[fragment, relative=1] +c2-~-( c8 fis fis4 ~ fis2 g2-) +@end lilypond + -The key signature is set with the command ``@code{\key}'': +The key signature is set with the command ``@code{\key}''. One +caution word of caution: you need to specify whether the key is +@code{\major} or @code{\minor}. @quotation @example \key d \major @@ -328,18 +477,17 @@ g' @c bit on the long/complex/scary taste @c cheating a bit: two lines makes for a friendlier look This example shows notes, ties, octave marks, and rests in action. -Don't worry about all the quotes. @quotation @example \score @{ \notes @{ \time 4/4 - \clef violin \key d \minor + \clef violin r4 r8 d''8 cis''4 e'' - d''8 a'4. ~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis'' ~ + d''8 a'4.-~ a' b'8 + cis''4 cis''8 cis'' bis'4 d''8 cis''-~ cis''2 r2 @} \paper @{ @} @@ -353,8 +501,8 @@ Don't worry about all the quotes. \clef violin \key d \minor r4 r8 d''8 cis''4 e'' - d''8 a'4. ~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis'' ~ + d''8 a'4.-~ a' b'8 + cis''4 cis''8 cis'' bis'4 d''8 cis''-~ cis''2 r2 } \paper { linewidth = 50*\staffspace } @@ -363,34 +511,28 @@ Don't worry about all the quotes. @end quotation @c accidentals... -There are some interesting points to note in this example. Firstly, -accidentals (sharps and flats) don't have to be marked explicitly: you +There are some interesting points to note in this example. +Accidentals (sharps and flats) do not have to be marked explicitly: you just enter the note name, and LilyPond determines whether or not to -print an accidental. Secondly, bar lines and beams are drawn -automatically. Thirdly, LilyPond calculates line breaks for you; it -doesn't matter where you make new lines in the source file. +print an accidental. Bar lines and beams are drawn automatically. +LilyPond calculates line breaks for you; it does not matter where you +make new lines in the source file. Finally, the order of time, key and +clef changes is not relevant: lilypond will use standard notation +conventions for ordering these items. The example also indicates that a piece of music written in a high -register needs lots of quotes. This makes the input a bit unreadable, -and is therefore also a potential source of errors. - -@separate - -The solution is to use ``relative octave'' mode. In practice, most -music is entered using this mode. - -To use relative mode, add @code{\relative} before the piece of music. -You must also give a note from which relative starts, in this case -@code{c''}. - -@c In relative octave mode, quotes are used to mark large jumps in the -@c melody. Without any quotes or commas, the interval between a note and -@c its predecessor is assumed to be a fourth or less. Quotes and commas -@c add octaves in up and down direction. - -If you type no octaviation quotes, relative mode chooses the note that -is closest to the previous one, which is often just the one you need. -@c don't use commas or quotes in this sentence +register needs lots of quotes. This makes the input less readable, +and is also a potential source of errors. + +The solution is to use ``relative octave'' mode. In practice, this is +the most convenient way to copy existing music. To use relative mode, +add @code{\relative} before the piece of music. You must also give a +note from which relative starts, in this case @code{c''}. If you do not +use octavation quotes (ie do not add ' or , after a note), relative mode +chooses the note that is closest to the previous one. Since most music +has small intervals, you can write quite a lot in relative mode without +using octavation quotes. +@c do not use commas or quotes in this sentence For example: @code{c f} goes up; @code{c g} goes down: @quotation @@ -410,15 +552,17 @@ For example: @code{c f} goes up; @code{c g} goes down: @end quotation @separate + @c needed better, maybe even redundant explanation +@c added another example below. @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep. @c in eerste instantie drong het `relative' niet door zonder extra uitleg. -You can make a large interval by adding octaviation quotes. Note that +You can make larger intervals by adding octavation quotes. Note that quotes or commas do not determine the absolute height of a note; the height of a note is relative to the previous one. -@c don't use commas or quotes in this sentence +@c do not use commas or quotes in this sentence For example: @code{c f,} goes down; @code{f, f} are both the same; -@code{c c'} are the same; and @code{c g'} goes up: +@code{c' c} are the same; and @code{c g'} goes up: @quotation @example @@ -437,13 +581,113 @@ For example: @code{c f,} goes down; @code{f, f} are both the same; @end quotation @separate + +Here's an example of the difference between relative mode and +``normal'' (non-relative) mode: + +@quotation +@example +\relative a @{ +\clef bass + a d a e d c' d' +@} +@end example + +@lilypond[fragment] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +\relative a { +\clef bass + a d a e d c' d' +} +@end lilypond +@end quotation +@separate + +@quotation +@example +\clef bass + a d a e d c' d' +@end example + +@lilypond[fragment] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +\clef bass + a d a e d c' d' +@end lilypond +@end quotation +@separate + +@strong{SUMMARY} + +The following table summarizes the syntax in this section. + +@c Is it possible to avoid page breaks directly after the +@c table head? /Mats + +@multitable @columnfractions .3 .3 .4 + +@item @b{Syntax} +@tab @b{Description} +@tab @b{Example} + +@item @code{r4 r8} +@tab rest +@tab +@lilypond[relative 1, notime] +\property Staff.Clef = \turnOff +r4 r8 +@end lilypond + +@item @code{~} +@tab tie +@tab +@lilypond[relative 1, notime] +\property Score.timing = ##f +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +d ~ d +@end lilypond + +@item @code{\key es \major } +@tab key signature +@tab +@lilypond[notime] +\clef treble +\key es \major +s4 +@end lilypond + +@item @var{note}@code{'} +@tab raise octave +@tab +@lilypond[relative 1, notime] +\property Score.timing = ##f +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +a a' +@end lilypond + +@item @var{note}@code{,} +@tab lower octave +@tab +@lilypond[relative 1, notime] +\property Score.timing = ##f +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +c c, +@end lilypond + +@end multitable + A slur is drawn across many notes, and indicates bound articulation (legato). The starting note and ending note are marked with a ``@code{(}'' and a ``@code{)}'' respectively: @quotation @lilypond[fragment,relative 1, verbatim] -d4( )c16( cis d e c cis d )e( )d4 +d4-( c16-)-( cis d e c cis d e-)-( d4-) @end lilypond @end quotation @separate @@ -453,26 +697,33 @@ phrasing), you can also make a phrasing slur with @code{\(} and @code{\)}. @c lousy example +@c ? --hwn +@c fragment of 1st hrn in Adams' The Chairman Dances, with creative +@c chromatic thing pasted in front. (admittedly the original does not +@c have a phrasing slur. The problem is that we do not want the slur +@c and the Phrasing slur to collide. We are trying to make a good +@c impression here. + @quotation @lilypond[fragment,relative 1, verbatim] -a8(\( ais b ) c cis2 b'2 a4 cis, \) c +a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\) @end lilypond @end quotation @separate -Beams are drawn automatically, but if you don't like the choices, you -can enter beams by hand. Surround the notes to be grouped with @code{[} -and @code{]}: +Beams are drawn automatically, but if you do not like the choices, you +can enter beams by hand. Mark the first note to be beamed with +@code{[} and the last one with @code{]}: @quotation @lilypond[fragment,relative 1, verbatim] -[a8 ais] [d es r d] +a8-[ ais-] d-[ es r d-] @end lilypond @end quotation @separate To print more than one staff, each piece of music that makes up a staff is marked by adding @code{\context Staff} before it. These -@code{Staff}'s can be grouped inside @code{<} and @code{>}, as is +@code{Staff}'s are then grouped inside @code{<} and @code{>}, as is demonstrated here: @quotation @@ -485,21 +736,26 @@ demonstrated here: @end quotation In this example, @code{staffA} and @code{staffB} are names that are -given to the staves. For now, it doesn't matter what names you give, as -long as each staff has a unique name. +given to the staves. It does not matter what names you give, as long +as each staff has a different name. If you give them the same name, +LilyPond will assume that you only want one staff, and will but both +pieces of music on the same staff. + @separate -We can typeset a melody with two staves now: +We can now typeset a melody with two staves: @quotation -@lilypond[verbatim] +@lilypond[verbatim,singleline] \score { \notes < \context Staff = staffA { \time 3/4 \clef violin - \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. } + \relative c'' { + e2-( d4 c2 b4 a8-[ a-] + b-[ b-] g-[ g-] a2.-) } } \context Staff = staffB { \clef bass @@ -534,188 +790,133 @@ c-\ff c-\mf @end quotation @separate -Crescendi are started with the commands @code{\<} and @code{\>}. The -command @code{\!} finishes a crescendo on the following note. +Crescendi and decrescendi are started with the commands @code{\<} and +@code{\>}. The command @code{\!} finishes a crescendo on the note it +is attached to. @quotation @lilypond[verbatim,relative 1] -c2\< \!c2-\ff \>c2 \!c2 +c2-\< c2-\!-\ff c2-\> c2-\! @end lilypond @end quotation @separate -Chords can be made by surrounding notes with @code{<} and @code{>}: +Chords can be made by surrounding notes with @code{<<} and @code{>>}: @quotation @lilypond[relative 0, fragment,verbatim] -r4 +r4 <>4 <>8 @end lilypond @end quotation @separate -@ignore -@c te diepzinnig? -@c hmm, te losjes, iig -In general, @code{ < @var{stuff} > } is used when @var{stuff} all -happens at the same time, like in chords, or (like in the two-staff -example above) in a bunch of stacked staves. -@end ignore -Of course, you can combine beams and ties with chords. Notice that -beam and tie markings are placed outside the chord markers: +You can combine beams and ties with chords. Beam and tie markings +must be placed outside the chord markers: @quotation @lilypond[relative 0, fragment,verbatim] -r4 [ ] ~ +r4 <>8-[ <>-]-~ <> @end lilypond @end quotation -When you want to combine chords with slurs and dynamics, an annoying -technical detail crops up: you have type these commands next to the -notes, which means that they have to be inside the @code{< >}: +@ignore +When you want to combine chords with slurs and dynamics, technical +detail crops up: you have type these commands next to the notes, which +means that they have to be inside the @code{< >}. Do Not get confused +by the chord @code{< >} and the dynamic @code{\< \>}! +@end ignore @quotation -@lilypond[relative 0, fragment,verbatim] -r4 ( > < ) \! c8 f a> -@end lilypond -@end quotation -@separate - -A nasty technical detail also crops up when you start a score with a -chord: - -@quotation -@lilypond[verbatim,singleline] -\score { \notes } -@end lilypond -@end quotation -@separate - -The program can not guess that you want the notes on only one staff. To -force the chord on a staff, add @code{\context Staff} like this: - -@quotation -@lilypond[verbatim,singleline] -\score { \notes \context Staff } +@example +r4 <>8-\>-( <> <> <>8-\!-\) +@end example +@lilypond[relative 0, fragment] +\slurUp +r4 <>8-\>-( <> <> <>8-\!-\) @end lilypond @end quotation @separate +@strong{SUMMARY} +@multitable @columnfractions .3 .3 .4 -@ignore -[TODO add some more here - -* lyrics, chords (?) - -* \header - -* identifiers? - -] -@end ignore - -This is the end of the simple tutorial. You know the basic ingredients -of a music file, so this is the right moment to try your at hand at -doing it yourself: try to type some simple examples, and experiment a -little. - -When you're comfortable with the basics, then you might want to read the -rest of this chapter. It also a manual in tutorial-style, but it is much -more in-depth. It will also be very intimidating if you're not familiar -with the basics. It deals with some of the more advanced features of -LilyPond. Topics include lyrics, chords, orchestral scores and parts, -fine tuning output, polyphonic music, and integrating text and music. - - -@c refer to this section -@node Simple legend -@section Simple legend +@item @b{Syntax} +@tab @b{Description} +@tab @b{Example} -@c need texinfo-4.0a or later for this - - -@c both Tim and my father came independently with a request for a -@c `legend' like this. - -@c what should be in it? - - - -@quotation -@multitable @columnfractions .10 .20 .40 - -@item @code{[ ]} -@tab beam +@item @code{( )} +@tab slur @tab @lilypond[fragment, relative 1] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f \property Staff.Clef = \turnOff -[a8 b] +c-( d e-) @end lilypond -@item @code{~} -@tab tie + +@item @code{\( \)} +@tab phrasing slur @tab @lilypond[fragment, relative 1] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f \property Staff.Clef = \turnOff -d ~ d +c-\( c-( d-) e-\) @end lilypond -@item @code{( )} -@tab slur + +@item @code{[ ]} +@tab beam @tab @lilypond[fragment, relative 1] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f \property Staff.Clef = \turnOff -c( d )e +a8-[ b-] @end lilypond -@item @code{'} -@tab raise octave + + +@item @code{< \context Staff ... >} +@tab more staffs @tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t -\property Staff.Clef = \turnOff -a a' +@lilypond[fragment] +< \context Staff = SA { c'1 } + \context Staff = SB { c'1 } > @end lilypond -@item @code{,} -@tab lower octave + +@item @code{-> -.} +@tab articulations @tab @lilypond[fragment, relative 1] -\property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t \property Staff.Clef = \turnOff -c c, +c-> c-. @end lilypond -@item @code{< >} -@tab chord + +@item @code{-\mf -\sfz} +@tab dynamics @tab @lilypond[fragment, relative 1] -\property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t \property Staff.Clef = \turnOff -\context Voice { } +c-\mf c-\sfz @end lilypond + @item @code{\< \!} @tab crescendo @tab @lilypond[fragment, relative 1] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f \property Staff.Clef = \turnOff a\< a \!a @end lilypond @@ -726,602 +927,175 @@ a\< a \!a @lilypond[fragment, relative 1] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f \property Staff.Clef = \turnOff -a\> a \!a +a-\> a a-\! @end lilypond -@end multitable -@end quotation - - - -@node Running LilyPond -@section Running LilyPond - -You write music with LilyPond as follows: first you edit a text file -containing a description of the notes. Then you run LilyPond on the -file. This leaves you with an output file, which you can view or print. - -In this section we explain how to run LilyPond, and view or print the -output. If you have not used LilyPond before, want to test your setup -of LilyPond, or try to run an example file yourself, then read this -section. - -The instructions that follow are for running LilyPond on Unix-like -systems. Some additional instructions for running LilyPond on Windows -are given at the end of this section. - -You begin with opening a terminal window, and start up a text editor. -For example, open an xterm and execute @code{joe}. In your text editor, -enter the following input, and save the file as @file{test.ly}: - -@quotation -@example -\score @{ - \notes @{ c'4 e' g' @} -@} -@end example -@end quotation - -@cindex ly2dvi - -@c now this is weird, running ly2dvi to run LilyPond -@c (therefore name change proposal) - -To run LilyPond, you invoke ly2dvi to compile your LilyPond source file: - -@quotation -@example -ly2dvi -P test.ly -@end example -@end quotation - -You will see the following on your screen: - -@quotation -@example -GNU LilyPond 1.4.0 -Now processing: `/home/fred/ly/test.ly' -Parsing... -Interpreting music...[1] - @emph{ ... more interesting stuff ... } -PS output to `test.ps'... -DVI output to `test.dvi'... -@end example -@end quotation -@cindex DVI file -@cindex Viewing music -@cindex xdvi - -The results of the ly2dvi run are two files, @file{test.dvi} and -@file{test.ps}. The PS file (@file{test.ps}) is the one you can print. -You can view the PS file using the program ghostview. If a version of -ghostview is installed on your system, one of these commands will -produce a window with some music notation on your screen: -@c eeek -@quotation -@example - gv test.ps - ghostview test.ps - ggv test.ps - kghostview test.ps -@end example -@end quotation -If you are satisfied with the looks of the music displayed on your -screen, you can print the PS file by clicking File/Print inside -ghostview. - -The DVI file (@file{test.dvi}) contains the same sheet music in a -different format. DVI files are more easily processed by the computer, -so viewing them usually is quicker. Execute @code{xdvi test.dvi} -to view the DVI file. -If your DVI viewer does not have a "Print" button, you can print the -file by executing @code{lpr test.ps}. - -@c volgende alinea schrappen? - -If you can't get the examples to print, then you should look into -installing and configuring ghostscript. Refer to GhostScript's website -at @uref{http://www.ghostscript.com}. - -@cindex GhostScript -@cindex @code{lpr} -@cindex Printing output -@cindex PostScript - -@unnumberedsubsec Windows users -Windows users start the terminal by clicking on the LilyPond icon. -Notepad is sufficient for editing the LilyPond file. Viewing the PS file -can be done with @code{gsview32 test.ps}. Viewing DVI files can be done -with @code{yap test.dvi}. The "print" button in Yap will print files. -You can also print from the command line by executing @code{gsview32 /s -test.ps} +@item @code{<< >>} +@tab chord +@tab +@lilypond[fragment, relative 1] +<> +@end lilypond +@end multitable -@node The first real tune -@section The first real tune +Now you know the basic ingredients of a music file, so this is the +right moment to experiment and try your at hand typing some simple +files. +When you are comfortable with the basics, you might want to read the +rest of this chapter. It continues in tutorial-style, but it is much +more in-depth, dealing with more advanced topics such as lyrics, +chords, orchestral scores and parts, fine tuning of output, polyphonic +music, and integrating text and music. -The rest of this tutorial will demonstrate how to use Lilypond by -presenting examples of input along with resulting output. We will use -English terms for notation. In case you are not familiar with those, -you may consult the glossary that is distributed with LilyPond. -The examples discussed are included in the distribution, in the -subdirectory @file{input/tutorial/}@footnote{When we refer to filenames, -they are relative to the top directory of the source package. } -To demonstrate what LilyPond input looks like, we start off with a -full-fledged, yet simple example. It is a convoluted version -of the famous minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file -is included in the distribution as @file{minuet.ly}. -@cindex Bach, Johann Sebastian +@node Printing lyrics +@section Printing lyrics +@cindex lyrics -@lilypond[verbatim] -% all text after a percent sign is a comment -% and is ignored by LilyPond -\include "paper16.ly" -\score { - \notes - \relative c'' \sequential { - \time 3/4 - \key g \major - - \repeat "volta" 2 { - d4 g,8 a b c d4 g, g | - e'4 c8 d e fis g4 g, g | - c4 d8( )c b a( )b4 c8 b a g | - a4 [b8 a] [g fis] g2. | - } - - b'4 g8 a b g - a4 d,8 e fis d | - g4 e8 fis g d cis4 b8 cis a4 | - a8-. b-. cis-. d-. e-. fis-. - g4 fis e | - fis a, r8 cis8 - d2.-\fermata - \bar "|." - } - \paper { - % standard settings are too big and wide for a book - indent = 1.0 \cm - linewidth = 15.0 \cm - } +In this section we shall explain how to typeset the following +fragment of The Free Software Song: + +@lilypond[singleline] +\score { \notes { \addlyrics + \notes \relative c' { + \time 7/4 + d'2 c4 b16-( a g a b a b c-) a2 + b2 c4 b8-( a16 g a4-) g2 } + \context Lyrics \lyrics { + Join us now __ and + share the soft -- ware; } +} +\paper { raggedright = ##t } } @end lilypond -We will analyse the input, line by line. -@separate -@example - % all text after a percent sign is a comment - % and is ignored by LilyPond -@end example -Percent signs introduce comments: everything after a percent sign is -ignored. You can use this to write down mental notes to yourself. You -can also make longer comments by enclosing text in @code{%@{} and -@code{%@}}. -@cindex comment -@cindex block comment -@cindex line comment -@separate -@example - \include "paper16.ly" - -@end example -@cindex @code{\include} -@cindex point, printer's -@cindex staff size setting -By default, LilyPond will typeset the music in a size such that each -staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output -(16 point staff height), so we must import the settings for that size, -which is done here. -@separate -@example +@cindex lyric mode +@cindex @code{\lyrics} - \score @{ - -@end example -Music is printed by combining a piece of music with directions for -outputting it. This combination is formed in the @code{\score} block. -@separate -@example - \notes - -@end example -Prepare LilyPond for accepting notes. -@cindex octaves, choosing -@cindex pitch -@separate -@example +Lyrics are a form of music. To get them printed, you must do two +things: indicate that lyrics are entered with @code{\lyrics}, and +indicate that this type of music must be interpreted as texts (and not +notes). This is done with @code{\context Lyrics}. - \relative c'' - +You can enter lyrics in a special input mode of LilyPond. This mode is +called Lyrics mode, and it is introduced by the keyword +@code{\lyrics}. In this mode you can enter lyrics, with punctuation +and accents without any hassle. Syllables are entered like notes, but +with pitches replaced by text. For example, +@example + Twin- kle twin- kle @end example -@cindex relative -@c removed duplicate introduction to octave marks /MB -@c Shorten even more? - -@c As we will see, each note is described by its note name, duration, -@c octave and possibly a chromatic alteration. In this setup, the octave -@c is indicated by using high quotes (@code{'}) and ``lowered quotes'' -@c (commas: @code{,}). The central C is denoted by @code{c'}. The C one -@c octave higher is @code{c''}. One and two octaves below the central C is -@c denoted by @code{c} and @code{c,} respectively. +enters four syllables. Spaces can be introduced into a lyric either +by using quotes: @code{"He could" not} or by using an underscore +without quotes: @code{He_could not}. -Even though a piece of music often spans a range of several octaves, it -mostly moves in small intervals. LilyPond has a special entry mode to -save typing in this situation. In this ``relative'' octave mode, -octaves of notes without quotes are chosen such that a note is as close -as possible (graphically, on the staff) to the preceding note. If you -add a high-quote an extra octave is added. A lowered quote (a comma) -will subtract an extra octave. +These are the lyrics for the free software song: -Because the first note has no predecessor, -you have to give the (absolute) pitch of the note to start with. -@separate -@example - - \sequential @{ - -@end example -What follows is sequential music, i.e., -@cindex sequential music -notes that are to be played and printed after each other. -@separate @example - - \time 3/4 - + \lyrics @{ + Join us now __ and + share the soft -- ware; @} @end example -@cindex time signature, setting -@cindex @code{\time} -Set (or change) the time signature of the current piece: a 3/4 sign is -printed. The time signature setting is also used to generate bar lines -at the right spots. -@separate -@example - \key g \major - -@end example -@cindex key signature, setting -@cindex @code{\key} -Set (or change) the current key signature to G-major. Although in this -example, the @code{\key} command happened to be entered after the -@code{\time} command, in the output the time signature will be printed -after the key signature; LilyPond knows about music typesetting -conventions. -@separate -@example + Extender lines are entered as @code{__}. This will create an +extender, which is a line that extends over the entire duration of the +lyric. This line will run all the way to the start of the next lyric, +so you may want to shorten it by using a blank lyric (using @code{_}). - \repeat "volta" 2 - -@end example -The following piece of music is played twice. The first argument -indicates the type of repeat. In this case, @code{"volta"} means that -prima volta/secunda volta brackets are used for the alternative -endings---if there were any. -@separate -@example - @{ - -@end example -The subject of the repeat is again sequential music. Since -@code{\sequential} is such a common construct, a shorthand is provided: -just leave off @code{\sequential}, and the result is the same. -@separate -@example - - d4 g,8 - -@end example -Two notes. The first note is a quarter note with relative pitch -@code{d}. The relative music was started with a @code{c''}, so the real -pitch of this note is @code{d''}. The duration of a note is designated -by a number; the @code{4} here represents a quarter note. - -The second note is an eight note with relative pitch @code{g,}. The -pitch is taken relative to the previous @code{d''}, making this -note have real pitch @code{g'}. The @code{8} represents an eight note. -@separate -@example - - a b - -@end example -Two more notes, with pitch @code{a} and @code{b}. Because their -duration is the same as the @code{g,8}, there is no need to enter the -duration, but you may enter it anyway, i.e., @code{a4 b4} -@separate -@example - - d4 g, g | - +You can use ordinary hyphens at the end of a syllable, i.e. +@example + soft- ware @end example -@cindex bar check -@cindex @code{|} -@cindex errors, finding -Three more notes. The @code{|} character is a ``bar check''. LilyPond -will verify that bar checks are found at the start of a measure. This can -help you track down typing errors. - -@cindex alteration, chromatic -@cindex chromatic alteration -@separate -@example - - c8 d e fis - -@end example -So far, no notes were chromatically altered. Here is the first one that -is: @code{fis}. LilyPond by default uses Dutch@footnote{Note names are -available in several languages, but we find the Dutch names quite -convenient.} note names, and ``Fis'' is the Dutch note name for ``F -sharp''. However, there is no sharp sign in the output. The program -keeps track of key signatures, and will only print accidentals if they -are needed. - -For groups of eighth notes and shorter, LilyPond can determine how the -notes should form a beam. In this case, the 4 eights are automatically -printed as a beam. -@separate -@example - - c4 d8( )c b a( )b4 c8 b a g | +but then the hyphen will be attached to the end of the first syllable. -@end example -The beginning and ending notes of a slur are marked with parentheses, -@code{(} and @code{)} for start and end respectively. The line above -indicates two slurs. These slur markers (parentheses) are entered -between the slurred notes. -@separate -@example - - a4 [b8 a] [g fis] - -@end example -Automatic beaming can be overridden by inserting beam marks, @code{[} -and @code{]}. These beam markers (brackets) are put around the notes -you want beamed. -@separate -@example - - g2. | +If you want them centered between syllables you can use the special +`@code{-}@code{-}' lyric as a separate word between syllables. The +hyphen will have variable length depending on the space between +the syllables and it will be centered between the syllables. +Normally the notes that you enter are transformed into note heads. +Note heads alone make no sense. They need surrounding information: a +key signature, a clef, staff lines, etc. They need @emph{context}. +In LilyPond, these symbols are created by objects called +`interpretation contexts'. Interpretation contexts exist for +generating notation (`notation context') and for generating sound +(`performance context'). These objects only exist while LilyPond is +executing. For lyrics, the command +@example + \context Lyrics @end example -@cindex augmentation dot -@cindex dotted note -A period adds a dot to the note. -@separate -@example +must be used to interpret a set of syllables as lyrics. - @} - -@end example -The end of the sequential music to be repeated. LilyPond will typeset a -repeat bar. -@separate -@example - cis'4 b8 cis a4 | - -@end example -Accidentals are printed whenever necessary: the first C sharp of the bar -will be printed with an accidental, the second one without. -@separate -@example +@cindex context +@cindex interpretation context +@cindex notation context - a8-. b-. cis-. d-. e-. fis-. - -@end example -@cindex articulation -You can enter articulation signs either in a verbose form or using a -shorthand. Here we demonstrate the shorthand: it is formed by a dash -and the character for the articulation to use, e.g. @code{-.} for -staccato as shown above. -@separate -@example - fis a, r8 cis8 - -@end example - -Rests are denoted by the special note name @code{r}. -@separate -@example - d2.-\fermata - -@end example -All articulations have a verbose form, like @code{\fermata}. The -command @code{\fermata} is not part of the core of the language, but it -is a shorthand for a more complicated description of a fermata symbol. -@code{\fermata} names that description and is therefore called an -identifier. -@cindex identifier -@cindex @code{\fermata} -@separate +The melody and the lyrics can be combined with the @code{\addlyrics}: @example - \bar "|." - @} -@end example -Here the music ends. LilyPond does not automatically typeset an end -bar, we must explicitly request one, using @code{"|."}. - -@separate -@example - - \paper @{ - % standard settings are too big and wide for a book - indent = 1.0\cm - linewidth = 15.0\cm - @} - -@end example -The @code{\paper} block specifies how entered music should be converted -to notation output. Most of the details of the conversion (font sizes, -dimensions, etc.) have been taken care of, but to fit the output in this -document, it has to be narrower. We do this by setting the line width -to 14 centimeters (approximately 5.5 inches). -@separate -@example - - @} - -@end example -The last brace ends the @code{\score} block. - - - - -@node Lyrics and chords -@section Lyrics and chords +\addlyrics + \notes \relative c' @dots{} + \context Lyrics \lyrics @dots{} +@end example -In this section we show how to typeset a song. This file is -included as @file{flowing.ly}. +The lyrics are also music expressions, similar to notes. Each lyric +syllable is put under a note of the melody. The complete file is +listed here: -@example -\header @{ - title = "The river is flowing" - composer = "Traditional" -@} -\include "paper16.ly" -melody = \notes \relative c' @{ - \partial 8 - \key c \minor - g8 | - c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | - c4 c8 d [es () d] c4 | d4 es8 d c4. - \bar "|." +@example +\score @{ \notes @{ \addlyrics + \notes \relative c' @{ + \time 7/4 + d'2 c4 b16 ( a g a b a b ) c a2 + b2 c4 b8 ( a16 g ) a4 g2 @} + \context Lyrics \lyrics @{ + Join us now __ and + share the soft -- ware; @} @} - -text = \lyrics @{ - The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the - ri -- ver is flo -- wing down to the sea. +\paper @{ raggedright = ##t @} @} - -accompaniment =\chords @{ - r8 - c2:3- f:3-.7 d:min es4 c8:min r8 - c2:min f:min7 g:7^3.5 c:min @} - -\score @{ - \simultaneous @{ - %\accompaniment - \context ChordNames \accompaniment - - \addlyrics - \context Staff = mel @{ - \property Staff.noAutoBeaming = ##t - \property Staff.automaticMelismata = ##t - \melody - @} - \context Lyrics \text - @} - \midi @{ \tempo 4=72 @} - \paper @{ linewidth = 10.0\cm @} -@} -@end example +@end example -The result would look this.@footnote{The titling and font size shown -may differ, since the titling in this document is not generated by -@code{ly2dvi}.} -@center @strong{The river is flowing} -@center Traditional +@node A melody with chords +@section A melody with chords -@lilypond[center] -\header { - title = "The river is flowing" - composer = "Traditional" -} -\include "paper16.ly" -melody = \notes \relative c' { - \partial 8 - \key c \minor - g8 | - c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | - c4 c8 d [es () d] c4 | d4 es8 d c4. - \bar "|." -} +In this section we show how to typeset a melody with chord +accompaniment. This file is included in +@inputfileref{input/tutorial,flowing.ly}. -text = \lyrics { - The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the - ri -- ver is flo -- wing down to the sea. -} +@lilypondfile[verbatim,intertext="the result looks like"]{flowing.ly} -accompaniment =\chords { - r8 - c2:3- f:3-.7 d:min es4 c8:min r8 - c2:min f:min7 g:7^3.5 c:min } -\score { - \simultaneous { - %\accompaniment - \context ChordNames \accompaniment - - \addlyrics - \context Staff = mel { - \property Staff.noAutoBeaming = ##t - \property Staff.automaticMelismata = ##t - \melody - } - \context Lyrics \text - } - \midi { \tempo 4=72 } - \paper { linewidth = 10.0\cm } -} -@end lilypond - -Again, we will dissect the file line by line. -@separate -@example - - \header @{ - -@end example -@cindex @code{\header} -Information about the music you are about to typeset goes into a -@code{\header} block. The information in this block is not used by -LilyPond, but it is passed into the output. @file{ly2dvi} uses this -information to print titles above the music. -@separate -@example - - title = "The river is flowing" - composer = "Traditional (?)" -@end example -@cindex assignments -@cindex identifier assignment -the @code{\header} block contains assignments. In each assignment, a -variable is set to a value. Lexically, both the variable name and the -assigned value are strings. The values have to be quoted here, because -they contain spaces. The variable names could also be put within quotes -but it is not necessary. @separate @example \include "paper16.ly" @end example -Smaller size for inclusion in a book. +Smaller size (suitable for inclusion in a book). @separate @example melody = \notes \relative c' @{ @end example -The structure of the file will be the same as the previous one, a +The structure of the file will be the same as the previous one: a @code{\score} block with music in it. To keep things readable, we will -give names to the different parts of music, and use the names to -construct the music within the score block. +give different names to the different parts of music, and use the names +to construct the music within the score block. @separate @example @@ -1330,12 +1104,8 @@ construct the music within the score block. @cindex @code{\partial} @cindex anacrusis -The piece starts with an anacrusis of one eighth. +The piece starts with an anacrusis (or ``pickup'') of one eighth. @separate -@example - \key c \minor -@end example -The key is C minor: we have three flats. @separate @example @@ -1348,8 +1118,8 @@ The key is C minor: we have three flats. @cindex manual beaming @cindex automatic beaming, turning off -We use explicit beaming. Since this is a song, we turn automatic -beams off, and use explicit beaming where needed. +We use explicit beaming. Since this is a song, we turn automatic +beams off and use explicit beaming where needed. @separate @example @@ -1367,26 +1137,8 @@ This ends the definition of @code{melody}. @cindex lyrics @cindex identifier assignment @cindex syllables, entering -Another identifier assignment. This one is for the lyrics. -Lyrics are formed by syllables that have duration, and not by -notes. To make LilyPond parse words as syllables, switch it into -lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics} -is a shorthand for @code{\sequential @{}. -@separate -@example +This defines the lyrics, similar to what we have seen before. - The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the - ri- ver is flo- __ wing down to the sea. -@} - -@end example -@cindex extenders, lyric -@cindex hyphens, lyric -The syllables themselves are separated by spaces. You can get syllable -extenders by entering @code{__}, and centered hyphens with -@code{-}@code{-}. We enter the syllables as if they are all quarter notes -in length (hence the @code{4}), and use a feature to align the -syllables to the music, which obviously isn't all quarter notes. @separate @example @@ -1395,9 +1147,9 @@ syllables to the music, which obviously isn't all quarter notes. @end example @cindex chords @cindex mode, chords -We'll put chords over the music. To enter them, there is a special mode +We will put chords over the music. To enter them, we use a special mode analogous to @code{\lyrics} and @code{\notes} mode, where you can give -the names of the chords you want, instead of listing the notes +the names of the chords you want instead of listing the notes comprising the chord. @separate @example @@ -1409,17 +1161,23 @@ There is no accompaniment during the anacrusis. @separate @example - c2:3- f:3-.7 + c2:3- @end example @cindex tonic @cindex chord modifier @cindex modifier, chord -A chord is started by the tonic of the chord. The -first one lasts a half note. An unadorned note creates a major -triad. Since a minor triad is wanted, @code{3-} is added to modify the -third to be small. @code{7} modifies (adds) a seventh, which is small by +This is a c minor chord, lasting for a half note. Chords are entered using +the tonic. Notes can be changed to create different chords. In this case, +a lowered third is used (making a C major chord into a C minor chord). +The code for this is @code{3-}. + +@separate +@example +f:3-.7 +@end example +Similarly, @code{7} modifies (adds) a seventh, which is small by default to create the @code{f a c es} chord. Multiple modifiers must be separated by dots. @separate @@ -1428,7 +1186,6 @@ separated by dots. d:min es4 c8:min r8 @end example - Some modifiers have predefined names, e.g. @code{min} is the same as @code{3-}, so @code{d-min} is a minor @code{d} chord. @separate @@ -1443,7 +1200,8 @@ A named modifier @code{min} and a normal modifier @code{7} do not have to be separated by a dot. Tones from a chord are removed with chord subtractions. Subtractions are started with a caret, and they are also separated by dots. In this example, @code{g:7^3.5} produces a -minor seventh. The brace ends the sequential music. +minor seventh (a G7 chord without the third or the fifth). The +brace ends the sequential music. @separate @example @@ -1456,117 +1214,40 @@ accompaniment have to sound at the same time, so they should be @code{\simultaneous}. @cindex @code{\simultaneous} @separate -@example - - %\accompaniment - -@end example -Chord mode generates notes grouped in @code{\simultaneous} music. If -you remove the comment sign, you can see the chords in normal -notation: they will be printed as note heads on a separate -staff. To print them as chords names, they have to be interpreted as -being chords, not notes. This is done with the following command: -@separate +To print chords as chords names, they have to be interpreted as +such. This is done with the following command: The following command +explicitly creates an interpretation context of @code{ChordNames} type +to interpret the music @code{\accompaniment}. @example \context ChordNames \accompaniment @end example -@cindex context -@cindex interpretation context -@cindex notation context - - -Normally, the notes that you enter are transformed into note heads. -Note heads alone make no sense, they need surrounding information: a key -signature, a clef, staff lines, etc. They need @emph{context}. In -LilyPond, these symbols are created by objects called `interpretation -contexts'. Interpretation contexts exist for generating notation -(`notation context') and for generating sound (`performance -context'). These objects only exist during a run of LilyPond. - -By default, LilyPond will create a Staff context for you. If you would -remove the @code{%} sign in the previous line, you would see that -mechanism in action. -We don't want that default here, because we want chord names. The -command above explicitly creates an interpretation context of -@code{ChordNames} type to interpret the music @code{\accompaniment}. @separate @example - \addlyrics + \context Staff @{ @end example -@cindex @code{\addlyrics} -@cindex lyrics and melody, combining -@cindex combining lyrics and melody -The lyrics should be aligned with the melody. This is done by -combining both with @code{\addlyrics}. @code{\addlyrics} takes two -pieces of music (usually a melody and lyrics, in that order) and -aligns the syllables of the second piece under the notes of the -first piece. If you would reverse the order, the notes would be -aligned on the lyrics, which is not very useful, and looks -silly. +We place the melody on a staff. @separate @example - \context Staff = mel @{ - -@end example - -The first argument of @code{\addlyrics} is the melody. We instantiate -a @code{Staff} context explicitly: should you choose to remove the -comment before the ``note heads'' version of the accompaniment, the -accompaniment will be on a nameless staff. The melody has to be on -staff different from the accompaniment. This is accomplished by giving -the melody and accompaniment staves different names. -@separate -@example - - \property Staff.noAutoBeaming = ##t + \property Staff.autoBeaming = ##f @end example @cindex \property @cindex context variables @cindex setting context variables -An interpretation context has variables, called properties, that tune -its behavior. One of the variables is @code{noAutoBeaming}. Setting -this @code{Staff}'s property to @code{##t}, which is the boolean value -@var{true}, turns the automatic beaming mechanism off for the current -staff. -@cindex GUILE -@cindex Scheme -@cindex accessing Scheme -@cindex evaluating Scheme -@cindex LISP - -LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a -language from the LISP family. You can learn more about Scheme at -@uref{http://www.scheme.org}. It is used to represent data throughout -the whole program. The hash-sign (@code{#}) accesses GUILE directly: the -code following the hash-sign is evaluated as Scheme. The boolean value -@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like -@code{##t}. - -If Scheme scares you, don't worry. You don't need to know Scheme to -create beautiful sheet music. - +An interpretation context has variables that tune its behavior. These +variables are also called @emph{properties}. The @code{autoBeaming} +variable in a @code{Staff} controls whether 8th and shorter notes are +beamed automatically. Setting the variable to @code{##f}, which is the +boolean value @var{false}, turns it off. -@separate -@example - - \property Staff.automaticMelismata = ##t - -@end example -@cindex automaticMelismata -@cindex melismata -@cindex @code{\addlyrics} and slurs -Similarly, we don't want to print a syllable when there is -a slur. This sets up @code{\addlyrics} to not put lyrics under each -separate note while there is a slur. @separate @example @@ -1578,16 +1259,7 @@ Finally, we put the melody on the current staff. Note that the @code{\property} directives and @code{\melody} are grouped in sequential music, so the property settings are done before the melody is processed. -@separate -@example - \context Lyrics \text - -@end example -The second argument of @code{\addlyrics} is the text. The text also -should not land on a Staff, but on a interpretation context for -syllables, extenders, hyphens etc. This context is called -Lyrics. @separate @example @@ -1595,70 +1267,93 @@ Lyrics. @end example MIDI (Musical Instrument Digital Interface) is a standard for -connecting and recording digital instruments. So a MIDI file is like a -tape recording of an instrument. The @code{\midi} block makes the -music go to a MIDI file, so you can listen to the music you entered. It -is great for checking the music. Whenever you hear something weird, you -probably hear a typing error. +connecting and recording digital instruments. A MIDI file is like a +tape recording of a MIDI instrument. The @code{\midi} block makes the +music go to a MIDI file, so you can listen to the music you entered. +It is great for checking the music. Whenever you hear something +weird, you probably hear a typing error. -Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it -also specifies an output method. You can specify the tempo using the -@code{\tempo} command, in this case the tempo of quarter notes is set to -72 beats per minute. +@code{\midi} is similar to @code{\paper @{ @}}, since it also +specifies an output method. You can specify the tempo using the +@code{\tempo} command, in this case the tempo of quarter notes is set +to 72 beats per minute. @separate @example \paper @{ linewidth = 10.0\cm @} @end example -We also want notation output. The linewidth is short so the piece +We also want notation output. The linewidth is short so that the piece will be set in two lines. -@node More movements -@section More movements +@node More stanzas +@section More stanzas -[FIXME: merge here with, or move this to: Other ways to run LilyPond] -You probably ran @file{ly2dvi} on the last example, and ended up with a -viewable @file{.dvi} file. However, between there are a few steps of -which LilyPond is only one. To enhance your understanding of what's -happening under the hood when you run @code{ly2dvi}, we explain what -programs are run. +@cindex phrasing -@code{ly2dvi} is a program that calls a number of programs in sequence. -The first thing it does, is running LilyPond on the input file. After -some calculations, a @file{.tex} is produced. The contents -of this file are very low-level instructions. +If you have multiple stanzas printed underneath each other, the vertical +groups of syllables should be aligned around punctuation. LilyPond can +do this if you tell it which lyric lines belong to which melody. +We show how you can do this by showing how you could print a frivolous +fragment of a fictional Sesame Street duet. -For example, consider the following file (@file{miniatures.ly}) +@lilypond[singleline,verbatim] +\score { +\addlyrics + \notes \relative c'' \context Voice = duet { \time 3/4 + g2 e4 a2 f4 g2. } + \lyrics \context Lyrics < + \context LyricsVoice = "duet-1" { + \property LyricsVoice . stanza = "Bert" + Hi, my name is bert. } + \context LyricsVoice = "duet-2" { + \property LyricsVoice . stanza = "Ernie" + Ooooo, ch\'e -- ri, je t'aime. } + > +} +@end lilypond +To this end, give the Voice context an identity, and set the +LyricsVoice to a name starting with that identity followed by a dash. +In the following example, the Voice identity is @code{duet}, @example -\version "1.4.0" -\header @{ - title = "Two miniatures" - tagline = "small is beautiful" -@} +\context Voice = duet @{ + \time 3/4 + g2 e4 a2 f4 g2. @} +@end example +and the +identities of the LyricsVoices are @code{duet-1} and @code{duet-2}. +@example + \context LyricsVoice = "duet-1" @{ + Hi, my name is bert. @} + \context LyricsVoice = "duet-2" @{ + Ooooo, ch\'e -- ri, je t'aime. @} +@end example +The convention for naming @code{LyricsVoice} and @code{Voice} must +also be used to get melismata on rests correct. -#(set! point-and-click line-column-location) -\paper @{ linewidth = -1.0 @} +We add the names of the singers. This can be done by setting +@code{LyricsVoice.Stanza} (for the first system) and +@code{LyricsVoice.stz} for the following systems. Note that you must +surround dots with spaces in @code{\lyrics} mode. -\score @{ - \notes @{ c'4 d'4 @} - \header @{ - opus = "Opus 1." - piece = "Up" @} -@} -\score @{ - \notes @{ d'4 c'4 @} - \header @{ - opus = "Opus 2." - piece = "Down" @} -@} +@example + \property LyricsVoice . stanza = "Bert" + @dots{} + \property LyricsVoice . stanza = "Ernie" @end example -The titling in this manual was not generated by ly2dvi, so we can't -exactly show what it would look like, but the result should resemble this: + +@node More movements +@section More movements + +The program @code{lilypond} only produces sheet music. Titles, +subtitles, and the composer's name are created by a separate program, +called use @code{ly2dvi}. @code{ly2dvi} creates the titles, then +calls @code{lilypond} to format the sheet music. In this section, we +show you how to create titles like this: @center @strong{Two miniatures} @flushright @@ -1670,7 +1365,7 @@ Opus 1. @lilypond \score { \notes { c'4 d'4 } - \paper { linewidth = -1.0 } + \paper { raggedright = ##t } } @end lilypond @flushright @@ -1686,83 +1381,90 @@ Opus 2. } @end lilypond -This file is produced by ly2dvi in a few stages, with the help of text -formatting tools. LilyPond produces two output files, -@file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain -only graphical music notation. @file{ly2dvi} looks at what output -LilyPond produces, and adds page layout and titling to those files. The -result is a DVI file called @file{miniatures.dvi}. +For example, consider the following file (@file{miniatures.ly}) -Next, now we'll look at the example line by line to explain new things. +@example +\version "1.5.72" +\header @{ + title = "Two miniatures" + composer = "F. Bar Baz" + tagline = "small is beautiful" @} -@separate -@example -\version "1.4.0" -@end example -Lilypond and its language are still under development, and occasionally, -details of the syntax are changed. This fragment indicates for which -version the input file was written. When you compile this file, the -version number will be checked, and you will get a warning when the file -is too old. +\paper @{ raggedright = ##t @} -This version number is also used by the @code{convert-ly} program (See -@ref{convert-ly}), which is used to update the file to the latest lily -version. +%@{ -@separate -@example - \header @{ - title = "Two miniatures" @} -@end example -This sets the titling information for the entire file. -@separate -@example - tagline = "small is beautiful" -@end example -A signature line is printed at the bottom of the last page. - This signature is produced from the @code{tagline} field of -@code{\header}. Many people find the default "Lily was here, -@var{version number}" too droll. If that is the case, assign -something else to @code{tagline}, as shown above. -@separate -@example - #(set! point-and-click line-column-location) +Mental note: discuss Schenkerian analysis of these key pieces. + +%@} + +\score @{ + \notes @{ c'4 d'4 @} + \header @{ + opus = "Opus 1." + piece = "Up" @} +@} +\score @{ + \notes @{ d'4 c'4 @} + \header @{ + opus = "Opus 2." + piece = "Down" @} +@} @end example -This piece of Scheme code sets the Scheme variable -@code{point-and-click} to the value @var{line-column-location} (which -itself is a Scheme procedure). -Editing input files can be quite complicated if you're working with -large files: if you're digitizing existing music, you have to -synchronize the .ly file, the sheet music on your lap and the sheet -music on the screen. The point-and-click mechanism makes it easy to -find the origin of an error in the LY file: when you view the file with -Xdvi and click on a note, your editor will jump to the spot where that -note was entered. For more information, see @ref{Point and click}. +The information for the global titling is in a so-called header block. +The information in this block is not used by LilyPond, but it is +passed into @code{ly2dvi}, which uses this information to print titles +above the music. +@cindex assignments +@cindex identifier assignment +the @code{\header} block contains assignments. In each assignment, a +variable is set to a value. The header block for this file looks like +this +@cindex @code{\header} +@example + \header @{ + title = "Two miniatures" + composer = "F. Bar Baz" + tagline = "small is beautiful" + @} +@end example + +When you process a file with ly2dvi, a signature line is printed at +the bottom of the last page. Many people find the default (``Lily was +here'' with a version number) too droll. If that is the case, you can +change @code{tagline} in the @code{\header}, as shown above. + +@cindex Lily was here +@cindex signature line +@cindex tag line @separate @example \paper @{ + raggedright = ##t @} @end example -The @code{\score} blocks that follow in the file don't have -@code{\paper} sections, so the settings of this block are substituted: A -paper block at top level, i.e. not in a @code{\score} block sets the -default page layout. +A paper block at top level (i.e. not in a @code{\score} block) sets +the default page layout. The following @code{\score} blocks do not +have @code{\paper} sections so the settings of this block are used. + +When @code{raggedright} is set, the spacing is set to natural length: +a short phrase takes up little space, a longer phrase takes more +space, all on the same line. -@separate @example - linewidth = -1.0 @} -@end example +%@{ +Mental note: discuss Schenkerian analysis of these key pieces. +%@} +@end example -The variable @code{linewidth} normally sets the length of the systems on -the page. However, a negative value has a special meaning. If -@code{linewidth} is less than 0, no line breaks are inserted into the -score, and the spacing is set to natural length: a short phrase takes up -little space, a longer phrase more space. +Mental notes to yourself can be put into comments. There are two types +of comments. Line comments are introduced by @code{%}, and block +comments are delimited by @code{%@{} and @code{%@}}. @separate @example @@ -1770,19 +1472,17 @@ little space, a longer phrase more space. \notes @{ c'4 d'4 @} @end example -In previous examples, notes were specified in relative octaves, -i.e. each note was put in the octave that is closest to its -predecessor. Besides relative, there is also absolute octave -specification, which you get when you don't specify @code{\relative}. In -this input mode, the central C is denoted by @code{c'}. Going down, you -get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''} -@code{c'''} etc. - -When you're copying music from existing sheet music, relative octaves -are probably the easiest to use: it's less typing work and errors are -easily spotted. However, if you write LilyPond input directly, either by -hand (i.e. composing) or by computer, absolute octaves may be easier to use. +In previous examples, most notes were specified in relative octaves +(i.e. each note was put in the octave that is closest to its preceding +note). This is convenient when copying existing music: you have to do +less typing, and errors are easily spotted. +There is also absolute octave specification, which you get when you do +not include @code{\relative} in your input file. In this input mode, +the middle C is denoted by @code{c'}. Going down, you get @code{c} +@code{c,} @code{c,,} etc. Going up, you get @code{c''} @code{c'''} +etc. Absolute octaves are convenient when you write LilyPond input +directly, either by hand (i.e. composing) or by computer. @separate @example @@ -1790,170 +1490,110 @@ hand (i.e. composing) or by computer, absolute octaves may be easier to use. @end example The @code{\header} is normally at the top of the file, where it sets -values for the rest of the file. If you want to typeset different pieces -from one file (for example, if there are multiple movements, or if -you're making an exercise book), you can put different @code{\score} -blocks into the input file. ly2dvi will assemble all LilyPond output -files into a big document. The contents of \header blocks specified -within each score, are used for the titling of each movement. +values for the rest of the file. If you want to typeset different +pieces from one file (for example, if there are multiple movements, or +if you are making an exercise book), you can put different +@code{\score} blocks into the input file. @code{ly2dvi} will assemble +all LilyPond output files into a one document. The contents of +@code{\header} blocks specified within each score is used for the +title of that movement. @separate @example opus = "Opus 1." piece = "Up" @} @end example -For example, the Opus number is put at the right, and the piece string +For example, the Opus number is put at the right, and the "piece" string will be at the left. -@node A piano excerpt -@section A piano excerpt - -Our fourth subject is a piece of piano music. The fragment in the input -file is a piano reduction of the G major Sinfonia by Giovanni Battista -Sammartini. It was composed around 1740. It's in the source package -under the name @file{sammartini.ly}. - -@lilypond[verbatim] -\include "paper16.ly" +@example +\version "1.5.72" +\header @{ + title = "Two miniatures" + composer = "F. Bar Baz" + tagline = "small is beautiful" @} -stemDown = \property Voice.Stem \override #'direction = #-1 -stemUp = \property Voice.Stem \override #'direction = #1 -stemBoth = \property Voice.Stem \revert #'direction +\paper @{ raggedright = ##t @} -viola = \notes \relative c' \context Voice = viola { - - \stemDown g'8. b,16 - s1 s2. r4 - g -} +\score @{ + \notes @{ c'4 d'4 @} + \header @{ + opus = "Opus 1." + piece = "Up" @} +@} +\score @{ + \notes @{ d'4 c'4 @} + \header @{ + opus = "Opus 2." + piece = "Down" @} +@} +@end example -oboes = \notes \relative c'' \context Voice = oboe { - \stemUp s4 g8. b,16 c8 r - \grace - \times 2/3 { } - < - { \times 2/3 { a8 g c } \! c2 } - \context Voice = oboeTwo { - \stemDown - \grace { - \property Voice.Stem \override #'direction = #-1 - [f,16 g] - \property Voice.Stem \revert #'direction - } - f8 e e2 - } - > - \stemBoth - \grace <)b8. d8.-\trill> | - [ < )f8. a>] <)b,8 d> r [ ] r | - [ < )e8. g>] -} +TODO: +@example -hoomPah = \repeat unfold 8 \notes - \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth } - -bassvoices = \notes \relative c' { - c4 g8. b,16 - \autochange Staff \hoomPah - \translator Staff = down - \stemDown [c8 c'8] r4 - r4 - < {\stemUp r2 } - \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } > -} +scoreA = \score @{ \deelA @} +scoreB = \score @{ \deelA @} -\score { - \context PianoStaff \notes < - \context Staff = up < \time 2/2 - \viola - \oboes - > - \context Staff = down < \time 2/2 \clef bass - \bassvoices - > - > - \midi { } - \paper { - indent = 0.0 - linewidth = 15.0 \cm } -} -@end lilypond +% \score @{ \scoreA @} +\score @{ \scoreB @} -If this looks like incomprehensible gibberish to you, you are right. -This example has been doctored to have as many quirks as possible. +@end example -As you can see, this example features multiple voices on one staff. To -make room for those voices, their notes have to be stemmed in opposite -directions. +@separate +@example +\version "1.5.72" +@end example +Lilypond and its language are still under development, and +occasionally details of the syntax are changed. The @code{version} +fragment indicates which version of lilypond the input file was written +for. When you compile this file, the version number will be checked +and you will get a warning when the file is too old. This version +number is also used by the @code{convert-ly} program (See +@ref{Invoking convert-ly}), which can used to update the file to the +latest lily version. -Printed symbols are internally represented by so-called Graphical -Objects (more colloquially: Grobs). These statements concern the -grob called `Stem'. Each grob is described by a bunch of settings. These -setting determine the fonts, offsets, sub-routines to be called on the -grob, etc. The initial values of these settings are set in the Scheme -file @file{scm/grob-description.scm}. -@separate -@example - stemDown = \property Voice.Stem \override #'direction = #-1 -@end example +@node A piano excerpt +@section A piano excerpt -Set a property for all Stem grobs in the current Voice: -@code{direction} is set to @code{-1}, which encodes down. The setting -remains in effect until it is reverted. +Our eighth subject is a piece of piano music. The fragment in the +input file is a piano reduction of the G major Sinfonia by Giovanni +Battista Sammartini, composed around 1740. It's in the source +package under the name @inputfileref{input/tutorial,sammartini.ly}. -@separate -@example - \property Voice.Stem \revert #'direction -@end example +@lilypondfile[smallverbatim]{sammartini.ly} -Revert the to the previous setting. The effect of precisely one -@code{\stemDown} or @code{\stemUp} is neutralized. +As you can see, this example features multiple voices on one staff. To +make room for those voices, their notes should be stemmed in opposite +directions. -LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along -with some other commonly used formatting instructions, but to explain how -it works, we wrote our own here. Of course, you should use predefined -identifiers like these if possible: then you will be affected less by -the implementation changes we occasionally make. @separate @example viola = \notes \relative c' \context Voice = viola @{ @end example -In this example, you can see multiple parts on a staff. Each part is +In this example you see multiple parts on a staff. Each part is associated with one notation context. This notation context handles -stems and dynamics (among others). The type name of this context is -@code{Voice}. For each part we have to make sure that there is -precisely one @code{Voice} context, so we give it a unique name -(`@code{viola}'). +stems and dynamics (among other things). The type name of this +context is @code{Voice}. For each part we have to make sure that +there is precisely one @code{Voice} context, so we give it a unique +name (`@code{viola}'). @separate @example - +<>4-\arpeggio @end example -The delimiters @code{<} and @code{>} are shorthands for -@code{\simultaneous @{} and @code{@}}. The expression enclosed in -@code{<} and @code{>} is a chord. +The delimiters @code{<<} and @code{>>} enclose the pitches of a chord. +@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) +before the chord. -@cindex dynamics -@cindex loudness -@cindex forte @cindex arpeggio -@code{\f} places a forte symbol under the chord. The forte applies to -the whole chord, but the syntax requires that commands like forte and -arpeggio are attached to a note, so here we attach them to the first -note. -@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before -the chord. -@separate -@example - \stemDown -@end example @separate @@ -1971,7 +1611,7 @@ s1 s2. r4 @end example @code{s} is a spacer rest. It does not print anything, but it does have the duration of a rest. It is useful for filling up voices that -temporarily don't play. In this case, the viola doesn't come until one +temporarily do not play. In this case, the viola does not come until one and a half measure later. @separate @@ -1984,25 +1624,23 @@ these notes are indeed processed by precisely one context with @code{\context}. @separate @example -\stemUp s4 g8. b,16 c8 r -@end example -@code{\stemUp} is a reference to the @code{\property \override} command -defined above. + s4 g8. b,16 c8 r <>8. <>16 +@end example + +The oboes should have stems up to keep them from interfering with +the staff-jumping bass figure. To do that, we use @code{\voiceOne}. + @separate @example -\grace < d4 f> +\grace <>-( <>4-) <>2 @end example @cindex @code{\grace} @cindex ornaments @cindex grace notes @code{\grace} introduces grace notes. It takes one argument, in this -case a chord. +case a chord. A slur is introduced starting from the @code{\grace} +ending on the following chord. -@ignore -The slur started on the @code{e} of the chord -will be attached to the next note.@footnote{LilyPond will squirm -about unended Slurs. In this case, you can ignore the warning}. -@end ignore @separate @example \times 2/3 @@ -2015,62 +1653,33 @@ of music is multiplied by the fraction. Triplets make notes occupy 2/3 of their notated duration, so in this case the fraction is 2/3. @separate @example -@{ @} +@{ <>8 <> <> @} @end example The piece of music to be `tripletted' is sequential music containing -three notes. On the first chord, a crescendo is started with -@code{\<}. To be precise, the crescendo start is syntactically attached -to the preceding note, the @code{d}. - -@cindex dynamics -@cindex crescendo -@cindex @code{\<} +three chords. @separate @example < @end example At this point, the homophonic music splits into two rhythmically -different parts. We can't use a sequence of chords to enter this, so -we make a `chord' of sequences to do it. We start with the upper +different parts. We cannot use a sequence of chords to enter this, so +we make a "chord of sequences" to do it. We start with the upper voice, which continues with upward stems: @separate @example - @{ \times 2/3 @{ a8 g c @} \! c2 @} + @{ \times 2/3 @{ a8 g c @} c2 @} @end example -@cindex @code{\!} - -The crescendo is ended at the half note by the escaped exclamation -mark @code{\!}. -@separate -@example -\context Voice = oboeTwo @{ -\stemDown -@end example -We can't share stems with the other voice, so we have to create a new -@code{Voice} context. We give it the name @code{oboeTwo} to distinguish -it from the other context. Stems go down in this voice. @separate -@example -\grace +@example +\\ @end example -@cindex Grace context -When a grace section is processed, a @code{Grace} context is -created. This context acts like a miniature score of its own. It has -its own time bookkeeping, and you can make notes, beams, slurs -etc. Here we fiddle with a property and make a beam. The argument of -@code{\grace} is sequential music. - -@separate -@example - \property Voice.Stem \override #'direction = #-1 - [f,16 g] - \property Voice.Stem \revert #'direction -@end example - -Normally, grace notes are always stem up, but in this case, the upper -voice interferes, so we set the stems down here. +The easiest way to enter multiple voices is demonstrated +here. Separate the components of the voice (single notes or entire +sequences) with @code{\\} in a simultaneous music expression. The +@code{\\} separators split first voice, second voice, third voice, and +so on. As far as relative mode is concerned, the previous note is the @code{c'''2} of the upper voice, so we have to go an octave down for @@ -2078,21 +1687,17 @@ the @code{f}. @separate @example - f8 e e2 + f,8 e e2 @} > @end example This ends the two-part section. @separate @example -\stemBoth -\grace <)b8. d8.-\trill> | +\grace <>8-( <>8.-\trill <>16 | @end example @cindex trill @cindex stemBoth -@code{\stemBoth} ends the forced stem directions. From here, stems are -positioned as if it were single part music. - The bass has a little hoom-pah melody to demonstrate parts switching between staves. Since it is repetitive, we use repeats: @separate @@ -2104,7 +1709,7 @@ The unfolded repeat prints the notes in its argument as if they were written out in full eight times. @separate @example -\notes \transpose c' @{ +\notes \transpose c c' @{ @end example @cindex transposing @cindex relative mode and transposing @@ -2114,24 +1719,40 @@ The first specifies what central C should be transposed to. The second is the to-be-transposed music. As you can see, in this case, the transposition has no effect, as central C stays at central C. -The purpose of this no-op is circumventing relative mode. Relative mode -can not be used together with transposition, so @code{\relative} will -leave the contents of @code{\hoomPah} alone. We can use it without -having to worry about getting the motive in a wrong octave. +The purpose of this no-op is to protect it from being interpreted as +relative notes. Relative mode cannot be used together with +transposition, so @code{\relative} will leave the contents of +@code{\hoomPah} alone. We can use it without having to worry about +getting the motive in a wrong octave. Conversely, if you want to +transpose a fragment of music entered with @code{\relative}, then you +should make sure that @code{\transpose} comes before @code{\relative}. + +@separate +@cindex staff switch, manual +@cindex cross staff voice, manual +@cindex @code{\translator} + +@example +\translator Staff = down +\stemUp +c8 +\translator Staff = up +\stemDown +c'8 @} +@end example +Voices can switch between staves. Here you see two staff switching +commands. The first one moves to the lower staff, the second one to +the lower one. If you set the stem directions explicitly +(using the identifiers @code{\stemUp} and @code{\stemDown}, the notes +can be beamed together (despite jumping between staffs). + @separate @example bassvoices = \notes \relative c' @{ c4 g8. b,16 -\autochange Staff \hoomPah +\autochange Staff \hoomPah \context Voice @end example -@cindex staff switch, automatic -@cindex cross staff voice, automatic -@cindex @code{\autochange} -Voices can switch between staves. The easiest way to get this, is to use -@code{\autochange}. This command looks at the pitch of each note, and if -necessary, will cross to the other staff. For this to work, the two -staves must be called @code{"up"} and @code{"down"}. @separate @example \translator Staff = down @@ -2142,16 +1763,7 @@ We want the remaining part of this melody on the lower staff, so we do a manual staff switch here. -@separate -@example -\context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} > -@end example -@cindex tie -@cindex @code{~} -After skipping some lines, we see @code{~}. This mark makes ties. Note -that ties and slurs are different things. A tie can only connect two -note heads of the same pitch, whereas a slur can connect many chords -with one curve. + @separate @example @@ -2182,6 +1794,280 @@ to the page layout of this document. @end ignore +@node Fine tuning a piece +@section Fine tuning a piece + +In this section we show some ways to fine tune the final output of a +piece. We do so using a single measure of a moderately complex piano +piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the +tuned and the untuned versions) are in @file{input/tutorial/}. + +The code for the untuned example shows us some new things. + +@lilypondfile[verbatim]{brahms-original.ly} + + +@cindex dynamics +@cindex loudness +@cindex forte +@cindex crescendo + + +@cindex fingering instructions +[TODO: moveme] + +Fingering indications are entered with @code{-@var{N}}, where +@var{N} is a digit. + +Now that we have the basic piece of music entered, we want to fine +tune it so that we get something that resembles the original printed +edition by Schott/Universal Edition: + +@lilypondfile{brahms-tweaked.ly} + +@cindex tuning graphical objects + +Fine tuning involves overriding the defaults of the printing system. +We do this by setting variables which control how Lilypond prints +symbols. Printed symbols are called graphical objects (often +abbreviated to @emph{grob}). Each object is described by a bunch of +settings. Every setting is a variable: it has a name and a value +which you can change. These values determine the fonts, offsets, +sub-routines to be called on the object, etc. The initial values of +these settings are set in the Scheme file +@file{scm/grob-description.scm}. + +@cindex slur attachments + +We start with the slur in the upper part, running from F sharp to A. In +the printed edition, this slur runs from stem to stem; in our version, +the slur begins at the note head of the F sharp. The following property +setting forces all slurs to run from stem to stem (not from or to note +heads!). + +@example + \property Voice.Slur \set #'attachment = #'(stem . stem) +@end example + +More precisely, this command modifies the definition of the @code{Slur} +object in the current @code{Voice}. The variable @code{attachment} is +set to the pair of symbols @code{'(stem . stem)}. + +@cindex internal documentation +@cindex finding graphical objects +@cindex graphical object descriptions + +This command fixes one particular problem with a slur. The rest of +this section explains how to figure out which properties to tune for +your own scores. To discover this, you must have a copy of the +internals document. This is a set of HTML pages which should be +included if you installed a binary distribution. [TODO: revise for +new site.] These HTML pages are also available on the web: go to the +lilypond website, click ``Documentation: Index'' on the side bar, look +in the ``Information for uses'' section, and click on ``Documentation +of internals''. + +You might want to bookmark either the HTML files on your disk, or the +one on the web (the HTML on your hard drive will load much faster than +the ones on the web!). One word of caution: the internals +documentation is generated from the definitions that the program uses. +Hence, the internals documentation is strongly tied to the version you +use. Before you proceed, make sure that the program and documentation +have matching version numbers. + +@c TODO: the quote is incorrect, although that shouldn't be a big +@c problem for the reader. +Suppose that you wanted to tune the behavior of the slur. The first +step is to get some general information on slurs in lilypond. Turn to +the index, and look up ``slur''. The section on slurs says +@quotation +The grob for this object is @internalsref{Slur}, generally in +@internalsref{Voice} context. +@end quotation + +So the graphical object for this object is called @code{Slur}, and +slurs are created in the @code{Voice} context. If you are reading +this tutorial in the HTML version, then you can simply click Slur, +otherwise, you should look it up the internal documentation: click +``grob overview'' and select ``slur'' (the list is alphabetical). + +Now you get a list of all the properties that the slur object +supports, along with their default values. Among the properties we +find the @code{attachment} property with its default setting. +The property documentation explains that the following setting will +produce the desired effect: +@example + \property Voice.Slur \set #'attachment = #'(stem . stem) +@end example + +@c this is a long section, and adding an extra space here helps to +@c break it into smaller subsections and thus is easier to understand. +@separate + +Next we want to move the fingering `3'. In the printed edition it is +not above the stem, but a little lower and slightly left of the stem. +From the user manual we find that the associated graphical object is +called @code{Fingering}, but how do we know if we should use +@code{Voice} or @code{Staff}? In many cases, @code{Voice} is a safe +bet, but you can also deduce this information from the internals +documentation: if you visit the documentation of @code{Fingering}, you +will notice +@example +Fingering grobs are created by: Fingering_engraver +@end example + +Clicking @code{Fingering_engraver} will show you the documentation of +the module responsible for interpreting the fingering instructions and +translating them to a @code{Fingering} object. Such a module is called +an @emph{engraver}. The documentation of the @code{Fingering_engraver} +says +@example +Fingering_engraver is part of contexts: Voice and TabVoice +@end example +so tuning the settings for Fingering should be done using either +@example + \property Voice.Fingering \set @dots{} +@end example +or +@example + \property TabVoice.Fingering \set @dots{} +@end example + +Since the @code{TabVoice} is only used for tab notation, we see that +the first guess @code{Voice} was indeed correct. + +@cindex setting object properties +@cindex @code{extra-offset} + +For shifting the fingering, we use the property @code{extra-offset}. +The following command manually adds an offset to the object. We move +it a little to the left, and 1.8 staff space downwards. +@example + \once \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) +@end example +The @code{extra-offset} is a low-level feature: it moves around +objects in the printout; the formatting engine is completely oblivious +to these offsets. The unit of these offsets are staff-spaces. The +first number controls left-right movement; a positive number will move +the object to the right. The second number controls up-down movement; +a positive number will move it higher. +We only want to offset a single object, so this statement is adorned +with @code{\once}. + +@cindex property types +@cindex translator properties +@cindex grob properties +@cindex music properties +@separate + +There are three different types of variables in LilyPond, something +which can be confusing at first (and for some people it stays +confusing). Variables such as @code{extra-offset} and +@code{attachment} are called grob properties. They are not the same +as translator properties, like @code{autoBeaming}. Finally, music +expressions are internally stored using properties (so-called music +properties). You will encounter music properties if you run Scheme +functions on music using @code{\apply}. + +The second fingering instruction should be moved up a little to avoid +a collision with the slur. This could be achieved with +@code{extra-offset}, but in this case, a simpler mechanism also +works. We insert an empty text between the 5 and the note. The empty +text pushes the fingering instruction away: +@example + a-)^" "^\markup @{ \finger "5" @} +@end example + +A fingering instruction, which would be entered as @code{^5}, is put +as close to the notes as possible, closer than the space entered to +push away the 5. Hence, the 5 is entered as a normal text, with the +formatting of fingering instructions. + +@separate + +Normally one would specify all dynamics in the same voice, so that +dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But +in this case, we do not want the decrescendo to be aligned with the +piano sign. We achieve this by putting the dynamic markings in different +voices. The crescendo should be above the upper staff. This can be +forced by using the precooked command +@example + \dynamicsUp +@end example + +However, if you do that the decrescendo will be too close to the upper +voice and collide with the stems. Looking at the manual for dynamics, +we notice that ``Vertical positioning of these symbols is handled by +the @internalsref{DynamicLineSpanner} grob.''. If we turn to the +documentation of @code{DynamicLineSpanner}, we find that +@code{DynamicLineSpanner} supports several so-called `interfaces'. +This object not only puts objects next to the staff +(@code{side-position-interface}), but it also groups dynamic objects +(@code{axis-group-interface}), is considered a dynamic sign itself +(@code{dynamic-interface}), and is an spanning object +(@code{spanner-interface}). It also has the standard +@code{grob-interface} with all the variables that come with it. + +For the moment we are interested in side positioning: +@quotation + side-position-interface + + Position a victim object (this one) next to other objects (the + support). In this case, the direction signifies where to put the + victim object relative to the support (left or right, up or down?) +@end quotation +Between the object and its support (in this case, the descending +notes), there should be more space. This space is controlled by +@code{padding}, so we increase it. +@example + \property Voice.DynamicLineSpanner \override #'padding = #5.0 +@end example + +This command resembles the one for setting slur attachments, but +subtly differs in its details. Grob properties can be manipulated +with two commands: @code{\override} extends the definition of a grob +with one setting, and @code{\revert} releases this setting. This has +a theoretical appeal: the operations are simple and symmetric. For +practical use, it can be cumbersome. The commands act like +parentheses: you should carefully balance the use of @code{\override} +and @code{\revert}. The @code{\set} command is more friendly: it +first does a @code{\revert} followed by @code{\override}. + +@separate + +Brahms uses music notation is a slightly unorthodox way. Ties +usually happen only within one voice. In this piece, the composer +gladly produces ties that jump voices. We deal with this by faking +these ties: whenever we need such a tie, we insert a notehead in a +different voice, and blank the stem. This is done in the following +snippet of code. + +@cindex transparent objects +@cindex removing objects +@cindex invisible objects +@example +\property Voice.Stem \set #'transparent = ##t +d' +@end example +Blanking the stem should be done for only one object. One of the ways +to achieve that, is by setting the property before a note. Reverting +it afterwards is tedious, so for setting a property only once, we have +the syntax @code{\once}: it reverts the property directly before +proceeding to the next step in time. + +The @code{\once} keyword is added to @code{\property}. + + +Finally, the last tie is forced up using @code{\tieUp}. + +@separate + +Here's the complete ``fine tuned'' version, which includes all the +modifications we discussed in this section: + +@lilypondfile[verbatim]{brahms-tweaked.ly} + + @node An orchestral score @section An orchestral score @@ -2191,22 +2077,24 @@ to the page layout of this document. @end menu -Our last two examples show a way to setup the music for an orchestral -score. When typesetting a piece for several instruments, you'll want to -create a conductor's full score, alongside several individual parts. +Our next two examples demonstrate one way to create an orchestral score +in LilyPond. When typesetting a piece for several instruments, you'll +want to create a full score (for the conductor) along with several +individual parts (for the players). -LilyPond is well suited for this task. We will declare the music for -each instrument individually, giving the music of each instrument its -own name. These pieces of music are then combined in different -@code{\score} blocks to produce different combinations of the score. + We will declare the music for each instrument individually, giving +the music of each instrument its own name. These pieces of music are +then combined in different @code{\score} blocks to produce different +combinations of instruments (for example, one @code{\score} block may +only include the cello part; another @code{\score} block may be for +all the strings, and yet another @code{\score} block may be for all +parts together). This orchestral score example consists of three input files. In the -first file, @file{os-music.ly}, we define the music for all instruments. -This file will be used both for producing the score and the separate -parts. - -If you were to run LilyPond on this file, no printable output would be -produced. +first file, @file{os-music.ly}, we define the music for all +instruments. This file will be used for producing the score and the +separate parts, but the file does not produce any sheet music itself. +Other files reference it by stating @code{\include "os-music.ly"}. @example % os-music.ly @@ -2245,92 +2133,91 @@ corno = \notes\relative c' @{ @} @end example -We will not go through the input line by line, but only indicate and -explain the new elements. +We will not examine this example line by line, since you already know +most of it. We'll examine a few lines which contain new elements. @separate @example global = @{ \time 2/4 - \skip 2*4 \bar "|."; + \skip 2*4 \bar "|." @} @end example -Declare setting to be used globally. The @code{\skip} command produces -no output, but moves forward in time: in this case, the duration of a -half note (@code{2}), and that four times (@code{*4}). This brings us -to the end of the piece, and we can set the end bar. +This declares settings to be used globally. The @code{\skip} command +produces no output, but moves forward in time: in this case, the +duration of a half note (@code{2}), and that four times (@code{*4}). +This brings us to the end of the piece, and we can set the end bar. +You can use @code{s} as a shortcut for @code{\skip} (the last line of +this section would be @code{s2*4 \bar"|."}). @separate @example Key = \notes \key as \major @end example -Declare the key signature of the piece and assign it to the identifier -@var{Key}. Later on, we'll use @code{\Key} for all staves except those -for transposing instruments. +This declares the key signature of the piece and assign it to the +identifier @var{Key}. Later on we will use @code{\Key} for all staves +except those for transposing instruments. @node The full score @subsection The full score -The second file, @file{os-score.ly} reads the definitions of the first -(@file{os-music.ly}), and defines the @code{\score} block for the full -conductor's score. - +The second file, @inputfileref{input/tutorial,os-score.ly}, reads the +definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and +defines the @code{\score} block for the full conductor's score. @example -% os-score.ly +\version "1.7.6" + \include "os-music.ly" \include "paper13.ly" -#(set! point-and-click line-column-location) -#(define text-flat '((font-relative-size . -2) - (music "accidentals--1"))) - +textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@} \score @{ < \global \property Score.BarNumber \override #'padding = #3 \context StaffGroup = woodwind < \context Staff = flauti < - \property Staff.midiInstrument = #"flute" - \property Staff.instrument = "2 Flauti" - \property Staff.instr = "Fl." + \property Staff.midiInstrument = #"flute" + \property Staff.instrument = "2 Flauti" + \property Staff.instr = "Fl." \Key - \context Voice=one @{ \voiceOne \flautoI @} - \context Voice=two @{ \voiceTwo \flautoII @} + \context Voice=one @{ \voiceOne \flautoI @} + \context Voice=two @{ \voiceTwo \flautoII @} > > \context StaffGroup = timpani < \context Staff = timpani < - \property Staff.midiInstrument = #"timpani" - \property Staff.instrument = #'(lines "Timpani" "(C-G)") - \property Staff.instr = #"Timp." - \clef bass + \property Staff.midiInstrument = #"timpani" + \property Staff.instrument = \markup @{ \column << "Timpani" "(C-G)" >> @} + \property Staff.instr = #"Timp." + \clef bass \Key - \timpani + \timpani > > \context StaffGroup = brass < \context Staff = trombe < \property Staff.midiInstrument = #"trumpet" - \property Staff.instrument = #`(lines "2 Trombe" "(C)") - \property Staff.instr = #`(lines "Tbe." "(C)") + \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @} + \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @} \Key - \context Voice=one \partcombine Voice - \context Thread=one \tromboI - \context Thread=two \tromboII + \context Voice=one \partcombine Voice + \context Thread=one \tromboI + \context Thread=two \tromboII > \context Staff = corni < \property Staff.midiInstrument = #"french horn" - \property Staff.instrument = #`(lines "Corno" - (columns "(E" ,text-flat ")")) - \property Staff.instr = #`(lines "Cor." - (columns "(E" ,text-flat ")")) - \property Staff.transposing = #3 - \notes \key bes \major - \context Voice=one \corno + \property Staff.instrument + = \markup @{ \column << "Corno" @{ "(E" \textFlat ")" @} >> @} + \property Staff.instr = + \markup @{ \column << "Cor." @{ "(E" \textFlat ")" @} >> @} + \property Staff.transposing = #3 + \notes \key bes \major + \context Voice=one \corno > > > @@ -2338,8 +2225,13 @@ conductor's score. indent = 15 * \staffspace linewidth = 60 * \staffspace textheight = 90 * \staffspace + \translator@{ + \VoiceContext + \consists "Multi_measure_rest_engraver" + @} \translator@{ \HaraKiriStaffContext + \remove "Multi_measure_rest_engraver" @} @} \midi @{ @@ -2364,16 +2256,29 @@ Opus 1. @example \include "os-music.ly" @end example -First, we need to include the music definitions we made in +First we need to include the music definitions we made in @file{os-music.ly}. +@ignore + +[TODO: mention in a more relevant place] + @separate @example -#(set! point-and-click line-column-location) +#(ly:set-point-and-click 'line-column) @end example -In a large orchestral score like this you're bound to make some small -mistakes, so we enable point and click (See @ref{Point and click}) -editing. + +This piece of Scheme code executes the function +@code{ly:set-point-and-click} with the argument +@code{line-column}. Editing input files can be complicated if you are +working with large files: if you are digitizing existing music, you have +to synchronize the .ly file, the sheet music on your lap and the sheet +music on the screen. The point-and-click mechanism makes it easy to +find the origin of an error in the LY file: when you view the file with +Xdvi and click on a note, your editor will jump to the spot where that +note was entered. For more information, see @ref{Point and click}. +@end ignore + @separate @example @@ -2381,11 +2286,11 @@ editing. (music "accidentals--1"))) @end example -When naming the tuning of the french horn, we'll need a piece of text -with a flat sign. LilyPond has a mechanism for font selection and +To name the transposition of the french horn, we will need a piece of +text with a flat sign. LilyPond has a mechanism for font selection and kerning called Scheme markup text (See @ref{Text markup}). The flat sign is taken from the music font, and its name is @code{accidentals--1} -(The sharp sign is called @code{accidentals-1}). The default font is +(The natural sign is called @code{accidentals-0}). The default font is too big for text, so we select a relative size of @code{-2}. @separate @@ -2393,29 +2298,33 @@ too big for text, so we select a relative size of @code{-2}. < \global @end example -Of course, all staves are simultaneous and use the same global settings. +All staves are simultaneous and use the same global settings. @separate @example \property Score.BarNumber \override #'padding = #3 @end example LilyPond prints bar numbers at the start of each line, but -unfortunately, they end up a bit too close to the staff in this example. -A bar number internally is a Grob called @var{BarNumber}. BarNumber -Grobs can be manipulated through their @var{side-position-interface}. One -of the properties of a @var{side-position-interface} that can be tweaked -is the @var{padding}: the amount of extra space that is put between this -Grob and other Grobs. We set the padding to three staff spaces. +unfortunately they end up a bit too close to the staff in this +example. In LilyPond, a bar number is called @var{BarNumber}. +BarNumber objects can be manipulated through their +@var{side-position-interface}. One of the properties of a +@var{side-position-interface} that can be tweaked is @var{padding}: +the amount of extra space that is put between this and other objects. +We set the padding to three staff spaces. You can find information on all these kind of properties in LilyPond's automatically generated documentation in @ifnottex -@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}. +@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals} +or in @ref{Fine tuning a piece}. @end ifnottex @iftex -the online documentation. +the online documentation or in the previous section of the tutorial. @end iftex +@c REFERENCE MAO + @separate @example \context StaffGroup = woodwind < @@ -2423,9 +2332,9 @@ the online documentation. @end example A new notation context: the @code{StaffGroup}. @code{StaffGroup} can hold one or more @code{Staff}'s, and will print a big bracket at the -left of the score. Start a new staff group for the woodwind section -(just the flutes in this case). Immediately after that, we start the -staff for the two flutes, that also play simultaneously. +left of the score. This starts a new staff group for the woodwind +section (just the flutes in this case). Immediately after that, we +start the staff for the two flutes, who also play simultaneously. @separate @example @@ -2439,9 +2348,9 @@ names}). \property Staff.instrument = "2 Flauti" \property Staff.instr = "Fl." @end example -And define the instrument names to be printed in the margin, -@code{instrument} for the first line of the score, @code{instr} for the -rest of the score. +This defines the instrument names to be printed in the +margin. @code{instrument} specifies the name for the first line +of the score, @code{instr} is used for the rest of the score. @separate @example @@ -2454,9 +2363,9 @@ The flutes play in the default key. \context Voice=one @{ \voiceOne \flautoI @} \context Voice=two @{ \voiceTwo \flautoII @} @end example -Last come the actual flute parts. Remember that we're still in +Last come the actual flute parts. Remember that we are still in simultaneous mode. We name both voices differently, so that LilyPond -will actually create two Voice contexts. The flute parts are simple, so +will create two Voice contexts. The flute parts are simple, so we specify manually which voice is which: @code{\voiceOne} forces the direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets directions down. @@ -2472,7 +2381,7 @@ Close the flutes staff and woodwind staff group. @example \property Staff.instrument = #'(lines "Timpani" "(C-G)") @end example -The timpani staff only shows a new piece of scheme markup, it sets two +The timpani staff demonstrates a new piece of scheme markup, it sets two lines of text. @separate @@ -2482,58 +2391,58 @@ lines of text. \context Thread=two \tromboII @end example You have seen the notation contexts Staff and Voice, but here's a new -one: Thread. One or more Threads can be part of a Voice. The Thread -takes care of note heads and rests, the Voice combine note heads onto a +one: Thread. One or more Threads can be part of a Voice. Thread +takes care of note heads and rests; Voice combine note heads onto a stem. For the trumpets we use the automatic part combiner (see @ref{Automatic part combining}) to combine the two simultaneous trumpet parts onto the trumpet staff. Each trumpet gets its own Thread context, which must be named @code{one} and @code{two}). The part combiner makes these two -threads share a Voice when they're similar, and splits the threads up -when they're different. +threads share a Voice when they are similar, and splits the threads up +when they are different. @separate @example - \property Staff.instrument = #`(lines "Corno" - (columns "(E" ,text-flat ")")) +\property Staff.instrument = #`(lines "Corno" + (columns "(E" ,text-flat ")")) @end example -The french horn has the most complex scheme markup name, made up of two -lines of text. The second line has three elements (columns), the @code{(E}, -the flat sign @code{text-flat} that we defined before and a final @code{")"}. -Note that we use a backquote instead of an ordinary quote at the -beginning of the Scheme expression to be able to access the -@code{text-flat} identifier, `unquoting' it with a @code{,}. +The french horn (``Corno'') has the most complex scheme markup name, made +up of two lines of text. The second line has three elements (columns) -- +the @code{(E}, the flat sign @code{text-flat} that we defined previously, +and a final @code{")"}. Note that we use a backquote instead of an +ordinary quote at the beginning of the Scheme expression to be able to +access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''. @separate @example \property Staff.transposing = #3 @end example -The french horn is to be tuned in E-flat, so we tell the MIDI backend to +The french horn is to be tuned in E-flat, so we tell the MIDI back-end to transpose this staff by three steps. -Note how we can choose different tuning for entering, printing and -playing, using @code{\transpose} and the MIDI Staff property -@var{transposing}. +Note how we can choose different tunings for the text input, sheet music +output and, and MIDI output, using @code{\transpose} and the MIDI Staff +property @var{transposing}. @separate @example \notes \key bes \major @end example -Therefore, it has a different key. +Since the horn is transposing, it is in a different key. @separate @example indent = 15 * \staffspace - linewidth = 60 * \staffspace + linewidth = 55 * \staffspace @end example We specify a big indent for the first line and a small linewidth for this tutorial. @separate -Usually, LilyPond's predefined setup of notation contexts (Thread, -Voice, Staff, Staffgroup, Score) is just fine. But in this case, we +Usually LilyPond's default setup of notation contexts (Thread, +Voice, Staff, Staffgroup, Score) is just fine. But in this case we want a different type of Staff context. @example @@ -2542,10 +2451,13 @@ want a different type of Staff context. @} @end example -In orchestral scores, it often happens that one instrument has only -rests during one line of the score. The @code{HaraKiriStaffContext} can +In orchestral scores it often happens that one instrument only has +rests during one line of the score. @code{HaraKiriStaffContext} can be used as a regular @code{StaffContext} drop-in and will take care of -the automatic removing of empty staves. +the automatic removing of empty staves -- so if the strings are the +only instruments playing for a line, LilyPond will only print the string +parts for that line of the score. This reduces the number of page turns +(and the number of dead trees!) required in a score. @node Extracting an individual part @subsection Extracting an individual part @@ -2594,15 +2506,16 @@ Opus 1. Because we separated the music definitions from the @code{\score} instantiations, we can easily define a second score with the music of -the second flute. This then is the part for the second flute player. -Of course, we make separate parts for all individual instruments. +the second flute. This is the part for the second flute player. Of +course, we would make separate parts for all individual instruments if +we were preparing the score for an orchestra. @separate @example \flautoII @end example In this individual part the second flute has a whole staff for itself, -so we don't want to force stem or tie directions. +so we do not want to force stem or tie directions. @separate @example @@ -2618,63 +2531,30 @@ but we need to set the instrument for this particular score. \property Score.skipBars = ##t @end example In the conductor's full score, all bars with rests are printed, but for -the individual parts, we want to contract pieces of consecutive empty -bars. LilyPond will do this if Score's @var{skipBars} property to -true. - - -@node Other ways to run LilyPond -@section Other ways to run LilyPond - -Until now, you have been using @file{ly2dvi} to invoke LilyPond. -There are three other routes. Firstly, there is a script called -@code{lilypond-book}, that allows you to freely mix LilyPond input with -Texinfo or \LaTeX input. For example, this manual was written using -@code{lilypond-book}. It is discussed below and in @ref{lilypond-book}. - - -Secondly, you can generate PostScript directly. This is useful if you -can not or do not want to run @TeX{} on your system. To obtain direct -PostScript output, invoke LilyPond as follows: -@cindex PostScript output -@example -lilypond -f ps test.ly -@end example -You have to set some environment variables to view or print this output. -More information can be found in @ref{Invoking LilyPond}. Since the -direct Postscript generation has some problems, it is recommended -to use @file{ly2dvi}. - - -Thirdly, if you want to do special things with your output, you can run -invoke LilyPond directly: -@example -lilypond test.ly -@end example -to produce plain @TeX{} output. Note that La@TeX{} will not work on the -resulting @file{test.tex}. You must run plain @TeX{} on it. - -@cindex @TeX{} - - - +the individual parts, we want to print one multimeasure rest instead of +many consecutive empty bars. LilyPond will do this if +@code{Score.skipBars} is set to true (@code{##t}). @node Integrating text and music @section Integrating text and music -Sometimes, you might want to use music examples in a text that you are -writing. For example, if you are writing a musicological treatise, a -songbook, or (like us) the LilyPond manual. You can make such texts by -hand, simply by importing a PostScript figure into your wordprocessor. -However, there is a also an automated procedure: -If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A -script called @code{lilypond-book} will extract the music fragments, run -LilyPond on them, and put back the resulting notation. lilypond-book is -described fully in @ref{lilypond-book}, but here we show a small -example. Since the example also contains explanatory text, we won't -comment on the contents. +@cindex La@TeX{}, music in +@cindex HTML, music in +@cindex Texinfo, music in + +Sometimes you might want to use music examples in a text that you are +writing (for example a musicological treatise, a songbook, or (like us) +the LilyPond manual). You can make such texts by hand, simply by +importing a PostScript figure into your word processor. However, +there is an automated procedure to reduce the amount of work. + +If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond +code. A script called @code{lilypond-book} will extract the music +fragments, run LilyPond on them, and put back the resulting notation. +This program is fully described in @ref{lilypond-book manual}. Here we show a small example. Since the example +also contains explanatory text, we will not comment it further. @example \documentclass[a4paper]@{article@} @@ -2687,6 +2567,7 @@ example: c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4 @} @} \end@{lilypond@} + Notice that the music line length matches the margin settings of the document. @@ -2697,7 +2578,7 @@ If you have no \verb+\score+ block in the fragment, c'4 \end@{lilypond@} -In the example you see here, a number of things happened: a +In the example you see here, two things happened: a \verb+\score+ block was added, and the line width was set to natural length. You can specify many more options using \LaTeX style options in brackets: @@ -2707,14 +2588,14 @@ in brackets: c'4 f bes es \end@{lilypond@} -\texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects -the default music size, \texttt@{fragment@} adds a score block, -\texttt@{relative@} uses relative mode for the fragment, and -\texttt@{intertext@} specifies what to print between the -\texttt@{verbatim@} code and the music. +The option \texttt@{verbatim@} prints the LilyPond code in addition to +the graphical score, \texttt@{11pt@} selects the default music size, +\texttt@{fragment@} adds a score block, \texttt@{relative@} uses +relative mode for the fragment, and \texttt@{intertext@} specifies +what to print between the \texttt@{verbatim@} code and the music. -If you include large examples into the text, it may be more convenient -to put the example in a separate file: +If you want to include large examples into the text, it may be more +convenient to put the example in a separate file: \lilypondfile[printfilename]@{sammartini.ly@} @@ -2726,11 +2607,11 @@ The \texttt@{printfilename@} option adds the file name to the output. Under Unix, you can view the results as follows. @example $ cd input/tutorial +$ mkdir -p out/ $ lilypond-book --outdir=out/ lilbook.tex -lilypond-book (GNU LilyPond) 1.3.146 -Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex' -Reading -`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly' +lilypond-book (GNU LilyPond) 1.7.16 +Reading `input/tutorial/lilbook.tex' +Reading `input/tutorial/sammartini.ly' @var{lots of stuff deleted} Writing `out/lilbook.latex' $ cd out @@ -2740,21 +2621,27 @@ $ xdvi lilbook @end example Notice the @code{outdir} option to lilypond-book. Running lilypond-book -and running latex creates a lot of temporary files, and you wouldn't want +and running latex creates a lot of temporary files, and you would not want those to clutter up your working directory. Hence, we have them created in a separate subdirectory. -The result more or less looks like this: +The result looks more or less like this: @separate In a lilypond-book document, you can freely mix music and text. For example: @lilypond - \score { \notes \relative c' { - c2 g'2 \times 2/3 { f8 e d } c'2 g4 - } } +\score { + \notes \relative c' { + c2 g'2 \times 2/3 { f8 e d } c'2 g4 + } + \paper { + raggedright = ##t + } +} @end lilypond + Notice that the music line length matches the margin settings of the document. @@ -2775,7 +2662,7 @@ in brackets: c'4 f bes es @end lilypond -@code{verbatim} also shows the LilyPond code, @code{11pt} selects +The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects the default music size, @code{fragment} adds a score block, @code{relative} uses relative mode for the fragment, and @code{intertext} specifies what to print between the @@ -2787,62 +2674,5 @@ to put the example in a separate file: @lilypondfile[printfilename]{sammartini.ly} The @code{printfilename} option adds the file name to the output. -@node End of tutorial -@section End of tutorial - -That's all folks. From here, you can either try fiddling with input -files, or you can read the reference manual. You can find more example -files in @file{input} and @file{input/test}. You can also look at some -real music. The website @uref{http://www.mutopiaproject.org} has many -examples of real music typeset by LilyPond. - - - -@ignore - -[TODO - -this should be on mutopia website. - -] - - -@c waar deze info? is uiteindelijk wel handig, schat ik. -[TODO: cut blabla] - -If you have a big music project, or just a lot of LilyPond input files, -all generated output from LilyPond, @TeX{} and metafont will clutter -your working directory. LilyPond comes with a one-size-fits-all -pre-cooked makefile that helps you manage producing output. It will -produce all output in the directory @file{out} , generate and track -dependencies. Also, it helps in preparing your submission to @ref{Mutopia -project}. - -@file{make/ly.make} -@example -mkdir my-project -cd my-project -cp /usr/share/lilypond/make/ly.make GNUmakefile -cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly . -make minuet -[..] -Generated out/minuet.ps for target minuet. -@end example - -Type @samp{make help} to see possible targets. - -[TODO] -@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly} - - - - - -[TODO: rewrite completely.] - -@menu -* Songs with additional verses:: -@end menu - -@end ignore +[TODO: include excercises? ]