Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@include included/generating-output.itexi
-@ignore
-Tutorial guidelines: (different from policy.txt!)
-- unless you have a really good reason, use either
- @lilypond[verbatim,quote]
- or
- @lilypond[verbatim,quote,relative=2]
-
- Don't use any other relative=X commands.
-
-- use "aes" and "ees" instead of "as" and "es". I know it's not
- correct Dutch naming, but let's not confuse people with this
- until we get to the Basic notation chapter.
+@c \version "2.19.21"
-- Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
- portions of the tutorial.
-
-@end ignore
+@node Tutorial
+@chapter Tutorial
-
-@node Common notation
-@chapter Common notation
-
-This tutorial starts with an introduction to the LilyPond music
-language and explains how to produce printed music. After this first
-contact we will explain how to create beautiful printed music
-containing common musical notation.
+This chapter gives a basic introduction to working with LilyPond.
@menu
-* Single staff notation::
-* Multiple notes at once::
-* Songs::
-* Final touches::
+* Compiling a file::
+* How to write input files::
+* Dealing with errors::
+* How to read the manuals::
@end menu
+@node Compiling a file
+@section Compiling a file
-@node Single staff notation
-@section Single staff notation
-
-This section introduces common notation that is used for one voice
-on one staff.
+This section introduces @qq{compiling}---the processing of
+LilyPond input files (written by you) to produce output files.
@menu
-* Accidentals and key signatures::
-* Ties and slurs::
-* Articulation and dynamics::
-* Adding text::
-* Automatic and manual beams::
-* Advanced rhythmic commands::
+* Entering input::
+* MacOS X::
+* Windows::
+* Command-line::
@end menu
+@node Entering input
+@subsection Entering input
-@node Accidentals and key signatures
-@subsection Accidentals and key signatures
-
-@subheading Accidentals
-
-@cindex accidentals
-@cindex accidentals and key signatures
-@cindex sharp
-@cindex double sharp
-@cindex sharp, double
-@cindex flat
-@cindex double flat
-@cindex flat, double
-
-@funindex es
-@funindex is
-@funindex eses
-@funindex isis
-
-Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
-@rglos{double flat}, @rglos{accidental}.
-
-A @notation{sharp} pitch is made by adding @code{is} to the name,
-and a @notation{flat} pitch by adding @code{es}. As you might
-expect, a @notation{double sharp} or @notation{double flat} is
-made by adding @code{isis} or @code{eses}. This syntax is derived
-from note naming conventions in Nordic and Germanic languages,
-like German and Dutch. To use other names for
-@notation{accidentals}, see @ruser{Note names in other languages}.
-
-@lilypond[verbatim,quote,relative=2]
-cis1 ees fisis, aeses
-@end lilypond
-
-@cindex key signature, setting
-@subheading Key signatures
-
-@cindex key signature
-@cindex major
-@cindex minor
-@cindex accidentals and key signature
-@cindex content vs. layout
-@cindex layout vs. content
-
-@funindex \key
-@funindex key
-@funindex \major
-@funindex major
-@funindex \minor
-@funindex minor
-
-Music Glossary: @rglos{key signature}, @rglos{major},
-@rglos{minor}.
-
-The @notation{key signature} is set with the command @code{\key}
-followed by a pitch and @code{\major} or @code{\minor}.
-
-@lilypond[verbatim,quote,relative=2]
-\key d \major
-a1
-\key c \minor
-a
-@end lilypond
-
-@smallspace
-
-@subheading Warning: key signatures and pitches
-
-Music Glossary: @rglos{accidental}, @rglos{key signature},
-@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
-@rglos{transposition}.
-
-To determine whether to print an @notation{accidental}, LilyPond
-examines the pitches and the @notation{key signature}. The key
-signature only affects the @emph{printed} accidentals, not the
-note's @notation{pitch}! This is a feature that often causes
-confusion to newcomers, so let us explain it in more detail.
-
-LilyPond makes a sharp distinction between musical content and
-layout. The alteration (@notation{flat}, @notation{natural sign} or
-@notation{sharp}) of a note is part of the pitch, and is therefore
-musical content. Whether an accidental (a @emph{printed} flat,
-natural or sharp sign) is printed in front of the corresponding
-note is a question of layout. Layout is something that follows
-rules, so accidentals are printed automatically according to those
-rules. The pitches in your music are works of art, so they will
-not be added automatically, and you must enter what you want to
-hear.
-
-In this example:
-
-@lilypond[verbatim,quote,relative=2]
-\key d \major
-d cis fis
-@end lilypond
-
-@noindent
-No note has a printed accidental, but you must still add
-@code{is} and type @code{cis} and @code{fis} in the input file.
-
-The code @code{b} does not mean @qq{print a black dot just on
-the middle line of the staff.} Rather, it means @qq{there is a
-note with pitch B-natural.} In the key of A-flat major, it
-@emph{does} get an accidental:
-
-@lilypond[verbatim,quote,relative=2]
-\key aes \major
-b
-@end lilypond
-
-Adding all alterations explicitly might require a little more
-effort when typing, but the advantage is that
-@notation{transposing} is easier, and accidentals can be printed
-according to different conventions. For some examples how
-accidentals can be printed according to different rules, see
-@ruser{Automatic accidentals}.
-
-
-@seealso
-Notation Reference: @ruser{Note names in other languages},
-@ruser{Accidentals}, @ruser{Automatic accidentals},
-@ruser{Key signature}.
-
-Music Glossary: @rglos{Pitch names}.
-
-
-@node Ties and slurs
-@subsection Ties and slurs
+@cindex compiling
+@cindex first example
+@cindex example, first
+@cindex case sensitive
-@cindex tie
-@cindex slur
-@cindex slur, phrasing
-@cindex phrasing slur
-
-@funindex ~
-@funindex ( ... )
-@funindex \( ... \)
-
-@subheading Ties
-
-
-Music Glossary: @rglos{tie}.
-
-A @notation{tie} is created by appending a tilde @code{~} to the
-first note being tied.
-
-@lilypond[verbatim,quote,relative=2]
-g4~ g c2~
-c4 ~ c8 a8 ~ a2
-@end lilypond
+@menu
+* Producing output::
+@end menu
-@subheading Slurs
+@qq{Compiling} is the term used for processing an input file in
+LilyPond format to produce output file(s). Output files are
+generally PDF (for printing or viewing), MIDI (for playing), and
+PNG (for online use). LilyPond input files are simple text files.
+This example shows a simple input file:
-Music Glossary: @rglos{slur}.
+@example
+\version "@w{@version{}}"
+@{
+ c' e' g' e'
+@}
+@end example
-A @notation{slur} is a curve drawn across many notes. The
-starting note and ending note are marked with @code{(} and
-@code{)} respectively.
+The graphical output is:
-@lilypond[verbatim,quote,relative=2]
-d4( c16) cis( d e c cis d) e( d4)
+@c in this case we don't want verbatim
+@lilypond[quote]
+{
+ c' e' g' e'
+}
@end lilypond
-@subheading Phrasing slurs
+@warning{Notes and lyrics in LilyPond input must always be
+surrounded by @w{@strong{@{ curly braces @}}}. The braces
+should also be surrounded by a space unless they are at the
+beginning or end of a line to avoid ambiguities. They may
+be omitted in some examples in this manual, but don't forget them
+in your own music! For more information about the display of
+examples in the manual, see @ref{How to read the manuals}.}
-Music Glossary: @rglos{slur}, @rglos{phrasing}.
+In addition, LilyPond input is @strong{case sensitive}.
+@w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
+produce an error message.
-Slurs to indicate longer @notation{phrasing} can be entered with
-@code{\(} and @code{\)}. You can have both @notation{slurs}
-and phrasing slurs at the same time, but you cannot have
-simultaneous slurs or simultaneous phrasing slurs.
-
-@lilypond[verbatim,quote,relative=2]
-a8(\( ais b c) cis2 b'2 a4 cis,\)
-@end lilypond
@smallspace
-@cindex slurs versus ties
-@subheading Warnings: slurs vs. ties
+@node Producing output
+@unnumberedsubsubsec Producing output
-Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
+@cindex PDF file
+@cindex viewing music
+@cindex text editors
-A @notation{slur} looks like a @notation{tie}, but it has a
-different meaning. A tie simply makes the first note longer, and
-can only be used on pairs of notes with the same pitch. Slurs
-indicate the @notation{articulation} of notes, and can be used on
-larger groups of notes. Slurs and ties can be nested.
+The method of producing output depends on your operating system
+and the program(s) you use.
-@lilypond[verbatim,quote,relative=2]
-c2~( c8 fis fis4 ~ fis2 g2)
-@end lilypond
-
-
-@seealso
-Notation Reference: @ruser{Ties}, @ruser{Slurs},
-@ruser{Phrasing slurs}.
+@itemize
+@item
+@ref{MacOS X, @sourceimage{logo-macosx,,,}}
+@ref{MacOS X, MacOS X} (graphical)
-@node Articulation and dynamics
-@subsection Articulation and dynamics
+@item
+@ref{Windows, @sourceimage{logo-windows,,,}}
+@ref{Windows, Microsoft Windows} (graphical)
+@item
+@ref{Command-line, @sourceimage{logo-linux,,,}
+@sourceimage{logo-freebsd,,,}
+@sourceimage{logo-macosx,,,}
+@sourceimage{logo-windows,,,}
+}
+@ref{Command-line, All operating systems} (command-line)
-@subheading Articulations
-
-@cindex articulation
-@cindex accent
-@cindex staccato
-
-Music Glossary: @rglos{articulation}.
-
-Common @notation{articulations} can be added to a note using a
-dash @code{-} and a single character:
+@end itemize
-@lilypond[verbatim,quote,relative=2]
-c-. c-- c-> c-^ c-+ c-_
-@end lilypond
+There are several other text editors available with specific
+support for LilyPond. For more information, see
+@rweb{Easier editing}.
-@subheading Fingerings
+@warning{The first time you ever run LilyPond, it may take a
+minute or two because all of the system fonts have to be analyzed
+first. After this, LilyPond will be much faster!}
-@cindex fingering
-@funindex ^
-@funindex _
+@node MacOS X
+@subsection MacOS X
-Music Glossary: @rglos{fingering}.
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
-Similarly, @notation{fingering} indications can be added to a note
-using a dash (@code{-}) and the digit to be printed:
+@lilypadOSX
-@lilypond[verbatim,quote,relative=2]
-c-3 e-5 b-2 a-1
-@end lilypond
-Articulations and fingerings are usually placed automatically, but
-you can specify a direction by replacing the dash (@code{-}) with
-@code{^} (up) or @code{_} (down). You can also use multiple
-articulations on the same note. However, in most cases it is best
-to let LilyPond determine the articulation directions.
+@node Windows
+@subsection Windows
-@lilypond[verbatim,quote,relative=2]
-c_-^1 d^. f^4_2-> e^-_+
-@end lilypond
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
-@subheading Dynamics
-
-@cindex dynamics
-@cindex decrescendo
-@cindex crescendo
-
-@funindex \f
-@funindex \ff
-@funindex \mp
-@funindex \p
-@funindex \mf
-@funindex \pp
-@funindex \<
-@funindex <
-@funindex \>
-@funindex >
-@funindex \!
-@funindex !
-
-Music Glossary: @rglos{dynamics}, @rglos{crescendo},
-@rglos{decrescendo}.
-
-@notation{Dynamic} signs are made by adding the markings (with a
-backslash) to the note:
-
-@lilypond[verbatim,quote,relative=2]
-c\ff c\mf c\p c\pp
-@end lilypond
+@lilypadWindows
-@notation{Crescendi} and @notation{decrescendi} are started with
-the commands @code{\<} and @code{\>}. The next dynamics sign, for
-example @code{\f}, will end the (de)crescendo, or the command
-@code{\!} can be used:
+@node Command-line
+@subsection Command-line
-@lilypond[verbatim,quote,relative=2]
-c2\< c2\ff\> c2 c2\!
-@end lilypond
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
+@lilypadCommandLine
-@seealso
-Notation Reference: @ruser{Articulations and ornamentations},
-@ruser{Fingering instructions}, @ruser{Dynamics}.
+@node How to write input files
+@section How to write input files
+This section introduces some basic LilyPond syntax to help get you
+started writing input files.
-@node Adding text
-@subsection Adding text
+@menu
+* Simple notation::
+* Working on input files::
+@end menu
-@cindex text, adding
-@cindex adding text
-@cindex markup
-@funindex \markup
-@funindex markup
+@node Simple notation
+@subsection Simple notation
-Text may be added to your scores:
+@cindex simple notation
+@cindex notation, simple
-@lilypond[verbatim,quote,relative=2]
-c1^"espr" a_"legato"
-@end lilypond
+@menu
+* Pitches::
+* Durations (rhythms)::
+* Rests::
+* Time signature::
+* Tempo marks::
+* Clef::
+* All together::
+@end menu
-Extra formatting may be added with the @code{\markup} command:
+LilyPond will add some notation elements automatically. In the
+next example, we have only specified four pitches, but LilyPond
+has added a clef, time signature, and rhythms.
-@lilypond[verbatim,quote,relative=2]
-c1^\markup{ \bold espr}
-a1_\markup{
- \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
+@lilypond[verbatim,quote]
+{
+ c' e' g' e'
}
@end lilypond
+@noindent
+This behavior may be altered, but in most cases these automatic
+values are useful.
-@seealso
-Notation Reference: @ruser{Writing text}.
-
-
-@node Automatic and manual beams
-@subsection Automatic and manual beams
-
-@cindex beaming
-@cindex automatic beams
-@cindex manual beams
-@cindex beams, automatic
-@cindex beams, manual
-@cindex beams, by hand
-
-@funindex [ ... ]
-@funindex [
-@funindex ]
-@funindex \autoBeamOff
-@funindex autoBeamOff
-@funindex \autoBeamOn
-@funindex autoBeamOn
-
-Music Glossary: @rglos{beam}.
-
-All @notation{beams} are drawn automatically:
-
-@lilypond[verbatim,quote,relative=2]
-a8 ais d ees r d c16 b a8
-@end lilypond
-
-If you do not like the automatic beams, they may be overridden
-manually. To correct just an occasional beam mark the first note
-to be beamed with @code{[} and the last one with @code{]}.
-
-@lilypond[verbatim,quote,relative=2]
-a8[ ais] d[ ees r d] a b
-@end lilypond
-
-If you want to turn off automatic beaming entirely or for an
-extended section of music, use the command @code{\autoBeamOff}
-to turn off automatic beaming and @code{\autoBeamOn} to turn it
-on again.
-
-@lilypond[verbatim,quote,relative=2]
-\autoBeamOff
-a8 c b4 d8. c16 b4
-\autoBeamOn
-a8 c b4 d8. c16 b4
-@end lilypond
-
-
-@seealso
-Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
-
-
-@node Advanced rhythmic commands
-@subsection Advanced rhythmic commands
-@subheading Partial measure
+@node Pitches
+@unnumberedsubsubsec Pitches
-@cindex pickup
-@cindex anacrusis
-@cindex partial measure
+@cindex pitches
+@cindex relative mode
+@cindex quote, single
+@cindex comma
+@cindex accidentals and relative mode
+@cindex relative mode, and accidentals
-@funindex \partial
-@funindex partial
+@funindex \relative
+@funindex '
+@funindex ,
-Music Glossary: @rglos{anacrusis}.
+Music Glossary: @rglos{pitch}, @rglos{interval},
+@rglos{scale}, @rglos{middle C}, @rglos{octave},
+@rglos{accidental}.
-A pickup (or @notation{anacrusis}) is entered with the keyword
-@code{\partial}. It is followed by a duration: @code{\partial 4}
-is a quarter note pickup and @code{\partial 8} an eighth note.
+LilyPond uses lower-case letters for pitches. The letters
+@code{c} through@tie{}@code{b} denote pitches in the
+@q{small octave} below @notation{middle C}. Added @code{'}
+or@tie{}@code{,} suffixes indicate higher or lower octaves.
+Here is a scale starting on @notation{middle C}, and an arpeggio:
-@lilypond[verbatim,quote,relative=2]
-\partial 8
-f8 c2 d
+@lilypond[verbatim,quote]
+{ c' d' e' f' g' a' b' c'' g c' e' g' c'' e'' g'' c''' }
@end lilypond
-@subheading Tuplets
-
-@cindex tuplets
-@cindex triplets
-
-@funindex \times
-@funindex times
+The easiest way to enter notes is by using @code{\relative} mode.
+In this mode, the octave is chosen automatically by assuming the
+following note is always to be placed closest to the previous
+note, i.e., it is to be placed in the octave which is within three
+staff spaces of the previous note. We begin by entering the most
+elementary piece of music, a @notation{scale}, in which every note
+is within just one staff space of the previous note.
-Music Glossary: @rglos{note value}, @rglos{triplet}.
-
-@notation{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
-@notation{triplet} has 2/3 as its fraction
-
-@lilypond[verbatim,quote,relative=2]
-\times 2/3 { f8 g a }
-\times 2/3 { c r c }
-\times 2/3 { f,8 g16[ a g a] }
-\times 2/3 { d4 a8 }
+@lilypond[verbatim,quote]
+\relative {
+ c' d e f
+ g a b c
+}
@end lilypond
-@subheading Grace notes
+The initial note is @notation{middle C}, denoted by @code{c'}.
+Each successive note is
+placed closest to the previous note -- in other words, the first
+@code{c} is the closest C to middle C. This is followed by the
+closest D to the previous note. We can create melodies which have
+larger intervals, still using only @code{\relative} mode:
-@cindex grace notes
-@cindex acciaccatura
-@cindex appoggiatura
-
-@funindex \grace
-@funindex grace
-@funindex \acciaccatura
-@funindex acciaccatura
-@funindex \appoggiatura
-@funindex acciaccatura
-
-Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
-@rglos{appoggiatura}.
-
-@notation{Grace notes} are created with the @code{\grace} command,
-although they can also be created by prefixing a music expression
-with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
-
-@lilypond[verbatim,quote,relative=2]
-c2 \grace { a32[ b] } c2
-c2 \appoggiatura b16 c2
-c2 \acciaccatura b16 c2
+@lilypond[verbatim,quote]
+\relative {
+ d' f a g
+ c b f d
+}
@end lilypond
+@noindent
+In the previous example, the first note -- the @code{d'} with one
+@code{'}-mark -- is the D in the octave starting from middle C
+and going up to B.
-@seealso
-Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
-@ruser{Upbeats}.
-
-
-@node Multiple notes at once
-@section Multiple notes at once
-
-This section introduces having more than one note at the same
-time: multiple instruments, multiple staves for a single
-instrument (i.e. piano), and chords.
-
-Polyphony in music refers to having more than one voice occurring
-in a piece of music. Polyphony in LilyPond refers to having more
-than one voice on the same staff.
-
-@menu
-* Music expressions explained::
-* Multiple staves::
-* Staff groups::
-* Combining notes into chords::
-* Single staff polyphony::
-@end menu
-
-
-@node Music expressions explained
-@subsection Music expressions explained
-
-@cindex music expression
-@cindex expression, music
-@cindex compound music expression
-@cindex music expression, compound
-
-In LilyPond input files, music is represented by @emph{music
-expressions}. A single note is a music expression:
-
-@lilypond[verbatim,quote,relative=2]
-a4
-@end lilypond
-
-Enclosing a note in braces creates a @emph{compound music
-expression}. Here we have created a compound music expression
-with two notes:
+By adding (or removing) quotes @code{'} or commas @code{,} from
+the first note, we can change the starting octave:
-@lilypond[verbatim,quote,relative=2]
-{ a4 g4 }
+@lilypond[verbatim,quote]
+\relative {
+ e'' c a c
+}
@end lilypond
-Putting a group of music expressions (e.g. notes) in braces means
-that they are in sequence (i.e. each one follows the previous
-one). The result is another music expression:
+Relative mode can be confusing initially, but is the easiest way
+to enter most melodies. Let us see how this relative calculation
+works in practice. Starting from a B, which is on the middle line
+in a treble clef, you can reach a C, D and E within 3 staff spaces
+going up, and an A, G and F within 3 staff spaces going down. So
+if the note following a B is a C, D or E it will be assumed to be
+above the B, and an A, G or F will be assumed to be below.
-@lilypond[verbatim,quote,relative=2]
-{ { a4 g } f g }
+@lilypond[verbatim,quote]
+\relative {
+ b' c % c is 1 staff space up, so is the c above
+ b d % d is 2 up or 5 down, so is the d above
+ b e % e is 3 up or 4 down, so is the e above
+ b a % a is 6 up or 1 down, so is the a below
+ b g % g is 5 up or 2 down, so is the g below
+ b f % f is 4 up or 3 down, so is the f below
+}
@end lilypond
-@subheading Analogy: mathematical expressions
-
-This mechanism is similar to mathematical formulas: a big formula
-is created by composing small formulas. Such formulas are called
-expressions, and they can contain other expressions, so you can
-make arbitrarily complex and large expressions. For example,
-
-@example
-1
-
-1 + 2
-
-(1 + 2) * 3
-
-((1 + 2) * 3) / (4 * 5)
-@end example
+Exactly the same happens even when any of these notes are
+sharpened or flattened. @notation{Accidentals} are
+@strong{totally ignored} in the calculation of relative position.
+Precisely the same staff space counting is done from a note at any
+other position on the staff.
-This is a sequence of expressions, where each expression is
-contained in the next (larger) one. The simplest expressions are
-numbers, and larger ones are made by combining expressions with
-operators (like @code{+}, @code{*} and @code{/}) and parentheses.
-Like mathematical expressions, music expressions can be nested
-arbitrarily deep, which is necessary for complex music like
-polyphonic scores.
-
-
-@subheading Simultaneous music expressions: multiple staves
-
-@cindex multiple staves
-@cindex staves, multiple
-@cindex polyphony
-@cindex combining expressions in parallel
-@cindex parallel expressions
-@cindex expressions, parallel
-@cindex relative notes and simultaneous music
-@cindex relative notes and parallel expressions
-@cindex simultaneous music and relative notes
-@cindex parallel expressions and relative notes
-
-@funindex <<
-@funindex >>
-@funindex << ... >>
-
-Music Glossary: @rglos{polyphony}.
-
-This technique is useful for @notation{polyphonic} music. To
-enter music with more voices or more staves, we combine
-expressions in parallel. To indicate that two voices should play
-at the same time, simply enter a simultaneous combination of music
-expressions. A @q{simultaneous} music expression is formed by
-enclosing expressions inside @code{<<} and @code{>>}. In the
-following example, three sequences (all containing two separate
-notes) are combined simultaneously:
+To add intervals that are larger than three staff spaces, we can
+raise the @notation{octave} by adding a single quote @code{'} (or
+apostrophe) to the note name. We can lower the octave by adding a
+comma @code{,} to the note name.
@lilypond[verbatim,quote]
-\relative c'' {
- <<
- { a4 g }
- { f e }
- { d b }
- >>
+\relative {
+ a' a, c' f,
+ g g'' a,, f'
}
@end lilypond
-Note that we have indented each level of the input with a
-different amount of space. LilyPond does not care how much (or
-little) space there is at the beginning of a line, but indenting
-LilyPond code like this makes it much easier for humans to read.
-
-@warning{each note is relative to the previous note in
-the input, not relative to the @code{c''} in the initial
-@code{@bs{}relative} command.}
-
-
-@subheading Simultaneous music expressions: single staff
-
-To determine the number of staves in a piece, LilyPond looks at
-the beginning of the first expression. If there is a single note,
-there is one staff; if there is a simultaneous expression, there
-is more than one staff. The following example shows a complex
-expression, but as it begins with a single note it will be set
-out on a single staff.
+@noindent
+To change a note by two (or more!) octaves, we use multiple
+@code{''} or @code{,,} -- but be careful that you use two single
+quotes @code{''} and not one double quote @code{"}@tie{}!
+@c " - keeps quotes in order for context-sensitive editor -td
+
+@node Durations (rhythms)
+@unnumberedsubsubsec Durations (rhythms)
+
+@cindex note durations
+@cindex durations
+@cindex rhythms
+@cindex whole note
+@cindex half note
+@cindex quarter note
+@cindex dotted note
+@cindex notating durations
+
+Music Glossary: @rglos{beam}, @rglos{duration},
+@rglos{whole note}, @rglos{half note}, @rglos{quarter note},
+@rglos{dotted note}.
+
+The @notation{duration} of a note is specified by a number after
+the note name: @code{1} for a @notation{whole note}, @code{2} for
+a @notation{half note}, @code{4} for a @notation{quarter note} and
+so on. @notation{Beams} are added automatically.
+
+If you do not specify a duration, the previous duration is used
+for the next note. The duration of the first note defaults to a
+quarter note.
@lilypond[verbatim,quote]
-\relative c'' {
- c2 <<c e>>
- << { e f } { c <<b d>> } >>
+\relative {
+ a'1
+ a2 a4 a8 a
+ a16 a a a a32 a a a a64 a a a a a a a a2
}
@end lilypond
-@node Multiple staves
-@subsection Multiple staves
-
-@cindex multiple staves
-@cindex staves, multiple
-@cindex context
-@cindex context, notation
-@cindex notation context
-
-@funindex \new Staff
-@funindex new Staff
-@funindex Staff
-@funindex \new
-@funindex new
-@funindex Score
-@funindex Voice
-@funindex Lyrics
-@funindex ChordNames
-
-LilyPond input files are constructed out of music expressions, as
-we saw in @ref{Music expressions explained}. If the score begins
-with simultaneous music expressions, LilyPond creates multiples
-staves. However, it is easier to see what happens if we create
-each staff explicitly.
-
-To print more than one staff, each piece of music that makes up a
-staff is marked by adding @code{\new Staff} before it. These
-@code{Staff} elements are then combined in parallel with @code{<<}
-and @code{>>}:
+To create @notation{dotted notes}, add a dot @code{.} to the
+duration number. The duration of a dotted note must be stated
+explicitly (i.e., with a number).
@lilypond[verbatim,quote]
-\relative c'' {
- <<
- \new Staff { \clef treble c }
- \new Staff { \clef bass c,, }
- >>
+\relative {
+ a'4 a a4. a8
+ a8. a16 a a8. a8 a4.
}
@end lilypond
-The command @code{\new} introduces a @q{notation context.} A
-notation context is an environment in which musical events (like
-notes or @code{\clef} commands) are interpreted. For simple
-pieces, such notation contexts are created automatically. For
-more complex pieces, it is best to mark contexts explicitly.
+@node Rests
+@unnumberedsubsubsec Rests
-There are several types of contexts. @code{Score}, @code{Staff},
-and @code{Voice} handle melodic notation, while @code{Lyrics} sets
-lyric texts and @code{ChordNames} prints chord names.
+@cindex rest
+@cindex notating rests
-In terms of syntax, prepending @code{\new} to a music expression
-creates a bigger music expression. In this way it resembles the
-minus sign in mathematics. The formula @math{(4+5)} is an
-expression, so @math{-(4+5)} is a bigger expression.
+Music Glossary: @rglos{rest}.
-Time signatures entered in one staff affects all other staves by
-default. On the other hand, the key signature of one staff does
-@emph{not} affect other staves. This different default behavior
-is because scores with transposing instruments are more common
-than polyrhythmic scores.
+A @notation{rest} is entered just like a note with the name
+@code{r}@tie{}:
@lilypond[verbatim,quote]
-\relative c'' {
- <<
- \new Staff { \clef treble \key d \major \time 3/4 c }
- \new Staff { \clef bass c,, }
- >>
+\relative {
+ a'4 r r2
+ r8 a r4 r4. r8
}
@end lilypond
+@node Time signature
+@unnumberedsubsubsec Time signature
+@cindex time signature
-@node Staff groups
-@subsection Staff groups
+@funindex \time
-@cindex piano staff
-@cindex staff, piano
-@cindex choir staff
-@cindex staff, choir
-@cindex grand staff
-@cindex staff, grand
-@cindex staff group
+Music Glossary: @rglos{time signature}.
-@funindex PianoStaff
-@funindex GrandStaff
-@funindex ChoirStaff
-
-Music Glossary: @rglos{brace}.
-
-Piano music is typeset in two staves connected by a
-@notation{brace}.
-Printing such a staff is similar to the polyphonic example in
-@ref{Multiple staves}. However, now this entire expression is
-inserted inside a @code{PianoStaff}:
-
-@example
-\new PianoStaff <<
- \new Staff @dots{}
- \new Staff @dots{}
->>
-@end example
-
-Here is a small example:
+The @notation{time signature} can be set with the @code{\time}
+command:
@lilypond[verbatim,quote]
-\relative c'' {
- \new PianoStaff <<
- \new Staff { \time 2/4 c4 e g g, }
- \new Staff { \clef bass c,, c' e c }
- >>
+\relative {
+ \time 3/4
+ a'4 a a
+ \time 6/8
+ a4. a
+ \time 4/4
+ a4 a a a
}
@end lilypond
-Other staff groupings are introduced with @code{\new GrandStaff},
-suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
-suitable for vocal scores. These staff groups each form another
-type of context, one that generates the brace at the left end of
-every system and also controls the extent of bar lines.
-
-
-@seealso
-Notation Reference: @ruser{Keyboard and other multi-staff
-instruments},
-@ruser{Displaying staves}.
-
-
-@node Combining notes into chords
-@subsection Combining notes into chords
+@node Tempo marks
+@unnumberedsubsubsec Tempo marks
-@cindex chords
-@cindex note durations in chords
+@cindex tempo marks
+@cindex metronome marks
-@funindex <
-@funindex >
-@funindex < ... >
+@funindex \tempo
-Music Glossary: @rglos{chord}.
+Music Glossary: @rglos{tempo indication}, @rglos{metronome}.
-We saw earlier how notes can be combined into @notation{chords} by
-indicating they are simultaneous by enclosing them in double angle
-brackets. However, the normal way of indicating a chord is to
-surround the pitches with @emph{single} angle brackets. Note that
-all the notes in a chord must have the same duration, and that the
-duration is placed after the closing bracket.
+The @notation{tempo indication} and @notation{metronome mark} can be
+set with the @code{\tempo} command:
-@lilypond[verbatim,quote,relative=2]
-r4 <c e g>4 <c f a>2
-@end lilypond
-
-Think of chords as almost equivalent to single notes:
-almost everything you can attach to a single note can be attached
-to a chord, and everything must go @emph{outside} the angle
-brackets. For example, you can combine markings like beams and
-ties with chords. They must be placed outside the angle brackets.
-
-@lilypond[verbatim,quote,relative=2]
-r4 <c e g>8[ <c f a>]~ <c f a>2
-r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
+@lilypond[verbatim,quote]
+\relative {
+ \time 3/4
+ \tempo "Andante"
+ a'4 a a
+ \time 6/8
+ \tempo 4. = 96
+ a4. a
+ \time 4/4
+ \tempo "Presto" 4 = 120
+ a4 a a a
+}
@end lilypond
-@node Single staff polyphony
-@subsection Single staff polyphony
-
-@cindex polyphony
-@cindex multiple voices
-@cindex voices, more on one staff
-@cindex single staff polyphony
-@cindex spacer rest
-@cindex rest, spacer
-
-@funindex << ... \\ ... >>
-@funindex <<
-@funindex \\
-@funindex >>
-
-Polyphonic music in lilypond, while not difficult, uses concepts
-that we haven't discussed yet, so we're not going to introduce
-them here. Instead, the following sections introduce these concepts
-and explain them thoroughly.
-
-@seealso
-Learning Manual: @ref{Voices contain music}.
-
-Notation Reference: @ruser{Simultaneous notes}.
-
-@node Songs
-@section Songs
-
-This section introduces vocal music and simple song sheets.
-
-@menu
-* Setting simple songs::
-* Aligning lyrics to a melody::
-* Lyrics to multiple staves::
-@end menu
-
-
-@node Setting simple songs
-@subsection Setting simple songs
+@node Clef
+@unnumberedsubsubsec Clef
-@cindex lyrics
-@cindex songs
+@cindex clef
+@cindex treble
+@cindex alto
+@cindex tenor
+@cindex bass
-@funindex \addlyrics
-@funindex addlyrics
+@funindex \clef
-Music Glossary: @rglos{lyrics}.
+Music Glossary: @rglos{clef}.
-Here is the start of the melody to a nursery
-rhyme, @notation{Girls and boys come out to play}:
+The @notation{clef} can be set using the @code{\clef} command:
@lilypond[verbatim,quote]
-\relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
+\relative {
+ \clef "treble"
+ c'1
+ \clef "alto"
+ c1
+ \clef "tenor"
+ c1
+ \clef "bass"
+ c1
}
@end lilypond
-The @notation{lyrics} can be set to these notes, combining both
-with the @code{\addlyrics} keyword. Lyrics are entered by
-separating each syllable with a space.
+
+@node All together
+@unnumberedsubsubsec All together
+
+Here is a small example showing all these elements together:
@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
- }
- \addlyrics {
- Girls and boys come out to play,
- }
->>
+\relative {
+ \clef "bass"
+ \time 3/4
+ \tempo "Andante" 4 = 120
+ c,2 e8 c'
+ g'2.
+ f4 e d
+ c4 c, r
+}
@end lilypond
-Note the curly brackets delimiting both the music and the lyrics,
-and the double angle brackets @w{@code{<< ... >>}} around the
-whole piece to show that the music and lyrics are to occur at the
-same time.
-@node Aligning lyrics to a melody
-@subsection Aligning lyrics to a melody
-
-@cindex melisma
-@cindex extender line
-@cindex hyphens
-@cindex underscore
-@cindex lyrics, aligning
-@cindex aligning lyrics
-@cindex lyrics, multi-syllable words
-@cindex words with multiple syllables in lyrics
+@seealso
+Notation Reference: @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
+
+
+@node Working on input files
+@subsection Working on input files
+
+@cindex curly braces
+@cindex braces, curly
+@cindex comments
+@cindex line comment
+@cindex comment, line
+@cindex block comment
+@cindex comment, line
+@cindex case sensitive
+@cindex whitespace insensitive
+@cindex expressions
+@cindex versioning
+@cindex version
+@cindex version number
-Music Glossary: @rglos{melisma}, @rglos{extender line}.
+@funindex \version
+@funindex { ... }
+@funindex %
+@funindex %@{ ... %@}
-The next line in the nursery rhyme is @notation{The moon doth
-shine as bright as day}. Let's extend it:
+LilyPond input files are similar to source files in many common
+programming languages. They contain a version statement, are case
+sensitive, and white-space is generally ignored. Expressions are
+formed with curly braces @w{@code{@{ @}}}, and comments are
+denoted with @code{%} or @w{@code{%@{ @dots{} %@}}}@tie{}.
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
- g8 a4 b8 c b a d4 b8 g4.
- }
- \addlyrics {
- Girls and boys come out to play,
- The moon doth shine as bright as day;
- }
->>
-@end lilypond
+If the previous sentences sound like nonsense, don't worry! We'll
+explain what all these terms mean:
-We see the extra lyrics do not align properly with the notes. The
-word @notation{shine} should be sung on two notes, not one. This
-is called a @notation{melisma}, a single syllable sung to more
-than one note. There are several ways to spread a syllable over
-multiple notes, the simplest being to add a slur across them, for
-details, see @ref{Ties and slurs}:
+@itemize
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
- g8 a4 b8 c( b) a d4 b8 g4.
- }
- \addlyrics {
- Girls and boys come out to play,
- The moon doth shine as bright as day;
- }
->>
-@end lilypond
+@item
+@strong{Version statement}:
+Every LilyPond file should contain a version statement. A version
+statement is a line that describes the version of LilyPond for which
+the file was written, as in the following example:
-The words now line up correctly with the notes, but the automatic
-beaming for the notes above @notation{shine as} does not look right.
-We can correct this by inserting manual beaming commands to override
-the automatic beaming here, for details, see @ref{Automatic and
-manual beams}.
+@example
+\version "@w{@version{}}"
+@end example
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
- g8 a4 b8 c([ b]) a d4 b8 g4.
- }
- \addlyrics {
- Girls and boys come out to play,
- The moon doth shine as bright as day;
- }
->>
-@end lilypond
+By convention, the version statement is placed at the top of the
+LilyPond file.
-As an alternative to using slurs, the melismata may be indicated
-in just the lyrics by using an underscore @code{_} for each note
-that should be included in the melisma:
+The version statement is important for at least two reasons. First,
+it allows automatic updating of the input file as LilyPond syntax
+changes. Second, it describes the version of LilyPond needed to
+compile the file.
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \major
- \time 6/8
- d4 b8 c4 a8 d4 b8 g4
- g8 a4 b8 c[ b] a d4 b8 g4.
- }
- \addlyrics {
- Girls and boys come out to play,
- The moon doth shine _ as bright as day;
- }
->>
-@end lilypond
+If the version statement is omitted from an input file, LilyPond will print
+a warning during the compilation of the file.
-If a syllable extends over several notes or a single very long
-note an @notation{extender line} is usually drawn from the
-syllable extending under all the notes for that syllable. It is
-entered as two underscores @code{__}. Here is an example from the
-first three bars of @notation{Dido's Lament}, from Purcell's
-@notation{Dido and Æneas}:
+@item
+@strong{Case sensitive}:
+it matters whether you enter a letter in lower case (e.g.
+@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
+Notes are lower case: @w{@samp{@{ c d e @}}} is valid input;
+@w{@samp{@{ C D E @}}} will produce an error message.
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key g \minor
- \time 3/2
- g2 a bes bes( a)
- b c4.( bes8 a4. g8 fis4.) g8 fis1
- }
- \addlyrics {
- When I am laid,
- am laid __ in earth,
- }
->>
-@end lilypond
+@item
+@strong{Whitespace insensitive}:
+it does not matter how many spaces (or tabs or new lines) you add.
+@w{@samp{@{ c4 d e @}}} means the same thing as
+@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
-None of the examples so far have involved words containing more
-than one syllable. Such words are usually split one syllable to a
-note, with hyphens between syllables. Such hyphens are entered as
-two dashes, resulting in a centered hyphen between the syllables.
-Here is an example showing this and everything we have learned so
-far about aligning lyrics to notes.
-
-@c no ragged-right here because otherwise the hyphens get lost,
-@c but the example is long enough to avoid looking strange.
-@lilypond[verbatim,quote,noragged-right]
-<<
- \relative c' {
- \key g \major
- \time 3/4
- \partial 4
- d4 g4 g a8( b) g4 g4
- b8( c) d4 d e4 c2
- }
- \addlyrics {
- A -- way in a __ man -- ger,
- no __ crib for a bed, __
- }
->>
-@end lilypond
+@example
+@{ c4 d
+ e @}
+@end example
-Some lyrics, especially those in Italian, require the opposite:
-setting more than one syllable to a single note. This is
-achieved by linking the syllables together with a single
-underscore @code{_} (with no spaces), or enclosing them in quotes.
-Here's an example from Rossini's @notation{Figaro}, where
-@notation{al} has to be sung on the same note as the @notation{go} of
-@notation{Largo} in Figaro's aria @notation{Largo al factotum}:
-
-@c no ragged-right here because otherwise the hyphens get lost,
-@c but the example is long enough to avoid looking strange.
-@lilypond[verbatim,quote,noragged-right]
-<<
- \relative c' {
- \clef bass
- \key c \major
- \time 6/8
- c4.~ c8 d b c([ d]) b c d b c
- }
- \addlyrics {
- Lar -- go_al fac -- to -- tum del -- la cit -- tà
- }
->>
-@end lilypond
+@noindent
+Of course, the previous example is hard to read. A good rule of
+thumb is to indent code blocks with two spaces:
+@example
+@{
+ c4 d e
+@}
+@end example
-@seealso
-Notation Reference: @ruser{Vocal music}.
+However, whitespace @emph{is} required to separate many
+syntactical elements from others. In other words, whitespace can
+always be @emph{added}, but not always @emph{eliminated}. Since
+missing whitespace can give rise to strange errors, it is
+advisable to always insert whitespace before and after every
+syntactic element, for example, before and after every curly
+brace.
+
+@item
+@strong{Expressions}:
+every piece of LilyPond input needs to have
+@strong{@{@tie{}curly@tie{}braces@tie{}@}} placed around the
+input. These braces tell LilyPond that the input is a single
+music expression, just like parentheses @code{()} in mathematics.
+The braces should be surrounded by a space unless they are at the
+beginning or end of a line to avoid ambiguities.
+
+A LilyPond command followed by a simple expression in braces (such
+as @q{@w{@code{@bs{}relative @{ @dots{} @}}}}) also counts as a
+single music expression.
+
+@cindex comments
+@cindex line comment
+@cindex block comment
+@item
+@strong{Comments}:
+a comment is a remark for the human reader of the music input; it
+is ignored while parsing, so it has no effect on the printed
+output. There are two types of comments. The percent symbol
+@code{%} introduces a line comment; anything after @code{%} on
+that line is ignored. By convention, a line comment is placed
+@emph{above} the code it refers to.
+@example
+a4 a a a
+% this comment refers to the Bs
+b2 b
+@end example
-@node Lyrics to multiple staves
-@subsection Lyrics to multiple staves
+A block comment marks a whole section of music input as a comment.
+Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
+However, block comments do not @q{nest}. This means that you
+cannot place a block comment inside another block comment. If you
+try, the first @code{%@}} will terminate @emph{both} block
+comments. The following fragment shows possible uses for
+comments:
-@cindex lyrics and multiple staves
-@cindex multiple staves and lyrics
+@example
+% notes for twinkle twinkle follow
+ c4 c g' g a a g2
-The simple approach using @code{\addlyrics} can be used for
-placing lyrics under more than one staff. Here is an
-example from Handel's @notation{Judas Maccabæus}:
+%@{
+ This line, and the notes below are ignored,
+ since they are in a block comment.
-@lilypond[verbatim,quote]
-<<
- \relative c'' {
- \key f \major
- \time 6/8
- \partial 8
- c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
- }
- \addlyrics {
- Let flee -- cy flocks the hills a -- dorn, __
- }
- \relative c' {
- \key f \major
- \time 6/8
- \partial 8
- r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
- }
- \addlyrics {
- Let flee -- cy flocks the hills a -- dorn,
- }
->>
-@end lilypond
+ f4 f e e d d c2
+%@}
+@end example
-Scores any more complex than this simple example are better
-produced by separating out the score structure from the notes and
-lyrics with variables. These are discussed in @ref{Organizing
-pieces with variables}.
+@end itemize
-@seealso
-Notation Reference: @ruser{Vocal music}.
+@node Dealing with errors
+@section Dealing with errors
+@cindex troubleshooting
-@node Final touches
-@section Final touches
+Sometimes LilyPond doesn't produce the output you expect. This
+section provides some links to help you solve the problems you
+might encounter.
-This is the final section of the tutorial; it demonstrates how to
-add the final touches to simple pieces, and provides an
-introduction to the rest of the manual.
@menu
-* Organizing pieces with variables::
-* Version number::
-* Adding titles::
-* Absolute note names::
-* After the tutorial::
+* General troubleshooting tips::
+* Some common errors::
@end menu
+@node General troubleshooting tips
+@subsection General troubleshooting tips
-@node Organizing pieces with variables
-@subsection Organizing pieces with variables
+Troubleshooting LilyPond problems can be challenging for
+people who are used to a graphical interface, because invalid
+input files can be created. When this happens, a logical approach
+is the best way to identify and solve the problem. Some guidelines
+to help you learn to do this are provided in @rprogram{Troubleshooting}.
-@cindex variables
-@cindex variables, defining
-@cindex identifiers
-@cindex macros
-@cindex assigning variables
-@cindex using variables
-@cindex variables, using
-@cindex variables, characters allowed in
-@cindex characters allowed in variables
-When all of the elements discussed earlier are combined to produce
-larger files, the music expressions get a lot bigger. In
-polyphonic music with many staves, the input files can become very
-confusing. We can reduce this confusion by using
-@emph{variables}.
+@node Some common errors
+@subsection Some common errors
-With variables (also known as identifiers or macros), we can break
-up complex music expressions. A variable is assigned as
-follows:
+@cindex common errors
+@cindex errors, common
-@example
-namedMusic = @{ @dots{} @}
-@end example
+There are a few common errors that are difficult to troubleshoot
+based simply on the error messages that are displayed. These are
+described in @rprogram{Common errors}.
-The contents of the music expression @code{namedMusic} can be used
-later by placing a backslash in front of the name
-(@code{\namedMusic}, just like a normal LilyPond command).
-@lilypond[verbatim,quote]
-violin = \new Staff {
- \relative c'' {
- a4 b c b
- }
-}
-cello = \new Staff {
- \relative c {
- \clef bass
- e2 d
- }
-}
-{
- <<
- \violin
- \cello
- >>
-}
-@end lilypond
-@noindent
-The name of a variable must have alphabetic characters only, no
-numbers, underscores, or dashes.
+@node How to read the manuals
+@section How to read the manuals
-Variables must be defined @emph{before} the main music
-expression, but may be used as many times as required anywhere after
-they have been defined. They may even be used in a later definition
-of another variable, giving a way of shortening the input if a
-section of music is repeated many times.
+This section shows how to read the documentation efficiently, and
+also introduces some useful interactive features available in the
+online version.
-@lilypond[verbatim,quote]
-tripletA = \times 2/3 { c,8 e g }
-barA = { \tripletA \tripletA \tripletA \tripletA }
+@menu
+* Omitted material::
+* Clickable examples::
+* Overview of manuals::
+@end menu
-\relative c'' {
- \barA \barA
-}
-@end lilypond
-Variables may be used for many other types of objects in
-the input. For example,
+@node Omitted material
+@subsection Omitted material
-@example
-width = 4.5\cm
-name = "Wendy"
-aFivePaper = \paper @{ paperheight = 21.0 \cm @}
-@end example
-Depending on its contents, the variable can be used in different
-places. The following example uses the above variables:
+@cindex how to read the manual
+@cindex manual, reading
+@cindex reading the manual
+@cindex examples, clickable
+@cindex clickable examples
+@cindex tips for constructing files
+@cindex templates
+@cindex constructing files, tips
+@cindex files, tips for constructing
+
+LilyPond input must be surrounded by @code{@{ @}} marks or a
+@q{@w{@code{@bs{}relative @{ @dots{} @}}}}, as we saw in
+@ref{Working on input files}. For the rest of this manual,
+some short examples will omit this. To replicate these examples,
+you can copy displayed input, but paste it between @code{@{}
+and @code{@}} in your input file.
@example
-\paper @{
- \aFivePaper
- line-width = \width
-@}
@{
- c4^\name
+ @dots{}example goes here@dots{}
@}
@end example
+Also, remember that every LilyPond file should have a
+@code{\version} statement. Because the examples in the manuals
+are snippets, not files, the @code{\version} statement is omitted.
+But you should make a practice of including them in your files.
-@node Version number
-@subsection Version number
-
-@cindex versioning
-@cindex version
-@cindex version number
-@cindex upgrades
-@cindex future upgrades
-@cindex updating files
-@cindex files, updating
-
-@funindex \version
-@funindex version
-@funindex convert-ly
-
-The @code{\version} statement records the version of LilyPond that
-was used to write the file:
-
-@example
-\version @w{"@version{}"}
-@end example
-
-@noindent
-By convention, this is placed at the top of your LilyPond file.
-
-These annotations make future upgrades of LilyPond go more
-smoothly. Changes in the syntax are handled with a special
-program, @command{convert-ly}, and it uses @code{\version} to
-determine what rules to apply. For details, see
-@rprogram{Updating files with convert-ly}.
+@node Clickable examples
+@subsection Clickable examples
+@warning{This feature is only available in the HTML manuals.}
-@node Adding titles
-@subsection Adding titles
+Many people learn programs by trying and fiddling around with the
+program. This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image. Try it on
+this image:
-@cindex title
-@cindex headers
-@cindex header block
+@c no verbatim here
+@lilypond[quote]
+\relative {
+ c''4-\markup { \bold \huge { Click here. } }
+}
+@end lilypond
-@funindex \header
-@funindex header
+By cutting and pasting everything in the @qq{ly snippet} section,
+you have a starting template for experiments. To see exactly the
+same output (line-width and all), copy everything from @qq{Start
+cut-&-pastable section} to the bottom of the file.
-The title, composer, opus number, and similar information are
-entered in the @code{\header} block. This exists outside of the
-main music expression; the @code{\header} block is usually placed
-underneath the version number.
-@example
-\version @w{"@version{}"}
-\header @{
- title = "Symphony"
- composer = "Me"
- opus = "Op. 9"
-@}
+@ignore
+This is item 825
-@{
- @dots{} music @dots{}
-@}
-@end example
+@n ode Keyboard navigation
+@s ubsection Keyboard navigation
-When the file is processed, the title and composer are printed
-above the music. More information on titling can be found in
-@ruser{Creating titles}.
+@warning{This features is only available in the HTML manuals.}
+@c TODO: once this is figured out, insert it here.
-@node Absolute note names
-@subsection Absolute note names
+We are currently working on this feature.
+@end ignore
-@cindex note names
-@cindex note names, absolute
-@cindex absolute mode
-@cindex absolute values for pitches
-@cindex pitches, absolute values
-@cindex absolute note names
+@node Overview of manuals
+@subsection Overview of manuals
-So far we have always used @code{\relative} to define pitches.
-This is the easiest way to enter most music, but another way of
-defining pitches exists: absolute mode.
+There is a lot of documentation for LilyPond. New users are
+sometimes confused about what part(s) they should read, and
+occasionally skip over reading vital portions.
-If you omit the @code{\relative}, LilyPond treats all pitches as
-absolute values. A @code{c'} will always mean middle C, a
-@code{b} will always mean the note one step below middle C, and a
-@code{g,} will always mean the note on the bottom staff of the
-bass clef.
+@warning{Please do not skip over important parts of the
+documentation. You will find it much harder to understand later
+sections.}
-@lilypond[verbatim,quote]
-{
- \clef bass
- c' b g, g,
- g, f, f c'
-}
-@end lilypond
+@itemize
-Here is a four-octave scale:
+@item
+@strong{Before trying to do @emph{anything}}: read the Learning
+manual's @ref{Tutorial}, and @ref{Common notation}. If you
+encounter musical terms which you do not recognize, please look
+them up in the @rglosnamed{Top, Glossary}.
-@lilypond[verbatim,quote]
-{
- \clef bass
- c, d, e, f,
- g, a, b, c
- d e f g
- a b c' d'
- \clef treble
- e' f' g' a'
- b' c'' d'' e''
- f'' g'' a'' b''
- c'''1
-}
-@end lilypond
+@item
+@strong{Before trying to write a complete piece of music}: read
+the Learning manual's @ref{Fundamental concepts}. After that, you
+may want to look in relevant sections of the
+@rusernamed{Top, Notation reference}.
-As you can see, writing a melody in the treble clef involves a lot
-of quote @code{'} marks. Consider this fragment from Mozart:
+@item
+@strong{Before trying to change the default output}: read the
+Learning manual's @ref{Tweaking output}.
-@lilypond[verbatim,quote]
-{
- \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
+@item
+@strong{Before undertaking a large project}: read the Usage
+document's @rprogram{Suggestions for writing files}.
-All these quotes makes the input less readable and they are a source
-of errors. With @code{\relative}, the previous example is much
-easier to read and type:
+@end itemize
-@lilypond[verbatim,quote]
-\relative c'' {
- \key a \major
- \time 6/8
- cis8. d16 cis8 e4 e8
- b8. cis16 b8 d4 d8
-}
-@end lilypond
-If you make a mistake with an octave mark (@code{'} or @code{,})
-while working in @code{\relative} mode, it is very obvious -- many
-notes will be in the wrong octave. When working in absolute mode,
-a single mistake will not be as visible, and will not be as easy
-to find.
-
-However, absolute mode is useful for music which has large
-intervals, and is extremely useful for computer-generated LilyPond
-files.
-
-
-
-@node After the tutorial
-@subsection After the tutorial
-
-After finishing the tutorial, you should probably try writing a
-piece or two. Start by adding notes to one of the
-@ref{Templates}. If you need any notation that was not covered in
-the tutorial, look at the Notation Reference, starting with
-@ruser{Musical notation}. If you want to write for an instrument
-ensemble that is not covered in the templates, take a look at
-@ref{Extending the templates}.
-
-Once you have written a few short pieces, read the rest of the
-Learning Manual (chapters 3-5). There's nothing wrong with
-reading it now, of course! However, the rest of the Learning
-Manual assumes that you are familiar with LilyPond input. You may
-wish to skim these chapters right now, and come back to them after
-you have more experience.
-
-In this tutorial and in the rest of the Learning Manual, there is a
-paragraph @strong{See also} at the end of each section, which contains
-cross-references to other sections: you should not follow these
-cross-references at first reading; when you have read all of the
-Learning Manual, you may want to read some sections again and follow
-cross-references for further reading.
-
-If you have not done so already, @emph{please} read
-FIXME FIXME FIXME
-@c @ref{About the documentation}.
-There is a lot of information about LilyPond, so
-newcomers often do not know where they should look for help. If
-you spend five minutes reading that section carefully, you might
-save yourself hours of frustration looking in the wrong places!
projects / lilypond.git / blobdiff