+2006-05-03 Graham Percival <gpermus@gmail.com>
+
+ * Documentation/user/ various: final round of reorg.
+
2006-05-02 Han-Wen Nienhuys <hanwen@lilypond.org>
* flower/file-path.cc (is_dir): canonicalize file name before stat'ing.
@item a sensible value: here @code{3.0}
@end itemize
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
@cindex internal documentation
@cindex finding graphical objects
@ifhtml
-This document is also available in @uref{source/Documentation/user/lilypond.pdf,PDF}.
+This document is also available as a @uref{source/Documentation/user/lilypond.pdf,PDF}.
@end ifhtml
@cindex web site
@cindex URL
-A further source of information is the website, which can be found at
+More information can be found at
@uref{http://@/www@/.lilypond@/.org/}. The website contains on-line copies
of this and other documentation.
@include dedication.itely
@menu
-Learning manual
+Learning Manual
* Preface:: Preface.
* Introduction:: What, Why, How.
* Tutorial:: A tutorial introduction.
-* Putting it all together:: Advanced tutorial? FIXME title
-* Working on LilyPond projects:: Demonstrates real-life LilyPond usage.
-* Tweaking output:: Tutorial-style explanation of chapters 10 and 11. FIXME title
+* Putting it all together:: More explanation about LilyPond concepts.
+* Working on LilyPond projects:: Discusses real-life usage.
+* Tweaking output:: Introduction to modifying output.
-Notation reference
+Notation Reference
* Basic notation:: Standard musical notation.
-* Instrument-specific notation:: Notation that is only used for some
- instruments.
+* Instrument-specific notation:: Specialized notation.
* Advanced notation:: Less frequently used notation.
* Changing defaults:: Tuning output.
* Global issues:: What LilyPond produces.
-* Interfaces for programmers::
+* Interfaces for programmers:: Expert usage.
-Technical details
+Technical Details
* Running LilyPond:: Operation.
* LilyPond-book:: Integrating text and music.
Appendices
-* Literature list::
-* Scheme tutorial::
-* Notation manual details::
-* Example templates:: Larger examples.
-* Cheat sheet::
-* GNU Free Documentation License:: FDL.
+* Literature list:: Reference works about music notation.
+* Scheme tutorial:: Programming inside LilyPond.
+* Notation manual tables:: Tables and charts.
+* Example templates:: Ready-made templates.
+* Cheat sheet:: Summary of LilyPond syntax.
+* GNU Free Documentation License:: License of this document.
* LilyPond index::
@end menu
@end ifnottex
@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
-@node Notation manual details
-@appendix Notation manual details
+@node Notation manual tables
+@appendix Notation manual tables
@menu
* Chord name chart::
@node Putting it all together
@chapter Putting it all together
-This chapter is an extention of the tutorial, dealing with FIXME.
+This chapter discusses general LilyPond concepts and how to
+create @code{\score} blocks.
@menu
* Extending the templates::
* How LilyPond files work::
* Score is a single musical expression::
-* Organizing larger pieces::
-* An orchestral part::
@end menu
@end example
@noindent
-Most people put some of those commands outside the
+Some people put some of those commands outside the
@code{\score} block -- for example, @code{\header} is
-almost always placed above the @code{\score}. That's
-just another shorthand.
+often placed above the @code{\score}. That's just
+another shorthand that LilyPond accepts.
Another great shorthand is the ability to define
variables. All the templates use this
@code{\melody}. There's nothing special about the
names -- it could be @code{melody}, @code{global},
@code{pianorighthand}, or @code{foofoobarbaz}. You
-can use whatever variable names you want.
+can use whatever variable names you want. For
+more details, see
+@ref{Saving typing with identifiers and functions}.
For a complete definition
of the input format, see @ref{File structure}.
text editor!
-@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 pieces,
-more deeply nested. Such large expressions can become unwieldy.
-
-By using variables, also known as identifiers, it is possible to break
-up complex music expressions. An identifier is assigned as follows
-
-@example
-namedMusic = @{ @dots{} @}
-@end example
-
-@noindent
-The contents of the music expression @code{namedMusic}, can be used
-later by preceding the name with a backslash, i.e., @code{\namedMusic}.
-In the next example, a two-note motive is repeated two times by using
-variable substitution
-
-@lilypond[quote,ragged-right,verbatim,nofragment]
-seufzer = {
- e'4( dis'4)
-}
-{ \seufzer \seufzer }
-@end lilypond
-
-The name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes. The assignment should be outside of
-running music.
-
-It is possible to use variables for many other types of objects in the
-input. For example,
-
-@example
-width = 4.5\cm
-name = "Wendy"
-aFivePaper = \paper @{ paperheight = 21.0 \cm @}
-@end example
-
-Depending on its contents, the identifier can be used in different
-places. The following example uses the above variables
-
-@example
-\paper @{
- \aFivePaper
- line-width = \width
-@}
-@{ c4^\name @}
-@end example
-
-More information on the possible uses of identifiers is given in the
-technical manual, in @ref{Input variables and Scheme}.
-@c fixme: the ref is too technical.
-
-
-@node An orchestral part
-@section An orchestral part
-
-In orchestral music, all notes are printed twice. Once in a part for
-the musicians, and once in a full score for the conductor. Identifiers can
-be used to avoid double work. The music is entered once, and stored in
-a variable. The contents of that variable is then used to generate
-both the part and the full score.
-
-It is convenient to define the notes in a special file. For example,
-suppose that the file @file{horn-music.ly} contains the following part
-of a horn/@/bassoon duo
-
-@example
-hornNotes = \relative c @{
- \time 2/4
- r4 f8 a cis4 f e d
-@}
-@end example
-
-@noindent
-Then, an individual part is made by putting the following in a file
-
-@example
-\include "horn-music.ly"
-\header @{
- instrument = "Horn in F"
-@}
-
-@{
- \transpose f c' \hornNotes
-@}
-@end example
-
-The line
-
-@example
-\include "horn-music.ly"
-@end example
-
-@noindent
-substitutes the contents of @file{horn-music.ly} at this position in
-the file, so @code{hornNotes} is defined afterwards. The command
-@code{\transpose f@tie{}c'} indicates that the argument, being
-@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
-@samp{f} is denoted by notated @code{c'}, which corresponds with the
-tuning of a normal French Horn in@tie{}F. The transposition can be seen
-in the following output
-
-@lilypond[quote,ragged-right]
-\transpose f c' \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 @samp{R} followed by a duration
-(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the
-duration, longer rests can be constructed. For example, this rest
-takes 3@tie{}measures in 2/4 time
-
-@example
-R2*3
-@end example
-
-When printing the part, multi-rests
-must be condensed. This is done by setting a run-time variable
-
-@example
-\set Score.skipBars = ##t
-@end example
-
-@noindent
-This command sets the property @code{skipBars} in the
-@code{Score} context to true (@code{##t}). Prepending the rest and
-this option to the music above, leads to the following result
-
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- \set Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e d
-}
-@end lilypond
-
-
-The score is made by combining all of the music together. Assuming
-that the other voice is in @code{bassoonNotes} in the file
-@file{bassoon-music.ly}, a score is made with
-
-@example
-\include "bassoon-music.ly"
-\include "horn-music.ly"
-
-<<
- \new Staff \hornNotes
- \new Staff \bassoonNotes
->>
-@end example
-
-@noindent
-leading to
-
-@lilypond[quote,ragged-right]
-\relative c <<
- \new Staff {
- \time 2/4 R2*3
- r4 f8 a cis4 f e d
- }
- \new Staff {
- \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f
- }
->>
-@end lilypond
-
-More in-depth information on preparing parts and scores can be found
-in the notation manual; see @ref{Orchestral music}.
-
-Setting run-time variables (`properties') is discussed in
-@ref{Changing context properties on the fly}.
-
-
* Adding titles::
* Single staff polyphony::
* Piano staves::
+* Organizing larger pieces::
+* An orchestral part::
+* After the tutorial::
@end menu
More information on formatting piano music is given in @ref{Piano music}.
+@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 pieces,
+more deeply nested. Such large expressions can become unwieldy.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions. An identifier is assigned as follows
+
+@example
+namedMusic = @{ @dots{} @}
+@end example
+
+@noindent
+The contents of the music expression @code{namedMusic}, can be used
+later by preceding the name with a backslash, i.e., @code{\namedMusic}.
+In the next example, a two-note motive is repeated two times by using
+variable substitution
+
+@lilypond[quote,ragged-right,verbatim,nofragment]
+seufzer = {
+ e'4( dis'4)
+}
+{ \seufzer \seufzer }
+@end lilypond
+
+The name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes. The assignment should be outside of
+running music.
+
+It is possible to use variables for many other types of objects in the
+input. For example,
+
+@example
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables
+
+@example
+\paper @{
+ \aFivePaper
+ line-width = \width
+@}
+@{ c4^\name @}
+@end example
+
+More information on the possible uses of identifiers is given in the
+technical manual, in @ref{Input variables and Scheme}.
+@c fixme: the ref is too technical.
+
+
+@node An orchestral part
+@section An orchestral part
+
+In orchestral music, all notes are printed twice. Once in a part for
+the musicians, and once in a full score for the conductor. Identifiers can
+be used to avoid double work. The music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the full score.
+
+It is convenient to define the notes in a special file. For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/@/bassoon duo
+
+@example
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
+@example
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
+
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
+@samp{f} is denoted by notated @code{c'}, which corresponds with the
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,ragged-right]
+\transpose f c' \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 @samp{R} followed by a duration
+(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
+@example
+R2*3
+@end example
+
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
+@example
+\set Score.skipBars = ##t
+@end example
+
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+
+The score is made by combining all of the music together. Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
+
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+<<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+>>
+@end example
+
+@noindent
+leading to
+
+@lilypond[quote,ragged-right]
+\relative c <<
+ \new Staff {
+ \time 2/4 R2*3
+ r4 f8 a cis4 f e d
+ }
+ \new Staff {
+ \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f
+ }
+>>
+@end lilypond
+
+More in-depth information on preparing parts and scores can be found
+in the notation manual; see @ref{Orchestral music}.
+
+Setting run-time variables (`properties') is discussed in
+@ref{Changing context properties on the fly}.
+
+
+@node After the tutorial
+@section After the tutorial
+
+After finishing the tutorial, you should probably try writing a
+piece or two. Start with one of the @ref{Example templates} and
+add notes. If you need any notation that was not covered in the
+tutorial, look at the Notation Reference, starting with
+@ref{Basic notation}. If you want to write for an instrument
+ensemble which is not covered in the @ref{Example 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 them 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.
+
+
@node Tweaking output
@chapter Tweaking output
-Tweak explanation.
+This chapter discusses how modify output. LilyPond is extremely
+configurable; virtually every fragment of output may be changed.
@menu
* Fixing overlapping notation::
* Common tweaks::
+* Default files::
* Advanced tweaks with scheme::
@end menu
This tweaks the display of text for the next note. If the note has
no text, this tweak does nothing (and does @strong{not} wait until
-the next bit of text).
+the next bit of text). To change the behavior of everything after
+the command, omit the @code{\once}. To stop this tweak, use a
+@code{\revert}. This is explained in depth in
+@ref{The \override command}.
@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
c4^"piu mosso" b
\override TextScript #'padding = #2.6
c4^"piu mosso" d e f
c4^"piu mosso" d e f
+\revert TextScript #'padding
+c4^"piu mosso" d e f
@end lilypond
This manual: @ref{The \override command}, @ref{Common tweaks}.
-@menu
-* Common tweaks::
-@end menu
-
@node Common tweaks
@section Common tweaks
-@c Should we point at ly/property-init.ly ? -gp
Some overrides are so common that predefined commands are provided as
-short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@c @ref{Notation manual},
-Notation manual
-@c FIXME
-under the sections for slurs and stems
-respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a few of these:
+short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
+commands are described in the Notation Reference under the appropriate
+sections.
+
+The complete list of modifications available for each type of
+object (like slurs or beams) are documented in the Program
+Reference. However, many layout objects share properties, which can be
+used to apply generic tweaks.
@itemize @bullet
-@item The @code{extra-offset} property, which
+
+@cindex @code{padding}
+@item The @code{padding} property can be set to increase
+(or decrease) the distance between symbols that are printed
+above or below notes. This applies to all objects with
+@code{side-position-interface}.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c2\fermata
+\override Script #'padding = #3
+b2\fermata
+@end lilypond
+
+@lilypond[quote,fragment,relative=1,verbatim]
+% This will not work, see below:
+\override MetronomeMark #'padding = #3
+\tempo 4=120
+c1
+% This works:
+\override Score.MetronomeMark #'padding = #3
+\tempo 4=80
+d1
+@end lilypond
+
+Note in the second example how important it is to figure out what
+context handles a certain object. Since the @code{MetronomeMark} object
+is handled in the Score context, property changes in the @code{Voice}
+context will not be noticed. For more details, see
+@ref{Constructing a tweak}.
+
@cindex @code{extra-offset}
-has a pair of numbers as value, moves objects around 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 units 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.
+@item The @code{extra-offset} property moves objects around
+in the output; it requires a pair of numbers. The first number
+controls horizontal movement; a positive number will
+move the object to the right. The second number controls vertical
+movement; a positive number will move it higher. The
+@code{extra-offset} property is a low-level feature: the
+formatting engine is completely oblivious to these offsets.
In the following example, the second fingering is moved a little to
the left, and 1.8 staff space downwards:
-@cindex setting object properties
-
@lilypond[quote,fragment,relative=1,verbatim]
\stemUp
f-5
} >>
@end lilypond
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase the distance between
-symbols that are printed above or below notes. We provide two
-examples; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
-\override Script #'padding = #3
-b2\fermata
-@end lilypond
-
-@lilypond[quote,fragment,relative=1,verbatim]
-% This will not work, see below:
-\override MetronomeMark #'padding = #3
-\tempo 4=120
-c1
-% This works:
-\override Score.MetronomeMark #'padding = #3
-\tempo 4=80
-d1
-@end lilypond
-
-Note in the second example how important it is to figure out what
-context handles a certain object. Since the @code{MetronomeMark} object
-is handled in the Score context, property changes in the @code{Voice}
-context will not be noticed.
-
@end itemize
-Some tweakable options are called ``subproperties'' and reside inside
-properties. To tweak those, use
-
-@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
-@end example
-
@cindex Tweaks, distances
@cindex Distances
is measured in staff-spaces. For more information, see the
relevant portion of the program reference.
-More specific overrides are also possible. The next section
-discusses in depth how to figure out these statements for yourself.
+
+@node Default files
+@section Default files
+
+The Program Reference documentation contains a lot of information
+about LilyPond, but even more information can be gathered from
+looking at the internal LilyPond files.
+
+Some default settings (such as the definitions for
+@code{\header@{@}}s) are stored as @code{.ly} files. Other
+settings (such as the definitions of markup commands) are
+stored as @code{.scm} (Scheme) files. Further explanation is
+outside the scope of this manual; users should be warned that
+a substantial amount of technical knowledge or time is required
+to understand these files.
+
+@itemize bullet
+
+@item Linux: @file{/usr/ ... }
+
+@item OSX:
+@file{@{LILYPOND_INSTALLED_DIR@}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
+To access this, either @code{cd} into this directory from
+the Terminal, or control-click on the LilyPond application
+and select "Show Package Contents".
+
+@item Windows:
+
+@end itemize
+
+The @file{ly/} and @file{scm/} directories will be of
+particular interest. Files such as @file{ly/property-init.ly} and
+@file{ly/declarations-init.ly} define all the common tweaks.
@node Advanced tweaks with scheme
We have seen how LilyPond output can be heavily modified using
commands like
@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
-we have even more power if we use scheme.
+we have even more power if we use scheme. For a full explantion
+of this, see @ref{Interfaces for programmers}.
+
+We can use scheme to simply @code{\override} commands,
+
+@lilypond[quote,verbatim,ragged-right]
+padText = #(define-music-function (parser location padding) (number?)
+#{
+ \once \override TextScript #'padding = #$padding
+#})
+
+\relative c''' {
+ c4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" d e f
+ \padText #2.6
+ c4^"piu mosso" fis a g
+}
+@end lilypond
+
+We can use it to create new commands,
+
+@lilypond[quote,verbatim,ragged-right]
+tempoMark = #(define-music-function (parser location marktext padding) (string? number?)
+#{
+ \once \override Score . RehearsalMark #'padding = $padding
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $marktext }
+#})
+
+\relative c'' {
+c2 e
+\tempoMark #"Allegro" #3.0
+g c
+}
+@end lilypond
-FIXME scheme stuffs
+Even music expressions can be passed in. Note that since we
+want an articulation attached to the second variable, we
+must #####.
+
+@lilypond[quote,verbatim,ragged-right]
+%pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
+%#{
+% $x e8-. a-. b-. $y-.-> b-. a-. e-.
+%#})
+
+\relative c''{
+c'4
+% \pattern c8 c8
+% \pattern d8 ais8
+% \pattern cis8 des8
+}
+@end lilypond
This section explains a how to solve or avoid certain common
problems. If you have programming experience, many of these
-tips may seem obvious; you may wish to simply skim this
-chapter.
+tips may seem obvious, but it is still advisable to read
+this chapter.
@menu
* Suggestions for writing LilyPond files::
+* Typesetting existing music::
* Updating old files::
* Troubleshooting (taking it all apart)::
-* Saving typing with identifiers::
+* Saving typing with identifiers and functions::
* Style sheets::
@end menu
@end itemize
-
+@node Typesetting existing music
+@section Typesetting existing music
If you are entering music from an existing score (i.e. typesetting a
piece of existing sheet music),
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- for example,
-"@code{No\"el}" (Christmas). In LilyPond 2.6 and above, the special
+"@code{No\"el}" (this would print the French word for
+`Christmas'). In LilyPond 2.6 and above, the special
"@code{ë}" must be entered directly into the LilyPond file as an
UTF-8 character. @code{convert-ly} cannot change all the LaTeX
special characters into UTF-8 characters; you must manually update
@code{bass} part until you find the problem line.
-@node Saving typing with identifiers
-@section Saving typing with identifiers
+@node Saving typing with identifiers and functions
+@section Saving typing with identifiers and functions
By this point, you've seen this kind of thing:
projects / lilypond.git / commitdiff