X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=5ab44df9fb8fa5cc1ac12439bf5da15929514d65;hb=74974cbb8d12ae3a8994b80f2c4d70a87d406474;hp=c4690beb7a505b604991c67785de5482aa60df6c;hpb=d9b43b93f2c885409bafdb157138158f65cc49aa;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index c4690beb7a..5ab44df9fb 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -11,64 +11,50 @@ @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, that +file is read, and after some computations, the program produces a file +containing the 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? +Some of the examples discussed are included as separate files in the +distribution, in the subdirectory @file{input/tutorial/} of the source +package. @node First steps @section First steps -@c @node Music language of LilyPond -@c @section Music language of LilyPond - -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. +In this section, we show how to make small, very simple pieces of +music in LilyPond. If you have not seen LilyPond input files before, +this section is for you. You get a simple note by typing its note name, from @code{a} through -@code{g}: - +@code{g}. So if you enter @quotation @example c d e f g a b @end example - +@end quotation +then the result looks like this: +@quotation @lilypond[fragment] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff @@ -77,6 +63,9 @@ c d e f g a b @end quotation @separate +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, ``@code{1}'' for a whole note, ``@code{2}'' for a half note, and so on: @@ -90,7 +79,7 @@ a1 a2 a4 a16 a32 @lilypond[fragment] \property Score.timing = ##f \property Staff.TimeSignature = \turnOff -\property Staff.noAutoBeaming = ##t +\property Staff.autoBeaming = ##f %\property Staff.Clef = \turnOff \transpose c'' { a1 a2 a4 a16 a32 } s16_" " @@ -98,11 +87,10 @@ s16_" " @end quotation @separate -If you don't specify a duration, the previous duration is used: - +If you don't specify a 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, @@ -144,7 +132,7 @@ a2. a4 a8. a16 @c as these are snippets anyway @lilypond[fragment] \property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +\property Staff.TimeSignature \set #'transparent = ##t %\property Staff.Clef = \turnOff \transpose c'' { a2. a4 a8. a16 } s16_" " @@ -152,7 +140,7 @@ s16_" " @end quotation @separate -The meter (or time signature) can be set with the ``@code{\time}'' command: +The meter (or time signature) can be set with the @code{\time} command: @quotation @example @@ -163,7 +151,7 @@ The meter (or time signature) can be set with the ``@code{\time}'' command: @c a clef here may lead to confusion @lilypond[fragment] -\property Staff.Clef = \turnOff +\property Staff.Clef \set #'transparent = ##t \time 3/4 s4_" " \time 6/8 @@ -220,9 +208,9 @@ LilyPond then knows that music follows (and not lyrics, for example): At this point, the piece of music is ready to be printed. This is done by combining 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 +The printing command is the so-called ``@code{\paper}'' block. You +will see later that the @code{\paper} block is necessary 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: @@ -254,11 +242,192 @@ LilyPond source file looks like: @separate -We continue with the introduction of the remaining musical constructs. +@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 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) + +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 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.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 or Cygwin +icon. Notepad is sufficient for editing the LilyPond file. Viewing +the PS file can be done with: +@quotation +@example +@code{gsview32 test.ps} +@end example +@end quotation +You can also print from the command line by executing: +@quotation +@example +@code{gsview32 /s test.ps} +@end example +@end quotation + + +@strong{SUMMARY} + +To run LilyPond, enter a file, and 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[fragment, relative 1] +\property Staff.TimeSignature = \turnOff +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +c1 c2 c8 c16 +@end lilypond + +@item @code{. ..} +@tab augmentation dots +@tab +@lilypond[fragment, relative 1] +\property Staff.TimeSignature = \turnOff +\property Staff.Clef = \turnOff +c4. c4.. +@end lilypond + +@item @code{c d e f g a b } +@tab scale +@tab +@lilypond[fragment, relative 1] +\property Staff.TimeSignature = \turnOff +\property Staff.Clef = \turnOff +c d e f g a b +@end lilypond + +@item @code{\clef treble \clef bass } +@tab clefs +@tab +@lilypond[fragment] +\property Staff.TimeSignature \set #'transparent = ##t +\clef treble +s4_" " +\clef bass +s4_" " +@end lilypond + +@item @code{\time 3/4 \time 4/4 } +@tab time signature +@tab +@lilypond[fragment] +\property Staff.Clef \set #'transparent = ##t +\time 3/4 +s4_" " +\time 4/4 +s16_" " +@end lilypond + +@end multitable -@c maybe legend here? -Rests are entered just like notes with the name ``@code{r}'': +@node More basics +@section More basics + +We continue with the introduction of the remaining musical constructs. +Normal rests are entered just like notes, but use the name +``@code{r}'': @quotation @example @@ -331,15 +500,14 @@ 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'' ~ @@ -366,33 +534,25 @@ 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) don't 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 doesn't 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, +register needs lots of quotes. This makes the input less readable, 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. +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 type +no octavation 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 For example: @code{c f} goes up; @code{c g} goes down: @@ -416,7 +576,7 @@ For example: @code{c f} goes up; @code{c g} goes down: @c needed better, maybe even redundant explanation @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 a large interval 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 @@ -440,6 +600,73 @@ For example: @code{c f,} goes down; @code{f, f} are both the same; @end quotation @separate + +@strong{SUMMARY} + +The following table summarizes the syntax learned in this section. + +@multitable @columnfractions .3 .3 .4 + +@item @b{Syntax} +@tab @b{Description} +@tab @b{Example} + +@item @code{r4 r8} +@tab rest +@tab +@lilypond[fragment, relative 1] +\property Staff.TimeSignature = \turnOff +\property Staff.Clef = \turnOff +r4 r8 +@end lilypond + + +@item @code{~} +@tab tie +@tab +@lilypond[fragment, relative 1] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +d ~ d +@end lilypond + + +@item @code{\key es \major } +@tab key signature +@tab +@lilypond[fragment] +\property Staff.TimeSignature \set #'transparent = ##t +\clef treble +\key es \major +s4 +@end lilypond + +@item @code{'} +@tab raise octave +@tab +@lilypond[fragment, relative 1] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +\property Staff.autoBeaming = ##f +\property Staff.Clef = \turnOff +a a' +@end lilypond + +@item @code{,} +@tab lower octave +@tab +@lilypond[fragment, relative 1] +\property Score.timing = ##f +\property Staff.TimeSignature = \turnOff +\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: @@ -456,6 +683,13 @@ 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 doesn't +@c have a phrasing slur. The problem is that we don't want the slur +@c and the Phrasing slur to collide. We're trying to make a good +@c impression here. + @quotation @lilypond[fragment,relative 1, verbatim] a8(\( ais b ) c cis2 b'2 a4 cis, \) c @@ -488,15 +722,15 @@ 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 doesn't matter what names you give, as long +as each staff has a unique name. @separate We can typeset a melody with two staves now: @quotation -@lilypond[verbatim] +@lilypond[verbatim,singleline] \score { \notes < \context Staff = staffA { @@ -563,162 +797,137 @@ 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: +beam and tie markings must be placed outside the chord markers: @quotation @lilypond[relative 0, fragment,verbatim] r4 [ ] ~ @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{< >}: +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{< >}: + @quotation -@lilypond[relative 0, fragment,verbatim] +@example +r4 ( > < ) \! c8 f a> +@end example +@lilypond[relative 0, fragment] +\slurUp r4 ( > < ) \! c8 f a> @end lilypond @end quotation @separate -A nasty technical detail also crops up when you start a score with a -chord: - +There is one golden rule that you should keep in mind when writing +LilyPond input: +@quotation +@strong{DO NOT START A PIECE WITH A CHORD} +@end quotation +Of course, it is a allowed, but the result might not be what you expect: @quotation @lilypond[verbatim,singleline] -\score { \notes } +\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: +If you have a piece that starts with a chord, then you must explicitly +state that the notes of the chord are to be put on the same staff, in +the same voice. This is done by specifying @code{\context Staff} for +the notes: @quotation @lilypond[verbatim,singleline] -\score { \notes \context Staff } +\score { \notes \context Voice } @end lilypond @end quotation @separate +@strong{SUMMARY} -@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 - - -@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? +@multitable @columnfractions .3 .3 .4 +@item @b{Syntax} +@tab @b{Description} +@tab @b{Example} -@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 @@ -729,473 +938,165 @@ 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 @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}.@footnote{ You can also view -DVI files with @code{yap test.dvi}, but unfortunately the postscript -interaction seems broken, meaning that you will not see slurs or beams -in the Yap window.} You can also print from the command line by -executing @code{gsview32 /s test.ps} +@item @code{< >} +@tab chord +@tab +@lilypond[fragment, relative 1] +\context Voice +@end lilypond +@end multitable +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. -@node The first real tune -@section The first real tune +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, dealing with more advanced topics such as +lyrics, chords, orchestral scores and parts, fine tuning 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 -@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. | - } +@node Printing lyrics +@section Printing lyrics +@cindex lyrics - 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 { linewidth = -1. } } @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 +To print lyrics, you must enter them, and then instruct lilypond to +handle the lyrics by printing them. +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}. +The purpose of this mode is that you can enter lyrics as plain text, +punctuation and accents without any hassle. - \relative c'' - -@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. +Syllables are entered like notes, with pitches replaced by text. For +example, @code{Twin- kle twin- kle} enters four syllables. Note that +the hyphen has no special meaning for lyrics, and does not introduce +special symbols. -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. +Spaces can be introduced into a lyric either by using quotes: +@code{"He could"4 not4} or by using an underscore without quotes: +@code{He_could4 not4}. All unquoted underscores are converted to +spaces. -Because the first note has no predecessor, -you have to give the (absolute) pitch of the note to start with. -@separate -@example +These are the lyrics for the free software song: - \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 +As you can see, extender lines are entered as @code{__}. This will +create an extender, 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{a8 b8} -@separate -@example - - d4 g, g | - +If you can use have 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 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] +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 +syllables. It will be centered between the syllables. -@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 +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. - g2. | - +When LilyPond interprets music, it will create a Staff context. +We don't want that default here, because we want lyric. The +command +@example + \context Lyrics @end example -@cindex augmentation dot -@cindex dotted note -A period adds a dot to the note. -@separate -@example +explicitly creates an interpretation context of +@code{Lyrics} type to interpret the song text that we entered. - @} - -@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 - - a8-. b-. cis-. d-. e-. fis-. - +The melody of the song doesn't offer anything new: +@example + \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 @} @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 +Both 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 +\addlyrics + \notes \relative c' @dots{} + \context Lyrics \lyrics @dots{} +@end example - @} - -@end example -The last brace ends the @code{\score} block. +The lyrics are also music expressions, similar to notes. What happens +here, is that each syllable of the lyrics is put under the a note of +the melody. +The complete file is listed here: +@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; @} +@} +\paper @{ linewidth = -1. @} +@} +@end example -@node Lyrics and chords -@section Lyrics and chords +@node A melody with chords +@section A melody with chords -In this section we show how to typeset a song. This file is -included as @file{flowing.ly}. +In this section we show how to typeset a melody with chord +accompaniment. This file is included as @file{flowing.ly}. @example -\header @{ - title = "The river is flowing" - composer = "Traditional" -@} \include "paper16.ly" melody = \notes \relative c' @{ \partial 8 @@ -1206,11 +1107,6 @@ melody = \notes \relative c' @{ \bar "|." @} -text = \lyrics @{ - The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the - ri -- ver is flo -- wing down to the sea. -@} - accompaniment =\chords @{ r8 c2:3- f:3-.7 d:min es4 c8:min r8 @@ -1220,14 +1116,10 @@ accompaniment =\chords @{ \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 @} @@ -1235,18 +1127,9 @@ accompaniment =\chords @{ @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 +The result would look this. @lilypond[center] -\header { - title = "The river is flowing" - composer = "Traditional" -} \include "paper16.ly" melody = \notes \relative c' { \partial 8 @@ -1257,11 +1140,6 @@ melody = \notes \relative c' { \bar "|." } -text = \lyrics { - The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the - ri -- ver is flo -- wing down to the sea. -} - accompaniment =\chords { r8 c2:3- f:3-.7 d:min es4 c8:min r8 @@ -1272,13 +1150,10 @@ accompaniment =\chords { %\accompaniment \context ChordNames \accompaniment - \addlyrics \context Staff = mel { - \property Staff.noAutoBeaming = ##t - \property Staff.automaticMelismata = ##t - \melody + \property Staff.autoBeaming = ##f + \melody } - \context Lyrics \text } \midi { \tempo 4=72 } \paper { linewidth = 10.0\cm } @@ -1286,30 +1161,7 @@ accompaniment =\chords { @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 @@ -1372,26 +1224,7 @@ 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 - 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 @@ -1414,17 +1247,22 @@ 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 half a note. Chord are entered by +entering the tonic. Then notes can be changed. In this case, a small third +is used. The cod 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 @@ -1433,7 +1271,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 @@ -1490,30 +1327,14 @@ 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. +When LilyPond interprets music, it will create a Staff context. If +the @code{%} sign in the previous line were removed, you could 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 - -@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. @separate @example @@ -1521,57 +1342,27 @@ silly. @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. +We place the melody on a staff called @code{mel}. We give it a name to +differentiate it from the one that would contain note heads for the +chords, if you would remove the comment before the ``note heads'' +version of the accompaniment. By giving this staff a name, it is +forced to be different. @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 +its behavior. One of the variables is @code{autoBeaming}. Setting +this @code{Staff}'s property to @code{##f}, which is the boolean value +@var{false}, 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. - - -@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 @@ -1583,16 +1374,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 @@ -1619,51 +1401,73 @@ also specifies an output method. You can specify the tempo using the We also want notation output. The linewidth is short so 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" -@} - -#(set! point-and-click line-column-location) +\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 -\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. Notice how 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 + +LilyPond only handles formatting sheet music. It doesn't concern +itself with producing titles. This is the jobs of a simple wrapper +program called ly2dvi. @code{ly2dvi} calls LilyPond to do the +sheet music formatting. Then it produces titles, and ties together all +inputs into a single @file{dvi} file. In this section, we show some of +the options for titling. We will show how you can produce a file +that looks like this: @center @strong{Two miniatures} @flushright @@ -1691,83 +1495,93 @@ 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.60" +\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 @{ linewidth = -1.0 @} -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" +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 -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) + +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 the output. @file{ly2dvi} 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 -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). +When you process a file with ly2dvi, a signature line is printed at +the bottom of the last page. This signature is produced from the +@code{tagline} field of @code{\header}. The default "Lily was here, +@var{version number}" is convenient for us programmers. Archived +the layout of different versions can be compared using archived +print-outs (that include a version number). -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}. +Many people find the default tagline too droll. If that is the case, +assign something else to @code{tagline}, as shown above. @separate @example \paper @{ + linewidth = -1.0 @} @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 don't have +@code{\paper} sections, so the settings of this block are substituted: + +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. -@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 @@ -1811,112 +1625,58 @@ will be at the left. -@node A piano excerpt -@section A piano excerpt +@example +\version "1.5.60" +\header @{ + title = "Two miniatures" + composer = "F. Bar Baz" + tagline = "small is beautiful" @} -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}. +\paper @{ linewidth = -1.0 @} -@lilypond[verbatim] -\include "paper16.ly" +\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 -stemDown = \property Voice.Stem \override #'direction = #-1 -stemUp = \property Voice.Stem \override #'direction = #1 -stemBoth = \property Voice.Stem \revert #'direction -viola = \notes \relative c' \context Voice = viola { - - \stemDown g'8. b,16 - s1 s2. r4 - g -} +@separate +@example +\version "1.6.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. This version number is also +used by the @code{convert-ly} program (See @ref{Older +LilyPond versions}), which is used to update the file to the latest +lily version. -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>] -} -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 } > -} +@node A piano excerpt +@section A piano excerpt -\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 +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}. -If this looks like incomprehensible gibberish to you, you are right. -This example has been doctored to have as many quirks as possible. +@lilypondfile[verbatim]{sammartini.ly} 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. -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 - -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. - -@separate -@example - \property Voice.Stem \revert #'direction -@end example - -Revert the to the previous setting. The effect of precisely one -@code{\stemDown} or @code{\stemUp} is neutralized. - - 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 @@ -1936,30 +1696,28 @@ precisely one @code{Voice} context, so we give it a unique name @separate @example - + @end example The delimiters @code{<} and @code{>} are shorthands for @code{\simultaneous @{} and @code{@}}. The expression enclosed in @code{<} and @code{>} is a 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 + \voiceTwo @end example +We want the viola to have stems down, and have all the other +characteristics of a second voice. This is enforced using the +@code{\voiceTwo} command: it inserts instructions that makes stem, +ties, slurs, etc. go down. + + @separate @example @@ -1989,25 +1747,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. +\voiceOne s4 g8. b,16 c8 r +@end example + +The oboes should have stems up, so they should have stems up, to keep +them from interfering with the staff-jumping bass figure. + @separate @example -\grace < d4 f> +\grace < d4 )f> @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 @@ -2020,16 +1776,10 @@ 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 -@{ @} +@{ @} @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 @@ -2041,41 +1791,18 @@ 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 @@ -2083,7 +1810,7 @@ the @code{f}. @separate @example - f8 e e2 + f,8 e e2 @} > @end example This ends the two-part section. @@ -2119,24 +1846,36 @@ 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 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. +@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 stem directions explicitly (using the +identifiers @code{\stemUp} and @code{\stemDown}. + @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 @@ -2187,6 +1926,281 @@ 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). +@cindex Brahms, Johannes + +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 @code{\<} +@cindex @code{\!} + +The crescendo is ended at the half note by the escaped exclamation +mark @code{\!}. + +Hairpin dynamics can be indicated using @code{\>} to start a +decrescendo, and @code{\!} to end one. The crescendo is started using +@code{\<} and also ended using @code{\!}. Absolute dynamics can be +entered using @code{\p}, @code{\mf}, etc. All these commands apply to +the complete chord where they are entered, but for syntactical +reasons, they must be attached to one of the notes of the chord. + +@cindex fingering instructions + +Fingering indications are entered simply using @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 we get something that resembles the original printed +edition by Schott/Universal Edition: + +@lilypondfile{brahms-tweaked.ly} + +@cindex tuning grob behavior + +The basic process that we follow is that we override defaults in the +printing system. We do this by setting variables in so-called grobs. +Printed symbols are internally represented by Graphical Objects +(Grobs). Each grob is described by a bunch of settings. Every +setting is a variable: it has a name, and you can assign a value to +the variable. 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}. + +@cindex slur attachments + +We start with the slur: the slur in the upper part, running from the F +sharp to the A, runs from stem to stem in the printed edition, while +ours starts from the note head at the left. The following property +setting forces all slurs to run from stem to stem (and not from or to +note head) + +@example + \property Voice.Slur \set #'attachment = #'(stem . stem) +@end example + +More precisely, this command extends 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)}. + +Although this is useful information, it is not very helpful: the +lilypond backend supports approximately 240 variables like +@code{attachment}, each with their own meaning and own type +(eg. number, symbol, list, etc). Besides slur, LilyPond has 80 +different types of Grobs, that may be created in 14 different context +types besides Voice. + +@cindex internal documentation +@cindex finding grobs +@cindex grob descriptiosn + +The interesting information is how you can 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 run a binary distribution@footnote{You can also +compile them by executing @code{make -C Documentation/user/ +out/lilypond-internals.html} in the source package.}. This document is +also available on the web: go to the lilypond website, click +``Documentation: other'' on the side bar, click +``lilypond-internals'', under information for users. + +You might want to bookmark either the HTML files on disk, or the one +on the web. One word of caution is in place here: the internals +documentation is generated from the definitions that lily uses. For +that reason, it is strongly tied to the version of LilyPond that you +use. Before you proceed, please make sure that you are using the +documentation that corresponds to the LilyPond version that you use. + +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 grob 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 +must 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 + +If you ran the previous example, you have unknowingly already used +this kind of command. The @file{ly/property-init.ly} contains the +definition of @code{\stemUp} +@example + stemUp = \property Voice.Stem \set #'direction = #1 +@end example + + +We also want to move around the fingering `3'. In the printed edition +it is not above the stem, but a little lower, slightly left of the +stem. From the user manual, we find that the associated grob 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} grob. 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 grob properties +@cindex @code{extra-offset} + +For shifting the fingering, we use the grob 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 + \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. + +@cindex reverting grob properties +@cindex undoing grob properties + +We only want to offset a single grob, so after the F-sharp, we must +undo the setting. The technical term is to revert the grob property. +@example + \property Voice.Fingering \revert #'extra-offset +@end example + +@cindex property types +@cindex translator properties +@cindex grob properties +@cindex music properties + + +There is three different types of variables in LilyPond, something +which is confusing at first (and for some, it stays like that). +Variables such as @code{extra-offset} and @code{attachment} are called +grob properties. They are something different from the translator +properties, like @code{autoBeaming}. Finally, music expressions are +internally also stored using properties, so-called music +properties. You will encounter the latter type 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^" "^#'(finger "5") +@end example + +Lilypond tries to put fingering instructions closer to the notes as +text instructions. To insert an empty text (@code{^" "}) between the +finger and the note, we have disguised the fingering instruction as a +text: @code{(finger "5")}. + +Normally, one would specify dynamics in a single voice, and start and +end dynamics (such as @b{f} and @b{p}) will be aligned with +hairpins. In this case, we want the decrescendo to be in a different +place from 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 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 the +@code{DynamicLineSpanner} supports several so-called +`interfaces'. This grob not only puts dynamic 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 a grob: it has the +@code{grob-interface}, with all the variables that come with it. + +For the moment, we are interested in the 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 grob and its support (in this case: the notes in the voice +going down), 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 is almost like the command for setting slur attachments, +but subtly different in its details. Grob properties can be +manipulated with two commands: @code{\override} extends the grob +variables with a setting, and @code{\revert} releases this +setting. This has a certain theoretical appeal: the operations are +simple and symmetric. For practical use, it can be cumbersome. Both +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}. + +Finally, 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. + +@example + \property Voice.Stem \set #'transparent = ##t + d' + \property Voice.Stem \revert #'transparent +@end example + +Finally, the last tie is forced up using @code{\tieUp}. + + @node An orchestral score @section An orchestral score @@ -2206,9 +2220,10 @@ own name. These pieces of music are then combined in different @code{\score} blocks to produce different combinations of the score. 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. +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. Other files reference this file by doing +@code{\include "os-music.ly"}. If you were to run LilyPond on this file, no printable output would be produced. @@ -2376,9 +2391,19 @@ First, we need to include the music definitions we made in @example #(set! point-and-click line-column-location) @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 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 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}. + @separate @example @@ -2405,12 +2430,13 @@ Of course, all staves are simultaneous and use the same global settings. \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. 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. You can find information on all these kind of properties in LilyPond's automatically generated documentation in @@ -2628,43 +2654,6 @@ 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{} - - - - - @node Integrating text and music @section Integrating text and music @@ -2674,12 +2663,13 @@ 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. +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 utility program is described fully in the chapter @ref{Merging text +and music with lilypond-book}. Here we show a small example. Since the +example also contains explanatory text, we won't comment on the +contents. @example \documentclass[a4paper]@{article@} @@ -2733,9 +2723,8 @@ Under Unix, you can view the results as follows. $ cd input/tutorial $ 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' +Reading `input/tutorial/lilbook.tex' +Reading `input/tutorial/sammartini.ly' @var{lots of stuff deleted} Writing `out/lilbook.latex' $ cd out