X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=1a93fe25526a3f5c6f6b00bc92cdb3a8ddd7daff;hb=8144751cb757612145b419a3ef53c972c1703747;hp=c9649192105be0454399aef07de93d30e1d7dda3;hpb=bf2d12a41b68f23d2122a805908e8dfd5d8f959b;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index c964919210..1a93fe2552 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,135 +1,139 @@ @c -*-texinfo-*- +@c This file is part of lilypond.tely @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? +@c * where to go from First steps+More basics? + +@c Your first LilyPond score in 10 minutes? @node Tutorial @chapter Tutorial -@html - -@end html +This tutorial starts with a short introduction to the LilyPond music +language. After this first contact we will show you how to produce +printed output. Then you will be able to create and print your own +sheets of music. + +@ifhtml +Many people learn programs by trying and fiddling around with the +program. This is also possible with LilyPond. If you click on a +picture in the HTML version of this manual, you will see the exact +LilyPond input that was used to generate that image. +Try it on this image + +@lilypond[fragment,quote,raggedright,relative=2] +c-\markup { \bold \huge { Click here. } } +@end lilypond +@end ifhtml + +By cutting and pasting the full input into a test file, you have a +starting template for experiments. If you like learning in this way, +you will probably want to print out or bookmark +@ifhtml +the +@end ifhtml +@ref{Cheat sheet}, which is a table listing all commands for quick +reference. @menu -* First steps:: Music language of LilyPond -* Running LilyPond:: Printing music -* More basics:: +* First steps:: +* Running LilyPond:: +* More about pitches:: +* Entering ties:: +* Automatic and manual beams:: +* Octave entry:: +* Music expressions explained:: +* More staves:: +* Adding articulation marks to notes:: +* Combining notes into chords:: +* Basic rhythmical commands:: +* Commenting input files:: * Printing lyrics:: * A lead sheet:: * Listening to output:: -* Titling :: -* Single staff polyphony :: -* Piano staffs:: -* Setting variables:: -* Fine tuning layout:: -* Organising larger pieces:: +* Adding titles:: +* Single staff polyphony:: +* Piano staves:: +* Organizing larger pieces:: * An orchestral part:: -* Integrating text and music:: Integrating text and music +* Integrating text and music:: @end menu -Operating is done through text files: To print a piece of music, you -enter the music in a file. When LilyPond is run (normally using the -program @code{ly2dvi}) on that file, another file containing formatted -sheet music, is produced. That file may be printed or viewed. - -This tutorial starts with a small introduction to the LilyPond music -language. After this first contact, we will show which commands to -run to produce printed output, so you should then be able to create -your first sheets of music. When starting out, it will be convenient -to print out -@ifhtml -the -@end ifhtml -@ref{Cheat sheet}, which is a table listing all commands for -convenient reference. - - @node First steps @section First steps -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 +The first example demonstrates how to enter the most elementary piece +of music, a scale. A note can be entered by typing its name, from +@samp{a} through @samp{g}. So, if you enter @example c d e f g a b @end example @noindent -then the result looks like this: +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] +@lilypond[fragment,quote,notime,relative=1] c d e f g a b @end lilypond -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: +The duration of a note is specified by a number after the note name. +@samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note}, +@samp{4} for a @rglos{quarter note} and so on @example a1 a2 a4 a16 a32 @end example -@lilypond[notime] -\property Score.timing = ##f -\property Staff.autoBeaming = ##f -\transpose c c' { a1 a2 a4 a16 a32 s16_" " } +@c FIXME: have NOTIME also remove Score.timing? +@lilypond[fragment,quote,notime,relative=1] +\set Score.timing = ##f +\set Staff.autoBeaming = ##f +{ a1 a2 a4 a16 a32 s16_" " } @end lilypond -If you do not specify a @rglos{duration}, the previous one is used: +If you do not specify a @rglos{duration}, the duration last entered is +used for the next notes. The duration of the first note in input +defaults to a quarter @example -a4 a a2 a +a a8 a a2 a @end example -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { a a a2 a s16_" " } +@lilypond[fragment,quote,notime,relative=1] +\set Score.timing = ##f +{ a a8 a a2 a s16_" " } @end lilypond -A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a -@rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect, -a @rglos{double sharp} or @rglos{double flat} is made by adding -@samp{isis} or @samp{eses}:@footnote{This syntax derived from note -naming conventions in Nordic and Germanic languages, like German and -Dutch} +Rests are entered just like notes, but with the name @samp{r} + +@cindex rests @example -cis1 ees fisis aeses +r2 r4 r8 r16 @end example -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { cis1 ees fisis aeses s16_" " } +@lilypond[fragment,quote,notime] +\set Score.timing = ##f +r2 r4 r8 r16 s16_" " @end lilypond -Add a dot @samp{.} after the duration to get a @rglos{dotted note}: +Add a dot @samp{.} after the duration to get a @rglos{dotted note} @example a2. a4 a8. a16 @end example -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { a2. a4 a8. a16 s16_" " } +@lilypond[fragment,quote,notime,relative=1] +\set Score.timing = ##f +{ a2. a4 a8. a16 s16_" " } @end lilypond -Entering pitches and durations is fully explained in @ref{Pitches} and -@ref{Durations}. - - The @rglos{meter} (or @rglos{time signature}) can be set with the -@code{\time} command: +@code{\time} command @example \time 3/4 @@ -137,9 +141,9 @@ The @rglos{meter} (or @rglos{time signature}) can be set with the \time 4/4 @end example -@c a clef here may lead to confusion -@lilypond -\property Staff.Clef \set #'transparent = ##t +@c A clef here may lead to confusion, remove it. +@lilypond[fragment,quote] +\override Staff.Clef #'transparent = ##t \time 3/4 s4_" " \time 6/8 @@ -148,15 +152,11 @@ s4_" " s16_" " @end lilypond -Time signatures and other timing commands are described in @ref{Time -signature}. - - -The @rglos{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. -@c in English its definitely treble. +@c in Dutch, it is violin. +@c in English it is definitely treble. @example \clef treble \clef bass @@ -164,8 +164,8 @@ The @rglos{clef} can be set using the @code{\clef} command: \clef tenor @end example -@lilypond[notime] -\property Score.timing = ##f +@lilypond[fragment,quote,notime] +\set Score.timing = ##f \clef violin s4_" " \clef bass @@ -176,213 +176,312 @@ s4_" " s16_" " @end lilypond -Clefs are fully explained in @ref{Clef}. - -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: +Remember to enclose the notes and commands in curly braces +@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output. -@example -\notes @{ +@lilypond[fragment,quote,noindent,linewidth=55\staffspace] +{ \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. -@} -@end example -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. 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 source file looks like: - -@example -\score @{ - \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. - @} - \paper @{ @} -@} -@end example - -@lilypond[noindent] -\score { - \notes { - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. - } - \paper { - linewidth = 55 * \staffspace - } + f4 e d c2 r4 } @end lilypond +For more elaborate information on + +@quotation +@table @asis +@item Entering pitches and durations +see +@ref{Pitches}, and @ref{Durations}. +@item Clefs +see @ref{Clef}. +@item Rests +see @ref{Rests}. +@item Time signatures and other timing commands +see @ref{Time signature}. +@end table +@end quotation + @node Running LilyPond @section Running LilyPond +@c FIXME: let's not be so casual about Emacs and VIM, but rather +@c instruct (how) to use them; let advanced user figure-out what +@c commands to type? + +@c +@c We don't have enough space to explain either VIM +@c or Emacs non-advanced users, and I fear that both editors will only +@c confuse newbies. I vote for keeping the material in footnotes. +@c +@c --hwn + In the last section we explained what kind of things you could enter -in a LilyPond file. In this section we explain what commands to run -and how to view or print the output. If you have not used LilyPond -before, want to test your setup, or want to run an example file -yourself, read this section. The instructions that follow are for -Unix-like systems. Some additional instructions for Microsoft 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}: +in a LilyPond file. In this section we will explain what commands to +run and how to view or print the output. If you have not used +LilyPond before, want to test your setup, or want to run an example +file yourself, read this section. The instructions that follow are +for Unix-like systems. Some additional instructions for Microsoft +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}.@footnote{There are macro files for VIM addicts, and there +is a @code{LilyPond-mode} for Emacs addicts. If it has not been +installed already, refer to +@c FIXME lousy reference. +the file @file{INSTALL.txt}.} In your text editor, enter the following +input and save the file as @file{test.ly} -@quotation @example -\score @{ - \notes @{ c'4 e' g' @} -@} +@{ 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 @code{ly2dvi}, proceed as follows: +@noindent +To process @file{test.ly}, proceed as follows -@quotation @example -ly2dvi -p test.ly +lilypond test.ly @end example -@end quotation -You will see the following on your screen: +@noindent +You will see something resembling -@quotation @example -GNU LilyPond 1.7.16 -Now processing: `/home/fred/ly/test.ly' +lilypond (GNU LilyPond) 2.2.0 +Running lilypond... +Now processing `/home/fred/ly/test.ly' Parsing... Interpreting music...[1] - @emph{ ... more interesting stuff ... } -PDF output to `test.pdf'... +@emph{... more interesting stuff ... } DVI output to `test.dvi'... +PDF output to `test.pdf'... +PS output to `test.ps'... @end example -@end quotation + @cindex DVI file @cindex Viewing music @cindex xdvi +@noindent +The result is the file @file{test.pdf}@footnote{For @TeX{} +aficionados: there is also a @file{test.dvi} file. It can be viewed +with @code{xdvi}. The DVI uses a lot of PostScript specials, which do +not show up in the magnifying glass. The specials also mean that the +DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for +printing. +@cindex dvips +@cindex dvilj +@cindex DVI driver +} which you can print or with the standard facilities of your +operating system.@footnote{If your system does not have any tools +installed, you can try @uref{Ghostscript, +http://www.cs.wisc.edu/~ghost/}, a freely available package for +viewing and printing PDF and PostScript files.} + +On Windows, start up a text-editor@footnote{Any simple or +programmer-oriented editor will do, for example Notepad. Do not use a +word processor, its formatting codes will confuse LilyPond.} and enter -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 - xpdf test.pdf - gpdf test.pdf +@{ c'4 e' g' @} @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} -@c KDVI doesn't grok the PS specials. -@c or -@c @code{kdvi test.dvi} -@c -to view the DVI file. In Xdvi, the mouse buttons -activate magnifying glasses. Unfortunately, variable symbols (such as -beams and slurs) are not displayed in the magnifying glasses. +Save it on the desktop as @file{test.ly} and make sure that it is not +called @file{test.ly.TXT}. Double clicking @file{test.ly} will process +the file and show the resulting PDF file. -@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}. LilyPond DVI use embedded PostScript code -and will not render correctly with other DVI drivers besides -@code{dvips}. +@node More about pitches +@section More about pitches -@cindex dvips -@cindex dvilj -@cindex DVI driver +A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to +the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}. As +you might expect, a @rglos{double sharp} or @rglos{double flat} is +made by adding @samp{isis} or @samp{eses}@footnote{This syntax +derived from note naming conventions in Nordic and Germanic languages, +like German and Dutch.} + +@example +cis1 ees fisis aeses +@end example +@lilypond[fragment,quote,notime] +\set Score.timing = ##f +\transpose c c' { cis1 ees fisis aeses s16_" " } +@end lilypond + +@cindex key signature, setting +The key signature is set with the command @code{\key}, followed by +a pitch and @code{\major} or @code{\minor} + +@example +\key d \major +g1 +\key c \minor +g +@end example -Various commands for formatting and printing music are detailed in -@ref{Invoking LilyPond}. +@lilypond[fragment,quote,notime,fragment] +\key d \major +g'1 +\key c \minor +g' +@end lilypond + +@noindent +Key signatures together with the pitches (including alterations) are +used to determine when to print accidentals. This is a +feature that often causes confusion to newcomers, so let us explain it +in more detail. -@unnumberedsubsec Windows users +LilyPond makes a sharp distinction between musical content and +layout. The alteration (flat, natural or sharp) of a note is part of +the pitch, and is therefore musical content. Whether an accidental (a +flat, natural or sharp @emph{sign}) is printed in front of the +corresponding note is a question of layout. Layout is something that +follows rules, so accidentals are printed automatically according to +those rules. The pitches in your music are works of art, so they will +not be added automatically, and you must enter what you want to hear. + +In this example + +@lilypond[quote,notime,fragment] +\key d \major +d' cis' fis' +@end lilypond + +@noindent +no note gets an explicit accidental, but you still must enter -On Windows, the terminal is started by clicking on the LilyPond or -Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be -used to edit the LilyPond file. When Cygwin's @code{XFree86} X11 -window system is installed along with @code{tetex-x11} and -@code{ghostscript-x11} packages, then the @code{dvi} output may be -viewed with @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} +\key d \major +d cis fis @end example -@end quotation -Printing may be done by executing -@quotation + +@noindent +The code @samp{d} does not mean `print a black dot just below the +staff.' Rather, it means: `a note with pitch D-natural.' In the key +of A-flat, it does get an accidental + +@lilypond[quote,notime,fragment] +\key as \major +d' +@end lilypond + @example -@code{gsview32 /s test.pdf} +\key as \major +d @end example -@end quotation +Adding all alterations explicitly might require a little more effort +when typing, but the advantage is that transposing is easier, and +music can be printed according to different conventions. See +@ref{Accidentals}, for some examples how accidentals can be printed +according to different rules. -@node More basics -@section More basics -We continue with the introduction of more musical constructs. Normal -rests are entered just like notes with the name ``@code{r}'': +For more information on @quotation +@table @asis +@item Accidentals +see @ref{Accidentals}. + +@item Key signature +see @ref{Key signature}. +@end table +@end quotation + +@node Entering ties +@section Entering ties + +@cindex tie +A tie is created by appending a tilde @samp{~} to the first note +being tied + +@lilypond[quote,notime,fragment,verbatim,relative=3] +g4~ g a2~ a4 +@end lilypond + +For more information on Ties see @ref{Ties}. + + + +@node Automatic and manual beams +@section Automatic and manual beams + +@cindex beams, by hand +Beams are drawn automatically + +@lilypond[quote,fragment,relative=2,verbatim] +a8 ais d es r d +@end lilypond + +@noindent +If you do not like where beams are put, they can be entered by +hand. Mark the first note to be beamed with @samp{[} and the last one +with @samp{]}. + +@lilypond[quote,fragment,relative=2,verbatim] +a8[ ais] d[ es r d] +@end lilypond + +For more information on beams, see @ref{Beaming}. + + +Here are key signatures, accidentals and ties in action + @example -r2 r4 r8 r16 +@{ + \time 4/4 + \key g \minor + \clef violin + r4 r8 a8 gis4 b + a8 d4.~ d e8 + fis4 fis8 fis8 eis4 a8 gis~ + gis2 r2 +@} @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.Clef = \turnOff -\property Staff.TimeSignature = \turnOff -r2 r4 r8 r16 -s16_" " +@ignore +FIXME +ugr: removing the ignore block, leaving the comment line below +@c TODO: use relative mode, verbatim, junk \transpose and above @example +@end ignore + + +@lilypond[fragment,quote,noindent,linewidth=50\staffspace] +\transpose c c' { + \time 4/4 + \key g \minor + \clef violin + r4 r8 a8 gis4 b + a8 d4.~ d e8 + fis4 fis8 fis8 eis4 a8 gis~ + gis2 r2 +} @end lilypond -@end quotation -@separate -Rests are described in full detail in @ref{Rests}. +@cindex accidentals + + +@noindent +There are some interesting points to note in this example. Bar lines +and beams are drawn automatically. Line breaks are calculated +automatically; it does not matter where the line breaks are in the +source file. Finally, the order in which time, key and clef changes +are entered is not relevant: in the printout, these are ordered +according to standard notation conventions. + + + +@node Octave entry +@section Octave entry @c Tim wants to move this quotes example just before the: quotes-do not-work @@ -392,1272 +491,1151 @@ Rests are described in full detail in @ref{Rests}. @c better to have this just before the `octaves are bad' snipped @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). Middle C is @code{c'}: +the note name, to lower a note one octave, add a `low quote' @code{,} +(a comma). Middle C is @code{c'} -@quotation @example c'4 c'' c''' \clef bass c c, @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +@lilypond[quote,notime,fragment] c'4 c'' c''' \clef bass c c, @end lilypond -@end quotation -@separate -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 +An example of the use of quotes is in the following Mozart fragment + +@lilypond[quote,raggedright,fragment,verbatim] +\key a \major +\time 6/8 +cis''8. d''16 cis''8 e''4 e''8 +b'8. cis''16 b'8 d''4 d''8 @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-) + +@noindent +The last example shows that music in a high register needs lots of quotes. +This makes the input less readable, and it is a 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. +@ignore +FIXME: move to notation manual? + You must also give a note +from which relative mode starts, in this case @code{c''}. +@end ignore +If you do not +use octavation quotes (i.e., do not add @code{'} or @code{,} after a +note), relative mode chooses the note that is closest to the previous +one. For example, @samp{c f} goes up while @samp{c g} goes down + +@lilypond[quote,notime,fragment,verbatim] +\relative { + c' f c g c +} @end lilypond -The notation manual discusses ties in @ref{Ties}. -The key signature is set with the command ``@code{\key}'', followed by -a pitch and @code{\major} or @code{\minor}: -@quotation -@example -\key d \major -g'1 -\key c \minor -g' -@end example +Since most music has small intervals, pieces can be written almost +without octavation quotes in relative mode. The previous example is +entered as -@lilypond[fragment] -\property Staff.TimeSignature = \turnOff -\key d \major -g'1 -\key c \minor -g' +@lilypond[quote,raggedright,fragment,verbatim] +\relative { + \key a \major + \time 6/8 + cis''8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 +} @end lilypond -@end quotation +@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. +Larger intervals are made by adding octavation quotes. +@lilypond[quote,notime,verbatim,fragment] +\relative c { + c'' f, f c' c g' c, +} +@end lilypond -@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. +In summary, quotes or commas no longer determine the absolute height +of a note in @code{\relative} mode. Rather, the height of a note is +relative to the previous one, and changing the octave of a single note +shifts all following notes an octave up or down. -@quotation -@example -\score @{ - \notes @{ - \time 4/4 - \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''-~ - cis''2 r2 - @} - \paper @{ @} -@} -@end example +For more information on Relative octaves see @ref{Relative octaves}, +and @ref{Octave check}. -@lilypond -\score { - \notes { - \time 4/4 - \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''-~ - cis''2 r2 - } - \paper { linewidth = 50*\staffspace } -} -@end lilypond -@end quotation -@c accidentals... -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 an accidental is printed -automatically, only when necessary. Bar lines and beams are drawn -automatically. Line breaks are calculated automatically; it does not -matter where the lines breaks are in the source file. Finally, the -order of time, key and clef changes is not relevant: in the printout, -these are ordered using standard notation conventions. - -The example also indicates that a piece of music written in a high -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 (i.e. do not add ' or , after a note), -relative mode chooses the note that is closest to the previous one. -@c do not use commas or quotes in this sentence -For example: @code{c f} goes up; @code{c g} goes down: +@node Music expressions explained +@section Music expressions explained -@quotation -@example -\relative c'' @{ - c f c g c -@} -@end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f c g c -} -@end lilypond -@end quotation -@separate +In input files, music is represent by so-called @emph{music +expression}. We have already seen in the previous examples; +a single note is a music expression +@lilypond[fragment,quote,verbatim,relative=3] +a4 +@end lilypond -Since most music has small intervals, in relative mode pieces can be -written almost without using octavation quotes. +Enclosing group of notes in braces creates a new music +expression -@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. -Larger intervals are made by adding octavation quotes. Quotes or -commas do not determine the absolute height of a note; the height of a -note is relative to the previous one. -@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: +@lilypond[fragment,quote,verbatim,relative=3] +{ a4 g4 } +@end lilypond -@quotation -@example -\relative c'' @{ - c f, f c' c g' c, -@} -@end example +Putting a bunch of music expressions (notes) in braces, means that +they should be played in sequence. The result again is a music +expression, which can be grouped with other expressions sequentially. +Here, the expression from the previous example is combined with two +notes -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f, f c' c g' c, -} +@lilypond[fragment,quote,verbatim,relative=3] +{ { a4 g } f g } @end lilypond -@end quotation -@separate +This technique is useful for non-monophonic music. To enter music +with more voices or more staves, we also combine expressions in +parallel. Two voices that should play at the same time, are entered +as a simultaneous combination of two sequences. A `simultaneous' +music expression is formed by enclosing expressions in @code{<<} and +@code{>>}. In the following example, three sequences (all containing +two notes) are combined simultaneously + +@lilypond[fragment,quote,verbatim,relative=3] +<< + { a4 g } + { f e } + { d b } +>> +@end lilypond -Here is an example of the difference between relative mode and -``normal'' (non-relative) mode: +This mechanism is similar to mathematical +formulas: a big formula is created by composing small formulas. Such +formulas are called expressions, and their definition is recursive, so +you can make arbitrarily complex and large expressions. For example, -@quotation @example -\relative a @{ -\clef bass - a d a e d c' d' -@} +1 + +1 + 2 + +(1 + 2) * 3 + +((1 + 2) * 3) / (4 * 5) @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative a { -\clef bass - a d a e d c' d' +@cindex expression +@cindex music expression +This example shows a sequence of expressions, where each expression is +contained in the next one. The simplest expressions are numbers and +operators (like @samp{+}, @samp{*} and @samp{/}). Parentheses are used +to group expressions. + +Like mathematical expressions, music expressions can be nested +arbitrarily deep@footnote{The reason for getting three staves in the +previous example but just a single staff in the current one will be +explained later.} + +@lilypond[fragment,quote,verbatim,relative=2] +{ + c <> + << { e f } { c <> } >> } @end lilypond -@end quotation -@separate -@quotation + +@cindex indent +When spreading expressions over multiple lines, it is customary to use +an indent that indicates the nesting level. Formatting music like this +eases reading, and helps you insert the right number of closing +braces at the end of an expression. For example, + @example -\clef bass - a d a e d c' d' +\book @{ + \score @{ + << + @{ + @dots{} + @} + @{ + @dots{} + @} + \paper @{ + @dots{} + @} + >> + @} +@} @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 +Some editors have special support for entering LilyPond, and can help +indenting source files. See @ref{Editor support}, for more information. -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: +@node More staves +@section More staves -@quotation -@lilypond[fragment,relative 1, verbatim] -d4-( c16-)-( cis d e c cis d e-)-( d4-) +To print more than one staff, each piece of music that makes up a +staff is marked by adding @code{\new Staff} before it. These +@code{Staff} elements are then combined parallel with @code{<<} and +@code{>>}, as demonstrated here + +@lilypond[quote,fragment,verbatim] +<< + \new Staff { \clef violin c'' } + \new Staff { \clef bass c } +>> @end lilypond -@end quotation -@separate -If you need two slurs at the same time (one for articulation, one for -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. +The command @code{\new} introduces a `notation context.' A notation +context is an environment in which musical events (like notes or +@code{\clef} commands) are interpreted. For simple pieces, such +notation contexts are created implicitly. For more complex pieces, it +is best to mark contexts explicitly. This ensures that each fragment +gets its own stave. -@quotation -@lilypond[fragment,relative 1, verbatim] -a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\) -@end lilypond -@end quotation -@separate +There are several types of contexts: @code{Staff}, @code{Voice} and +@code{Score} handle normal music notation. Other contexts are also +@code{Lyrics} (for setting lyric texts) and @code{ChordNames} (for +printing chord names). -Beams are drawn automatically, but if you do not like where they are -put, they can be entered 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-] + +In terms of syntax, prepending @code{\new} to a music expression +creates a bigger music expression. In this way it resembles the minus +sign in mathematics. The formula @math{(4+5)} is an expression, so +@math{-(4+5)} is a bigger expression. + +We can now typeset a melody with two staves + +@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together) + +@lilypond[fragment,quote,verbatim,raggedright] +<< + \new Staff { + \time 3/4 + \clef violin + \relative { + e''2 d4 c2 b4 a8[ a] + b[ b] g[ g] a2. } + } + \new Staff { + \clef bass + c2 e4 g2. + f4 e d c2. + } +>> @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 are then grouped inside @code{\simultaneous @{} and @code{@}}, as is -demonstrated here: +For more information on context see the description in +@ref{Interpretation contexts}. -@quotation -@lilypond[fragment,verbatim] -\simultaneous { - \context Staff = staffA { \clef violin c'' } - \context Staff = staffB { \clef bass c } -} + + +@node Adding articulation marks to notes +@section Adding articulation marks to notes + +@cindex articulation +@cindex accents +@cindex staccato + +Common accents can be added to a note using a dash (@samp{-}) and a +single character + +@lilypond[fragment,quote,verbatim,relative=2] +c-. c-- c-> c-^ c-+ c-_ @end lilypond -@end quotation -In this example, @code{staffA} and @code{staffB} are names that are -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, -they are assumed to belong on the same staff, and will be printed like -that. @code{\simultaneous } indicates that both fragments happen at -the same time, and must be printed stacked vertically. +@cindex fingering +Similarly, fingering indications can be added to a note using a dash +(@samp{-}) and the digit to be printed -@separate +@lilypond[fragment,quote,verbatim,relative=2] +c-3 e-5 b-2 a-1 +@end lilypond -We can now typeset a melody with two staves: -@quotation -@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.-) } - } - \context Staff = staffB { - \clef bass - c2 e4 g2. - f4 e d c2. - } - > - \paper {} -} +Dynamic signs are made by adding the markings (with a backslash) to +the note + +@lilypond[fragment,quote,verbatim,relative=2] +c\ff c\mf @end lilypond -@end quotation -The time signature is specified in one melody staff only -(the top staff), but is printed on both, since common practice -dictates that all staves have the same time signature. +@cindex dynamics +@cindex decrescendo +@cindex crescendo -@separate +Crescendi and decrescendi are started with the commands @code{\<} and +@code{\>}. An ending dynamic, for example @code{\f}, will finish the +crescendo, or the command @code{\!} can be used -Common accents can be added to a note using @code{-.}, @code{--}, @code{->}: -@quotation -@lilypond[verbatim,relative 1] -c-. c-- c-> +@lilypond[fragment,quote,verbatim,relative=2] +c2\< c2\ff\> c2 c2\! @end lilypond -@end quotation -@separate -Similarly, fingering indications can be added to a note using @code{-} -and the digit to be printed. -@lilypond[verbatim,relative 1] - c-3 e-5 b-2 a-1 + + +@cindex slur + +A slur is a curve drawn across many notes, and indicates legato +articulation. The starting note and ending note are marked with +@samp{(} and @samp{)}, respectively + +@lilypond[fragment,quote,fragment,relative=2,verbatim] +d4( c16)( cis d e c cis d e)( d4) @end lilypond +@cindex slurs versus ties +A slur looks like a tie, but it has a different meaning. 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[quote,fragment,relative=2] +c2~( c8 fis fis4 ~ fis2 g2) +@end lilypond +@cindex phrasing slurs +Slurs to indicate phrasing can be entered with @code{\(} and +@code{\)}, so you can have both legato slurs and phrasing slurs at the +same time. -Dynamic signs are made by adding the markings to the note: -@quotation -@lilypond[verbatim,relative 1] -c-\ff c-\mf +@lilypond[quote,fragment,relative=2,verbatim] +a8(\( ais b c) cis2 b'2 a4 cis, c\) @end lilypond -@end quotation -@separate -Crescendi and decrescendi are started with the commands @code{\<} and -@code{\>}. The command @code{\!} finishes a crescendo on the note it -is attached to. + +For more information on + @quotation -@lilypond[verbatim,relative 1] -c2-\< c2-\!-\ff c2-\> c2-\! -@end lilypond +@table @asis +@item Fingering +see @ref{Fingering instructions}. +@item Articulations +see @ref{Articulations}. +@item Slurs +see @ref{Slurs}. +@item Phrasing slurs +see @ref{Phrasing slurs}. +@item Dynamics +see @ref{Dynamics}. +@end table @end quotation -@separate -Chords can be made by -surrounding pitches with @code{<<} and @code{>}>: -@quotation -@lilypond[relative 0, fragment,verbatim] -r4 <>4 <>8 + +@node Combining notes into chords +@section Combining notes into chords + +@cindex chords +Chords can be made by surrounding pitches with angle brackets. +Angle brackets are the symbols @samp{<} and @samp{>}. + +@lilypond[quote,relative=1,fragment,verbatim] +r4 4 8 @end lilypond -@end quotation -@separate -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 <>8-[ <>-]-~ <> +You can combine markings like beams and ties with chords. They must +be placed outside the angled brackets + +@lilypond[quote,relative=1,fragment,verbatim] +r4 8[ ]~ @end lilypond -@end quotation -@quotation @example -r4 <>8-\>-( <> <> <>8-\!-) +r4 8\>( 8\!) @end example -@lilypond[relative 0, fragment] + +@lilypond[quote,relative=1,fragment] \slurUp -r4 <>8-\>-( <> <> <>8-\!-) +r4 8\>( 8\!) @end lilypond -@end quotation -@separate -A pickup (or upstep) is entered with the keyword @code{\partial}. It + + +@node Basic rhythmical commands +@section Basic rhythmical commands + +@cindex pickup +@cindex anacruse +@cindex partial measure +A pickup is entered with the keyword @code{\partial}. It is followed by a duration: @code{\partial 4} is a quarter note upstep -and @code{\partial 8} an eighth note. -@lilypond[relative 1,verbatim,fragment] - \partial 8 - f8 c2 d e +and @code{\partial 8} an eighth note + +@lilypond[quote,relative=2,verbatim,fragment] +\partial 8 +f8 c2 d e @end lilypond +@cindex tuplets +@cindex triplets Tuplets are made with the @code{\times} keyword. It takes two arguments: a fraction and a piece of music. The duration of the piece of music is multiplied by the fraction. Triplets make notes occupy -2/3 of their notated duration, so a triplet has 2/3 as its fraction. -@c -@lilypond[relative 0,verbatim,fragment] - \times 2/3 { f8 g a } - \times 2/3 { c r c } -@end lilypond - -Grace notes are also made by prefixing a note, or a set of notes with -a keyword. In this case, the keyword is @code{\grace}. -@lilypond[relative 1, verbatim,fragment] - \grace b16-( c4-) - \grace { d16-( e } d4-) +2/3 of their notated duration, so a triplet has 2/3 as its fraction + +@lilypond[quote,relative=1,verbatim,fragment] +\times 2/3 { f8 g a } +\times 2/3 { c r c } +@end lilypond + +@cindex grace notes +@cindex acciaccatura +Grace notes are also made by prefixing a music expression with the +keyword @code{\appoggiatura} or @code{\acciaccatura} +@cindex appoggiatura +@cindex acciaccatura + +@lilypond[quote,relative=2,verbatim,fragment] +c4 \appoggiatura b16 c4 +c4 \acciaccatura b16 c4 @end lilypond @noindent -More information on the use of grace notes is in @ref{Grace notes}. +For more information on + +@quotation +@table @asis +@item Grace notes +see @ref{Grace notes}, +@item Tuplets +see @ref{Tuplets}, +@item Pickups +see @ref{Partial measures}. +@end table +@end quotation + + +@node Commenting input files +@section Commenting input files -Comments are pieces of the input that are ignored. There are two -types of comments. A line comments are introduced by @code{%}: after -that, the rest of that line is ignored. Block comments span larger -sections of input. Anything that is enclosed in @code{%@{} and -@code{%@}} is ignored too. The following fragment shows possible uses -for comments. +@cindex comments +@cindex line comment +@cindex block comment +A comment is a remark for the human reader of the music input; it is +ignored and has no effect on the printed output. There are two types +of comments. The percent symbol @samp{%} introduces a line comment; +the rest of the line is ignored. A block comments marks a whole +section of music input---anything that is enclosed in @code{%@{} and +@code{%@}} is ignored. The following fragment shows possible uses for +comments @example - % notes for twinkle twinkle follow: - c4 c g' g a a - - %@{ - +% notes for twinkle twinkle follow +c4 c g' g a a + +%@{ This line, and the notes below are ignored, since they are in a block comment. g g f f e e d d c2 - %@} +%@} @end example +There is a special statement that really is a kind of comment. The +version statement marks for which version of LilyPond the file was +written. To mark a file for version 2.1.17, use +@example +\version "2.1.17" +@end example + +@noindent +These annotations make future upgrades of LilyPond go more +smoothly. Changes in the syntax are handled with a special program, +@file{convert-ly} (see @ref{Invoking convert-ly}), and it uses +@code{\version} to determine what rules to apply. @node Printing lyrics @section Printing lyrics @cindex lyrics -Lyrics are entered by separating each syllable with a space, and -surrounding them with @code{\lyrics @{ @dots{} @}}, for example -@example - \lyrics @{ I want to break free @} -@end example +@c TODO: (c) status of the Queen fragment. + +@cindex Lyrics +@cindex Songs +Lyrics are entered by separating each syllable with a space -Like notes, lyrics are also a form of music, but they must not be -printed on a staff, which is the default way to print music. To print -them as lyrics, they must be marked with @code{ \context Lyrics}: @example - \context Lyrics \lyrics @{ I want to break free @} +I want to break free @end example -The melody for this song is as follows -@lilypond[fragment,relative=1] - \partial 8 - c8 - \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) } +Consider the melody + +@lilypond[quote,verbatim,fragment,raggedright] +\relative { + r4 c \times 2/3 { f g g } + \times 2/3 { g4( a2) } +} @end lilypond +@c FIXME: when/how/to what rename newlyrics? The lyrics can be set to these notes, combining both with the -@code{\addlyrics} keyword: -@example - \addlyrics - \notes @{ @dots{} @} - \context Lyrics @dots{} -@end example +@code{\newlyrics} keyword -The final result is -@lilypond[singleline,verbatim] -\score { - \notes { - \addlyrics - \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4-( a2-) } - } - \context Lyrics \lyrics { I want to break free } - } - \paper{ } -} +@lilypond[quote,verbatim,fragment,raggedright] +<< + \relative { + r4 c \times 2/3 { f g g } + \times 2/3 { g4( a2) } + } + \newlyrics { I want to break free } +>> @end lilypond -This melody ends on a @rglos{melisma}, a single syllable (``free'') -sung to more than one note. This is indicated with a @emph{extender -line}. It is entered as two underscores, i.e., +@cindex melisma +@cindex extender line +@c synonyms? +This melody ends on a @rglos{melisma}, a single syllable (`free') +sung to more than one note. This is indicated with an @emph{extender +line}. It is entered as two underscores, i.e., + @example - \lyrics @{ I want to break free __ @} +@{ I want to break free __ @} @end example -@lilypond[] -\score { - \notes { - \addlyrics - \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4-( a2-) } - - %% ugh, this is to deal with bugs in the extender implementation - \hideNotes - c8 - } - \context Lyrics \lyrics { I want to break free __ } - } - \paper{ linewidth = 9.0 \cm } -} + +@lilypond[fragment,quote,raggedright] +<< + \relative { + r4 c \times 2/3 { f g g } + \times 2/3 { g4( a2) } + } + \newlyrics { I want to break free __ } +>> @end lilypond Similarly, hyphens between words can be entered as two dashes, -resulting in a centered hyphen between two syllables. +resulting in a centered hyphen between two syllables + @example - Twin -- kle twin -- kle +Twin -- kle twin -- kle @end example -@lilypond[singleline] -\score { - \addlyrics \notes \relative f' { \time 2/4 - f4 f c' c' } - \context Lyrics \lyrics { Twin -- kle twin -- kle - } -\paper { linewidth = 6.0 \cm } - } - + +@lilypond[fragment,quote,raggedright] +<< + \relative { + \time 2/4 + f4 f c' c + } + \newlyrics { Twin -- kle twin -- kle } +>> @end lilypond More options, like putting multiple lines of lyrics below a melody are discussed in @ref{Vocal music}. +@c FIXME: too geeky, for notation manual? +@c or introduce using foo = \lyrics { a b c } ? + +When using variables for a piece of lyrics +To prevent certain words (for example `as') as being read as a +pitch, the input-mode must be switched. This is done with +@code{\lyrics}. In @code{\lyrics} mode, all words are read as lyric +syllables. + +@example +myText = \lyrics @{ I want to break free @} +@end example + +@noindent +The braces @code{@{@}} signify that the syllables are sung in +sequence. + +@ignore +By default, music expressions are interpreted in @code{Staff} context. For +lyrics, this is obviously not desirable, so it is necessary +to explicitly specify a @code{Lyrics} context, + +@example +\lyrics @{ I want to break free @} +@end example + +The melody for this song is as follows + +@lilypond[fragment,quote,fragment,relative=2] +r4 c \times 2/3 { f4 g g } +\times 2/3 { g4( a2) } +@end lilypond + +@end ignore + @node A lead sheet @section A lead sheet -In popular music, it is common to denote accompaniment as chord-names. -Using them in LilyPond has two parts, just like lyrics: entering the -chords (with @code{\chords}), and printing them (with @code{\context -ChordNames}). +@cindex Lead sheets +@cindex chords +@cindex chord names -Chord names are entered by starting chords mode (with @code{\chords}). -In chords mode, you can enter chords with a letter (indicating the -root of the chord), and a durations following that. -@c -@lilypond[verbatim] - \chords { c2 f4. g8 } -@end lilypond +In popular music, it is common to denote accompaniment as chord names. +Such chords can be entered like notes, + +@example +c2 f4. g8 +@end example @noindent -The result of @code{\chords} is a list of chords, and is equivalent -to entering chords with @code{<<@dots{}>>}. +but now, each pitch is read as the root of a chord instead of a note. +This mode is switched on with @code{\chords} -Other chords can be created by adding modifiers, after a colon. The -following example shows a few common modifiers -@c -@lilypond[verbatim] - \chords { c2 f4:m g4:maj7 gis1:dim7 } +@lilypond[quote,verbatim,raggedright] +\chords { c2 f4. g8 } @end lilypond -Printing chords is done by adding @code{\context ChordNames} -before the chords thus entered: -@c -@lilypond[verbatim] - \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 } +Other chords can be created by adding modifiers after a colon. The +following example shows a few common modifiers + +@lilypond[quote,verbatim] +\chords { c2 f4:m g4:maj7 gis1:dim7 } @end lilypond -A complete list of modifiers, and other options for layout are in the -reference manual section @ref{Chords}. +For lead sheets, chords are not printed on staves, but as names on a +line of themselves. Hence, we have to override the context with +@code{\new}, rendering the music expression in a @code{ChordNames} +context -@cindex lead sheet -When put together, chord names, lyrics and a melody form +@lilypond[quote,verbatim] +\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 } +@end lilypond + +@cindex lead sheet +When put together, chord names, lyrics and a melody form a lead sheet, for example, @example -\score @{ - < - \context ChordNames \chords @{ @emph{chords} @} - \addlyrics - \notes @emph{the melody} - \context Lyrics \lyrics @{ @emph{the text} @} - > - \paper @{ @} +<< + \new ChordNames \chords @{ @emph{chords} @} + @emph{the melody} + \newlyrics @{ @emph{the text} @} +>> @} @end example -@lilypond[] -\score { - < - \context ChordNames \chords { r8 c2:sus4 f } - \addlyrics - \notes \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4-( a2-) } } - \context Lyrics \lyrics { I want to break free __ } - > - \paper{ raggedright = ##t } -} + +@lilypond[quote,raggedright] +<< + \new ChordNames \chords { r2 c:sus4 f } + \relative { + r4 c' \times 2/3 { f g g } + \times 2/3 { g4( a2) } + } + \newlyrics { I want to break free __ } +>> @end lilypond +A complete list of modifiers and other options for layout can be found +in @ref{Chords}. +@c FIXME: we talk about \midi before mentioning \paper (or \layout?) @node Listening to output @section Listening to output +@cindex sound +@cindex MIDI + MIDI (Musical Instrument Digital Interface) is a standard for -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: octaves that are off, or -accidentals that were mistyped, stand out very much when listening to -the musical transcription. - -@code{\midi} can be used in similarly to @code{\paper @{ @}}, for -example +connecting and controlling digital instruments. A MIDI file is like a +tape recording of a MIDI instrument. + +To create a MIDI from a music piece of music, add a @code{\midi} +block. This causes LilyPond to create a MIDI file, so you can listen +to what you just entered. It is great for checking the music. +Octaves that are off or accidentals that were mistyped stand out very +much when listening to the musical transcription. + +The @code{\midi} block is added to @code{\score}, for example, + @example \score @{ - @var{..music..} - \midi @{ \tempo 4=72 @} - \paper @{ @} + @var{...music...} + \midi @{ \tempo 4=72 @} @} @end example Here, the tempo is specified using the @code{\tempo} command. In this -case the tempo of quarter notes is set to 72 beats per minute. More -information on auditory output is in the @ref{Sound} section in the -notation manual. +case the tempo of quarter notes is set to 72 beats per minute. More +information on auditory output in the notation manual can be found in +@ref{Sound}. + +If there is a @code{\midi} command in a @code{\score}, only MIDI will +be produced. If notation is needed too, a @code{\paper} block must be +added + +@example +\score @{ + @var{...music...} + \midi @{ \tempo 4=72 @} + \paper @{ @} +@} +@end example +@cindex paper block -@node Titling -@section Titling +@node Adding titles +@section Adding titles Bibliographic information is entered in a separate block, the -@code{\header} block. The name of the piece, its composer, etc. are -entered as assignment within @code{\header @{ @dots{} @}}. For -example, +@code{\header} block. The name of the piece, its composer, etc., are +entered as an assignment, within @code{\header +@{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at +the top of the file. For example, + @example - \header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" - tagline = "small is beautiful" - @} - - \score @{ @dots{} @} +\header @{ + title = "Eight miniatures" + composer = "Igor Stravinsky" + tagline = "small is beautiful" +@} + +@{ @dots{} @} @end example @cindex bibliographic information @cindex titles @cindex composer -@cindex ly2dvi +@cindex Engraved by LilyPond + +When the file is processed the title and composer are printed above +the music. The `tagline' is a short line printed at bottom of the last +page which normally says `Engraved by LilyPond, version @dots{}'. In +the example above it is replaced by the line `small is +beautiful.'@footnote{Nicely printed parts are good PR for us, so +please leave the tagline if you can.} + + +The @code{\header} block is usually put at the top of the file. + +A document may contains multiple pieces of music, examples are an +etude book, or an orchestral part with multiple movements. +@c FIXME: ugh. \header can only live at toplevel, or inside \score. +@c If we allow it also to live inside \book, we do not need \score here? +The @code{\book} block is used to group the individual @code{\score} +blocks. +The header for each piece of music can be put inside the @code{\score} +block. The @code{piece} name from the header will be printed before +each movement. -When the file is processed by @code{ly2dvi}, the title and composer -specified are printed above the music. The `tagline' is a short line -printed at bottom of the last page, which normally says ``Lily was -here, version @dots{}''. In the example above, it is replaced by the -line ``small is beautiful.'' +@ignore -Normally, the @code{\header} is put at the top of the file. However, -for a document that contains multiple pieces (e.g. a etude book, or -part with multiple movements), then the header can be put into the -@code{\score} block as follows In this case, the name of each piece -will be printed before each movement. +FIXME: introduce \BOOK +FIXME: Using "Adagio" as a name is confusing, it's more common to be +a plain tempo indication. -@cindex Lily was here +Since today (CVS-1.211) we also allow headers and composite music +inside book: + + \header { ... } + \book { + \header { ... } + { ... } + \header { ... } + { ... } + } + +@end ignore + +@cindex Engraved by LilyPond @cindex signature line @cindex tag line @example - \header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" - tagline = "small is beautiful" - @} - - \score @{ @dots{} +\header @{ + title = "Eight miniatures" + composer = "Igor Stravinsky" + tagline = "small is beautiful" +@} + +\book @{ + \score @{ + @dots{} \header @{ piece = "Adagio" @} @} - \score @{ @dots{} + \score @{ + @dots{} \header @{ piece = "Menuetto" @} @} +@} @end example -More information on titling can be found in @ref{Invoking ly2dvi}. +More information on titling can be found in @ref{Invoking lilypond}. -@node Single staff polyphony +@node Single staff polyphony @section Single staff polyphony -When different melodic lines are combined on a single staff, these are -printed as polyphonic voices: each voice has its own stems, slurs -and beams, and the top voice has the stems up, while the bottom voice -has stems down. +@cindex polyphony +@cindex multiple voices +@cindex voices, more -- on a staff +When different melodic lines are combined on a single staff they are +printed as polyphonic voices; each voice has its own stems, slurs and +beams, and the top voice has the stems up, while the bottom voice has +them down. Entering such parts is done by entering each voice as a sequence (with -@code{@{ .. @}}), and combing those simultaneously, separating the -voices with @code{\\}: +@code{@{...@}}), and combining those simultaneously, separating the +voices with @code{\\} -@lilypond[verbatim,relative] - < { a4 g2 f4-~ f4 } \\ - { r4 g4 f2 f4 } > +@lilypond[quote,verbatim,relative=3] +<< { a4 g2 f4~ f4 } \\ + { r4 g4 f2 f4 } >> @end lilypond -The notation @code{< .. >} is a shorthand for @code{\simultaneous @{ -.. @}}. -For polyphonic typesetting spacer rests can also be convenient: these +For polyphonic music typesetting, spacer rests can also be convenient; these are rests that do not print. It is useful for filling up voices that -temporarily do not play: -@lilypond[verbatim,relative] - < { a4 g2 f4-~ f4 } \\ - { s4 g4 f2 f4 } > +temporarily do not play. Here is the same example with a spacer rest +instead of a normal rest---just use @samp{s} instead of @samp{r} + +@lilypond[quote,verbatim,relative=3] +<< { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } >> +@end lilypond + +@noindent +Again, these expressions can be nested arbitrarily + +@lilypond[quote,fragment,verbatim,relative=3] +<< + \new Staff << + { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } + >> + \new Staff << + \clef bass + { 1 ~ 4 } \\ + { f4 d e2 ~ e4} + >> +>> @end lilypond -More features of polyphonic typesetting are in the notation manual -in @ref{Polyphony}. +More features of polyphonic typesetting in the notation manual are +described in @ref{Polyphony}. -@node Piano staffs -@section Piano staffs + +@node Piano staves +@section Piano staves @cindex staff switch, manual @cindex cross staff voice, manual -@cindex @code{\translator} +@cindex @code{\context} +Piano music is typeset in two staves connected by a brace. Printing +such a staff is similar to the polyphonic example in @ref{More staves}, -Piano music is always typeset in two staffs connected by a brace. -Printing such a staff is done similar to the polyphonic example in -@ref{More basics}: -@example - < \context Staff = up @{ @dots{} @} - \context Staff = down @{ @dots{} @} - > -@end example -but now this entire expression must be interpreted as a -@code{PianoStaff}: @example - \context PianoStaff < \context Staff @dots{} > +<< \new Staff @{ @dots{} @} + \new Staff @{ @dots{} @} >> @end example -Here is a complete-fledged example: -@lilypond[relative 0,fragment] -\context PianoStaff - < \context Staff = up { - c4 c g g } - \context Staff = down { - \clef bass c, c' e c } - > -@end lilypond - -More information on formatting piano music is in @ref{Piano music}. - -@node Setting variables -@section Setting variables - -When the music is converted from notes to print, it is interpreted -from left-to-right order, similar to what happens when we read -music. During this step, context-sensitive information, such as the -accidentals to print, and where barlines must be placed, are stored in -variables. These variables are called @emph{translation properties}. -The properties can also be manipulated from input files: for example, -@example -\property Staff.autoBeaming = ##f -@end example -sets the property named @code{autoBeaming} in the current staff to -@code{##f} which means `false'. This property controls whether beams -are printed automatically: -@lilypond[relative 1,fragment,verbatim] - c8 c c c - \property Staff.autoBeaming = ##f - c8 c c c -@end lilypond - @noindent -LilyPond includes a built-in programming language, namely, a dialect -of Scheme. The argument to @code{\property}, @code{##f}, is an -expression in that language. The first hash-mark signals that a piece -of Scheme code follows. The second hash character is part of the -boolean value true (@code{#t}). Values of other types may be -entered as follows -@itemize @bullet -@item a string, enclosed in double quotes, for example -@example - \property Staff.instrument = #"French Horn" -@end example -@item a boolean: either @code{#t} or @code{#f}, for true and false -respectively, e.g. -@example - \property Voice.autoBeaming = ##f - \property Score.skipBars = ##t -@end example +but now this entire expression must be interpreted as a +@code{PianoStaff} -@item a number @example - \property Score.currentBarNumber = #20 +\new PianoStaff << \new Staff @dots{} >> @end example -@item a symbol, which is introduced by a quote character, -@example - \property Staff.crescendoSpanner = #'dashed-line -@end example +Here is a full-fledged example -@item a pair, which is also introduced by a quote character. -The following statements set properties to the pairs (-7.5, 6) and -(3, 4) respectively. +@lilypond[quote,verbatim,relative=1,fragment] +\new PianoStaff << + \new Staff { \time 2/4 c4 c g' g } + \new Staff { \clef bass c,, c' e c } +>> +@end lilypond -@example - \property Staff.minimumVerticalExtent = #'(-7.5 . 6) - \property Staff.timeSignatureFraction = #'(3 . 4) -@end example +More information on formatting piano music is in @ref{Piano music}. -@end itemize +@node Organizing larger pieces +@section Organizing larger pieces -There are many different properties, and not all of them are listed in -this manual. However, the internal documentation lists them all in the -@internalsref{All translation properties}, and almost all properties -are demonstrated in one of the -@ifhtml -@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks} -@end ifhtml -@ifnothtml -tips-and-tricks -@end ifnothtml -examples. - - -@node Fine tuning layout -@section Fine tuning layout - -Sometimes it is necessary to change music layout by hand. When music -is formatted, layout objects are created for each symbol. For -example, every clef and every note head is represented by a layout -object. These layout objects also carry variables, which -we call @emph{layout properties}. By changing these variables, we can -alter the look of a formatted score. - -@lilypond[verbatim,relative 0] - c4 - \property Voice.Stem \override #'thickness = #3.0 - c4 c4 c4 -@end lilypond +When all of the elements discussed earlier are combined to produce +larger files, the @code{\score} blocks get a lot bigger, because the +music expressions are longer, and, in the case of polyphonic pieces, +more deeply nested. Such large expressions can become unwieldy. -@noindent -In the example shown here, the layout property @code{thickness} (a -symbol) is set to 3 in the @code{Stem} layout objects of the current -Voice. As a result, the notes following @code{\property} have thicker -stems. - -In most cases of manual overrides, only a single object must be -changed. This can be achieved by prefix @code{\once} to the -@code{\property} statement, i.e., +By using variables, also known as identifiers, it is possible to break +up complex music expressions. An identifier is assigned as follows @example - \once \property Voice.Stem \set #'thickness = #3.0 +namedMusic = @{ @dots{} @} @end example -@lilypond[relative 0] - c4 - \once \property Voice.Stem \set #'thickness = #3.0 - c4 c4 c4 -@end lilypond - @noindent -Some overrides are so common that predefined commands are provided as -a short cut. For example, @code{\slurUp} and @code{\stemDown}. These -commands are described in the @ref{Notation manual}. - - - - - -@node Organising larger pieces -@section Organising larger pieces - -TODO: discuss identifiers, p&c, . - - - - -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} - +The contents of the music expression @code{namedMusic}, can be used +later by preceding the name with a backslash, i.e., @code{\namedMusic}. +In the next example, a two-note motive is repeated two times by using +variable substitution + +@lilypond[quote,raggedright,verbatim,nofragment] +seufzer = { + e'4( dis'4) +} +{ \seufzer \seufzer } +@end lilypond -@cindex dynamics -@cindex loudness -@cindex forte -@cindex crescendo +The name of an identifier should have alphabetic characters only; +no numbers, underscores or dashes. The assignment should be outside of +running music. +It is possible to use variables for many other types of objects in the +input. For example, +@example +width = 4.5\cm +name = "Wendy" +aFivePaper = \paper @{ paperheight = 21.0 \cm @} +@end example +Depending on its contents, the identifier can be used in different +places. The following example uses the above variables -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: +@example + \paper @{ + \aFivePaper + linewidth = \width + @} + @{ c4^\name @} +@end example -@lilypondfile{brahms-tweaked.ly} +More information on the possible uses of identifiers is in the +technical manual, in TODO. -@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}. +@node An orchestral part +@section An orchestral part -@cindex slur attachments +In orchestral music, all notes are printed twice; in a part for +the musicians, and in a full score for the conductor. Identifiers can +be used to avoid double work. The music is entered once, and stored in +a variable. The contents of that variable is then used to generate +both the part and the score. -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!). +It is convenient to define the notes in a special file. For example, +suppose that the file @file{horn-music.ly} contains the following part +of a horn/bassoon duo @example - \property Voice.Slur \set #'attachment = #'(stem . stem) +hornNotes = \relative c @{ + \time 2/4 + r4 f8 a cis4 f e d +@} @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 users'' 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 +@noindent +Then, an individual part is made by putting the following in a file -@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 +\include "horn-music.ly" +\header @{ + instrument = "Horn in F" +@} -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{} +@{ + \transpose f c' \hornNotes +@} @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} +The line -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" @} +\include "horn-music.ly" @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 +@noindent +substitutes the contents of @file{horn-music.ly} at this position in +the file, so @code{hornNotes} is defined afterwards. The command +@code{\transpose f@tie{}c'} indicates that the argument, being +@code{\hornNotes}, should be transposed by a fifth downwards. Sounding +@samp{f} is denoted by notated @code{c'}, which corresponds with +tuning of a normal French Horn in@tie{}F. The transposition can be seen +in the following output + +@lilypond[quote,raggedright] + \transpose f c' \relative c { + \time 2/4 + r4 f8 a cis4 f e d + } +@end lilypond -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 +In ensemble pieces, one of the voices often does not play for many +measures. This is denoted by a special rest, the multi-measure +rest. It is entered with a capital @samp{R} followed by a duration +(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the +duration, longer rests can be constructed. For example, this rest +takes 3@tie{}measures in 2/4 time - 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 +R2*3 @end example +When printing the part, multi-rests +must be condensed. This is done by setting a run-time variable -@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' +\set Score.skipBars = ##t @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}. +@noindent +This command sets the property @code{skipBars} in the +@code{Score} context to true (@code{##t}). Prepending the rest and +this option to the music above, leads to the following result + +@lilypond[quote,raggedright] +\transpose f c' \relative c { + \time 2/4 + \set Score.skipBars = ##t + R2*3 + r4 f8 a cis4 f e d + } +@end lilypond -Finally, the last tie is forced up using @code{\tieUp}. - -@separate -Here is the complete ``fine tuned'' version, which includes all the -modifications we discussed in this section: +The score is made by combining all of the music together. Assuming +that the other voice is in @code{bassoonNotes} in the file +@file{bassoon-music.ly}, a score is made with -@lilypondfile[verbatim]{brahms-tweaked.ly} +@example +\include "bassoon-music.ly" +\include "horn-music.ly" + << + \new Staff \hornNotes + \new Staff \bassoonNotes + >> +@end example -@node An orchestral part -@section An orchestral part +@noindent +leading to +@lilypond[quote,raggedright] + \relative c << + \new Staff { + \time 2/4 R2*3 + r4 f8 a cis4 f e d + } + \new Staff { + \clef bass + r4 d,8 f | gis4 c | b bes | + a8 e f4 | g d | gis f + } + >> +@end lilypond -TODO: +More in-depth information on preparing parts and scores can be found +in the notation manual; see @ref{Orchestral music}. -\markup, mmrest, transposing, cue notes, identifiers?. +Setting run-time variables (`properties') is discussed in ref-TODO. -@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 LilyPond version the input file was written -for. When you compile this file, the version number will be -checked. When the file is too old, a warning is issued. The version -number is also used by the @code{convert-ly} program (See -@ref{Invoking convert-ly}), which updates the file to the latest -version automatically. @node Integrating text and music @section Integrating text and music - @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. +Some texts include music examples. Examples are musicological +treatises, songbooks or manuals like this. Such texts can be made by +hand, simply by importing a PostScript figure into the word processor. +However, there is an automated procedure to reduce the amount of work +involved HTML, La@TeX{}, and Texinfo documents. + +A script called @code{lilypond-book} will extract the music fragments, +run format them, and put back the resulting notation. This program is +fully described in @ref{lilypond-book manual}. Here we show a small +example. The example also contains explanatory text, so we will not +comment on it further @example \documentclass[a4paper]@{article@} \begin@{document@} -In a lilypond-book document, you can freely mix music and text. For -example: -\begin@{lilypond@} - \score @{ \notes \relative c' @{ - 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. - -If you have no \verb+\score+ block in the fragment, -\texttt@{lilypond-book@} will supply one: +Documents for lilypond-book may freely mix music and text. For +example, \begin@{lilypond@} - c'4 + @{ \relative c' @{ + c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4 + @} \end@{lilypond@} -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: +Options are put in brackets. -\begin[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"]@{lilypond@} - c'4 f bes es +\begin[fragment,quote,staffsize=26,verbatim]@{lilypond@} + c'4 f16 \end@{lilypond@} -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. +Larger examples can be put in a separate file, and introduced with +\verb+\lilypondfile+. -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]@{screech-boink.ly@} - -The \texttt@{printfilename@} option adds the file name to the output. +\lilypondfile[quote,noindent]@{screech-boink.ly@} \end@{document@} @end example -Under Unix, you can view the results as follows. +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.7.16 -Reading `input/tutorial/lilbook.tex' -Reading `input/screech-boink6.ly' +$ lilypond-book --output=out/ lilybook.tex +lilypond-book (GNU LilyPond) 2.1.19 +Reading `input/tutorial/lilybook.tex' +Reading `input/screech-boink.ly' @var{lots of stuff deleted} -Writing `out/lilbook.latex' +Writing `out/lilybook.tex' $ cd out -$ latex lilbook.latex +$ latex lilybook @var{lots of stuff deleted} -$ xdvi lilbook +$ xdvi lilybook @end example -Notice the @code{outdir} option to lilypond-book. Running lilypond-book -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. +To convert the file into a nice PDF document, run the following +commands -The result looks more or less like this: +@example +$ dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook +$ ps2pdf lilybook.ps +@end example -@separate +Running lilypond-book and running latex creates a lot of temporary +files, which would clutter up the working directory. To remedy this, +use the @code{--output=@var{dir}} option. It will create the files in +a separate subdirectory @file{dir}. -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 - } - \paper { - raggedright = ##t - } -} -@end lilypond +Finally the result of the La@TeX{} example shown above.@footnote{Note +that in this tutorial the example is processed with Texinfo. This gives +slightly different results in layout.} This finishes the tutorial +section. -Notice that the music line length matches the margin settings of the -document. +@page -If you have no @code{\score} block in the fragment, -@code{lilypond-book} will supply one: +Documents for lilypond-book may freely mix music and text. For +example, @lilypond - c'4 +\relative c' { + c2 g'2 \times 2/3 { f8 e d } c'2 g4 +} @end lilypond -In the example you see here, a number of things happened: a -@code{\score} block was added, and the line width was set to natural -length. You can specify many more options using La@TeX{} style options -in brackets: +Options are put in brackets. -@lilypond[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"] - c'4 f bes es +@lilypond[fragment,quote,staffsize=26,verbatim] +c'4 f16 @end lilypond -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 -@code{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: - -@lilypondfile[printfilename]{screech-boink.ly} - -The @code{printfilename} option adds the file name to the output. +Larger examples can be put in a separate file, and introduced with +@code{\lilypondfile}. +@lilypondfile[quote,noindent]{screech-boink.ly}