+@c -*-texinfo-*-
+@c TODO:
+@c * more details about running lilypond; error messages,
+@c compiling/viewing (emacs?)
+@c * where to go from First steps+More basics?
+
+@node Tutorial
@chapter Tutorial
-@node Tutorial, , , Top
+
+Using LilyPond comes down to encoding music in an input file. After
+entering the music, the program is run on the file producing output
+which can be viewed or printed. In this tutorial, we will show step
+by step how to enter such files, by showing fragments of input and the
+corresponding output. At the end of every section, a paragraph will
+list where to find further information on the topics discussed.
+
+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.
+@ifhtml
+For example, consider the following input:
+@c TODO: intertext fixme
+@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
+ c'^\markup { \bold \huge { Click on this image! } }
+@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.
+
+
+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.
+
@menu
-* Introduction:: Introduction
-* The first tune:: The first tune
-* Lyrics and chords:: Lyrics and chords
-* Piano music:: Piano music
-* end of tutorial:: The end
+* First steps:: Music language of LilyPond.
+* Running LilyPond:: Printing music.
+* More about pitches and accidentals::
+* Octave entry::
+* Combining music into compound expressions::
+* Adding articulation marks to notes::
+* Combining notes into chords::
+* Printing lyrics::
+* A lead sheet::
+* Listening to output::
+* Titling::
+* Single staff polyphony::
+* Piano staves::
+* Setting variables::
+* Fine tuning layout::
+* Organizing larger pieces::
+* An orchestral part::
+* Integrating text and music:: Integrating text and music.
@end menu
-@node Introduction, , , Tutorial
-@section Introduction
-
-LilyPond prints music from a specification that you, the user, supply.
-You have to give that specification using a @emph{language}. This
-document is a gentle introduction to that language, which is called
-Mudela, an acronym of Music Definition Language.
+@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 note 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:
+
+@c ?
+@c \transpose c c' { c d e f g a b }
+@c @lily pond[notime]
+@c \property Score.timing = ##f
+@lilypond[notime, relative=2]
+c d e f g a b
+@end lilypond
+
+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:
+
+@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_" " }
+@end lilypond
+
+If you do not specify a @rglos{duration}, the previous one is used:
+
+@example
+a4 a a2 a
+@end example
+
+@lilypond[notime]
+\property Score.timing = ##f
+\transpose c c' { a a a2 a s16_" " }
+@end lilypond
-This tutorial will demonstrate how to use Mudela by presenting
-examples of input along with resulting output. We will use English
-terms for notation. In case you are not familiar with those, you may
-consult the glossary that is distributed with LilyPond.
-The examples discussed are included in the distribution, in the
-subdirectory @file{input/tutorial/}. It is recommended that you
-experiment with writing Mudela input yourself, to get a feel for
-how LilyPond behaves.
+Rests are entered just like notes, but with the name ``@code{r}'':
+
+@cindex rests
+@quotation
+@example
+r2 r4 r8 r16
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.Clef = \turnOff
+\property Staff.TimeSignature = \turnOff
+r2 r4 r8 r16
+s16_" "
+@end lilypond
+@end quotation
+@separate
-@node The first tune, , , Tutorial
-@section The first tune
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
+
+@example
+a2. a4 a8. a16
+@end example
-To demonstrate what LilyPond input looks like, we start off with a
-full fledged, yet simple example. It is a convoluted version
-of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
+@lilypond[notime]
+\property Score.timing = ##f
+\transpose c c' { a2. a4 a8. a16 s16_" " }
+@end lilypond
-@mudela[verbatim]
-% lines preceded by a percent are comments.
-\include "paper16.ly"
+
+The @rglos{meter} (or @rglos{time signature}) can be set with the
+@code{\time} command:
+
+@example
+\time 3/4
+\time 6/8
+\time 4/4
+@end example
+
+@c a clef here may lead to confusion
+@lilypond
+\property Staff.Clef \set #'transparent = ##t
+\time 3/4
+s4_" "
+\time 6/8
+s4_" "
+\time 4/4
+s16_" "
+@end lilypond
+
+
+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.
+@example
+\clef treble
+\clef bass
+\clef alto
+\clef tenor
+@end example
+
+@lilypond[notime]
+\property Score.timing = ##f
+\clef violin
+s4_" "
+\clef bass
+s4_" "
+\clef alto
+s4_" "
+\clef tenor
+s16_" "
+@end lilypond
+
+Notes and commands like @code{\clef} and @code{\time} , are enclosed
+in @code{\notes @{@dots{}@}}. This indicates that music (as opposed
+to @rglos{lyrics}) follows:
+
+@example
+\notes @{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ 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. The
+@code{\paper} block is used to customize printing specifics, but we
+accept the defaults for now. The music and the @code{\paper} block
+are combined by enclosing them in @code{\score @{ ... @}}. The
+following is a complete and valid input file.
+
+@example
+\score @{
+ \notes @{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
+ @}
+ \paper @{ @}
+@}
+@end example
+
+@lilypond[noindent]
\score {
- \notes
- \relative c'' \sequential{
- \time 3/4;
- \key g;
-
- \repeat "volta" 2 {
- d4 g,8 a b c d4 g, g |
- e'4 c8 d e fis g4 g, g |
- c4 d8()c b a( )b4 c8 b a g |
- a4 [b8 a] [g fis] g2. |
- }
-
- b'4 g8 a b g
- a4 d,8 e fis d |
- g4 e8 fis g d cis4 b8 cis a4 |
- a8-. b-. cis-. d-. e-. fis-.
- g4 fis e |
- fis a, r8 cis8
- d2.-\fermata
- \bar "|.";
- }
- \paper {
- % standard settings are too wide for a book
- linewidth = 14.0 \cm;
- }
+ \notes {
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
+ }
+ \paper {
+ linewidth = 55 * \staffspace
+ }
}
-@end mudela
+@end lilypond
+
+During the rest of the tutorial, we will often leave out @code{\score}
+and @code{\paper}, for clarity. However, both must be present when
+feeding the file to LilyPond.
+
+More elaborate information on entering pitches and durations is in
+@ref{Pitches} and @ref{Durations}. Clefs are fully explained in
+@ref{Clef}. Time signatures and other timing commands are described
+in @ref{Time signature}.
+
+
+@node Running LilyPond
+@section Running LilyPond
+
+In the last section we explained what kind of things you could enter
+in a LilyPond file. In this section we explain 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, then refer to 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' @}
+@}
+@end example
+@end quotation
+
+@cindex ly2dvi
-Enter it (or copy it, the filename is @file{menuet.ly}), compile it
-with LilyPond and view the output. Details of this procedure may vary
-from system to system. To create the output, one would issue the
-command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
-the job of running LilyPond and TeX, handling of titles and
-adjusting of page margins.
+@c now this is weird, running ly2dvi to run LilyPond
+@c (therefore name change proposal)
-If all goes well, the file @file{menuet.dvi} will be created.
-To view this output, issue the command `@code{xdvi menuet}'.
+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:
-Now that we are familiar with the procedure of producing output, we
-will analyse the input, line by line.
-@ignore
-Let's try to redo this
+@quotation
@example
+ly2dvi -p test.ly
+@end example
+@end quotation
- % lines preceded by a percent are comments.
-
-@end example
-The percent sign, `@code{%}', introduces a line comment. If you want to
-make larger comments, you can use block comments. These are delimited
-by `@code{%@{}' and `@code{%@}}'
-@end ignore
-@multitable @columnfractions .60 .39
-@item
-@noindent
-@c @example urg: no tt font
-@c @exdent % lines preceded by a percent are comments.
-@exdent @code{% lines preceded by a percent are comments.}
-@c @end example
-@tab
-The percent sign, `@code{%}', introduces a line comment. If you
-want to make larger comments, you can use block comments. These
-are delimited by `@code{%@{}' and `@code{%@}}'
-@end multitable
-@example
+You will see something resembling:
- \input "paper16.ly"
-
-@end example
-By default, LilyPond will use definitions for a 20
-point@footnote{A point is the standard measure of length for
-printing. One point is 1/72.27 inch.} high staff. We want smaller
-output (16 point staff height), so we must import the settings for
-that size, which is done.@example
+@quotation
+@example
+GNU LilyPond 1.8.0
+Now processing: `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+ @emph{ ... more interesting stuff ... }
+PDF output to `test.pdf'...
+DVI output to `test.dvi'...
+@end example
+@end quotation
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+
+The result of the ly2dvi is the file @file{test.pdf}.@footnote{For
+@TeX{} afficionados, 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
+} One of the following commands should put the PDF on your
+screen:
+@quotation
+@example
+ gv test.pdf
+ ghostview test.pdf
+ ggv test.pdf
+ kghostview test.pdf
+ xpdf test.pdf
+ gpdf test.pdf
+ acroread test.pdf
+ gsview32 test.pdf
+@end example
+@end quotation
+If the music on your screen looks good, you can print it by clicking
+File/Print inside your viewing program.
- \score @{
-
-@end example
- A mudela file combines music with directions for outputting that
-music. The music is combined with the output directions by putting
-them into a @code{\score} block.
-@example
+@cindex Ghostscript
+@cindex @code{lpr}
+@cindex Printing output
+@cindex PostScript
+@cindex PDF
- \notes
-
-@end example
- This makes LilyPond ready for accepting notes.
-@example
- \relative c''
-
-@end example
- As we will see, pitches are combinations of octave, note name and
-chromatic alteration. In this scheme, the octave is indicated by
-using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
-`@code{,}'). The central C is denoted by @code{c'}. The C one octave
-higher is @code{c''}. One and two octaves below the central C is
-denoted by @code{c} and @code{c,} respectively.
-
-For pitches in a long piece you might have to type many quotes. To
-remedy this, LilyPond has a ``relative'' octave entry mode. In this
-mode, octaves of notes without quotes are chosen such that a note is
-as close as possible (graphically, on the staff) to the the preceding
-note. If you add a high-quote an extra octave is added. The lowered
-quote (a comma) will subtract an extra octave. Because the first note
-has no predecessor, you have to give the (absolute) pitch of the note
-to start with.@example
-
- \sequential @{
-
-@end example
- What follows is sequential music, i.e.,
-notes that are to be played and printed after each other.@example
+On Windows, the same procedure should work, 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.
- \time 3/4;
-
-@end example
- This command changes the time signature of the current piece: a 3/4
-sign is printed. This command is also used to generate bar lines in
-the right spots.@example
+To view the PDF file, try the following:
+@itemize
+@item
+If your system has a PDF viewer installed, open
+@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
+@file{test.pdf}.
+@item
+If you prefer the keyboard, you can also try the list of commands
+shown before. If none work, go to
+@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
+@end itemize
- \key g;
-
-@end example
- This command changes the current key to G-major. Although this
-command comes after the @code{\time} command, in the output, the key
-signature comes before the time signature: LilyPond knows about music
-typesetting conventions. @example
+The commands for formatting and printing music on all platforms are
+detailed in @ref{Invoking LilyPond}.
- \repeat "volta" 2
-
-@end example
- This command tells LilyPond that the following piece of music must
-be played twice; @code{"volta"} volta brackets should be used for
-alternatives---if there were any.
-@example
+@node More about pitches and accidentals
+@section More about pitches and accidentals
- @{
-
-@end example
-The subject of the repeat is again sequential music. Since
-@code{\sequential} is such a common construct, a shorthand is provided:
-just leave off @code{\sequential}, and the result is the same. @example
+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.}
- d4
-
-@end example
- This is a note with pitch @code{d} (determined up to octaves). The
-relative music was started with a @code{c''}, so the real pitch of this
-note is @code{d''}. The @code{4} designates the duration of the note
-(it is a quarter note). @example
+@example
+cis1 ees fisis aeses
+@end example
- a b
-
-@end example
-These are notes with pitch @code{a} and @code{b}. Because their
-duration is the same as the @code{g}, there is no need to enter the
-duration (You may enter it anyway, eg. @code{a4 b4}) @example
+@lilypond[notime]
+\property Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
+@end lilypond
- d4 g, g |
-@end example
- Three more notes. The `@code{|}' character is a `barcheck'. When
-processing the music, LilyPond will verify that barchecks are found at
-the start of a measure. This can help you track down errors.
-
- So far, no notes were chromatically altered. Here is the first one
-that is: @code{fis}. Mudela by default uses Dutch note names, and
-``Fis'' is the Dutch note name for ``F sharp''. However, there is no
-sharp sign in the output. The program keeps track of key signatures,
-and will only print accidentals if they are needed.
-@example
+@cindex key signature, setting
- c8 d e fis
-
-@end example
-LilyPond guesses were beams can be added to eighth and shorter notes.
-In this case, a beam over 4 eighths is added.
-@example
+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
+g1
+\key c \minor
+g
+@end example
- c4 d8( )c b a( )b4 c8 b a g |
-
-@end example
- The next line shows how to make a slur:
-the beginning and ending note of the slur is marked with an opening and
-closing parenthesis respectively. In the line shown above this is
-done for two slurs. Slur markers (parentheses) are between
-the notes.@example
+@lilypond[fragment]
+\property Staff.TimeSignature = \turnOff
+\key d \major
+g'1
+\key c \minor
+g'
+@end lilypond
+@end quotation
+
+
+@cindex tie
+A tie is created by adding a tilde ``@code{~}'' to the first note
+being tied:
+@quotation
+@lilypond[fragment,verbatim,relative 2]
+g4-~ g a2-~ a4
+@end lilypond
+@end quotation
+@separate
+
+This example shows the key signature, accidentals and ties in action:
+
+@quotation
+@example
+\score @{
+ \notes @{
+ \time 4/4
+ \key g \minor
+ \clef violin
+ r4 r8 a8 gis4 b
+ g8 d4.-~ d' e'8
+ fis4 fis8 fis8 eis4 a8 gis-~
+ gis2 r2
+ @}
+ \paper @{ @}
+@}
+@end example
- a4 [b8 a] [g fis]
-
-@end example
-Automatic beaming can be overridden by inserting beam marks
-(brackets). Brackets are put around notes you want beamed.@example
+@lilypond
+\score {
+ \notes { \transpose c c' {
+ \time 4/4
+ \key g \minor
+ \clef violin
+ r4 r8 a8 gis4 b
+ g8 d4.-~ d e8
+ fis4 fis8 fis8 eis4 a8 gis-~
+ gis2 r2
+ }}
+ \paper { linewidth = #(* 50 staffspace) }
+}
+@end lilypond
+@end quotation
+@cindex accidentals
+
+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 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 according to standard
+notation conventions.
+
+Accidentals (sharps and flats) do not have to be marked explicitly:
+you just enter the pitch of the note, and an accidental is printed
+only when necessary. The flip side of this mechanism, is that you have
+to mark notes as sharp or flat, even when they do not get accidentals.
+For example, in this example:
+@lilypond[fragment]
+\clef bass
+\property Staff.TimeSignature = #'()
+\key cis \major
+cis dis eis fis gis ais bis
+@end lilypond
+no note gets an explicit accidental, but still you enter
+@example
+\clef bass
+\key cis \major
+cis dis eis fis gis ais bis
+@end example
- g2. |
-
-@end example
-A duration with augmentation dot is notated
-with the duration number followed by a period.@example
+Adding all alterations explicitly might require some more effort when
+typing, but the advantage is that transposing is easier. It also makes
+it possible to use different conventions for when to print
+accidentals.
- @}
-
-@end example
- This ends the sequential music to be repeated. LilyPond will typeset
-a repeat bar. @example
+@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-]
+@end lilypond
+@end quotation
+@separate
- cis'4 b8 cis a4 |
-
-@end example
- This line shows that Lily will print an accidental if that is
-needed: the first C sharp will be printed with an accidental, the
-second one without. @example
+Rests are described in full detail in @ref{Rests}.
- a8-. b-. cis-. d-. e-. fis-.
-
-@end example
-You can enter articulation signs either in a verbose form using a
-shorthand. Here we demonstrate the shorthand: it is formed by a dash
-and the the character for the articulation to use, e.g. `@code{-.}' for
-staccato as shown above. @example
+The notation manual discusses ties in @ref{Ties}.
- fis a, r8 cis8
-
-@end example
-
-Rests are denoted by the special notename `@code{r}'. You can also enter
-an invisible rest by using the special notename `@code{s}'.
-@example
- d2.-\fermata
-
-@end example
- All articulations have a verbose form, like @code{\fermata}. The
-command `@code{\fermata}' is not part of the core of the language (most
-of the other discussed elements are), but it is a shorthand for a more
-complicated description of a fermata. @code{\fermata} names that
-description and is therefore called an @emph{identifier}. @example
+@node Octave entry
+@section Octave entry
- @}
-
-@end example
-
-Here the music ends.
-@example
- \paper @{
- linewidth = 14.0\cm;
- @}
-
-@end example
-This specifies a conversion from music to notation output. Most of
-the details of this conversions (font sizes, dimensions, etc.) have
-been taken care of, but to fit the output in this document, it has
-to be smaller. We do this by setting the line width to 14 centimeters
-(approximately 6 inches).
-@example
+@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...
- @}
-
-@end example
-The last brace ends the @code{\score} block.
+@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'}:
-There are two things to note here. The format contains musical
-concepts like pitches and durations, instead of symbols and positions:
-the input format tries to capture the meaning of @emph{music}, and not
-notation. Therefore Second, the format tries to be @emph{context-free}:
-a note will sound the same regardless of the current time signature,
-the key, etc.
+@quotation
+@example
+c'4 c'' c''' \clef bass c c,
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+c'4 c'' c''' \clef bass c c,
+@end lilypond
+@end quotation
+@separate
+
+An example of the use of quotes is in the following Mozart fragment:
+@lilypond[singleline,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
+
+This 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. 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.
+For example, @code{c f} goes up while @code{c g} goes down:
+
+@quotation
+@example
+\relative c'' @{
+ c f c g c
+@}
+@end example
-The purpose of LilyPond is explained informally by the term `music
-typesetter'. This is not a fully correct name: not only does the
-program print musical symbols, it also makes esthetic decisions. All
-symbols and their placement is @emph{generated} from a high-level musical
-description. In other words, LilyPond would be best
-described by `music compiler' or `music to notation compiler'.
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\relative c'' {
+ 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. In relative mode, the
+Mozart example is entered as
+@c
+@lilypond[singleline,fragment,verbatim]
+\relative c'' {
+ \key a \major
+ \time 6/8
+ cis8. d16 cis8 e4 e8
+ b8. cis16 b8 d4 d8
+}
+@end lilypond
-@node Lyrics and chords, , , Tutorial
-@section Lyrics and chords
-In this section we show how to typeset a song of unknown
-origin.@footnote{The author would welcome information about the origin
-of this song.}.
+@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:
-@example
-\header @{
- title = "The river is flowing";
- composer = "Traditional (?)";
-@}
-\include "paper16.ly"
-melody = \notes \relative c' @{
- \partial 8;
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|.";
+@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,
+}
+@end lilypond
+@end quotation
+@separate
+
-text = \lyrics @{
- The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri -- ver is flo -- wing down to the sea.
+Here is an example of the difference between relative mode and
+``normal'' (non-relative) mode:
+
+@quotation
+@example
+\relative a @{
+\clef bass
+ a d a e d c' d'
@}
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\relative a {
+\clef bass
+ a d a e d c' d'
+}
+@end lilypond
+@end quotation
+@separate
+
+@quotation
+@example
+\clef bass
+ a d a e d c' d'
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\clef bass
+ a d a e d c' d'
+@end lilypond
+@end quotation
+@separate
+
-accompaniment =\chords @{
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min @}
-\score @{
- \simultaneous @{
-% \accompaniment
- \context ChordNames \accompaniment
-
- \addlyrics
- \context Staff = mel @{
- \property Staff.noAutoBeaming = "1"
- \property Staff.automaticMelismata = "1"
- \melody
- @}
- \context Lyrics \text
- @}
- \midi @{ @}
- \paper @{ linewidth = 10.0\cm; @}
-@}
-@end example
-The result would look this@footnote{The titling and font size shown
-may differ, since the titling in this document is not generated by
-@file{ly2dvi}.}.
-@center @strong{The river is flowing}
-@center Traditional
-@mudela[center]
-\header {
- title = "The river is flowing";
- composer = "Traditional (?)";
-}
-\include "paper16.ly"
-melody = \notes \relative c' {
- \partial 8;
- \key c \minor;
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|.";
-}
-text = \lyrics {
- The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri -- ver is flo -- wing down to the sea.
-}
-accompaniment =\chords {
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min }
+@node Combining music into compound expressions
+@section Combining music into compound expressions
+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:
+
+@quotation
+@lilypond[fragment,verbatim]
+\simultaneous {
+ \context Staff = staffA { \clef violin c'' }
+ \context Staff = staffB { \clef bass c }
+}
+@end lilypond
+@end quotation
+
+
+In this example, @code{\simultaneous } indicates that both music
+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 @{ .. @}}.
+
+@code{\context} introduces a ``notation context''. To understand this
+concept, imagine that you are performing a piece of music. When you
+perform the music, you combine the symbols printed at a certain point
+with contextual information. For example, without knowing the current
+clef, and the accidentals in the last measure, it would be impossible
+to determine the pitch of a note. In other words, this information
+forms context that helps you decipher a score. LilyPond produces
+notation from music, so in effect, it does the inverse of reading
+scores. Therefore, it also needs to keep track of contextual
+information. This information is maintained in ``notation contexts.''
+There are several types of contexts, e.g. @code{Staff}, @code{Voice}
+and @code{Score}, but also @code{Lyrics} and
+@code{ChordNames}. Prepending @code{\context} to a chunk of music
+indicates what kind of context to use for interpreting it.
+
+By specifying different names (in this case @code{staffA} and
+@code{staffB}), two different contexts are created, leading to two
+staves. It does not matter which names they are given, as long as they
+are different. If they get the same name, the chunks of music are
+assumed to belong on the same staff, and will be printed like that.
+
+@separate
+
+We can now typeset a melody with two staves:
+
+@quotation
+@lilypond[verbatim,singleline]
\score {
- \simultaneous {
-% \accompaniment
- \context ChordNames \accompaniment
-
- \addlyrics
- \context Staff = mel {
- \property Staff.noAutoBeaming = "1"
- \property Staff.automaticMelismata = "1"
- \melody
- }
- \context Lyrics \text
- }
- \midi { }
- \paper { linewidth = 10.0\cm; }
+ \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 {}
}
-@end mudela
+@end lilypond
+@end quotation
-Again, we will dissect the file line by line.@example
+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,
- \header @{
-
-@end example
-Information about the music you are about to typeset goes into a
-@code{\header} block. The information in this block is not used by
-LilyPond, but it is included in the output. @file{ly2dvi} uses this
-information to print titles above the music.
-@example
+@quotation
+ 1
- title = "The river is flowing";
- composer = "Traditional (?)";
-@end example
-the @code{\header} block contains assignments. An assignment starts
-with a string. (which is unquoted, in this case). Then comes the
-equal sign `@code{=}'. After the equal sign comes the expression you
-want to store. In this case, you want to put in strings. The
-information has to be quoted here, because it contains spaces. The
-assignment is finished with a semicolon.@example
-
- \include "paper16.ly"
-
-@end example
-Smaller size for inclusion in a book.@example
+ 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; prepending it to a music expression yields
+a new expression.
+
+Like mathematical expressions, music expressions can be nested
+arbitrarily deep, e.g.
+@lilypond[verbatim,relative 1]
+ { c <c e>
+ < { e f } { c <b d> }
+ >
+ }
+@end lilypond
+
+
+@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
- melody = \notes \relative c' @{
-
-@end example
-The structure of the file will be the same as the previous one, a
-@code{\score} block with music in it. To keep things readable, we will
-give names to the different parts of music, and use the names to
-construct the music within the score block.
-@example
- \partial 8;
-@end example
-The piece starts with an anacrusis of one eighth.
+
+@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 (`@code{-}') and a
+single character:
+@quotation
+@lilypond[verbatim,relative 1]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
+@end quotation
+@separate
+
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(`@code{-}') and the digit to be printed:
+@c
+@lilypond[verbatim,relative 1]
+ 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
+@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-\!
+@end lilypond
+@end quotation
+@separate
+
+
+
+@cindex slur
+
+A slur is drawn across many notes, and indicates bound articulation
+(legato). The starting note and ending note are marked with a
+``@code{(}'' and a ``@code{)}'' respectively:
+
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+d4-( c16-)-( cis d e c cis d e-)-( d4-)
+@end lilypond
+@end quotation
+@separate
+@cindex slurs versus ties
+A slur is different from a tie. A tie simply makes the first note
+sound longer, and can only be used on pairs of notes with the same
+pitch. Slurs indicate the articulations of notes, and can be used on
+larger groups of notes. Slurs and ties are also nested in practice:
+@lilypond[fragment, relative=1]
+c2-~-( c8 fis fis4 ~ fis2 g2-)
+@end lilypond
+
+@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{\)}.
+
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
+@end lilypond
+@end quotation
+
+
+More information on fingering, articulation, slurs, phrasing slurs,
+and dynamics can be found in @ref{Fingering instructions},
+@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
+respectively.
+
+@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 <<c e g>>4 <<c f a>>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 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
+@end lilypond
+@end quotation
+
+@quotation
@example
- \key c \minor
+r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
@end example
-The key is C minor: we have three flats.
+@lilypond[relative 0, fragment]
+\slurUp
+r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
+@end lilypond
+@end quotation
+@separate
-@example
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|.";
-
-@end example
-We use explicit beaming. Since this is a song, we will turn automatic
-beams off, and use explicit beaming where needed.@example
+@menu
+* Basic rhythmical commands::
+* Commenting input files::
+@end menu
- @}
-
-@end example
-This ends the definition of @code{melody}. Note that there are no
-semicolons after assignments at top level.@example
+@node Basic rhythmical commands
+@subsection Basic rhythmical commands
+
+@cindex pickup
+@cindex anacruse
+@cindex upstep
+@cindex partial measure
+A pickup (or upstep) 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
+@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
+
+@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-)
+@end lilypond
+
+@noindent
+More information on grace notes, tuplets and upsteps are in @ref{Grace
+notes}, @ref{Tuplets} and @ref{Partial measures}.
+
+
+
+@node Commenting input files
+@subsection 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 is 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:
+
+@example
+ % 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
+
+
+
+
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
+
+@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
+
+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 @}
+@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-) }
+@end lilypond
+
+The lyrics can be set to these notes, combining both with the
+@code{\addlyrics} keyword:
+@example
+ \addlyrics
+ \notes @{ @dots{} @}
+ \context Lyrics @dots{}
+@end example
+
+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{ }
+}
+@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.
+@example
+ \lyrics @{ 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
+ c32
+ }
+ \context Lyrics \lyrics { I want to break free __ }
+ }
+ \paper{ linewidth = 9.0 \cm }
+}
+@end lilypond
- text = \lyrics @{
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables:
+@example
+ 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 }
+ }
-@end example
-Another identifier assignment. This one is for the lyrics.
-Lyrics are formed by syllables that have duration, and not by
-notes. To make LilyPond parse words as syllables, switch it into
-lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
-is a shorthand for @code{\sequential @{}. @example
-
- The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri- ver is flo- __ wing down to the sea.
- @}
+@end lilypond
+
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
+
+
+
+@node A lead sheet
+@section A lead sheet
+
+@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
+
+@noindent
+The result of @code{\chords} is a list of chords, and is equivalent
+to entering chords with @code{<<@dots{}>>}.
+
+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 }
+@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 }
+@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 @{ @}
+@}
+@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 }
+}
+@end lilypond
+
+
+A complete list of modifiers, and other options for layout are in the
+reference manual section @ref{Chords}.
+
+@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
+@example
+\score @{
+ @var{..music..}
+ \midi @{ \tempo 4=72 @}
+ \paper @{ @}
+@}
@end example
-The syllables themselves are separated by spaces. You can get syllable
-extenders by entering `@code{__}', and centered hyphens with
-`@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
-in length (hence the @code{4}), and use a feature to align the
-syllables to the music (which obviously isn't all quarter notes.)
+
+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.
+
+
+
+@node Titling
+@section Titling
+
+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,
@example
+ \header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+ @}
+
+ \score @{ @dots{} @}
+@end example
+
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex ly2dvi
+
+
+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''.
+
+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:
+
+
+@cindex Lily was here
+@cindex signature line
+@cindex tag line
- accompaniment =\chords @{
-
-@end example
-We'll put chords over the music. There is a special mode (analogous
-to @code{\lyrics} and @code{\notes} mode) where you can give the names
-of the chords you want, instead of the notes comprising the chord.
@example
+ \header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+ @}
+
+ \score @{ @dots{}
+ \header @{ piece = "Adagio" @}
+ @}
+ \score @{ @dots{}
+ \header @{ piece = "Menuetto" @}
+ @}
+@end example
- r8
-
-@end example
-There is no accompaniment during the anacrusis.@example
+More information on titling can be found in @ref{Invoking ly2dvi}.
- c2:3- f:3-.7
-
-@end example
-A chord is started by the tonic of the chord. The
-first one lasts a half note. An unadorned note creates a major
-triad, while a minor triad is wanted. @code{3-} modifies the third to
-be small. @code{7} modifies (adds) a seventh, which is small by default
-to create the @code{f a c es} chord. Multiple modifiers must be
-separated by a dot.@example
-
- d:min es4 c8:min r8
-
-@end example
-Some modifiers have predefined names, eg. @code{min} is the same as
-@code{3-}, so @code{d-min} is a minor @code{d} chord.@example
- c2:min f:min7 g:7^3.5 c:min @}
-
-@end example
-A named modifier @code{min} and a normal modifier @code{7} do not have
-to be separated by a dot. Tones from a chord are removed with chord
-subtractions. Subtractions are started with a caret, and they are
-also separated by dots. In this example, @code{g:7^3.5} produces a
-minor seventh. The brace ends the sequential music. @example
-
- \score @{
- \simultaneous @{
-
-@end example
-We assemble the music in the @code{\score} block. Melody, lyrics and
-accompaniment have to sound at the same time, so they should be
-@code{\simultaneous}.@example
+@node Single staff polyphony
+@section Single staff polyphony
- %\accompaniment
-
-@end example
-Chord mode generates notes grouped in @code{\simultaneous} music. If
-you remove the comment sign, you can see the chords in normal
-notation: they will be printed as note heads on a separate
-staff. @example
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
- \context ChordNames \accompaniment
-
-@end example
-Normally, the notes that you enter are transformed into note heads.
-The note heads alone make no sense, they need surrounding information:
-a key signature, a clef, staff lines, etc. They need @emph{context}. In
-LilyPond, these symbols are created by objects called `interpretation
-context'. Interpretation contexts only exist during a run of
-LilyPond. Interpretation contexts that are for printing music (as
-opposed to playing music) are called `notation context'.
-
-By default, LilyPond will create a Staff contexts for you. If you
-would remove the @code{%} sign in the previous line, you can see that
-mechanism in action.
-
-We don't want default contexts here, because we want names, not note
-heads. An interpretation context can also created upon explicit
-request. The keyword for such a request is @code{\context}. It takes
-two arguments. The first is the name of a interpretation context.
-The name is a string, it can be quoted with double quotes). The
-second argument is the music that should be interpreted in this
-context. For the previous line, we could have written @code{\context
-Staff \accompaniment}, and get the same effect.@example
-
- \addlyrics
-
-@end example
-The lyrics need to be aligned with the melody. This is done by
-combining both with @code{\addlyrics}. @code{\addlyrics} takes two
-pieces of music (usually a melody and lyrics, in that order) and
-aligns the syllables of the second piece under the notes of the
-first piece. If you would reverse the order, the notes would be
-aligned on the lyrics, which is not very useful. (Besides, it looks
-silly.)@example
-
- \context Staff = mel @{
-
-@end example
-This is the argument of @code{\addlyrics}. We instantiate a
-@code{Staff} context explicitly: should you chose to remove comment
-before the ``note heads'' version of the accompaniment, the
-accompaniment will be on a nameless staff. The melody has to be on a
-different staff as the accompaniment. This is accomplished by giving
-the melody staff a different name.@example
-
- \property Staff.noAutoBeaming = "1"
-
-@end example
-An interpretation context has variables that tune its behaviour. One
-of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
-true) LilyPond will not try to put automatic beaming on the current
-staff.@example
+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.
- \property Staff.automaticMelismata = "1"
-
-@end example
-Similarly, we don't want to print a syllable when there is
-a slur. This sets up the Staff context to signal slurs while
-@code{\addlyrics} is processed. @example
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{ .. @}}), and combining those simultaneously, separating the
+voices with @code{\\}:
- \melody
- @}
-
-@end example
-Finally, we put the melody on the current staff. Note that the
-@code{\property} directives and @code{\melody} are grouped in sequential
-music, so the property settings are done before the melody is
-processed. @example
+@example
+ < @{ a4 g2 f4-~ f4 @} \\
+ @{ r4 g4 f2 f4 @} >
+@end example
+@lilypond[relative 1]
+\context Staff < { a4 g2 f4-~ f4 } \\
+ { r4 g4 f2 f4 } >
+@end lilypond
+
+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
+
+Again, these expressions can be nested arbitrarily:
+
+@lilypond[fragment]
+<
+ \context Staff = staffA
+ \relative c''
+ < { a4 g2 f4-~ f4 } \\
+ { s4 g4 f2 f4 } >
+ \context Staff = staffB
+ < { \clef bass <<c g>>1 } \\
+ { f4 d e2 }
+ >
+>
+@end lilypond
+
+
+More features of polyphonic typesetting are in the notation manual
+in @ref{Polyphony}.
+
+@node Piano staves
+@section Piano staves
+
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
+
+Piano music is always typeset in two staves connected by a brace.
+Printing such a staff is done similar to the polyphonic example in
+@ref{Combining music into compound expressions}:
+@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
- \context Lyrics \text
-
-@end example
-The second argument of @code{\addlyrics} is the text. The text also
-should not land on a Staff, but on a interpretation context for
-syllables, extenders, hyphens etc. This context is called
-Lyrics.@example
+Here is a full-fledged example:
- @}
-
-@end example
-This ends @code{\simultaneous}.@example
+@lilypond[relative 0,fragment]
+\context PianoStaff
+ < \context Staff = up { \time 2/4
+ c4 c g' g }
+ \context Staff = down {
+ \clef bass c,, c' e c }
+ >
+@end lilypond
- \midi @{ @}
-
-@end example
-This makes the music go to a MIDI file. MIDI is great for
-checking music you enter. You listen to the MIDI file: if you hear
-something unexpected, it's probably a typing error. @code{\midi} is an
-`output definition', a declaration that specifies how to output music
-analogous to @code{\paper @{ @}}.@example
+More information on formatting piano music is in @ref{Piano music}.
- \paper @{ linewidth = 10.0\cm; @}
-
-@end example
-We also want notation output. The linewidth is short so the piece
-will be set in two lines. @example
+@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. Consider this input:
+@example
+\property Staff.autoBeaming = ##f
@end example
-End the score block.
+It 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
-@node Piano music, , , Tutorial
-@section Piano music
+@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
-Our third subject is a piece piano music. The fragment in the input
-file is a piano reduction of the G major Sinfonia by Giovanni Battista
-Sammartini. It was composed around 1740.
+@item a number, such as
+@example
+ \property Score.currentBarNumber = #20
+@end example
-@mudela[verbatim]
+@item a symbol, which is introduced by a quote character, as in
+@example
+ \property Staff.crescendoSpanner = #'dashed-line
+@end example
-\include "paper16.ly";
+@item a pair, which is also introduced by a quote character, like in
+the following statements, which set properties to the pairs (-7.5, 6)
+and (3, 4) respectively:
-viola = \notes \relative c' \context Voice = viola {
- <c4-\f g' c>
- \property Voice.verticalDirection = \down g'8. b,16
- s1 s2. r4
- g
-}
+@example
+ \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
+ \property Staff.timeSignatureFraction = #'(3 . 4)
+@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 most 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
-oboes = \notes \relative c'' \context Voice = oboe {
- \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
- \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
- <
- { \times 2/3 { a8 g c } \! c2 }
- \context Voice = oboeTwo {
- \stemdown
- \grace {
- \property Grace.verticalDirection = \down
- [f,16 g] }
- f8 e e2
- } >
- \stemboth
- \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
- [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
- [<c16( e> < )e8. g>] <c8 e,>
+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 prefixing @code{\once} to the
+@code{\property} statement, i.e.
+
+@example
+ \once \property Voice.Stem \set #'thickness = #3.0
+@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
+@ifhtml
+the
+@end ifhtml
+@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
+@item The @code{extra-offset} property, which
+@cindex @code{extra-offset}
+has a pair of numbers as value, moves around objects in the printout.
+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 unit of these
+offsets are staff-spaces. The @code{extra-offset} property 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
+
+@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, it 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,verbatim]
+\context Staff < {
+ \once \property Voice.Stem \set #'transparent = ##t
+ b8~ b8
+ } \\ {
+ b-[ g8-]
+ } >
+@end lilypond
+
+@item
+The @code{padding} property for objects with
+@cindex @code{padding}
+@code{side-position-interface} can be set to increase distance between
+symbols that are printed above or below notes. We only give an
+example; a more elaborate explanation is in @ref{Constructing a
+tweak}:
+
+@lilypond[relative 1]
+ c2-\fermata
+ \property Voice.Script \set #'padding = #3
+ b2-\fermata
+@end lilypond
+
+@end itemize
+
+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.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions.
+An identifier is assigned as follows:
+@example
+ namedMusic = \notes @{ @dots{}
+@end example
+
+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 thrice by using
+variable substitution:
+
+@lilypond[singleline,verbatim]
+seufzer = \notes {
+ dis'8 e'8
}
+\score { \notes {
+ \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.
+
+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:
+@example
+ \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}.
+
+
+@node An orchestral part
+@section An orchestral part
-hoomPah = \notes \transpose c' {
- c8 \translator Staff = top \stemdown
- c'8 \translator Staff = bottom \stemup }
+In orchestral music, all notes are printed twice: both 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
+variable. The contents of that variable is then used to generate
+both the part and the score.
-hoomPahHoomPah = { [\hoomPah \hoomPah] }
+It is convenient to define the notes in a special file, for example,
+suppose that the @file{horn-music.ly} contains the following part of a
+horn/bassoon duo.
+@example
+hornNotes = \notes \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
-bassvoices = \notes \relative c' {
- c4 g8. b,16
- \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
- \stemdown [c8 c'8] r4
- <g d'> r4
- < {\stemup r2 <e4 c'> <c8 g'> }
- \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
+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
+@}
+@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. The code @code{\transpose f c'} indicates that the
+argument, being @code{\hornNotes}, should be transposed by a fifth
+downwards: sounding @code{f} is denoted by notated @code{c'}, which
+corresponds with tuning of a normal French Horn in F. The
+transposition can be seen in the following output:
+
+@lilypond[singleline]
+\score {
+ \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:
+@example
+ 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:
+@example
+ \property Score.skipBars = ##t
+@end example
+Prepending the rest and the property setting above, leads to the
+following result:
+
+@lilypond[singleline]
+\score {\notes { \transpose f c' \relative c { \time 2/4
+\property 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{bassoonNotes}, in the
+file @file{bassoon-music.ly}:
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+\score @{
+ \simultaneous @{
+ \context Staff = hornStaff \hornNotes
+ \context Staff = bsnStaff \bassoonNotes
+ @} @}
+@end example
+This would lead to the simple score depicted below:
+
+@lilypond[singleline]
\score {
- \context PianoStaff \notes <
- \context Staff = top < \time 2/2;
- \context Voice = viola \viola
- \oboes
- >
- \context Staff = bottom < \time 2/2; \clef bass;
- \bassvoices
- >
- >
- \midi { }
- \paper {
- indent = 0.0;
- linewidth = 15.0 \cm; }
+ \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
+
+More in-depth information on preparing parts and scores is in the
+notation manual, in @ref{Orchestral music}.
+
+
+@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 contains also explanatory
+text, we will not comment 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:
+
+\begin@{lilypond@}
+ c'4
+\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 options by putting them in brackets:
+
+\begin[26pt,verbatim]@{lilypond@}
+ c'4 f16
+\end@{lilypond@}
+
+If you want to include large examples into the text, it is more
+convenient to put it in a separate file:
+
+\lilypondfile@{screech-boink.ly@}
+
+\end@{document@}
+@end example
+
+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'
+@var{lots of stuff deleted}
+Writing `out/lilbook.latex'
+$ cd out
+$ latex lilbook.latex
+@var{lots of stuff deleted}
+$ xdvi lilbook
+@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}.
+
+The result looks more or less like this:
+
+@separate
+
+In a lilypond-book document, you can freely mix music and text. For
+example:
+@lilypond
+\score {
+ \notes \relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+ }
+ \paper {
+ raggedright = ##t
+ }
}
-@end mudela
+@end lilypond
-If it looks like incomprehensible gibberish to you@dots{} Then you are
-right. The author has doctored this example to have as many quirks in
-one system as possible.@example
-viola = \notes \relative c' \context Voice = viola @{
-@end example
-In this example, you can see multiple parts on a staff. Each part is
-associated with one notation context. This notation context handles
-stems and dynamics (among others). The name of this context is
-@code{Voice}. For each part we have to make sure that there is
-precisely one Voice context@footnote{If @code{\context} would not
-have been specified explicitly, three @code{Voice} contexts would be
-created: one for each note in the first chord.}.@example
-<c4-\f g' c>
-@end example
-@code{<} and @code{>} are short hands for @code{\simultaneous @{} and
-@code{@}}. So the expression enclosed in @code{<} and @code{>} is a
-chord. @code{\f} places a forte symbol under the chord.@example
-\property Voice.verticalDirection = \down
-@end example
-@code{verticalDirection} is a property of the voice context. It
-controls the directions of stems, articulations marks and other
-symbols.
- If @code{verticalDirection} is set to @code{\down}
-(identifier for the integer -1) the stems go down,
-@code{\up} (identifier for the integer 1) makes the stems go up.@example
- g'8. b,16
-@end example
-Relative octaves work a little differently with chords. The starting
-point for the note following a chord is the first note of the chord. So
-the @code{g} gets an octave up quote: it is a fifth above the starting
-note of the previous chord (the central C).
+Notice that the music line length matches the margin settings of the
+document.
-@example
-s1 s2. r4
-@end example
-@code{s} is a `spacer' rest. It does not print anything, but it does
-have the duration of a rest. @example
-oboes = \notes \relative c'' \context Voice = oboe @{
-@end example
-Now comes a part for two oboes. They play homophonically, so we
-print the notes as one voice that makes chords. Again, we insure that
-these notes are indeed processed by precisely one context with
-@code{\context}.@example
-\stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
-@end example
-@code{\stemup} is an identifier reference. It is shorthand for
-@code{\property Voice.verticalDirection = \up}. If possible, you
-should use predefined identifiers like these for setting properties.
-Your input will be less dependent upon the implementation of LilyPond.
-@example
-\grace <e8( g> < )d4 f> <c2 e>
-@end example
-@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord. The slur started on the @code{e} of the chord
-will be attached to the next note.@footnote{LilyPond will squirm
-about unended Slurs. In this case, you can ignore the warning}.
-@example
-\times 2/3
-@end example
-Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the
-second argument is multiplied by the first argument. Triplets make
-notes occupy 2/3 of their notated duration, so in this case the
-fraction is 2/3. @example
-@{ <d8 \< f> <e g> <f a> @}
-@end example
-The piece of music to be `tripletted' is sequential music containing
-three notes. On the first chord (the @code{d}), a crescendo is started
-with @code{\<}.@example
-<
-@end example
-At this point, the homophonic music splits into two rhythmically
-different parts. We can't use a sequence of chords to enter this, so
-we make a `chord' of sequences to do it. We start with the upper
-voice, which continues with upward stems: @example
- @{ \times 2/3 @{ a8 g c @} \! c2 @}
-@end example
-The crescendo is ended at the half note by the escaped exclamation
-mark `@code{\!}'. @example
-\context Voice = oboeTwo @{
-\stemdown
-@end example
-We can't share stems with the other voice, so we have to create a new
-@code{Voice} context. We give it the name @code{oboeTwo} to distinguish
-it from the other context. Stems go down in this voice. @example
-\grace @{
-@end example
-When a grace section is processed, a @code{Grace} context is
-created. This context acts like a miniature score of its own. It has
-its own time bookkeeping, and you can make notes, beams, slurs
-etc. Here fiddle with a property and make a beam. The argument of
-@code{\grace} is sequential music.@example
-\property Grace.verticalDirection = \down
-[f,16 g] @}
-@end example
-Normally, grace notes are always stem up, but in this case, the upper
-voice interferes. We set the stems down here.
+If you have no @code{\score} block in the fragment,
+@code{lilypond-book} will supply one:
-As far as relative mode is concerned, the previous note is the
-@code{c'''2} of the upper voice, so we have to go an octave down for
-the @code{f}.
-@example
+@lilypond
+ c'4
+@end lilypond
- f8 e e2
-@} >
-@end example
-This ends the two-part section. @example
-\stemboth
-\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
-@end example
-@code{\stemboth} ends the forced stem directions. From here, stems are
-positioned as if it were single part music.
+In the example you see here, two things happened: a
+@code{score} block was added, and the line width was set to natural
+length. You can specify options by putting them in brackets:
-The bass has a little hoom-pah melody to demonstrate parts switching
-between staffs. Since it is repetitive, we use identifiers:@example
-hoomPah = \notes \transpose c' @{
-@end example
-Transposing can be done with @code{\transpose}. It takes two
-arguments; the first specifies what central C should be transposed to.
-The second is the to-be-transposed music. As you can see, in this
-case, the transposition is a no-op. Central C is transposed to
-central C.
-
-The purpose of this no-op is circumventing relative mode. Relative
-mode can not be used in conjunction with transposition, so relative
-mode will leave the contents of @code{\hoomPah} alone. We can use it
-without having to worry about getting the motive in a wrong
-octave@footnote{@code{hoomPah = \relative @dots{}} would be more
-intuitive to use, but that would not let me plug @code{\transpose}
-:-).}.@example
-c8 \translator Staff = top \stemdown
-@end example
-We assume that the first note will be put in the lower staff. After
-that note we switch to the upper staff with @code{\translator}. To be
-precise, this @code{\translator} entry switches the current voice to a
-@code{Staff} named @code{top}. So we have to name the upper staff
-`@code{top}'. Stem directions are set to avoid interfering with the
-oboe voices. @example
-c'8 \translator Staff = bottom \stemup @}
-@end example
-Then a note is put on the upper staff, and we switch again. We have
-to name the lower staff `@code{bottom}'. @example
-hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
-@end example
-Put two of these fragments in sequence, and beam them.@example
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
-\hoomPahHoomPah
-@end example
-Entering the bass part is easy: the hoomPahHoomPah variable is
-referenced four times.@example
-\context Voice = reallyLow @{\stemdown g2 ~ | g4 c8 @} >
-@end example
-After skipping some lines, we see @code{~}. This mark makes ties.@example
-\context PianoStaff
-@end example
-For piano music, a special context is needed to get cross staff
-beaming right. It is called @code{PianoStaff}.@example
-\context Staff = bottom < \time 2/2; \clef bass;
-@end example
-The bottom staff must have a different clef.@example
-indent = 0.0;
-@end example
-To make some more room on the line, the first (in this case the only)
-line is not indented. The line still looks is very cramped, but that is due
-to the format of this tutorial.
-
-This example shows a lot of features, but the organisation isn't
-perfect. For example, it would be less confusing to use a chord
-containing sequential music than a sequence of chords for the oboe
-parts.
-
-[TODO: demonstrate Hara-Kiri with scores and part extraction.]
-
-@node end of tutorial, , , Tutorial
-@section The end
-
-That's all folks. From here, you can either try fiddling with input
-files, or you can read the reference manual.
+@lilypond[26pt,verbatim]
+ c'4 f16
+@end lilypond
+
+If you want to include large examples into the text, it is more
+convenient to put it in a separate file:
+
+@lilypondfile{screech-boink.ly}
projects / lilypond.git / blobdiff