X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=a0408d0d8a271ff95e3b6ccf1844e3fed7665743;hb=e0412b07662da2a8f812f18b153913e43de02580;hp=eee67cf14e29b496b0036bc1e60d42872a0acc9e;hpb=f855540cda9634e38bd9fd9908e56de676be8c50;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index eee67cf14e..a0408d0d8a 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,134 +1,139 @@ @c -*-texinfo-*- +@c This file is part of lilypond.tely @c TODO: @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 - -@menu -* First steps:: Music language of LilyPond. -* Running LilyPond:: Printing music. -* More basics:: -* Printing lyrics:: -* A lead sheet:: -* Listening to output:: -* Titling :: -* Single staff polyphony :: -* Piano staffs:: -* Setting variables:: -* Fine tuning layout:: -* Organizing larger pieces:: -* An orchestral part:: -* Integrating text and music:: Integrating text and music. -@end menu +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. -Printing music with LilyPond is a two step process. First, the music -to be printed is described in a text file. After that, LilyPond reads -this @emph{input file} that describes the music and produces an -@emph{output file} that can be printed or viewed. +@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 -This tutorial starts with a short introduction to the LilyPond music -language. After this first contact, we will show you how to to -produce printed output, normally using the program @code{ly2dvi}. You -should then be able to create and print your first sheets of music. -Before starting out, it will be convenient for you to print +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:: +* 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:: +* Adding titles:: +* Single staff polyphony:: +* Piano staves:: +* Organizing larger pieces:: +* An orchestral part:: +* Integrating text and music:: +@end menu @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 @@ -136,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 @@ -147,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 @@ -163,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 @@ -175,27 +176,24 @@ s4_" " s16_" " @end lilypond -Clefs are fully explained in @ref{Clef}. - - -These commands must be enclosed in @code{\notes @{@dots{}@}}. This -indicates that music (as opposed to @rglos{lyrics}) follows: +@ignore +To recognize names like @samp{c} and @samp{d} as pitches, they have to +be entered inside a so-called @code{\notes} block. This block is +formed by enclosing notes and commands are enclosed in curly braces +@code{@{@tie{}@dots{}@tie{}@}} and adding the keyword @code{\notes} before +the opening brace @example -\notes @{ +@{ \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 @} @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: +Now the piece of music is almost ready to be printed. Enclose +the @code{\notes} block in a @code{\score} block @example \score @{ @@ -203,638 +201,710 @@ enclosing them in @code{\score @{ ... @}}. This is what a full source file look \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 @} - \paper @{ @} @} @end example -@lilypond[noindent] -\score { - \notes { - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. - } - \paper { - linewidth = 55 * \staffspace - } +@noindent +and the music will be converted to printable output. +@end ignore + +Remember to enclose the notes and commands in curly braces +@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output. + +@lilypond[fragment,quote,noindent,linewidth=55\staffspace] +{ + \time 3/4 + \clef bass + c2 e4 g2. + 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}. - -@cindex dvips -@cindex dvilj -@cindex DVI driver +@node More about pitches +@section More about pitches +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.} -Various commands for formatting and printing music are detailed in -@ref{Invoking LilyPond}. +@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 -@unnumberedsubsec Windows users +@cindex key signature, setting +The key signature is set with the command @code{\key}, followed by +a pitch and @code{\major} or @code{\minor} -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} -@end example -@end quotation -Printing may be done by executing -@quotation -@example -@code{gsview32 /s test.pdf} +\key d \major +g1 +\key c \minor +g @end example -@end quotation +@lilypond[fragment,quote,notime,fragment] +\key d \major +g'1 +\key c \minor +g' +@end lilypond -@node More basics -@section More basics +@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. -We continue with the introduction of more musical constructs. Normal -rests are entered just like notes with the name ``@code{r}'': -@cindex rests -@quotation +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 + @example -r2 r4 r8 r16 +\key d \major +d cis fis @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.Clef = \turnOff -\property Staff.TimeSignature = \turnOff -r2 r4 r8 r16 -s16_" " +@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 -@end quotation -@separate -Rests are described in full detail in @ref{Rests}. +@example +\key as \major +d +@end example +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. -@c Tim wants to move this quotes example just before the: quotes-do not-work -@c score, but we'd need to remove quotes from the other two (key and -@c tie) examples... -@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'}: +For more information on @quotation -@example -c'4 c'' c''' \clef bass c c, -@end example +@table @asis +@item Accidentals +see @ref{Accidentals}. -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -c'4 c'' c''' \clef bass c c, -@end lilypond +@item Key signature +see @ref{Key signature}. +@end table @end quotation -@separate + +@node Entering ties +@section Entering ties @cindex tie - -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 -@end lilypond -@end quotation -@separate -@cindex slurs versus ties -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-) +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 -The notation manual discusses ties in @ref{Ties}. +For more information on Ties see @ref{Ties}. -@cindex key signature, setting -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 -@lilypond[fragment] -\property Staff.TimeSignature = \turnOff -\key d \major -g'1 -\key c \minor -g' +@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 -@end quotation +@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 -@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. +For more information on beams, see @ref{Beaming}. + + +Here are key signatures, accidentals and ties in action -@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 @{ @} +@{ + \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 -\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 } +@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 @cindex 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: -@quotation +@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 +@c score, but we'd need to remove quotes from the other two (key and +@c tie) examples... + +@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'} + @example -\relative c'' @{ - c f c g c -@} +c'4 c'' c''' \clef bass c c, @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f c g c +@lilypond[quote,notime,fragment] +c'4 c'' c''' \clef bass c c, +@end lilypond + +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 + +@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 -@end quotation -@separate -Since most music has small intervals, in relative mode pieces can be -written almost without using octavation quotes. +Since most music has small intervals, pieces can be written almost +without octavation quotes in relative mode. The previous example is +entered as + +@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 @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: +Larger intervals are made by adding octavation quotes. -@quotation -@example -\relative c'' @{ - c f, f c' c g' c, -@} -@end example - -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f, f c' c g' c, +@lilypond[quote,notime,verbatim,fragment] +\relative c { + c'' f, f c' c g' c, } @end lilypond -@end quotation -@separate +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. -Here is an example of the difference between relative mode and -``normal'' (non-relative) mode: +For more information on Relative octaves see @ref{Relative octaves}, +and @ref{Octave check}. -@quotation -@example -\relative a @{ -\clef bass - a d a e d c' d' -@} -@end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative a { -\clef bass - a d a e d c' d' -} -@end lilypond -@end quotation -@separate +@node Music expressions explained +@section Music expressions explained -@quotation -@example -\clef bass - a d a e d c' d' -@end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\clef bass - a d a e d c' d' -@end lilypond -@end quotation -@separate +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 -@cindex slur +@lilypond[fragment,quote,verbatim,relative=3] +a4 +@end lilypond -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: +Enclosing group of notes in braces creates a new music +expression -@quotation -@lilypond[fragment,relative 1, verbatim] -d4-( c16-)-( cis d e c cis d e-)-( d4-) +@lilypond[fragment,quote,verbatim,relative=3] +{ a4 g4 } @end lilypond -@end quotation -@separate -@cindex phrasing slurs -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. +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 -@quotation -@lilypond[fragment,relative 1, verbatim] -a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\) +@lilypond[fragment,quote,verbatim,relative=3] +{ { a4 g } f g } @end lilypond -@end quotation -@separate -@cindex beams, by hand -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-] +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 -@end quotation -@separate -@menu -* Combining music into compound expressions:: -* Adding articulation marks to notes :: -* Basic rhythmical commands:: -* Commenting input files:: -@end menu +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, -@node Combining music into compound expressions -@subsection Combining music into compound expressions +@example +1 -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: +1 + 2 -@quotation -@lilypond[fragment,verbatim] -\simultaneous { - \context Staff = staffA { \clef violin c'' } - \context Staff = staffB { \clef bass c } +(1 + 2) * 3 + +((1 + 2) * 3) / (4 * 5) +@end example + +@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 -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. The notation -@code{< .. >} can also be used as a shorthand for @code{\simultaneous -@{ .. @}}. -@separate +@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, -We can now typeset a melody with two staves: +@example +\book @{ + \score @{ + << + @{ + @dots{} + @} + @{ + @dots{} + @} + \paper @{ + @dots{} + @} + >> + @} +@} +@end example -@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 {} -} +Some editors have special support for entering LilyPond, and can help +indenting source files. See @ref{Editor support}, for more information. + +@node More staves +@section More staves + +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 -The example shows how small chunks of music, for example the notes -@code{c2}, @code{e4}, etc. of the second staff, are combined to form a -larger chunk by enclosing it in braces. Again, a larger chunk is -formed by prefix @code{\context Staff} to it, and that chunk is -combined with @code{< >}. This mechanism is similar with mathematical -formulas: in a formula, a so-called expression is formed by combining -simpler expressions into larger expressions. For example, -@quotation - 1 +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. + +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). + + +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 + +For more information on context see the description in +@ref{Interpretation contexts}. - 1 + 2 - - (1 + 2) * 3 - - ((1 + 2) * 3) / (4 * 5) -@end quotation -@cindex expression -@cindex music expression -is a sequence of expressions, where each expression is contained in -the next one. The simplest expressions are numbers and operators -(like +, * and /). Parentheses are used to group expressions. In -LilyPond input, a similar mechanism is used. Here, the simplest -expressions are notes and rests. By enclosing expressions in @code{< ->} and @code{@{ @}}, more complex music is formed. The @code{\context} -also forms new expressions; it is prepended to a music expression. -@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 amount of closing -braces at the end of an expression. For example -@example -\score @{ - \notes < - @{ - @dots{} - @} - @{ - @dots{} - @} - > -@} -@end example -@node Adding articulation marks to notes -@subsection Adding articulation marks to notes +@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 @code{-.}, @code{--}, @code{->}: -@quotation -@lilypond[verbatim,relative 1] -c-. c-- c-> +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 -@separate @cindex fingering -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 +Similarly, fingering indications can be added to a note using a dash +(@samp{-}) and the digit to be printed + +@lilypond[fragment,quote,verbatim,relative=2] +c-3 e-5 b-2 a-1 @end lilypond -Dynamic signs are made by adding the markings to the note: -@quotation -@lilypond[verbatim,relative 1] -c-\ff c-\mf +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 -@separate @cindex dynamics @cindex decrescendo @cindex crescendo Crescendi and decrescendi are started with the commands @code{\<} and -@code{\>}. The command @code{\!} finishes a crescendo on the note it -is attached to. -@quotation -@lilypond[verbatim,relative 1] -c2-\< c2-\!-\ff c2-\> c2-\! +@code{\>}. An ending dynamic, for example @code{\f}, will finish the +crescendo, or the command @code{\!} can be used + +@lilypond[fragment,quote,verbatim,relative=2] +c2\< c2\ff\> c2 c2\! +@end lilypond + + + +@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. + +@lilypond[quote,fragment,relative=2,verbatim] +a8(\( ais b c) cis2 b'2 a4 cis, c\) @end lilypond + + +For more information on + +@quotation +@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 + + +@node Combining notes into chords +@section Combining notes into chords @cindex chords -Chords can be made by -surrounding pitches with @code{<<} and @code{>}>: -@quotation -@lilypond[relative 0, fragment,verbatim] -r4 <>4 <>8 +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 + + @node Basic rhythmical commands -@subsection Basic rhythmical commands +@section Basic rhythmical commands @cindex pickup @cindex anacruse -@cindex upstep @cindex partial measure -A pickup (or upstep) is entered with the keyword @code{\partial}. It +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 @@ -842,156 +912,195 @@ and @code{\partial 8} an eighth note. 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 +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 accacciatura -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] - c4 \grace b16-( c4-) - \grace { d16-( e } d4-) +@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 -@subsection Commenting input files +@section Commenting input files @cindex comments @cindex line comment @cindex block comment -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. +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 +@c TODO: (c) status of the Queen fragment. + @cindex Lyrics @cindex Songs -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 +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[verbatim,linewidth=6.0cm] -\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 @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 a @emph{extender -line}. It is entered as two underscores, i.e., +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 -TODO: discuss contexts. +@end ignore @node A lead sheet @@ -1000,72 +1109,66 @@ TODO: discuss contexts. @cindex Lead sheets @cindex chords @cindex chord names - -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}). - -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 + +@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 +@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 } + \notes \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 @@ -1073,406 +1176,290 @@ a lead sheet, for example, @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.} -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.'' +The @code{\header} block is usually put at the top of the file. -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. +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. -@cindex Lily was here +@ignore + +FIXME: introduce \BOOK + +FIXME: Using "Adagio" as a name is confusing, it's more common to be +a plain tempo indication. + +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 @cindex polyphony @cindex multiple voices @cindex voices, more -- on a staff - -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. +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{\\} -@example - < @{ a4 g2 f4-~ f4 @} \\ - @{ r4 g4 f2 f4 @} > -@end example -@lilypond[relative 1] -\context Staff < { a4 g2 f4-~ f4 } \\ - { r4 g4 f2 f4 } > +@lilypond[quote,verbatim,relative=3] +<< { a4 g2 f4~ f4 } \\ + { r4 g4 f2 f4 } >> @end lilypond -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: -@example - < @{ a4 g2 f4-~ f4 @} \\ - @{ s4 g4 f2 f4 @} > -@end example -@lilypond[relative 1] -\context Staff < { a4 g2 f4-~ f4 } \\ - { s4 g4 f2 f4 } > -@end lilypond - -More features of polyphonic typesetting are in the notation manual -in @ref{Polyphony}. - -@node Piano staffs -@section Piano staffs - -@cindex staff switch, manual -@cindex cross staff voice, manual -@cindex @code{\translator} - -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{} > -@end example - -Here is a full-fledged example: +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[relative 0,fragment] -\context PianoStaff - < \context Staff = up { - c4 c g' g } - \context Staff = down { - \clef bass c,, c' e c } - > +@lilypond[quote,verbatim,relative=3] +<< { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } >> @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 +@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 -@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 +More features of polyphonic typesetting in the notation manual are +described in @ref{Polyphony}. -@item a number -@example - \property Score.currentBarNumber = #20 -@end example -@item a symbol, which is introduced by a quote character, -@example - \property Staff.crescendoSpanner = #'dashed-line -@end example +@node Piano staves +@section Piano staves -@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. +@cindex staff switch, manual +@cindex cross staff voice, manual +@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}, @example - \property Staff.minimumVerticalExtent = #'(-7.5 . 6) - \property Staff.timeSignatureFraction = #'(3 . 4) +<< \new Staff @{ @dots{} @} + \new Staff @{ @dots{} @} >> @end example - -@end itemize - -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 from their -values, 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 - @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., +but now this entire expression must be interpreted as a +@code{PianoStaff} @example - \once \property Voice.Stem \set #'thickness = #3.0 +\new PianoStaff << \new Staff @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}, under the -sections for slurs and stems respectively. - -The exact tuning possibilities for each type of layout object are -documented in the internal documentation of the respective -object. However, many layout objects share properties, which can be -used to apply generic tweaks. We mention a couple of these: - -@itemize @bullet -@cindex @code{extra-offset} -@item The @code{extra-offset} property -moves around objects in the printout. 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. The -@code{extra-offset} is a low-level feature: the formatting engine is -completely oblivious to these offsets. - -In the following example example, the second fingering is moved a -little to the left, and 1.8 staff space downwards. - -@cindex setting object properties - -@lilypond[relative 1,verbatim] -\stemUp -f-5 -\once \property Voice.Fingering - \set #'extra-offset = #'(-0.3 . -1.8) -f-5 -@end lilypond +Here is a full-fledged example -@item -Setting the @code{transparent} property will make an object be -printed in `invisible ink': the object is not printed, but all its -other behavior is retained. The object still takes space, takes part -in collisions, and slurs, ties and beams can be attached to it. - -@cindex transparent objects -@cindex removing objects -@cindex invisible objects -The following example demonstrates how to connect different voices -using ties. Normally ties only happen between notes of the same -voice. By introducing a tie in a different voice, and blanking a stem -in that voice, the tie appears to cross voices. - -@lilypond[fragment,relative 1] -\context Staff < { - \once \property Voice.Stem \set #'transparent = ##t - b8~ b8 - } \\ { - b-[ g8-] - } > +@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 -@item -The @code{padding} property for objects with -@code{side-position-interface} can be set to increase distance between -symbols that are printed above or below notes. An example of the use -of padding is in @ref{Constructing a tweak}. -@end itemize +More information on formatting piano music is in @ref{Piano music}. -More specific overrides are also possible. The notation manual -discusses in depth how to figure out these statements for yourself, in -@ref{Tuning output}. @node Organizing larger pieces @section Organizing larger pieces 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 and/or -orchestral pieces, more deeply nested. +music expressions are longer, and, in the case of polyphonic pieces, +more deeply nested. Such large expressions can become unwieldy. By using variables, also known as identifiers, it is possible to break -up complex music expressions. -An identifier is assigned as follows +up complex music expressions. An identifier is assigned as follows + @example - namedMusic = \notes @{ @dots{} +namedMusic = \notes @{ @dots{} @} @end example +@noindent The contents of the music expression @code{namedMusic}, can be used -later by preceding the name with a backslash, i.e. @code{\namedMusic}. -For example +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[singleline,verbatim] -seufzer = \notes { - dis'8 e'8 +@lilypond[quote,raggedright,verbatim,nofragment] +seufzer = \notes { + e'4( dis'4) } -\score { \notes { - \seufzer \seufzer -} } +{ \seufzer \seufzer } @end lilypond -The name of an identifier should only have alphabetic characters only, -and no numbers, underscores or dashes. The assignment should be -outside of the @code{\score} block. +The name of an identifier should have alphabetic characters only; +no numbers, underscores or dashes. The assignment should be outside of +the @code{\score} block. It is possible to use variables for many other types of objects in the input. For example, + @example - width = 1.5\cm - name = "Wendy" - aFivePaper = \paper @{ paperheight = 22.7 \cm @} +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: +places. The following example uses the above variables + @example - \score @{ - \notes @{ c4^\name @} - \paper @{ - \aFivePaper - linewidth = \width - @} +\score @{ + \notes @{ c4^\name @} + \paper @{ + \aFivePaper + linewidth = \width @} +@} @end example More information on the possible uses of identifiers is in the -technical manual, in @ref{Scheme datatypes}. +technical manual, in TODO. @node An orchestral part @section An orchestral part -In orchestral music, all notes are printed twice: both in a part for -the musicians, and in a full score for the which is printed both in -parts as in full score. Identifiers can be used to avoid double work: -the music is entered once, and stored in an variables. The contents of -that variable is then used to generate both the part and the score. +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. + +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 -It is convenient to define the notes in a special file, for example, -suppose that the following is in @file{horn-music.ly}: @example hornNotes = \notes \relative c @{ \time 2/4 @@ -1480,229 +1467,241 @@ hornNotes = \notes \relative c @{ @} @end example +@noindent Then, an individual part is made by putting the following in a file + @example \include "horn-music.ly" \header @{ instrument = "Horn in F" @} \score @{ - \notes \transpose c' f \hornNotes + \notes \transpose f c' \hornNotes @} @end example -The @code{\include} command substitutes the contents of the file at -this position in the file, so that @code{hornNotes} is defined -afterwards. Since the horn is tuned in F, the @code{\transpose} -command is used. The code @code{\transpose c' f} indicates that the -argument, being @code{\hornNotes} should be transposed by a fifth -downwards: the @code{c'} becomes a @code{f}. The transposition can be -seen in the following output: - -@lilypond[singleline] + +The line + +@example +\include "horn-music.ly" +@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] \score { - \notes \transpose c' f \notes \relative c' { - \time 2/4 - r4 f8 a cis4 f e d -} + \notes \transpose f c' \notes \relative c { + \time 2/4 + r4 f8 a cis4 f e d + } } @end lilypond 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 R, and followed by a duration (1 -for a whole note, 2 for a half note, etc.) By multiplying the -duration, longer rests can be constructed. For example, the next rest -takes 3 measures in 2/4 time. +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 + @example - R2*3 +R2*3 @end example -When printing the part, the following @code{skipBars} property must be -set to false, to prevent the rest from being expanded in three one bar -rests. +When printing the part, multi-rests +must be condensed. This is done by setting a run-time variable + @example - \property Score.skipBars = ##t +\set Score.skipBars = ##t @end example -The result would look like +@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[singleline] -\score {\notes { \transpose c' f \relative c' { \time 2/4 -\property Score.skipBars = ##t - R2*3 - r4 f8 a cis4 f e d } }} +@lilypond[quote,raggedright] +\score { + \notes \transpose f c' \relative c { + \time 2/4 + \set Score.skipBars = ##t + R2*3 + r4 f8 a cis4 f e d + } +} @end lilypond -The score is made by combining all of the music in a @code{\score} -block, assuming that the other voice is in @code{hornNotes}, in the -file @file{horn-music.ly}: + +The score is made by combining all of the music in a @code{\score} +block. Assuming that the other voice is in @code{bassoonNotes} in the +file @file{bassoon-music.ly}, a score is made with + @example -\include "fagot-music.ly" +\include "bassoon-music.ly" \include "horn-music.ly" \score @{ \simultaneous @{ - \context Staff = hornStaff \hornNotes - \context Staff = fagStaff \fagottoNotes - @} @} + \new Staff \hornNotes + \new Staff \bassoonNotes + @} +@} @end example -This would lead to the following output: +@noindent +leading to -@lilypond[singleline] +@lilypond[quote,raggedright] \score { \notes \relative c \simultaneous { - \context Staff = hornStaff { \time 2/4 - R2*3 - r4 f8 a cis4 f e d } - \context Staff = fagStaff { \clef bass - r4 d,8 f | gis4 c | b bes | - a8 e f4 | g d | gis f } - } } -@end lilypond + \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 + +More in-depth information on preparing parts and scores can be found +in the notation manual; see @ref{Orchestral music}. -More in depth information is in the notation manual, in -@ref{Orchestral music}. +Setting run-time variables (`properties') is discussed in ref-TODO. @node Integrating text and music @section Integrating text and music -TODO: shorten. - @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: +Documents for lilypond-book may 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: +If there is no \verb+\score+ block in the fragment, +\texttt@{lilypond-book@} will supply one -\begin@{lilypond@} +\begin[quote]@{lilypond@} c'4 \end@{lilypond@} -In the example you see here, two things happened: a +\noindent +In this example 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: - -\begin[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"]@{lilypond@} - c'4 f bes es -\end@{lilypond@} +length. -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. +Options are put in brackets. -If you want to include large examples into the text, it may be more -convenient to put the example in a separate file: +\begin[quote,staffsize=26,verbatim]@{lilypond@} + c'4 f16 +\end@{lilypond@} -\lilypondfile[printfilename]@{screech-boink.ly@} +Larger examples can be put in a separate file, and introduced with +\verb+\lilypondfile+. -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.23 -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 -Running lilypond-book and running latex creates a lot of temporary -files, and you would not want those to clutter up your working -directory. The @code{outdir} option to lilypond-book creates the -temporary files in a separate subdirectory @file{out}. +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 +\score { \notes \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: +If there is no @code{\score} block in the fragment, +@code{lilypond-book} will supply one -@lilypond[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"] - c'4 f bes es +@lilypond[fragment,quote] +c'4 @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. +@noindent +In this example two things happened. A +@code{score} block was added, and the line width was set to natural +length. -If you include large examples into the text, it may be more convenient -to put the example in a separate file: +Options are put in brackets. -@lilypondfile[printfilename]{screech-boink.ly} +@lilypond[fragment,quote,staffsize=26,verbatim] +c'4 f16 +@end lilypond -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}