@c -*-texinfo-*-
-@c TODO: LilyPond Lilypond lilypond
+@c TODO: LilyPond LilyPond LilyPond
@node Tutorial
@chapter Tutorial
-LilyPond prints music from a specification that you, the user, supply.
-You have to give that specification using a textual @emph{language}.
-This chapter is a gentle introduction to that language.
-
-This tutorial will demonstrate how to use Lilypond by presenting
-examples of input along with resulting output. We will use English
-terms for notation. In case you are not familiar with those, you may
-consult the glossary that is distributed with LilyPond.
-
-@cindex examples, tutorial
-
-The examples discussed are included in the distribution, in the
-subdirectory @file{input/tutorial/}@footnote{When we refer
-to filenames, they are relative to the top directory of the source
-package. In binary installations you should look in your doc section,
-eg, @code{/usr/share/doc/lilypond1.3/examples/input/tutorial}
-@cindex file names
-}. We recommend that you experiment with writing Lilypond input
-yourself, to get a feel for how the program behaves.
-
@menu
-* Running LilyPond:: Getting started
+* First steps:: Music language of LilyPond
+* Simple legend:: Small table of music language symbols
+* Running LilyPond:: Printing music
* The first tune:: The first tune
* Lyrics and chords:: Lyrics and chords
-* More movements ::
+* More movements :: Joining separate pieces of music
* A piano excerpt:: Piano music
-* An orchestral score::
-* Other ways to run LilyPond::
-* Integrating text and music::
-* end of tutorial:: The end
+* An orchestral score:: Conductor's score and individual parts
+* Other ways to run LilyPond:: Other ways to run LilyPond
+* Integrating text and music:: Integrating text and music
+* End of tutorial:: The end
@end menu
-@node Running LilyPond
-@section Running LilyPond
+The music is described in a text file, using a simple music language.
+LilyPond reads that text file and generates music that you can print or
+view.
-Before we dive into describing the input language of LilyPond, we first
-show you through the procedure for getting notes on your screen and out
-of your printer.
+Therefore, creating music notation with LilyPond is done in two steps.
+Using a text editor, you write down the notes to print. Then, you run
+LilyPond to get your printed output.
-The first step is creating an input file. Using your favorite
-text-editor, create @file{test.ly} containing
+This tutorial starts with a small introduction to the LilyPond music
+language. After this first contact, we will show you how to run
+LilyPond to produce printed output; you should then be able to create
+your first sheets of music.
-@ignore
+The tutorial continues with a bit more elaborate example of real music.
+This piece introduces and explains some finer details of LilyPond.
+Then, a number of more complex examples follow, that will help you to
+produce most complex music with LilyPond.
-NOTE: if you're reading this, ie, the Texinfo source itself, test.ly
-should of course contain:
- \score{
- \notes { c'4 e' g' }
- }
+@c title?
-@end ignore
+@node First steps
+@section First steps
+
+@c @node Music language of LilyPond
+@c @section Music language of LilyPond
+
+This section shows how easy writing music with LilyPond actually is. If
+you have not seen LilyPond input source before, this section is for you.
+
+The next section has a table (see @ref{Simple legend}) of all symbols
+that are introduced here, you may want to keep an eye on that.
+
+Writing music with LilyPond is explained below by a number of small
+examples. Each example has a small piece of text; the LilyPond input
+that you should type, with the resulting music printed below it.
+You get a simple note by typing its note name, from @code{a} through
+@code{g}:
+
+@quotation
@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
+c d e f g a b
@end example
-@unnumberedsubsec Unix
-@cindex Unix, Running lilypond on
-@cindex ly2dvi
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\transpose c'' { c d e f g a b }
+@end lilypond
+@end quotation
+@separate
+
+The length of a note is specified by adding a number, ``@code{1}'' for a
+whole note, ``@code{2}'' for a halve note, and so on:
+
+@quotation
+@example
+a1 a2 a4 a16 a32
+@end example
+
+@c missing clef seems to raise more questions than actual pitch of notes,
+@c as these are snippets anyway
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+%\property Staff.Clef = \turnOff
+\transpose c'' { a1 a2 a4 a16 a32 }
+s16_" "
+@end lilypond
+@end quotation
+@separate
-On unix, you invoke ly2dvi to compile your lilypond source file (you can
-omit the @code{.ly}):
+If you don't specify a duration, the previous duration is used:
+@quotation
@example
-ly2dvi -P test
+a a a2 a
@end example
-You will see the following on your screen:
+@c missing clef seems to raise more questions than actual pitch of notes,
+@c as these are snippets anyway
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+%\property Staff.Clef = \turnOff
+\transpose c'' { a a a2 a }
+s16_" "
+@end lilypond
+@end quotation
+@separate
+
+A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
+(@texiflat{}) by adding ``@code{es}'':
+@quotation
@example
-GNU LilyPond 1.3.145
-Now processing: `/home/fred/ly/test.ly'
-Parsing...
-Interpreting music...[1]
-Preprocessing elements...
-Calculating column positions... [2]
-paper output to test.tex...
+cis1 ees fisis aeses
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\transpose c'' { cis1 ees fisis aeses }
+s16_" "
+@end lilypond
+@end quotation
+@separate
-Analyzing test.tex...
-Running LaTeX...
-Running dvips...
-PS output to test.ps...
-DVI output to test.dvi...
+Add a dot ``@code{.}'' after the duration to get a dotted note:
+@quotation
+@example
+a2. a4 a8. a16
@end example
-The results of the ly2dvi run are a ``DeVice Independent'' file
-(@file{test.dvi}) and a PostScript file (@file{test.ps}).
+@c missing clef seems to raise more questions than actual pitch of notes,
+@c as these are snippets anyway
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+%\property Staff.Clef = \turnOff
+\transpose c'' { a2. a4 a8. a16 }
+s16_" "
+@end lilypond
+@end quotation
+@separate
-@cindex DVI file
+The meter (or time signature) can be set with the ``@code{\time}'' command:
-@cindex Viewing music
-@cindex xdvi
-@cindex .dvi
+@quotation
+@example
+\time 3/4
+\time 6/8
+\time 4/4
+@end example
+
+@c a clef here may lead to confusion
+@lilypond[fragment]
+\property Staff.Clef = \turnOff
+\time 3/4
+s4_" "
+\time 6/8
+s4_" "
+\time 4/4
+s16_" "
+@end lilypond
+@end quotation
+@separate
-To view the @code{test.dvi} output, run Xdvi (you may omit the
-@code{.dvi}):
+The clef can be set using the ``@code{\clef}'' command:
+@c what is more common name treble or violin?
+@c in Dutch, its violin.
+@quotation
@example
-xdvi test
+\clef violin
+\clef bass
+\clef alto
+\clef tenor
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\clef violin
+s4_" "
+\clef bass
+s4_" "
+\clef alto
+s4_" "
+\clef tenor
+s16_" "
+@end lilypond
+@end quotation
+@separate
+
+From these commands and notes, a piece of music can be formed. A piece
+of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
+LilyPond then knows that music follows (and not lyrics, for example):
+
+@quotation
+@example
+\notes @{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2.
+@}
@end example
+@end quotation
+@separate
-@c FIXME: should we say anything on xdvi-gs interaction?
+At this point, the piece of music is ready to be printed. This is done
+by combining the music with a printing command.
+
+The printing command is the so-called ``@code{\paper}'' block. You will
+see later that the \paper block is necessary to customize all kinds of
+printing specifics. The music and the \paper block are combined by
+enclosing them in ``@code{\score @{ ... @}}''. This is what a full
+LilyPond source file looks like:
+
+@quotation
+@example
+\score @{
+ \notes @{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2.
+ @}
+ \paper @{ @}
+@}
+@end example
-You should see the following in a window next to some buttons.
@lilypond
\score {
- \notes { c'4 e' g' }
-}
+ \notes {
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2.
+ }
+ \paper { linewidth = 60 * \staffspace }
+}
@end lilypond
+@end quotation
+@separate
-When you're satisfied with the result, you can print the
-PostScript file:
+We continue with the introduction of the remaining musical constructs.
+
+@c maybe legend here?
+
+Rests are entered just like notes with the name ``@code{r}'':
+
+@quotation
@example
-lpr test.ps
+r2 r4 r8 r16
@end example
-If this does not make your printer produce a page of music, you should
-look into installing and configuring ghostscript. Refer to
-GhostScript's website at @uref{http://www.ghostscript.com}.
-@cindex GhostScript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-@cindex .ps
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.Clef = \turnOff
+\property Staff.TimeSignature = \turnOff
+r2 r4 r8 r16
+s16_" "
+@end lilypond
+@end quotation
+@separate
+@c Tim wants to move this quotes example just before the: quotes-don't-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). The central C is @code{c'}:
+
+@quotation
+@example
+c'4 c'' c''' \clef bass c c,
+@end example
-@unnumberedsubsec Windows
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+c'4 c'' c''' \clef bass c c,
+@end lilypond
+@end quotation
+@separate
+A tie is created by entering a tilde ``@code{~}'' between the notes to
+be tied. A tie between two notes means that the second note must not be
+played separately, but just makes the first note sound longer:
-On windows, you open a LilyPond shell, and then you invoke ly2dvi
-compile your lilypond source file, just like on Unix:
+@quotation
+@lilypond[fragment,verbatim]
+g'4 ~ g' a'2 ~ a'4
+@end lilypond
+@end quotation
+@separate
+The key signature is set with the command ``@code{\key}'':
+@quotation
@example
-ly2dvi -P test
-@end 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'
+@end lilypond
+@end quotation
-You will see the following on your screen:
-@c FIXME: leave this out, just refer to unix section?
-@c FIXME: commands run in dos shell: we can't redirect output
+@c bit on the long/complex/scary taste
+@c cheating a bit: two lines makes for a friendlier look
+This example shows notes, ties, octave marks, and rests in action.
+Don't worry about all the quotes.
+
+@quotation
@example
-GNU LilyPond 1.3.150
-Now processing: `/home/tim/ly/test.ly'
-Parsing...
-Interpreting music...[1]
-Preprocessing elements...
-Calculating column positions... [2]
-paper output to test.tex...
-
-This is TeX, Version 3.14159 (MiKTeX 2)
-LaTeX2e <2000/06/01>
-Babel <v3.6Z> and hyphenation patterns for english, french, german, ngerman, du
-mylang, nohyphenation, loaded.
-
-(test.latex (C:\cygwin\usr\windows\MiKTeX\tex\latex\base\article.cls
-Document Class: article 2000/05/19 v1.4b Standard LaTeX document class
-(C:\cygwin\usr\windows\MiKTeX\tex\latex\base\size10.clo))
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\geometry.sty
-(C:\cygwin\usr\windows\MiKTeX\tex\latex\graphics\keyval.sty))
-(C:\cygwin\usr\windows\MiKTeX\tex\latex\base\inputenc.sty
-(C:\cygwin\usr\windows\MiKTeX\tex\latex\base\latin1.def))
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\titledefs.tex)
-No file test.aux.
-(test.tex
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\lilyponddefs.tex
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\lilypond-latex.tex
-LaTeX definitions)
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\feta20.tex)
-(C:\cygwin\usr\lilypond-1.3.150.jcn2\share\lilypond\tex\lily-ps-defs.tex)
-[footer empty]))
-Overfull \hbox (15.0pt too wide) in paragraph at lines 20--24
-[] $[]$
-
-Overfull \vbox (0.7539pt too high) has occurred while \output is active
-[1] (test.aux) )
-(see the transcript file for additional information)
-Output written on test.dvi (1 page, 4292 bytes).
-Transcript written on test.log.
-This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
-' TeX output 2001.04.25:0015' -> test.ps
-<texc.pro><special.pro>. [1]
-Running LilyPond...
-Analyzing test.tex...
-PS output to test.ps...
-DVI output to test.dvi...
-@end example
-
-To view the @code{test.dvi} output, run Yap
-
-@example
-yap test
-@end example
-
-You should see the following in a window
+\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 @{ @}
+@}
+@end example
+
@lilypond
\score {
- \notes { c'4 e' g' }
-}
+ \notes {
+ \time 4/4
+ \clef violin
+ \key d \minor
+ r4 r8 d''8 cis''4 e''
+ d''8 a'4. ~ a' b'8
+ cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
+ cis''2 r2
+ }
+ \paper { linewidth = 50*\staffspace }
+}
+@end lilypond
+@end quotation
+
+@c accidentals...
+There are some interesting points to note in this example. Firstly,
+accidentals (sharps and flats) don't have to be marked explicitly: you
+just enter the note name, and LilyPond determines whether or not to
+print an accidental. Secondly, bar lines and beams are drawn
+automatically. Thirdly, LilyPond calculates line breaks for you; it
+doesn't matter where you make new lines in the source file.
+
+The example also indicates that a piece of music written in a high
+register needs lots of quotes. This makes the input a bit unreadable,
+and is therefore also a potential source of errors.
+
+@separate
+
+The solution is to use ``relative octave'' mode. In practice, most
+music is entered using this mode.
+
+To use relative mode, add @code{\relative} before the piece of music.
+You must also give a note from which relative starts, in this case
+@code{c''}.
+
+@c In relative ocatave mode, quotes are used to mark large jumps in the
+@c melody. Without any quotes or commas, the interval between a note and
+@c its predecessor is assumed to be a fourth or less. Quotes and commas
+@c add octaves in up and down direction.
+
+If you type no octaviation quotes, relative mode chooses the note that
+is closest to the previous one, which is often just the one you need.
+@c don't use commas or quotes in this sentence
+For example: @code{c f} goes up; @code{c g} goes down:
+
+@quotation
+@example
+\relative c'' @{
+ c f c g c
+@}
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\relative c'' {
+ c f c g c
+}
+@end lilypond
+@end quotation
+@separate
+
+@c needed better, maybe even redundant explanation
+@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
+@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
+You can make a large interval by adding octaviation quotes. Note that
+quotes or commas do not determine the absolote height of a note;
+the height of a note is relative to the previous one.
+@c don't use commas or quotes in this sentence
+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:
+
+@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
+
+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
+
+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
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+a8(\( ais b ) c cis2 b'2 a4 cis, \) c
+@end lilypond
+@end quotation
+@separate
+
+Beams are drawn automatically, but if you don't like the choices, you
+can enter beams by hand. Surround the notes to be grouped with @code{[}
+and @code{]}:
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+[a8 ais] [d es r d]
+@end lilypond
+@end quotation
+@separate
+
+To print more than one staff, each piece of music that makes up a staff
+is marked by adding @code{\context Staff} before it. These staffs can
+be grouped inside @code{<} and @code{>}, as is demonstrated here:
+
+@quotation
+@lilypond[fragment,verbatim]
+<
+ \context Staff = staffA { \clef violin c'' }
+ \context Staff = staffB { \clef bass c }
+>
+@end lilypond
+@end quotation
+
+In this example, @code{staffA} and @code{staffB} are names that are
+given to the staffs. For now, it doesn't matter what names you give, as
+long as each staff has a unique name.
+
+@separate
+
+We can typeset a melody with two staffs now:
+
+@quotation
+@lilypond[verbatim]
+\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 {}
+}
+@end lilypond
+@end quotation
+
+Notice that the time signature is specified in one melody staff only
+(the top staff), but is printed on both. LilyPond knows that the time
+signature should be the same for all staffs.
+
+@separate
+
+Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
+@quotation
+@lilypond[verbatim,relative 1]
+c-. c-- c->
+@end lilypond
+@end quotation
+@separate
+
+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
+
+Crescendi are started with the commands @code{\<} and @code{\>}. The
+command @code{\!} finishes a crescendo on the following.
+@quotation
+@lilypond[verbatim,relative 1]
+c2\< \!c2-\ff \>c2 \!c2
+@end lilypond
+@end quotation
+@separate
+
+Chords can be made by surrounding notes with @code{<} and @code{>}:
+@quotation
+@lilypond[relative 0, fragment,verbatim]
+r4 <c e g> <c f a>
+@end lilypond
+@end quotation
+@separate
+
+@ignore
+@c te diepzinnig?
+@c hmm, te losjes, iig
+In general, @code{ < @var{stuff} > } is used when @var{stuff} all
+happens at the same time, like in chords, or (like in the two-staff
+example above) in a bunch of stacked staffs.
+@end ignore
+
+Of course, you can combine beams and ties with chords. Notice that
+beam and tie markings are placed outside the chord markers:
+@quotation
+@lilypond[relative 0, fragment,verbatim]
+r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
+@end lilypond
+@end quotation
+
+When you want to combine chords with slurs and dynamics, an annoying
+technical detail crops up: you have type these commands next to the
+notes, which means that they have to be inside the @code{< >}:
+
+@quotation
+@lilypond[relative 0, fragment,verbatim]
+r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
+@end lilypond
+@end quotation
+@separate
+
+A nasty technical detail also crops up when you start a score with a
+chord:
+
+@quotation
+@lilypond[verbatim,singleline]
+\score { \notes <c'1 e'1> }
+@end lilypond
+@end quotation
+@separate
+
+The program can not guess that you want the notes on only one staff. To
+force the chord on a staff, add @code{\context Staff} like this:
+
+@quotation
+@lilypond[verbatim,singleline]
+\score { \notes \context Staff <c'1 e'1> }
+@end lilypond
+@end quotation
+@separate
+
+
+
+
+@ignore
+[TODO add some more here
+
+* lyrics, chords (?)
+
+* \header
+
+* identifiers?
+
+]
+@end ignore
+
+This is the end of the simple tutorial. You know the basic ingredients
+of a music file, so this is the right moment to try your at hand at
+doing it yourself: try to type some simple examples, and experiment a
+little.
+
+When you're comfortable with the basics, then you might want to read the
+rest of this chapter. It also a manual in tutorial-style, but it is much
+more in-depth. It will also be very intimidating if you're not familiar
+with the basics. It deals with some of the more advanced features of
+LilyPond. Topics include lyrics, chords, orchestral scores and parts,
+fine tuning output, polyphonic music, and integrating text and music.
+
+
+@c refer to this section
+@node Simple legend
+@section Simple legend
+
+
+@c need texinfo-4.0a or later for this
+
+
+@c both Tim and my father came independently with a request for a
+@c `legend' like this.
+
+@c what should be in it?
+
+
+
+@quotation
+@multitable @columnfractions .10 .20 .40
+
+@item @code{[]}
+@tab beam
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+[a8 b]
+@end lilypond
+
+@item @code{~}
+@tab tie
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+d ~ d
+@end lilypond
+
+@item @code{()}
+@tab slur
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+c( d )e
+@end lilypond
+@item @code{'}
+@tab raise octave
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+a a'
+@end lilypond
+
+@item @code{,}
+@tab lower octave
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+c c,
+@end lilypond
+
+@item @code{<>}
+@tab chord
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+\context Voice { <a c> }
+@end lilypond
+
+@item @code{\< \!}
+@tab crescendo
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+a\< a \!a
+@end lilypond
+
+@item @code{\> \!}
+@tab decrescendo
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.noAutoBeaming = ##t
+\property Staff.Clef = \turnOff
+a\> a \!a
@end lilypond
-@c FIXME: talk about newer Yap versions, proper gs installation?
-When you're satisfied with the result, you can print from within Yap
-(File/Print). Note that Yap may not display embedded PostScript symbols
-such as beams and slurs. Don't worry, they'll be printed anyway.
+@end multitable
+@end quotation
+
+
+
+@node Running LilyPond
+@section Running LilyPond
+
+You write music with LilyPond as follows: first you edit a text file
+containing a description of the notes. Then you run LilyPond on the
+file. This leaves you with an output file, which you can view or print.
+
+In this section we explain how to run LilyPond, and view or print the
+output. If you have not used LilyPond before, want to test your setup
+of LilyPond, or try to run an example file yourself, then read this
+section.
+
+The instructions that follow are for running LilyPond on Unix-like
+systems. Some additional instructions for running LilyPond on Windows
+are given at the end of this section.
+
+You begin with opening a terminal window, and start up a text editor.
+For example, open an xterm and execute @code{joe}. In your text editor,
+enter the following input, and save the file as @file{test.ly}:
+
+@quotation
+@example
+\score @{
+ \notes @{ c'4 e' g' @}
+@}
+@end example
+@end quotation
+
+@cindex ly2dvi
+
+@c now this is weird, running ly2dvi to run LilyPond
+@c (therefore name change proposal)
+
+To run LilyPond, you invoke ly2dvi to compile your LilyPond source file:
+
+@quotation
+@example
+ly2dvi -P test.ly
+@end example
+@end quotation
-You can also print the PostScript file directly from the
-command line using GSview:
+You will see the following on your screen:
+@quotation
@example
-gsview32 /s test.ps
+GNU LilyPond 1.4.0
+Now processing: `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+ @emph{ ... more interesting stuff ... }
+PS output to `test.ps'...
+DVI output to `test.dvi'...
@end example
+@end quotation
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+The results of the ly2dvi run are two files, @file{test.dvi} and
+@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
+You can view the PS file using the program ghostview. If a version of
+ghostview is installed on your system, one of these commands will
+produce a window with some music notation on your screen:
+@c eeek
+@quotation
+@example
+ gv test.ps
+ ghostview test.ps
+ ggv test.ps
+ kghostview test.ps
+@end example
+@end quotation
+If you are satisfied with the looks of the music displayed on your
+screen, you can print the PS file by clicking File/Print inside
+ghostview.
+
+The DVI file (@file{test.dvi}) contains the same sheet music in a
+different format. DVI files are more easily processed by the computer,
+so viewing them usually is quicker. Execute @code{xdvi test.dvi}
+to view the DVI file.
+
+If your DVI viewer does not have a "Print" button, you can print the
+file by executing @code{lpr test.ps}.
+
+@c volgende alinea schrappen?
+
+If you can't get the examples to print, then you should look into
+installing and configuring ghostscript. Refer to GhostScript's website
+at @uref{http://www.ghostscript.com}.
+
+@cindex GhostScript
+@cindex @code{lpr}
+@cindex Printing output
+@cindex PostScript
+
+@unnumberedsubsec Windows users
+Windows users start the terminal by clicking on the LilyPond icon.
+Notepad is sufficient for editing the LilyPond file. Viewing the PS file
+can be done with @code{gsview32 test.ps}. Viewing DVI files can be done
+with @code{yap test.dvi}. The "print" button in Yap will print files.
+You can also print from the command line by executing @code{gsview32 /s
+test.ps}
@node The first tune
@section The first tune
+This tutorial will demonstrate how to use Lilypond by presenting
+examples of input along with resulting output. We will use English
+terms for notation. In case you are not familiar with those, you may
+consult the glossary that is distributed with LilyPond.
+
+The examples discussed are included in the distribution, in the
+subdirectory @file{input/tutorial/}@footnote{When we refer to filenames,
+they are relative to the top directory of the source package. }
+
To demonstrate what LilyPond input looks like, we start off with a
full-fledged, yet simple example. It is a convoluted version
of the famous minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
@lilypond[verbatim]
% all text after a percent sign is a comment
-% and is ignored by Lilypond
+% and is ignored by LilyPond
\include "paper16.ly"
\score {
\notes
\bar "|."
}
\paper {
- % standard settings are too wide for a book
- linewidth = 14.0 \cm
+ % standard settings are too big and wide for a book
+ indent = 1.0 \cm
+ linewidth = 15.0 \cm
}
}
@end lilypond
@separate
@example
% all text after a percent sign is a comment
- % and is ignored by Lilypond
+ % and is ignored by LilyPond
@end example
-The percent sign, @code{%}, introduces a line comment. You can also
-comment out a block of several lines, by enclosing them in
-@code{%@{} and @code{%@}}.
+Percent signs introduce comments: everything after a percent sign is
+ignored. You can use this to write down mental notes to yourself. You
+can also make longer comments by enclosing text in @code{%@{} and
+@code{%@}}.
@cindex comment
@cindex block comment
@cindex line comment
@cindex @code{\include}
@cindex point, printer's
@cindex staff size setting
-By default, LilyPond will typeset the music in a size such that each
-staff is 20 point@footnote{A point is the standard measure of length for
-printing; one point is 1/72.27 inch.} high. We want smaller
-output (16 point staff height), so we must import the settings for that
-size, which is done here.
+By default, LilyPond will typeset the music in a size such that each
+staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
+(16 point staff height), so we must import the settings for that size,
+which is done here.
@separate
@example
@end example
So far, no notes were chromatically altered. Here is the first one that
-is: @code{fis}. Lilypond by default uses Dutch@footnote{Note names are
+is: @code{fis}. LilyPond by default uses Dutch@footnote{Note names are
available in several languages, but we find the Dutch names quite
convenient.} note names, and ``Fis'' is the Dutch note name for ``F
sharp''. However, there is no sharp sign in the output. The program
@end example
@cindex augmentation dot
-@cindex dot
-A period adds an augmentation dot to the note.
+@cindex dotted note
+A period adds a dot to the note.
@separate
@example
@example
\paper @{
- linewidth = 14.0\cm
+ % standard settings are too big and wide for a book
+ indent = 1.0\cm
+ linewidth = 15.0\cm
@}
@end example
some calculations, a @file{.tex} is produced. The contents
of this file are very low-level instructions.
-For example, the following file (@file{miniatures.ly})
+For example, the following file (@file{miniatures.ly})
@example
\version "1.3.124"
-\header @{ title = "Two miniatures" @}
+\header @{
+ title = "Two miniatures"
+ tagline = "small is beautiful"
+@}
#(set! point-and-click line-column-location)
@end lilypond
This file is produced by ly2dvi in a few stages, with the help of text
-formatting tools. LilyPond produces two output files, @file{miniatures.tex}
-and @file{miniatures-1.tex}. They both look like this:
-
-@example
- ...
- \placebox@{-5 \outputscale @}%
- @{ 8.7229 \outputscale @}%
- @{\magfontWXGEomMMBo\char90 @}%
-
- \placebox@{-4 \outputscale @}%
- @{ 81.0647 \outputscale @}%
- ...
-@end example
-
-@file{ly2dvi} looks at what output LilyPond produces, and generates a
-file called @file{ly2dvi.out.tex}. This file contains formatting
-instructions for the title and page layout. A fragment might look like
-
-@example
-
- \def\lilypondopus@{Opus 1.@}
- \def\lilypondpiece@{Up@}
- \def\mustmakelilypondtitle@{@}
- \input miniatures.tex
- \def\lilypondtitle@{Two miniatures@}
-
-@end example
-
-@file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
-built on top of @TeX{}. It's very popular in the academic world. If LaTeX
-is successful, this will produce a @file{.dvi} file, containing both the
-titling and the actual music. @code{ly2dvi} completes its task by
-deleting the two temporary files, leaving only @file{miniatures.dvi}.
+formatting tools. LilyPond produces two output files,
+@file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain
+only graphical music notation. @file{ly2dvi} looks at what output
+LilyPond produces, and adds page layout and titling to those files. The
+result is a DVI file called @file{miniatures.dvi}.
Next, now we'll look at the example line by line to explain new things.
@separate
@example
- \header @{ title = "Two miniatures" @}
+ \header @{
+ title = "Two miniatures" @}
@end example
This sets the titling information for the entire file.
-
+@separate
+@example
+ tagline = "small is beautiful"
+@end example
+A signature line is printed at the bottom of the last page.
+ This signature is produced from the @code{tagline} field of
+@code{\header}. Many people find the default "Lily was here,
+@var{version number}" too droll. If that is the case, assign
+something else to @code{tagline}, as shown above.
@separate
@example
#(set! point-and-click line-column-location)
large files: if you're digitizing existing music, you have to
synchronize the .ly file, the sheet music on your lap and the sheet
music on the screen. The point-and-click mechanism makes it easy to
-find the origin of an error in the .ly file: when you view the file with
+find the origin of an error in the LY file: when you view the file with
Xdvi and click on a note, your editor will jump to the spot where that
note was entered. For more information, see @ref{Point and click}.
When you're copying music from existing sheet music, relative octaves
are probably the easiest to use: it's less typing work and errors are
-easily spotted. However, if you write LilyPond input, either by hand
-(ie. composing) or by computer, absolute octaves are probably less work.
+easily spotted. However, if you write LilyPond input directly, either by
+hand (i.e. composing) or by computer, absolute octaves are easier to use.
@separate
This file will be used both for producing the score and the separate
parts.
-If you were to run lilypond on this file, no printable output would be
+If you were to run LilyPond on this file, no printable output would be
produced.
@example
Thirdly, if you want to do special things with your output, you can run
-invoke lilypond directly:
+invoke LilyPond directly:
@example
lilypond test.ly
@end example
hand, simply by importing a PostScript figure into your wordprocessor.
However, there is a also an automated procedure:
-If you use La@TeX{} or texinfo, you can mix text and lilypond code. A
+If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A
script called @code{lilypond-book} will extract the music fragments, run
-lilypond on them, and put back the resulting notation. lilypond-book is
+LilyPond on them, and put back the resulting notation. lilypond-book is
described fully in @ref{lilypond-book}, but here we show a small
example. Since the example also contains explanatory text, we won't
comment on the contents.
c'4 f bes es
\end@{lilypond@}
-\texttt@{verbatim@} also shows the lilypond code, \texttt@{11pt@} selects
+\texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
the default music size, \texttt@{fragment@} adds a score block,
\texttt@{relative@} uses relative mode for the fragment, and
\texttt@{intertext@} specifies what to print between the
c'4 f bes es
@end lilypond
-@code{verbatim} also shows the lilypond code, @code{11pt} selects
+@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
@lilypondfile[printfilename]{sammartini.ly}
The @code{printfilename} option adds the file name to the output.
-@node end of tutorial
-@section The end
+@node End of tutorial
+@section End of tutorial
That's all folks. From here, you can either try fiddling with input
files, or you can read the reference manual. You can find more example
files in @file{input} and @file{input/test}. You can also look at some
-real music. Have a look at the @uref{Mutopia project,
-http://www.mutopiaproject.org}.
+real music. The website @uref{http://www.mutopiaproject.org} has many
+examples of real music typeset by LilyPond.
projects / lilypond.git / blobdiff