Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.19.2"
@node General input and output
@chapter General input and output
* Working with input files::
* Controlling output::
* MIDI output::
+* Extracting musical information::
@end menu
@section Input structure
The main format of input for LilyPond are text files. By convention,
-these files end with @code{.ly}.
+these files end with @file{.ly}.
@menu
* Structure of a score::
* Multiple scores in a book::
+* Multiple output files from one input file::
+* Output file names::
* File structure::
@end menu
@example
\score @{
-...
+ @dots{}
@}
@end example
Comments are one exception to this general rule. (For others see
@ref{File structure}.) Both single-line comments and comments
-delimited by @code{%@{ .. %@}} may be placed anywhere within an
+delimited by @code{%@{ @dots{} %@}} may be placed anywhere within an
input file. They may be placed inside or outside a @code{\score}
block, and inside or outside the single music expression within a
@code{\score} block.
+Remember that even in a file containing only a @code{\score} block, it
+is implicitly enclosed in a \book block. A \book block in a source
+file produces at least one output file, and by default the name of the
+output file produced is derived from the name of the input file, so
+@file{fandangoforelephants.ly} will produce
+@file{fandangoforelephants.pdf}.
+
+(For more details about @code{\book} blocks, see
+@ref{Multiple scores in a book},
+@ref{Multiple output files from one input file} @ref{File structure}.)
@seealso
Learning Manual:
@example
\score @{
- @var{..music..}
+ @var{@dots{}music@dots{}}
@}
@end example
@example
\markup @{
- @var{..text..}
+ @var{@dots{}text@dots{}}
@}
@end example
@funindex \book
-All the movements and texts which appear in the same @code{.ly} file
+All the movements and texts which appear in the same @file{.ly} file
will normally be typeset in the form of a single output file.
@example
\score @{
- @var{..}
+ @var{@dots{}}
@}
\markup @{
- @var{..}
+ @var{@dots{}}
@}
\score @{
- @var{..}
+ @var{@dots{}}
@}
@end example
-However, if you want multiple output files from the same @code{.ly}
-file, then you can add multiple @code{\book} blocks, where each such
-@code{\book} block will result in a separate output. If you do not
-specify any @code{\book} block in the file, LilyPond will implicitly
-treat the full file as a single @code{\book} block, see @ref{File
-structure}. One important exception is within lilypond-book documents,
+One important exception is within lilypond-book documents,
where you explicitly have to add a @code{\book} block, otherwise only
the first @code{\score} or @code{\markup} will appear in the output.
\header @{ piece = "Romanze" @}
@}
\markup @{
- ..text of second verse..
+ @dots{}text of second verse@dots{}
@}
\markup @{
- ..text of third verse..
+ @dots{}text of third verse@dots{}
@}
\score @{
@dots{}
@}
@end example
+@node Multiple output files from one input file
+@subsection Multiple output files from one input file
+
+If you want multiple output files from the same @file{.ly} file,
+then you can add multiple @code{\book} blocks, where each
+such \book block will result in a separate output file.
+If you do not specify any @code{\book} block in the
+input file, LilyPond will implicitly treat the whole
+file as a single \book block, see
+@ref{File structure}.
+
+When producing multiple files from a single source file, Lilypond
+ensures that none of the output files from any @code{\book} block
+overwrites the output file produced by a preceding @code{\book} from
+the same input file.
+
+It does this by adding a suffix to the output name for each
+@code{\book} which uses the default output file name derived from the
+input source file.
+
+The default behaviour is to append a version-number suffix for each
+name which may clash, so
+
+@example
+\book @{
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+@end example
+
+in source file @file{eightminiatures.ly}
+will produce
+
+@itemize
+@item
+@file{eightminiatures.pdf},
+@item
+@file{eightminiatures-1.pdf} and
+@item
+@file{eightminiatures-2.pdf}.
+@end itemize
+
+@node Output file names
+@subsection Output file names
+
+@funindex \bookOutputSuffix
+@funindex \bookOutputName
+
+Lilypond provides facilities to allow you to control what file names
+are used by the various back-ends when producing output files.
+
+In the previous section, we saw how Lilypond prevents name-clashes when
+producing several ouputs from a single source file. You also have the
+ability to specify your own suffixes for each @code{\book} block, so
+for example you can produce files called
+@file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
+and @file{eightminiatures-Nocturne.pdf} by adding a
+@code{\bookOutputSuffix} declaration inside each @code{\book} block.
+
+@example
+\book @{
+ \bookOutputSuffix "Romanze"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Menuetto"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Nocturne"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+@end example
+
+You can also specify a different output filename for @code{book} block,
+by using @code{\bookOutputName} declarations
+
+@example
+\book @{
+ \bookOutputName "Romanze"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Menuetto"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Nocturne"
+ \score @{ @dots{} @}
+ \paper @{ @dots{} @}
+@}
+@end example
+
+The file above will produce these output files:
+
+@itemize
+@item
+@file{Romanze.pdf},
+@item
+@file{Menuetto.pdf} and
+@item
+@file{Nocturne.pdf}.
+@end itemize
+
+
@node File structure
@subsection File structure
@funindex \book
@funindex \bookpart
-A @code{.ly} file may contain any number of toplevel expressions, where a
+A @file{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
-@itemize @bullet
+@itemize
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
-book-wide settings. If more than one such definition of
-the same type is entered at the top level any definitions in the later
-expressions have precedence.
+book-wide settings. If more than one such definition of the same type
+is entered at the top level the definitions are combined, but in
+conflicting situations the later definitions take precedence. For
+details of how this affects the @code{\layout} block see
+@ref{The layout block,,The @code{@bs{}layout} block}.
@item
A direct scheme expression, such as
@code{#(ly:set-option 'point-and-click #f)}.
@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
+A @code{\header} block. This sets the global (i.e. the top of
+file) header block. This is the block containing the default
+settings of titling fields like composer, title, etc. for all
+books within the file (see @ref{Titles explained}).
@item
A @code{\score} block. This score will be collected with other
toplevel scores, and combined as a single @code{\book}.
This behavior can be changed by setting the variable
@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{../scm/lily.scm}.
@item
A @code{\book} block logically combines multiple movements
are a number of @code{\score}s, one output file will be created
for each @code{\book} block, in which all corresponding movements
are concatenated. The only reason to explicitly specify
-@code{\book} blocks in a @code{.ly} file is if you wish to create
+@code{\book} blocks in a @file{.ly} file is if you wish to create
multiple output files from a single input file. One exception is
within lilypond-book documents, where you explicitly have to add
a @code{\book} block if you want more than a single @code{\score}
or @code{\markup} in the same example. This behavior can be
changed by setting the variable @code{toplevel-book-handler} at
toplevel. The default handler is defined in the init file
-@file{../@/scm/@/lily@/.scm}.
+@file{../scm/lily.scm}.
@item
A @code{\bookpart} block. A book may be divided into several parts,
@{ c'4 d' e'2 @}
@}
@}
+ \layout @{ @}
@}
- \layout @{ @}
- \header @{ @}
+ \paper @{ @}
+ \header @{ @}
@}
@end example
This behavior can be changed by setting the variable
@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{../scm/lily.scm}.
@item
A markup text, a verse for example
At any point in a file, any of the following lexical instructions can
be entered:
-@itemize
-@item @code{\version}
-@item @code{\include}
-@item @code{\sourcefilename}
-@item @code{\sourcefileline}
-@item
-A single-line comment, introduced by a leading @code{%} sign.
+@itemize
+@item @code{\version}
+@item @code{\include}
+@item @code{\sourcefilename}
+@item @code{\sourcefileline}
+@item
+A single-line comment, introduced by a leading @code{%} sign.
+
+@item
+A multi-line comment delimited by @code{%@{ @dots{} %@}}.
+
+@end itemize
+
+@cindex whitespace
+
+Whitespace between items in the input stream is generally ignored,
+and may be freely omitted or extended to enhance readability.
+However, whitespace should always be used in the following
+circumstances to avoid errors:
+
+@itemize
+
+@item Around every opening and closing curly bracket.
+
+@item After every command or variable, i.e. every item that
+begins with a @code{\} sign.
+
+@item After every item that is to be interpreted as a Scheme
+expression, i.e. every item that begins with a @code{#}@tie{}sign.
+
+@item To separate all elements of a Scheme expression.
+
+@item In @code{lyricmode} before and after @code{\set} and
+@code{\override} commands.
+
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work}.
+
+Notation Reference:
+@ref{Titles explained},
+@ref{The layout block,,The @code{@bs{}layout} block}.
+
+
+@node Titles and headers
+@section Titles and headers
+
+Almost all printed music includes a title and the composer's name;
+some pieces include a lot more information.
+
+@menu
+* Creating titles headers and footers::
+* Custom titles headers and footers::
+* Creating footnotes::
+* Reference to page numbers::
+* Table of contents::
+@end menu
+
+
+@node Creating titles headers and footers
+@subsection Creating titles headers and footers
+
+@menu
+* Titles explained::
+* Default layout of bookpart and score titles::
+* Default layout of headers and footers::
+@end menu
+
+
+@node Titles explained
+@unnumberedsubsubsec Titles explained
+
+Each @code{\book} block in a single input file produces a separate
+output file, see @ref{File structure}. Within each output file
+three types of titling areas are provided: @emph{Book Titles} at the
+beginning of each book, @emph{Bookpart Titles} at the beginning of
+each bookpart and @emph{Score Titles} at the beginning of each score.
+
+Values of titling fields such as @code{title} and @code{composer}
+are set in @code{\header} blocks. (For the syntax of @code{\header}
+blocks and a complete list of the fields available by default see
+@ref{Default layout of bookpart and score titles}). Book Titles,
+Bookpart Titles and Score Titles can all contain the same fields,
+although by default the fields in Score Titles are limited to
+@code{piece} and @code{opus}.
+
+@code{\header} blocks may be placed in four different places to form
+a descending hierarchy of @code{\header} blocks:
+
+@itemize
+
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
+
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
+
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
+
+@item
+After the music expression in a @code{\score} block.
+
+@end itemize
+
+The values of the fields filter down this hierarchy, with the values
+set higher in the hierarchy persisting unless they are over-ridden
+by a value set lower in the hierarchy, so:
+
+@itemize
+
+@item
+A Book Title is derived from fields set at the top of the input file,
+modified by fields set in the @code{\book} block. The resulting
+fields are used to print the Book Title for that book, providing that
+there is other material which generates a page at the start of the
+book, before the first bookpart. A single @code{\pageBreak} will
+suffice.
+
+@item
+A Bookpart Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, and further
+modified by fields set in the @code{\bookpart} block. The resulting
+values are used to print the Bookpart Title for that bookpart.
+
+@item
+A Score Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, further
+modified by fields set in the @code{\bookpart} block and finally
+modified by fields set in the @code{\score} block. The resulting
+values are used to print the Score Title for that score. Note,
+though, that only @code{piece} and @code{opus} fields are printed
+by default in Score Titles unless the @code{\paper} variable,
+@code{print-all-headers}, is set to @code{#t}.
+
+@end itemize
+
+@warning{Remember when placing a @bs{}@code{header} block inside a
+@bs{}@code{score} block, that the music expression must come before the
+@bs{}@code{header} block.}
+
+It is not necessary to provide @code{\header} blocks in all four
+places: any or even all of them may be omitted. Similarly, simple
+input files may omit the @code{\book} and @code{\bookpart} blocks,
+leaving them to be created implicitly.
+
+If the book has only a single score, the @code{\header} block should
+normally be placed at the top of the file so that just a Bookpart
+Title is produced, making all the titling fields available for use.
+
+If the book has multiple scores a number of different arrangements
+of @code{\header} blocks are possible, corresponding to the various
+types of musical publications. For example, if the publication
+contains several pieces by the same composer a @code{\header} block
+placed at the top of the file specifying the book title and the
+composer with @code{\header} blocks in each @code{\score} block
+specifying the @code{piece} and/or @code{opus} would be most
+suitable, as here:
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\header {
+ title = "SUITE I."
+ composer = "J. S. Bach."
+}
+
+\score {
+ \new Staff \relative g, {
+ \clef bass
+ \key g \major
+ \repeat unfold 2 { g16( d' b') a b d, b' d, } |
+ \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
+ }
+ \header {
+ piece = "Prélude."
+ }
+}
+
+\score {
+ \new Staff \relative b {
+ \clef bass
+ \key g \major
+ \partial 16 b16 |
+ <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
+ d16( b g fis) g( e d c) b(c d e) fis( g a b) |
+ }
+ \header {
+ piece = "Allemande."
+ }
+}
+@end lilypond
+
+More complicated arrangements are possible. For example, text
+fields from the @code{\header} block in a book can be displayed in
+all Score Titles, with some fields over-ridden and some manually
+suppressed:
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ print-all-headers = ##t
+ }
+ \header {
+ title = "DAS WOHLTEMPERIRTE CLAVIER"
+ subtitle = "TEIL I"
+ % Do not display the tagline for this book
+ tagline = ##f
+ }
+ \markup { \vspace #1 }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "PRAELUDIUM I"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "FUGA I"
+ subsubtitle = "A 4 VOCI"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{File structure},
+@ref{Default layout of bookpart and score titles},
+@ref{Custom layout for titles}.
+
+
+@node Default layout of bookpart and score titles
+@unnumberedsubsubsec Default layout of bookpart and score titles
+
+This example demonstrates all @code{\header} variables:
+
+@lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
+\book {
+ \header {
+ % The following fields are centered
+ dedication = "Dedication"
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ % The following fields are evenly spread on one line
+ % the field "instrument" also appears on following pages
+ instrument = \markup \with-color #green "Instrument"
+ poet = "Poet"
+ composer = "Composer"
+ % The following fields are placed at opposite ends of the same line
+ meter = "Meter"
+ arranger = "Arranger"
+ % The following fields are centered at the bottom
+ tagline = "tagline goes at the bottom of the last page"
+ copyright = "copyright goes at the bottom of the first page"
+ }
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 1"
+ opus = "Opus 1"
+ }
+ }
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 2 on the same page"
+ opus = "Opus 2"
+ }
+ }
+ \pageBreak
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 3 on a new page"
+ opus = "Opus 3"
+ }
+ }
+}
+@end lilypond
+
+Note that
+
+@itemize
+@item
+The instrument name will be repeated on every page.
+
+@item
+Only @code{piece} and @code{opus} are printed in a @code{\score}
+when the paper variable @code{print-all-headers} is set to
+@code{##f} (the default).
+
+@item
+@c Is the bit about \null markups true? -mp
+Text fields left unset in a @code{\header} block are replaced with
+@code{\null} markups so that the space is not wasted.
+
+@item
+The default settings for @code{scoreTitleMarkup} place the @code{piece}
+and @code{opus} text fields at opposite ends of the same line.
+
+@end itemize
+
+To change the default layout see @ref{Custom layout for titles}.
+
+@cindex breakbefore
+
+If a @code{\book} block starts immediately with a @code{\bookpart}
+block, no Book Title will be printed, as there is no page on which
+to print it. If a Book Title is required, begin the @code{\book}
+block with some markup material or a @code{\pageBreak} command.
+
+Use the @code{breakbefore} variable inside a @code{\header} block
+that is itself in a @code{\score} block, to make the higher-level
+@code{\header} block titles appear on the first page on their own, with
+the music (defined in the @code{\score} block) starting on the next.
+
+@lilypond[papersize=c7landscape,verbatim,noragged-right]
+\book {
+ \header {
+ title = "This is my Title"
+ subtitle = "This is my Subtitle"
+ copyright = "This is the bottom of the first page"
+ }
+ \score {
+ \repeat unfold 4 { e'' e'' e'' e'' }
+ \header {
+ piece = "This is the Music"
+ breakbefore = ##t
+ }
+ }
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work},
+
+Notation Reference:
+@ref{Custom layout for titles},
+@ref{File structure}.
+
+Installed Files:
+@file{ly/titling-init.ly}.
+
+
+@node Default layout of headers and footers
+@unnumberedsubsubsec Default layout of headers and footers
+
+@emph{Headers} and @emph{footers} are lines of text appearing at
+the top and bottom of pages, separate from the main text of a book.
+They are controlled by the following @code{\paper} variables:
+
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
+
+These markup variables can only access text fields from top-level
+@code{\header} blocks (which apply to all scores in the book) and are
+defined in @file{ly/titling-init.ly}. By default:
+
+@itemize
+
+@item
+page numbers are automatically placed on the top far left (if even) or
+top far right (if odd), starting from the second page.
+
+@item
+the @code{instrument} text field is placed in the center of every
+page, starting from the second page.
+
+@item
+the @code{copyright} text is centered on the bottom of the first page.
+
+@item
+the @code{tagline} is centered on the bottom of the last page, and below
+the @code{copyright} text if there is only a single page.
+
+@end itemize
+
+The default tagline can be changed by adding a @code{tagline} in the
+top-level @code{\header} block.
+
+@lilypond[papersize=a8landscape,verbatim]
+\book {
+ \header {
+ tagline = "... music notation for Everyone"
+ }
+ \score {
+ \relative c' {
+ c4 d e f
+ }
+ }
+}
+@end lilypond
+
+To remove the @code{tagline} set the value to @code{##f}.
+
+
+@node Custom titles headers and footers
+@subsection Custom titles headers and footers
+
+@c TODO: somewhere put a link to header spacing info
+@c (you'll have to explain it more in NR 4).
+
+@menu
+* Custom text formatting for titles::
+* Custom layout for titles::
+* Custom layout for headers and footers::
+@end menu
+
+
+@node Custom text formatting for titles
+@unnumberedsubsubsec Custom text formatting for titles
+
+Standard @code{\markup} commands can be used to customize any header,
+footer and title text within the @code{\header} block.
+
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
+ opus = \markup { \italic "BWV 846" }
+ }
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Formatting text}.
+
+
+@node Custom layout for titles
+@unnumberedsubsubsec Custom layout for titles
+
+@cindex bookTitleMarkup
+@cindex scoreTitleMarkup
+@funindex bookTitleMarkup
+@funindex scoreTitleMarkup
+
+@code{\markup} commands in the @code{\header} block are useful for
+simple text formatting, but they do not allow precise control over the
+placement of titles. To customize the placement of the text fields,
+change either or both of the following @code{\paper} variables:
+
+@itemize
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
+@end itemize
+
+The placement of titles when using the default values of these
+@code{\markup} variables is shown in the examples in
+@ref{Default layout of bookpart and score titles}.
+
+The default settings for @code{scoreTitleMarkup} as defined in
+@file{ly/titling-init.ly} are:
+
+@example
+scoreTitleMarkup = \markup @{ \column @{
+ \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \fill-line @{
+ \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ @}
+@}
+@}
+@end example
+
+This places the @code{piece} and @code{opus} text fields at opposite
+ends of the same line:
+
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+}
+@end lilypond
+
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \fontsize #4 \bold \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
+
+Text fields not normally effective in score @code{\header} blocks
+can be printed in the Score Title area if @code{print-all-headers} is
+placed inside the @code{\paper} block. A disadvantage of using this
+method is that text fields that are intended specifically for the
+Bookpart Title area need to be manually suppressed in every
+@code{\score} block. See @ref{Titles explained}.
+
+To avoid this, add the desired text field to the @code{scoreTitleMarkup}
+definition. In the following example, the @code{composer} text field
+(normally associated with @code{bookTitleMarkup}) is added to
+@code{scoreTitleMarkup}, allowing each score to list a different
+composer:
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \fontsize #4 \bold \fromproperty #'header:piece
+ \fromproperty #'header:composer
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "MENUET"
+ composer = "Christian Petzold"
+ }
+ }
+ \score {
+ { s1 }
+ \header {
+ piece = "RONDEAU"
+ composer = "François Couperin"
+ }
+ }
+}
+@end lilypond
+
+It is also possible to create your own custom text fields, and refer to
+them in the markup definition.
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \override #`(direction . ,UP) {
+ \dir-column {
+ \center-align \fontsize #-1 \bold
+ \fromproperty #'header:mycustomtext %% User-defined field
+ \center-align \fontsize #4 \bold
+ \fromproperty #'header:piece
+ }
+ }
+ \fromproperty #'header:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "FUGA I"
+ mycustomtext = "A 4 VOCI" %% User-defined field
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Titles explained}.
+
+
+@node Custom layout for headers and footers
+@unnumberedsubsubsec Custom layout for headers and footers
+
+@c can make-header and make-footer be removed from
+@c paper-defaults-init.ly? -mp
+
+@code{\markup} commands in the @code{\header} block are useful for
+simple text formatting, but they do not allow precise control over the
+placement of headers and footers. To customize the placement of
+the text fields, use either or both of the following @code{\paper}
+variables:
+
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
+
+@cindex markup, conditional
+@cindex on-the-fly
+@funindex \on-the-fly
+
+The @code{\markup} command @code{\on-the-fly} can be used to add
+markup conditionally to header and footer text defined within the
+@code{\paper} block, using the following syntax:
+
+@example
+@code{variable} = @code{\markup} @{
+ @dots{}
+ @code{\on-the-fly} \@var{procedure} @var{markup}
+ @dots{}
+@}
+@end example
+
+The @var{procedure} is called each time the @code{\markup} command
+in which it appears is evaluated. The @var{procedure} should test
+for a particular condition and interpret (i.e. print) the
+@var{markup} argument if and only if the condition is true.
+
+A number of ready-made procedures for testing various conditions are
+provided:
+
+@quotation
+@multitable {print-page-number-check-first-----} {should this page be printed-----}
+
+@headitem Procedure name @tab Condition tested
-@item
-A multi-line comment delimited by @code{%@{ .. %@}}.
+@item print-page-number-check-first @tab should this page number be printed?
+@item create-page-number-stencil @tab print-page-numbers true?
+@item print-all-headers @tab print-all-headers true?
+@item first-page @tab first page in the book?
+@item (on-page nmbr) @tab page number = nmbr?
+@item last-page @tab last page in the book?
+@item not-first-page @tab not first page in the book?
+@item part-first-page @tab first page in the book part?
+@item part-last-page @tab last page in the book part?
+@item not-single-page @tab pages in book part > 1?
-@end itemize
+@end multitable
+@end quotation
-@cindex whitespace
+The following example centers page numbers at the bottom of every
+page. First, the default settings for @code{oddHeaderMarkup} and
+@code{evenHeaderMarkup} are removed by defining each as a @emph{null}
+markup. Then, @code{oddFooterMarkup} is redefined with the page
+number centered. Finally, @code{evenFooterMarkup} is given the
+same layout by defining it as @code{\oddFooterMarkup}:
-Whitespace between items in the input stream is generally ignored,
-and may be freely omitted or extended to enhance readability.
-However, whitespace should always be used in the following
-circumstances to avoid errors:
+@lilypond[papersize=a8,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ print-page-number = ##t
+ print-first-page-number = ##t
+ oddHeaderMarkup = \markup \null
+ evenHeaderMarkup = \markup \null
+ oddFooterMarkup = \markup {
+ \fill-line {
+ \on-the-fly \print-page-number-check-first
+ \fromproperty #'page:page-number-string
+ }
+ }
+ evenFooterMarkup = \oddFooterMarkup
+ }
+ \score {
+ \new Staff { s1 \break s1 \break s1 }
+ }
+}
+@end lilypond
-@itemize
-@item Around every opening and closing curly bracket.
-@item After every command or variable, i.e. every item that
-begins with a @code{\} sign.
-@item After every item that is to be interpreted as a Scheme
-expression, i.e. every item that begins with a @code{#} sign.
-@item To separate all elements of a Scheme expression.
-@item In @code{lyricmode} to separate all the terms in both
-@code{\override} and @code{\set} commands. In particular, spaces
-must be used around the dot and the equals sign in commands like
-@code{\override Score . LyricText #'font-size = #5} and before and
-after the entire command.
+Several @code{\on-the-fly} conditions can be combined with an
+@q{and} operation, for example,
-@end itemize
+@example
+ @code{\on-the-fly \first-page}
+ @code{\on-the-fly \last-page}
+ @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
+@end example
+determines if the output is a single page.
@seealso
-Learning Manual:
-@rlearning{How LilyPond input files work}.
+Notation Reference:
+@ref{Titles explained},
+@ref{Default layout of bookpart and score titles}.
+Installed Files:
+@file{../ly/titling-init.ly}.
-@node Titles and headers
-@section Titles and headers
-Almost all printed music includes a title and the composer's name;
-some pieces include a lot more information.
+@node Creating footnotes
+@subsection Creating footnotes
+
+@cindex footnotes
+
+Footnotes may be used in many different situations. In all cases,
+a @q{footnote mark} is placed as a reference in text or music, and
+the corresponding @q{footnote text} appears at the bottom of the
+same page.
+
+Footnotes within music expressions and footnotes in stand-alone text
+outside music expressions are created in different ways.
@menu
-* Creating titles::
-* Custom titles::
-* Reference to page numbers::
-* Table of contents::
+* Footnotes in music expressions::
+* Footnotes in stand-alone text::
@end menu
+@node Footnotes in music expressions
+@unnumberedsubsubsec Footnotes in music expressions
-@node Creating titles
-@subsection Creating titles
+@cindex footnotes in music expressions
+@funindex \footnote
-Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block) and book parts (created by
-@code{\bookpart} blocks).
+@subsubsubheading Music footnotes overview
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
+Footnotes in music expressions fall into two categories:
+@table @emph
+@item Event-based footnotes
+are attached to a particular event. Examples for such events are
+single notes, articulations (like fingering indications, accents,
+dynamics), and post-events (like slurs and manual beams). The
+general form for event-based footnotes is as follows:
-@table @code
-@funindex dedication
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
+@example
+[@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-@funindex title
-@item title
-The title of the music, centered just below the dedication.
+@item Time-based footnotes
+are bound to a particular point of time in a musical context. Some
+commands like @code{\time} and @code{\clef} don't actually use events
+for creating objects like time signatures and clefs. Neither does a
+chord create an event of its own: its stem or flag is created at the
+end of a time step (nominally through one of the note events inside).
+Exactly which of a chord's multiple note events will be deemed the
+root cause of a stem or flag is undefined. So for annotating those,
+time-based footnotes are preferable as well.
-@funindex subtitle
-@item subtitle
-Subtitle, centered below the title.
+A time-based footnote allows such layout objects to be annotated
+without referring to an event. The general form for Time-based
+footnotes is:
-@funindex subsubtitle
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
+@end example
-@funindex poet
-@item poet
-Name of the poet, flush-left below the subsubtitle.
+@end table
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the subsubtitle. Also
-centered at the top of pages (other than the first page).
+The elements for both forms are:
+
+@table @var
+
+@item direction
+If (and only if) the @code{\footnote} is being applied to a
+post-event or articulation, it must be preceded with a direction
+indicator (@code{-, _, ^}) in order to attach @var{music} (with
+a footnote mark) to the preceding note or rest.
+
+@item mark
+is a markup or string specifying the footnote mark which is used for
+marking both the reference point and the footnote itself at the
+bottom of the page. It may be omitted (or equivalently replaced with
+@code{\default}) in which case a number in sequence will be generated
+automatically. Such numerical sequences restart on each page
+containing a footnote.
+
+@item offset
+is a number pair such as @samp{#(2 . 1)} specifying the X and
+Y@tie{}offsets in units of staff-spaces from the boundary of the
+object where the mark should be placed. Positive values of the
+offsets are taken from the right/top edge, negative values from the
+left/bottom edge and zero implies the mark is centered on the edge.
+
+@item Context
+is the context in which the grob being footnoted is created. It
+may be omitted if the grob is in a bottom context, e.g. a
+@code{Voice} context.
+
+@item GrobName
+specifies a type of grob to mark (like @samp{Flag}). If it is
+specified, the footnote is not attached to a music expression in
+particular, but rather to all grobs of the type specified which
+occur at that moment of musical time.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the
+bottom of the page.
+
+@item music
+is the music event or post-event or articulation
+that is being annotated.
-@funindex composer
-@item composer
-Name of the composer, flush-right below the subsubtitle.
+@end table
-@funindex meter
-@item meter
-Meter string, flush-left below the poet.
+@subsubsubheading Event-based footnotes
-@funindex arranger
-@item arranger
-Name of the arranger, flush-right below the composer.
+@cindex footnotes, event-based
-@funindex piece
-@item piece
-Name of the piece, flush-left below the meter.
+A footnote may be attached to a layout object directly caused
+by the event corresponding to @var{music} with the syntax:
-@funindex opus
-@item opus
-Name of the opus, flush-right below the arranger.
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-@cindex page breaks, forcing
-@funindex breakbefore
-@item breakbefore
-This forces the title to start on a new page (set to ##t or ##f).
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ \footnote #'(-1 . 3) "A note" a4
+ a4
+ \footnote #'(2 . 2) "A rest" r4
+ a4
+ }
+}
+@end lilypond
-@funindex copyright
-@item copyright
-Copyright notice, centered at the bottom of the first page. To
-insert the copyright symbol, see @ref{Text encoding}.
+Marking a @emph{whole} chord with an event-based footnote is not
+possible: a chord, even one containing just a single note, does
+not produce an actual event of its own. However, individual
+notes @emph{inside} of the chord can be marked:
-@funindex tagline
-@item tagline
-Centered at the bottom of the last page.
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ \footnote #'(2 . 3) "Does not work" <a-3>2
+ <\footnote #'(-2 . -3) "Does work" a-3>4
+ <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
+ }
+}
+@end lilypond
-@end table
+If the footnote is to be attached to a post-event or articulation
+the @code{\footnote} command @emph{must} be preceded by a direction
+indicator, @code{-, _, ^}, and followed by the post-event or
+articulation to be annotated as the @var{music} argument. In this
+form the @code{\footnote} can be considered to be simply a copy of
+its last argument with a footnote mark attached to it. The syntax
+is:
-Here is a demonstration of the fields available. Note that you
-may use any @ref{Formatting text}, commands in the header.
+@example
+@var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\paper {
- line-width = 9.0\cm
- paper-height = 10.0\cm
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ a4_\footnote #'(0 . -1) "A slur forced down" (
+ b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
+ b8 ]
+ c4 )
+ c-\footnote #'(1 . 1) "Tenuto" --
+ }
}
+@end lilypond
+
+@subsubsubheading Time-based footnotes
+
+@cindex footnotes, time-based
+If the layout object being footmarked is @emph{indirectly} caused by
+an event (like an @code{Accidental} or @code{Stem} caused by a
+@code{NoteHead} event), the @var{GrobName} of the layout object
+is required after the footnote text instead of @var{music}:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
- \header {
- dedication = "dedicated to me"
- title = \markup \center-column { "Title first line" "Title second line,
-longer" }
- subtitle = "the subtitle,"
- subsubtitle = #(string-append "subsubtitle LilyPond version "
-(lilypond-version))
- poet = "Poet"
- composer = \markup \center-column { "composer" \small "(1847-1973)" }
- texttranslator = "Text Translator"
- meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
-"r" }
- arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
-#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
- instrument = \markup \bold \italic "instrument"
- piece = "Piece"
+ \header { tagline = ##f }
+ \relative c'' {
+ \footnote #'(-1 . -3) "A flat" Accidental
+ aes4 c
+ \footnote #'(-1 . 0.5) "Another flat" Accidental
+ ees
+ \footnote #'(1 . -2) "A stem" Stem
+ aes
}
+}
+@end lilypond
- \score {
- { c'1 }
- \header {
- piece = "piece1"
- opus = "opus1"
- }
- }
- \markup {
- and now...
- }
- \score {
- { c'1 }
- \header {
- piece = "piece2"
- opus = "opus2"
- }
+Note, however, that when a GrobName is specified, a footnote
+will be attached to all grobs of that type at the current time step:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote #'(-1 . 3) "A flat" Accidental
+ <ees ges bes>4
+ \footnote #'(2 . 0.5) "Articulation" Script
+ c'->-.
}
}
@end lilypond
-As demonstrated before, you can use multiple @code{\header} blocks.
-When same fields appear in different blocks, the latter is used.
-Here is a short example.
+A note inside of a chord can be given an individual (event-based)
+footnote. A @samp{NoteHead} is the only grob directly caused
+from a chord note, so an event-based footnote command is
+@emph{only} suitable for adding a footnote to the @samp{NoteHead}
+within a chord. All other chord note grobs are indirectly caused.
+The @code{\footnote} command itself offers no syntax for
+specifying @emph{both} a particular grob type @emph{as well as} a
+particular event to attach to. However, one can use a time-based
+@code{\footnote} command for specifying the grob type, and then
+prefix this command with @code{\single} in order to have it
+applied to just the following event:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ < \footnote #'(1 . -2) "An A" a
+ \single \footnote #'(-1 . -1) "A sharp" Accidental
+ cis
+ \single \footnote #'(0.5 . 0.5) "A flat" Accidental
+ ees fis
+ >2
+ }
+}
+@end lilypond
-@example
-\header @{
- composer = "Composer"
-@}
-\header @{
- piece = "Piece"
-@}
-\score @{
- \new Staff @{ c'4 @}
- \header @{
- piece = "New piece" % overwrite previous one
- @}
-@}
-@end example
+@warning {When footnotes are attached to several musical elements at
+the same musical moment, as they are in the example above, the
+footnotes are numbered from the higher to the lower elements as they
+appear in the printed output, not in the order in which they are
+written in the input stream.}
+
+Layout objects like clefs and key-change signatures are mostly caused
+as a consequence of changed properties rather than actual events.
+Others, like bar lines and bar numbers, are a direct consequence of
+timing. For this reason, footnotes on such objects have to be based
+on their musical timing. Time-based footnotes are also preferable
+when marking features like stems and beams on @emph{chords}: while
+such per-chord features are nominally assigned to @emph{one} event
+inside the chord, relying on a particular choice would be imprudent.
+
+The layout object in question must always be explicitly specified
+for time-based footnotes, and the appropriate context must be
+specified if the grob is created in a context other than the bottom
+context.
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ r1 |
+ \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
+ \time 3/4
+ \footnote #'(1 . -1) "Chord stem" Stem
+ <c e g>4 q q
+ \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
+ q q
+ \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
+ \key c \minor
+ q
+ }
+}
+@end lilypond
-If you define the @code{\header} inside the @code{\score} block, then
-normally only the @code{piece} and @code{opus} headers will be printed.
-Note that the music expression must come before the @code{\header}.
+Custom marks can be used as alternatives to numerical marks, and the
+annotation line joining the marked object to the mark can be
+suppressed:
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\score {
- { c'4 }
- \header {
- title = "title" % not printed
- piece = "piece"
- opus = "opus"
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
+ b8
+ \footnote \markup { \super "$" } #'(0.5 . 1)
+ \markup { \super "$" \italic " The second note" } e
+ c4
+ \once \override Score.FootnoteItem.annotation-line = ##f
+ b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
+ \markup { \super "+" \italic " Editorial" } \p
}
}
@end lilypond
-@funindex print-all-headers
-@noindent
-You may change this behavior (and print all the headers when defining
-@code{\header} inside @code{\score}) by using
+More examples of custom marks are shown in
+@ref{Footnotes in stand-alone text}.
-@example
-\paper@{
- print-all-headers = ##t
-@}
-@end example
-@cindex copyright
-@cindex tagline
+@node Footnotes in stand-alone text
+@unnumberedsubsubsec Footnotes in stand-alone text
+
+@cindex footnotes in stand-alone text
+
+These are for use in markup outside of music expressions. They do
+not have a line drawn to their point of reference: their marks simply
+follow the referenced markup. Marks can be inserted automatically,
+in which case they are numerical. Alternatively, custom marks can be
+provided manually.
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added. The default
-tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
-printed parts are good PR for us, so please leave the tagline if you
-can.}
+Footnotes to stand-alone text with automatic and custom marks are
+created in different ways.
-Headers may be completely removed by setting them to false.
+@subsubsubheading Footnotes in stand-alone text with automatic marks
+
+The syntax of a footnote in stand-alone text with automatic marks is
@example
-\header @{
- tagline = ##f
- composer = ##f
-@}
+\markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
@end example
+The elements are:
-@node Custom titles
-@subsection Custom titles
+@table @var
-A more advanced option is to change the definitions of the following
-variables in the @code{\paper} block. The init file
-@file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
+@item text
+is the markup or string to be marked.
-@table @code
-@funindex bookTitleMarkup
-@item bookTitleMarkup
- This is the title added at the top of the entire output document.
-Typically, it has the composer and the title of the piece
+@item footnote
+is the markup or string specifying the footnote text to use at the bottom
+of the page.
-@funindex scoreTitleMarkup
-@item scoreTitleMarkup
- This is the title put over a @code{\score} block. Typically, it has
-the name of the movement (@code{piece} field).
+@end table
+
+For example:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup {
+ "A simple"
+ \auto-footnote "tune" \italic " By me"
+ "is shown below. It is a"
+ \auto-footnote "recent" \italic " Aug 2012"
+ "composition."
+ }
+ \relative c' {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
+
+@subsubsubheading Footnotes in stand-alone text with custom marks
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+The syntax of a footnote in stand-alone text with custom marks is
-@funindex evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@example
+\markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
+@end example
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+The elements are:
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+@table @var
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+@item mark
+is a markup or string specifying the footnote mark which is used for
+marking the reference point. Note that this mark is @emph{not}
+inserted automatically before the footnote itself.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the
+bottom of the page, preceded by the @var{mark}.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
@end table
+Any easy-to-type character such as * or + may be used as a mark, as
+shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
+aliases may be used (see @ref{ASCII aliases}):
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \paper { #(include-special-characters) }
+ \header { tagline = ##f }
+ \markup {
+ "A simple tune"
+ \footnote "*" \italic "* By me"
+ "is shown below. It is a recent"
+ \footnote \super † \concat {
+ \super † \italic " Aug 2012"
+ }
+ "composition."
+ }
+ \relative c' {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+Unicode character codes may also be used to specify marks
+(see @ref{Unicode}):
-@verbatim
-\paper {
- bookTitleMarkup = \markup {
- \fill-line {
- \fromproperty #'header:title
- \fromproperty #'header:composer
- }
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup {
+ "A simple tune"
+ \footnote \super \char##x00a7 \concat {
+ \super \char##x00a7 \italic " By me"
+ }
+ "is shown below. It is a recent"
+ \footnote \super \char##x00b6 \concat {
+ \super \char##x00b6 \italic " Aug 2012"
+ }
+ "composition."
+ }
+ \relative c' {
+ a'4 b8 e c4 d
}
}
-@end verbatim
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{Objects and interfaces}.
+
+Notation Reference:
+@ref{ASCII aliases},
+@ref{Balloon help},
+@ref{List of special characters},
+@ref{Text marks},
+@ref{Text scripts},
+@ref{Unicode}.
+
+Internals Reference:
+@rinternals{FootnoteEvent},
+@rinternals{FootnoteItem},
+@rinternals{FootnoteSpanner},
+@rinternals{Footnote_engraver}.
+
+@knownissues
+Multiple footnotes for the same page can only be stacked, one above
+the other; they cannot be printed on the same line.
+
+Footnotes cannot be attached to @code{MultiMeasureRests} or
+automatic beams or lyrics.
+
+Footnote marks may collide with staves, @code{\markup} objects, other
+footnote marks and annotation lines.
+
@node Reference to page numbers
@subsection Reference to page numbers
referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.
-@lilypond[verbatim,line-width=11.0\cm]
+@lilypond[verbatim,papersize=a8landscape]
\header { tagline = ##f }
\book {
\label #'firstScore
c'1
}
}
-
\markup { The first score begins on page \page-ref #'firstScore "0" "?" }
\markup { Mark A is on page \page-ref #'markA "0" "?" }
}
@node Table of contents
@subsection Table of contents
-A table of contents is included using the @code{\markuplines \table-of-contents}
+A table of contents is included using the @code{\markuplist \table-of-contents}
command. The elements which should appear in the table of contents are
entered with the @code{\tocItem} command, which may be used either at
top-level, or inside a music expression.
@verbatim
-\markuplines \table-of-contents
+\markuplist \table-of-contents
\pageBreak
\tocItem \markup "First score"
(add-toc-item! 'tocActMarkup text))
@end verbatim
-@lilypond[line-width=11.0\cm]
+@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
tocActMarkup = \markup \large \column {
(add-toc-item! 'tocActMarkup text))
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
\tocItem \markup { Cesare. Presti omai l'Egizzia terra }
}
@end lilypond
+Dots can be added to fill the line between an item and its page number:
-@seealso
-Init files: @file{../@/ly/@/toc@/-init@/.ly}.
+@lilypond[verbatim,line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplist \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+@seealso
+Installed Files:
+@file{ly/toc-init.ly}.
@predefined
@funindex \table-of-contents
@menu
* Including LilyPond files::
* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Special characters::
@end menu
@example
\include "parts/VI.ly"
\include "parts/VII.ly"
-... etc
+@dots{} etc
@end example
Files which are to be included can also contain @code{\include}
@code{\include} statements are not interpreted until they have
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
-not the directory containing the included file. However,
-this behavior can be changed by passing the option
-@code{-drelative-includes} option at the command line
+not the directory containing the included file. However,
+this behavior can be changed globally by passing the option
+@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
-at the top of the main input file). With @code{relative-includes}
-set, the path for each @code{\include} command will be taken
-relative to the file containing that command. This behavior is
-recommended and it will become the default behavior in a future
-version of lilypond.
+at the top of the main input file).
+
+When @code{relative-includes} is set to @code{#t}, the path for each
+@code{\include} command will be taken relative to the file containing
+that command. This behavior is recommended and it will become the
+default behavior in a future version of lilypond.
+
+Files relative to the main directory and files relative to some other
+directory may both be @code{\include}d by setting
+@code{relative-includes} to @code{#t} or @code{#f} at appropriate
+places in the files. For example, if a general library, libA, has
+been created which itself uses sub-files which are @code{\include}d
+by the entry file of that library, those @code{\include} statements
+will need to be preceded by
+@code{#(ly:set-option #relative-includes #t)} so they are interpreted
+correctly when brought into the main @code{.ly} file, like this:
+
+@example
+libA/
+ libA.ly
+ A1.ly
+ A2.ly
+ @dots{}
+@end example
+
+@noindent
+then the entry file, @code{libA.ly}, will contain
+
+@example
+#(ly:set-option 'relative-includes #t)
+\include "A1.ly"
+\include "A2.ly"
+@dots{}
+% return to default setting
+#(ly:set-option 'relative-includes #f)
+@end example
+
+Any @file{.ly} file can then include the entire library simply with
+
+@example
+\include "~/libA/libA.ly"
+@end example
+
+More complex file structures may be devised by switching at
+appropriate places.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
@example
\include "VI.ly"
\include "VII.ly"
-... etc
+@dots{} etc
@end example
Files which are to be included in many scores may be placed in
Some simple examples of using @code{\include} are shown in
@rlearning{Scores and parts}.
-
@seealso
Learning Manual:
@rlearning{Other sources of information},
@rlearning{Scores and parts}.
-
@knownissues
-
If an included file is given a name which is the same as one in
LilyPond's installation files, LilyPond's file from the
installation files takes precedence.
-
@node Different editions from one source
@subsection Different editions from one source
-Several mechanisms are available to facilitate the generation
-of different versions of a score from the same music source.
-Variables are perhaps most useful for combining lengthy sections
-of music and/or annotation in various ways, while tags are more
-useful for selecting one from several alternative shorter sections
-of music. Whichever method is used, separating the notation from
-the structure of the score will make it easier to change the
-structure while leaving the notation untouched.
+Several methods can be used to generate different versions of a score
+from the same music source. Variables are perhaps the most useful for
+combining lengthy sections of music and/or annotation. Tags are more
+useful for selecting one section from several alternative shorter
+sections of music, and can also be used for splicing pieces of music
+together at different points.
+
+Whichever method is used, separating the notation from the structure of
+the score will make it easier to change the structure while leaving the
+notation untouched.
@menu
* Using variables::
* Using tags::
+* Using global settings::
@end menu
@node Using variables
@headitem Filter
@tab Result
@item
-Tagged music preceded by @code{\keepWithTag #'@var{name}}
- @tab Untagged music and music tagged with @var{name} is included;
- music tagged with any other tag name is excluded.
+Tagged music preceded by @code{\keepWithTag #'@var{name}} or
+ @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music tagged with any of the given tag
+ names is included;
+ music tagged with any other tag name is excluded.
@item
-Tagged music preceded by @code{\removeWithTag #'@var{name}}
-@tab Untagged music and music tagged with any tag name other than
- @var{name} is included; music tagged with @var{name} is
+Tagged music preceded by @code{\removeWithTag #'@var{name}} or
+ @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music not tagged with any of the given tag names
+ is included; music tagged with any of the given tag names is
excluded.
@item
Tagged music not preceded by either @code{\keepWithTag} or
@end multitable
The arguments of the @code{\tag}, @code{\keepWithTag} and
-@code{\removeWithTag} commands should be a symbol
-(such as @code{#'score} or @code{#'part}), followed
-by a music expression.
+@code{\removeWithTag} commands should be a symbol or list of
+symbols (such as @code{#'score} or @code{#'(violinI violinII}),
+followed by a music expression. If @emph{and only if} the symbols
+are valid LilyPond identifiers (alphabetic characters only, no
+numbers, underscores, or dashes) which cannot be confused with notes,
+the @code{#'} may be omitted and, as a shorthand, a list of symbols
+can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can
+be written @code{\tag violinI.violinII}. The same applies to
+@code{\keepWithTag} and @code{\removeWithTag}.
In the following example, we see two versions of a piece of music,
one showing trills with the usual notation, and one with trills
@end example
Multiple tags may be placed on expressions with multiple
-@code{\tag} entries:
+@code{\tag} entries, or by combining multiple tags into one symbol
+list:
@lilypond[quote,verbatim]
music = \relative c'' {
\tag #'a \tag #'both { a4 a a a }
- \tag #'b \tag #'both { b4 b b b }
+ \tag #'(b both) { b4 b b b }
}
<<
\keepWithTag #'a \music
@end lilypond
Multiple @code{\removeWithTag} filters may be applied to a single
-music expression to remove several differently named tagged sections:
+music expression to remove several differently named tagged
+sections. Alternatively, you can use a single
+@code{\removeWithTag} with a list of tags.
@lilypond[verbatim,quote]
music = \relative c'' {
-\tag #'A { a4 a a a }
-\tag #'B { b4 b b b }
-\tag #'C { c4 c c c }
-\tag #'D { d4 d d d }
+ \tag #'A { a4 a a a }
+ \tag #'B { b4 b b b }
+ \tag #'C { c4 c c c }
+ \tag #'D { d4 d d d }
}
-{
-\removeWithTag #'B
-\removeWithTag #'C
-\music
+\new Voice {
+ \removeWithTag #'B
+ \removeWithTag #'C
+ \music
+ \removeWithTag #'(B C)
+ \music
}
@end lilypond
expression will cause @emph{all} tagged sections to be removed, as
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
+Usually you would rather want to use a single @code{\keepWithTag}
+command with a list of multiple tags: this will only remove tagged
+sections not given in @emph{any} of the tags.
+
+@cindex tag groups
+@funindex \tagGroup
+While @code{\keepWithTag} is convenient when dealing with
+@emph{one} set of alternatives, the removal of music tagged with
+@emph{unrelated} tags is problematic when using tags for more than
+one purpose. For that reason, @q{tag groups} of related tags can
+be declared:
+
+@example
+\tagGroup #'(violinI violinII viola cello)
+@end example
+
+declares the respective tags as belonging to one tag group.
+
+@example
+\keepWithTag #'violinI @dots{}
+@end example
+
+will then only be concerned with tags from @code{violinI}'s tag
+group: any element of the included music that is tagged with one
+or more of tags from this set but @emph{not} with @code{violinI}
+will get removed.
+
+To any @code{\keepWithTag} command, only tags from the tag groups
+of the tags given in the command are visible.
+
+Tags cannot be members of more than one tag group.
+
+@funindex \pushToTag
+@funindex \appendToTag
+@cindex splice into tagged music
+
+Sometimes you want to splice some music at a particular place in an
+existing music expression. You can use @code{\pushToTag} and
+@code{\appendToTag} for adding material at the front or end of the
+@code{elements} of an existing music construct. Not every music
+construct has @code{elements}, but sequential and simultaneous music are
+safe bets:
+
+@lilypond[verbatim,quote]
+test = { \tag #'here { \tag #'here <<c''>> } }
+{
+ \pushToTag #'here c'
+ \pushToTag #'here e'
+ \pushToTag #'here g' \test
+ \appendToTag #'here c'
+ \appendToTag #'here e'
+ \appendToTag #'here g' \test
+}
+@end lilypond
+
+Both commands get a tag, the material to splice in at every occurence of
+the tag, and the tagged expression.
@seealso
Learning Manual:
@ref{Automatic part combining},
@ref{Including LilyPond files}.
+@knownissues
+Calling @code{\relative} on a music expression obtained by filtering
+music through @code{\keepWithTag} or @code{\removeWithTag} might cause
+the octave relations to change, as only the pitches actually
+remaining in the filtered expression will be considered. Applying
+@code{\relative} first, before @code{\keepWithTag} or
+@code{\removeWithTag}, avoids this danger as @code{\relative} then
+acts on all the pitches as-input.
-@ignore
-@c This warning is more general than this placement implies.
-@c Rests are not merged whether or not they come from tagged sections.
-@c Should be deleted? -td
-@knownissues
+@node Using global settings
+@unnumberedsubsubsec Using global settings
-Multiple rests are not merged if you create a score with more
-than one tagged section at the same place.
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+
+
+@node Special characters
+@subsection Special characters
+
+@cindex special characters
+@cindex non-ASCII characters
+
+@menu
+* Text encoding::
+* Unicode::
+* ASCII aliases::
+@end menu
-@end ignore
@node Text encoding
-@subsection Text encoding
+@unnumberedsubsubsec Text encoding
-@cindex Unicode
@cindex UTF-8
-@cindex non-ASCII characters
LilyPond uses the character repertoire defined by the Unicode
consortium and ISO/IEC 10646. This defines a unique name and
\addlyrics { \portuguese }
@end lilypond
+
+@node Unicode
+@unnumberedsubsubsec Unicode
+
+@cindex Unicode
+
To enter a single character for which the Unicode code point is
known but which is not available in the editor being used, use
either @code{\char ##xhhhh} or @code{\char #dddd} within a
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2015" \char ##x00A9 }
@end lilypond
@cindex copyright sign
@}
@end example
-@node Displaying LilyPond notation
-@subsection Displaying LilyPond notation
-@funindex \displayLilyMusic
-Displaying a music expression in LilyPond notation can be
-done with the music function @code{\displayLilyMusic} but only when
-using the command line. For example,
+@node ASCII aliases
+@unnumberedsubsubsec ASCII aliases
+
+A list of ASCII aliases for special characters can be included:
+
+@lilypond[quote,verbatim]
+\paper {
+ #(include-special-characters)
+}
+
+\markup "&flqq; – &OE;uvre incomplète… &frqq;"
+
+\score {
+ \new Staff { \repeat unfold 9 a'4 }
+ \addlyrics {
+ This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
+ }
+}
-@example
-@{
- \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
-@}
-@end example
+\markup \column {
+ "The replacement can be disabled:"
+ "– &OE; …"
+ \override #'(replacement-alist . ()) "– &OE; …"
+}
+@end lilypond
-will display
+You can also make your own aliases, either globally:
-@example
-@{ a,4 cis e fis g @}
-@end example
+@lilypond[quote,verbatim]
+\paper {
+ #(add-text-replacements!
+ '(("100" . "hundred")
+ ("dpi" . "dots per inch")))
+}
+\markup "A 100 dpi."
+@end lilypond
-By default, LilyPond will print these messages to the console
-along with all the other LilyPond compilation messages. To split
-up these messages and save the results of @code{\display@{STUFF@}},
-redirect the output to a file.
+or locally:
-@example
-lilypond file.ly >display.txt
-@end example
+@lilypond[quote,verbatim]
+\markup \replace #'(("100" . "hundred")
+ ("dpi" . "dots per inch")) "A 100 dpi."
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{List of special characters}.
+Installed Files:
+@file{ly/text-replacements.ly}.
@node Controlling output
rhythmic-locations to the list.
In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}. The clips are output as EPS files, and are
+@option{-dclip-systems}. The clips are output as EPS files, and are
converted to PDF and PNG if these formats are switched on as well.
-For more information on output formats, see @rprogram{Invoking lilypond}.
+For more information on output formats, see @rprogram{Invoking LilyPond}.
@node Skipping corrected music
@subsection Skipping corrected music
this correction process, it is possible to skip typesetting of all but
the last few measures. This is achieved by putting
-@verbatim
+@example
showLastLength = R1*5
-\score { ... }
-@end verbatim
+\score @{ @dots{} @}
+@end example
@noindent
in your source file. This will render only the last 5 measures
it skips all events, including tempo and instrument changes. You have
been warned.
-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
- c8 d
- \set Score.skipTypesetting = ##t
- e8 e e e e e e e
- \set Score.skipTypesetting = ##f
- c8 d b bes a g c2
-}
+@lilypond[quote,relative=2,ragged-right,verbatim]
+c8 d
+\set Score.skipTypesetting = ##t
+e8 e e e e e e e
+\set Score.skipTypesetting = ##f
+c8 d b bes a g c2
@end lilypond
In polyphonic music, @code{Score.skipTypesetting} will affect all
Document Format (PDF) and PostScript (PS). Scalable Vector
Graphics (SVG), Encapsulated PostScript (EPS) and Portable
Network Graphics (PNG) output formats are also available through
-command line options, see @rprogram{Command line options for
-lilypond}.
+command line options, see
+@rprogram{Basic command line options for LilyPond}.
@node Replacing the notation font
@c NOTE: these images are a bit big, but that's important
@c for the font comparison. -gp
-@sourceimage{Gonville_after,,,}
+@sourceimage{Gonville_after,15cm,,}
Here are a few sample bars of music set in LilyPond's Feta font:
-@sourceimage{Gonville_before,,,}
+@sourceimage{Gonville_before,15cm,,}
@subsubheading Installation Instructions for MacOS
Download and extract the zip file. Copy the @code{lilyfonts}
directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
-information, see @rlearning{Other sources of information}.
-Move the existing @code{fonts} directory to @code{fonts_orig} and
-move the @code{lilyfonts} directory to @code{fonts}. Simply move
-@code{fonts_orig} back to @code{fonts} to revert back to Feta.
+information, see @rlearning{Other sources of information}. Rename the
+existing @code{fonts} directory to @code{fonts_orig} and the
+@code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
+reverse the process.
@seealso
-Learning Manual: @rlearning{Other sources of information}.
+Learning Manual:
+@rlearning{Other sources of information}.
@knownissues
-
-Gonville cannot be used to typeset @q{Ancient Music} notation. Please
-refer to the author's website for more information on this and other
-specifics including licensing of Gonville.
+Gonville cannot be used to typeset @q{Ancient Music} notation and it is
+likely newer glyphs in later releases of LilyPond may not exist in the
+Gonville font family. Please refer to the author's website for more
+information on these and other specifics, including licensing of
+Gonville.
@node MIDI output
@cindex Sound
@cindex MIDI
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and controlling digital instruments. A MIDI file is a
-series of notes in a number of tracks. It is not an actual
-sound file; you need special software to translate between the
-series of notes and actual sounds.
+MIDI (Musical Instrument Digital Interface) is a standard for connecting
+and controlling digital instruments. A MIDI file is a series of notes
+in a number of tracks. It is not an actual sound file; you need special
+software to translate between the series of notes and actual sounds.
Pieces of music can be converted to MIDI files, so you can listen to
what was entered. This is convenient for checking the music; octaves
-that are off or accidentals that were mistyped stand out very much
-when listening to the MIDI output.
+that are off or accidentals that were mistyped stand out very much when
+listening to the MIDI output.
+
+Standard MIDI output is somewhat crude; optionally, an enhanced and
+more realistic MIDI output is available by means of
+@ref{The Articulate script}.
-@c TODO Check this
-The midi output allocates a channel for each staff, and one for global
-settings. Therefore the midi file should not have more than 15 staves
-(or 14 if you do not use drums). Other staves will remain silent.
+The MIDI output allocates a channel for each staff, and reserves channel
+10 for drums. There are only 16 MIDI channels per device, so if the
+score contains more than 15 staves, MIDI channels will be reused.
@menu
* Creating MIDI files::
-* MIDI block::
+* MIDI Instruments::
* What goes into the MIDI output?::
* Repeats in MIDI::
* Controlling MIDI dynamics::
* Percussion in MIDI::
+* The Articulate script::
@end menu
@node Creating MIDI files
@subsection Creating MIDI files
-To create a MIDI output file from a LilyPond input file, add a
-@code{\midi} block to a score, for example,
+@cindex MIDI block
+To create a MIDI output file from a LilyPond file, insert a @code{\midi}
+block inside a @code{\score} block;
@example
\score @{
- @var{...music...}
+ @var{@dots{}music@dots{}}
+ \layout @{ @}
\midi @{ @}
@}
@end example
-If there is a @code{\midi} block in a @code{\score} with no
-@code{\layout} block, only MIDI output will be produced. When
-notation is needed too, a @code{\layout} block must also be
-present.
+If there is @emph{only} a @code{\midi} block in a @code{\score} (i.e.
+without any @code{\layout} block), then @emph{only} MIDI output will be
+produced. No musical notation will be typeset.
@example
\score @{
- @var{...music...}
+ @var{@dots{}music@dots{}}
\midi @{ @}
- \layout @{ @}
@}
@end example
-Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
-and translated correctly to the MIDI output. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels.
-Dynamic marks translate to a fixed fraction of the available MIDI
-volume range. Crescendi and decrescendi make the volume vary
-linearly between their two extremes. The effect of dynamic markings
-on the MIDI output can be removed completely, see @ref{MIDI block}.
-
-The initial tempo and later tempo changes can be specified
-with the @code{\tempo} command within the music notation. These
-are reflected in tempo changes in the MIDI output. This command
-will normally result in the metronome mark being printed, but this
-can be suppressed, see @ref{Metronome marks}. An alternative way
-of specifying the inital or overall MIDI tempo is described below,
-see @ref{MIDI block}.
-
-Due to some limitations on Windows, the default extension for
-MIDI files on Windows is @code{.mid}. Other operating systems still
-use the extension @code{.midi}. If a different extension is preferred,
-insert the following line at the top-level of the input file,
-before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
-
-@example
-#(ly:set-option 'midi-extension "midi")
-@end example
+Dynamics, pitches, rhythms, tempo changes and ties are all interpreted
+and translated correctly. Dynamic @q{marks} translate into volume
+levels with a @q{fixed fraction} of the available MIDI volume range;
+crescendi and decrescendi make the volume vary linearly between their
+two extremes.
-The line above will set the default extension for MIDI files to
-@code{.midi}.
+All @code{\tempo} indications, including all subsequent tempo changes,
+specified within the music notation will be reflected in the MIDI
+output.
-Alternatively, this option can also be supplied on the command line:
+Usually it is enough to leave the @code{\midi} block empty, but it can
+contain context rearrangements, new context definitions or code to set
+the values of properties. Here the tempo is set to 72 quarter-note
+beats per minute, but @emph{only} for the MIDI's audio playback.
@example
-lilypond … -dmidi-extension=midi lilyFile.ly
+\score @{
+ @var{@dots{}music@dots{}}
+ \midi @{
+ \tempo 4 = 72
+ @}
+@}
@end example
+Note that @code{\tempo} is actually a command for setting properties
+during the interpretation of the music and in the context of output
+definitions, like a @code{\midi} block, is reinterpreted as if it were a
+context modification.
-@unnumberedsubsubsec Instrument names
-
-@cindex instrument names
-@funindex Staff.midiInstrument
+@cindex MIDI context definitions
-The MIDI instrument to be used is specified by setting the
-@code{Staff.midiInstrument} property to the instrument name.
-The name should be chosen from the list in @ref{MIDI instruments}.
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{...notes...}
+\score @{
+ @var{@dots{}music@dots{}}
+ \midi @{
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+ @}
@}
@end example
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{...notes...}
-@}
-@end example
+removes the effect of dynamics from the MIDI output. Translation
+modules for sound are called @q{performers}.
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-@snippets
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+Installed Files:
+@file{ly/performer-init.ly}.
-@knownissues
+Snippets:
+@rlsr{MIDI}.
-@c In 2.11 the following no longer seems to be a problem -td
-@ignore
-Unterminated (de)crescendos will not render properly in the midi file,
-resulting in silent passages of music. The workaround is to explicitly
-terminate the (de)crescendo. For example,
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+@knownissues
+Some operating systems require a @emph{specific} file extension for MIDI
+files. If a different extension is preferred insert the following line
+at the top-level of the input file, before the start of any
+@code{\book}, @code{\bookpart} or @code{\score} blocks;
@example
-@{ a4\< b c d\f @}
+#(ly:set-option 'midi-extension "mid")
@end example
-@noindent
-will not work properly but
+This will set the default extension for MIDI files to @code{.mid}.
+
+Alternatively, an option can be supplied on the command line:
@example
-@{ a4\< b c d\!\f @}
+lilypond -dmidi-extension=mid MyFile.ly
@end example
-@noindent
-will.
-@end ignore
-
Changes in the MIDI volume take place only on starting a note, so
-crescendi and decrescendi cannot affect the volume of a
-single note.
-
-Not all midi players correctly handle tempo changes in the midi
-output. Players that are known to work include MS Windows Media
-Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+crescendi and decrescendi cannot affect the volume of a single note.
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
-
-A @code{\midi} block must appear within a score block if MIDI output
-is required. It is analogous to the layout block, but somewhat
-simpler. Often, the @code{\midi} block is left empty, but it
-can contain context rearrangements, new context definitions or code
-to set the values of properties. For example, the following will
-set the initial tempo exported to a MIDI file without causing a tempo
-indication to be printed:
+Some MIDI players may not always correctly handle tempo changes in the
+midi output.
-@example
-\score @{
- @var{...music...}
- \midi @{
- \context @{
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 4)
- @}
- @}
-@}
-@end example
+Changes to @code{midiInstrument} (and other MIDI options) at the
+beginning of a staff may appear twice in the MIDI output.
-In this example the tempo is set to 72 quarter note
-beats per minute. This kind of tempo specification cannot take
-a dotted note length as an argument. If one is required, break
-the dotted note into smaller units. For example, a tempo of 90
-dotted quarter notes per minute can be specified as 270 eighth
-notes per minute:
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
+@node MIDI Instruments
+@subsection MIDI Instruments
-@cindex MIDI context definitions
+@cindex instrument names
+@cindex MIDI, instruments
+@funindex Staff.midiInstrument
-Context definitions follow precisely the same syntax as those
-within a @code{\layout} block. Translation modules for sound are
-called performers. The contexts for MIDI output are defined in
-@file{../@/ly/@/performer@/-init@/.ly},
-see @rlearning{Other sources of information}.
-For example, to remove the effect of dynamics
-from the MIDI output, insert the following lines in the
-@code{\midi@{ @}} block.
+The MIDI instrument to be used is specified by setting the
+@code{Staff.midiInstrument} property to the instrument name. The name
+should be chosen from the list in @ref{MIDI instruments}.
@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
+\new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{@dots{}notes@dots{}}
@}
@end example
-MIDI output is created only when a @code{\midi} block is included
-within a score block defined with a @code{\score} command. If it
-is placed within an explicitly instantiated score context (i.e.
-within a @code{\new Score} block) the file will fail. To solve
-this, enclose the @code{\new Score} and the @code{\midi} commands
-in a @code{\score} block.
-
@example
-\score @{
- \new Score @{ @dots{}notes@dots{} @}
- \midi @{ @}
+\new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{@dots{}notes@dots{}}
@}
@end example
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
+@seealso
+Notation Reference:
+@ref{MIDI instruments}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
@node What goes into the MIDI output?
@subsection What goes into the MIDI output?
@c TODO Check grace notes - timing is suspect?
+@menu
+* Supported in MIDI::
+* Unsupported in MIDI::
+@end menu
+
+@node Supported in MIDI
@unnumberedsubsubsec Supported in MIDI
@cindex Pitches in MIDI
@cindex MIDI, chord names
@cindex Rhythms in MIDI
@cindex MIDI, Rhythms
+@cindex Articlulate scripts
+@cindex MIDI, articulations
+@cindex articulations in MIDI
+@cindex trills in MIDI
+@cindex turns in MIDI
+@cindex rallentando in MIDI
+@cindex accelerando in MIDI
@c TODO etc
The following items of notation are reflected in the MIDI output:
@itemize
@item Pitches
-@item Microtones (See @ref{Accidentals}. Rendering needs a
+@item Microtones (See @ref{Accidentals}. Rendering needs a
player that supports pitch bend.)
@item Chords entered as chord names
@item Rhythms entered as note durations, including tuplets
@item Crescendi, decrescendi over multiple notes
@item Tempo changes entered with a tempo marking
@item Lyrics
+@item Simple articulations: staccato, staccatissimo, accent, marcato, portato
+@item @ref{Breath marks}
+@end itemize
+
+There is a script that adds the following items; see
+@ref{The Articulate script}:
+
+@itemize
+@item Slurs and phrasing slurs
+@item Ornaments (mordents, trills, turns, etc.)
+@item Rallentando, accelerando, ritard, and a tempo
@end itemize
+@seealso
+Notation Reference:
+@ref{Accidentals},
+@ref{Breath marks},
+@ref{Expressive marks}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
+
+@node Unsupported in MIDI
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output, even
+if you use @ref{The Articulate script}:
@itemize
@item Rhythms entered as annotations, e.g. swing
@item Tempo changes entered as annotations with no tempo marking
-@item Staccato and other articulations and ornamentations
-@item Slurs and Phrasing slurs
+@item Fermatas
+@item Other articulations
@item Crescendi, decrescendi over a single note
@item Tremolos entered with @q{@code{:}[@var{number}]}
@item Figured bass
@item Microtonal chords
+@item Glissandi, falls and doits
@end itemize
+@seealso
+Installed Files:
+@file{ly/articulate.ly}.
+
@node Repeats in MIDI
@subsection Repeats in MIDI
@cindex repeats in MIDI
@funindex \unfoldRepeats
-With a few minor additions, all types of repeats can be represented
-in the MIDI output. This is achieved by applying the
-@code{\unfoldRepeats} music function. This function changes all
-repeats to unfold repeats.
+With a few minor additions, all types of repeats can be represented in
+the MIDI output. This is achieved by applying the @code{\unfoldRepeats}
+music function. This function changes all repeats to unfold repeats.
@lilypond[quote,verbatim]
\unfoldRepeats {
\bar "|."
@end lilypond
-When creating a score file using @code{\unfoldRepeats} for MIDI,
-it is necessary to make two @code{\score} blocks: one for MIDI
-(with unfolded repeats) and one for notation (with volta, tremolo,
-and percent repeats). For example,
+In scores containing multiple voices, unfolding of repeats in MIDI
+output will only occur correctly if @emph{each} voice contains fully
+notated repeat indications.
+
+When creating a score file using @code{\unfoldRepeats} for MIDI, it is
+necessary to make two @code{\score} blocks: one for MIDI (with unfolded
+repeats) and one for notation (with volta, tremolo, and percent
+repeats):
@example
\score @{
- @var{..music..}
- \layout @{ .. @}
+ @var{@dots{}music@dots{}}
+ \layout @{ @dots{} @}
@}
\score @{
- \unfoldRepeats @var{..music..}
- \midi @{ .. @}
+ \unfoldRepeats @var{@dots{}music@dots{}}
+ \midi @{ @dots{} @}
@}
@end example
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
+
@node Controlling MIDI dynamics
@subsection Controlling MIDI dynamics
-MIDI dynamics are implemented by the Dynamic_performer which lives
-by default in the Voice context. It is possible to control the
-overall MIDI volume, the relative volume of dynamic markings and
-the relative volume of different instruments.
+MIDI dynamics are implemented by the Dynamic_performer which lives by
+default in the Voice context. It is possible to control the overall
+MIDI volume, the relative volume of dynamic markings and the relative
+volume of different instruments.
+
+@menu
+* Dynamic marks::
+* Overall MIDI volume::
+* Equalizing different instruments (i)::
+* Equalizing different instruments (ii)::
+@end menu
+@node Dynamic marks
@unnumberedsubsubsec Dynamic marks
-Dynamic marks are translated to a fixed fraction of the available
-MIDI volume range. The default fractions range from 0.25 for
+Dynamic marks are translated to a fixed fraction of the available MIDI
+volume range. The default fractions range from 0.25 for
@notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
marks and the associated fractions can be seen in
-@file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
+@file{../scm/midi.scm}, see @rlearning{Other sources of information}.
This set of fractions may be changed or extended by providing a
function which takes a dynamic mark as its argument and returns the
required fraction, and setting
@code{Score.dynamicAbsoluteVolumeFunction} to this function.
-For example, if a @notation{rinforzando} dynamic marking,
-@code{\rfz}, is required, this will not by default
-have any effect on the MIDI volume, as this dynamic marking is not
-included in the default set. Similarly, if a new dynamic marking
-has been defined with @code{make-dynamic-script} that too will not
-be included in the default set. The following example shows how the
-MIDI volume for such dynamic markings might be added. The Scheme
-function sets the fraction to 0.9 if a dynamic mark of rfz is
-found, or calls the default function otherwise.
+For example, if a @notation{rinforzando} dynamic marking, @code{\rfz},
+is required, this will not by default have any effect on the MIDI
+volume, as this dynamic marking is not included in the default set.
+Similarly, if a new dynamic marking has been defined with
+@code{make-dynamic-script} that too will not be included in the default
+set. The following example shows how the MIDI volume for such dynamic
+markings might be added. The Scheme function sets the fraction to 0.9
+if a dynamic mark of @code{rfz} is found, or calls the default function
+otherwise.
@lilypond[verbatim,quote]
#(define (myDynamics dynamic)
}
@end lilypond
-Alternatively, if the whole table of fractions needs to be
-redefined, it would be better to use the
-@notation{default-dynamic-absolute-volume} procedure in
-@file{../@/scm/@/midi.scm} and the associated table as a model.
+Alternatively, if the whole table of fractions needs to be redefined, it
+would be better to use the @notation{default-dynamic-absolute-volume}
+procedure in @file{../scm/midi.scm} and the associated table as a model.
The final example in this section shows how this might be done.
+@seealso
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
+
+Installed Files:
+@file{scm/midi.scm}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
+
+@node Overall MIDI volume
@unnumberedsubsubsec Overall MIDI volume
The minimum and maximum overall volume of MIDI dynamic markings is
controlled by setting the properties @code{midiMinimumVolume} and
-@code{midiMaximumVolume} at the @code{Score} level. These
-properties have an effect only on dynamic marks, so if they
-are to apply from the start of the score a dynamic mark must be
-placed there. The fraction corresponding to each dynamic mark is
-modified with this formula
+@code{midiMaximumVolume} at the @code{Score} level. These properties
+have an effect only at the start of a voice and on dynamic marks. The
+fraction corresponding to each dynamic mark is modified with this
+formula
@example
midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
\set Staff.midiInstrument = #"flute"
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
>>
\layout {}
\midi {
+ \tempo 2 = 72
\context {
\Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
midiMinimumVolume = #0.2
midiMaximumVolume = #0.5
}
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
+
+@node Equalizing different instruments (i)
@unnumberedsubsubsec Equalizing different instruments (i)
-If the minimum and maximum MIDI volume properties are set in
-the @code{Staff} context the relative volumes of the MIDI
-instruments can be controlled. This gives a basic instrument
-equalizer, which can enhance the quality of the MIDI output
-remarkably.
+If the minimum and maximum MIDI volume properties are set in the
+@code{Staff} context the relative volumes of the MIDI instruments can be
+controlled. This gives a basic instrument equalizer, which can enhance
+the quality of the MIDI output remarkably.
-In this example the volume of the clarinet is reduced relative
-to the volume of the flute. There must be a dynamic
-mark on the first note of each instrument for this to work
-correctly.
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
@lilypond[verbatim,quote]
\score {
\set Staff.midiMaximumVolume = #0.9
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
>>
\layout {}
\midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
+ \tempo 2 = 72
}
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+
+@node Equalizing different instruments (ii)
@unnumberedsubsubsec Equalizing different instruments (ii)
-If the MIDI minimum and maximum volume properties are not set
-LilyPond will, by default, apply a small degree of equalization
-to a few instruments. The instruments and the equalization
-applied are shown in the table @notation{instrument-equalizer-alist}
-in @file{../@/scm/@/midi.scm}.
+If the MIDI minimum and maximum volume properties are not set LilyPond
+will, by default, apply a small degree of equalization to a few
+instruments. The instruments and the equalization applied are shown in
+the table @notation{instrument-equalizer-alist} in
+@file{../scm/midi.scm}.
This basic default equalizer can be replaced by setting
-@code{instrumentEqualizer} in the @code{Score} context to a new
-Scheme procedure which accepts a MIDI instrument name as its only
-argument and returns a pair of fractions giving the minimum and
-maximum volumes to be applied to that instrument. This replacement
-is done in the same way as shown for resetting the
-@code{dynamicAbsoluteVolumeFunction} at the start of this section.
-The default equalizer, @notation{default-instrument-equalizer}, in
-@file{../@/scm/@/midi.scm} shows how such a procedure might be written.
-
-The following example sets the relative flute and clarinet volumes
-to the same values as the previous example.
+@code{instrumentEqualizer} in the @code{Score} context to a new Scheme
+procedure which accepts a MIDI instrument name as its only argument and
+returns a pair of fractions giving the minimum and maximum volumes to be
+applied to that instrument. This replacement is done in the same way as
+shown for resetting the @code{dynamicAbsoluteVolumeFunction} at the
+start of this section. The default equalizer,
+@notation{default-instrument-equalizer}, in @file{../scm/midi.scm} shows
+how such a procedure might be written.
+
+The following example sets the relative flute and clarinet volumes to
+the same values as the previous example.
@lilypond[verbatim,quote]
#(define my-instrument-equalizer-alist '())
\set Staff.midiInstrument = #"flute"
\new Voice \relative c''' {
r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
+ 4 g8 fis e2~
+ 4 d8 cis d2
}
}
\new Staff {
>>
\layout { }
\midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
+ \tempo 2 = 72
}
}
@end lilypond
+@seealso
+Installed Files:
+@file{scm/midi.scm}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
@ignore
@c Delete when satisfied this is adequately covered elsewhere -td
@subsection Percussion in MIDI
Percussion instruments are generally notated in a @code{DrumStaff}
-context and when notated in this way they are outputted correctly
-to MIDI channel@tie{}10, but some pitched percussion instruments,
-like the xylophone, marimba, vibraphone, timpani, etc., are
-treated like @qq{normal} instruments and music for these instruments
-should be entered in a normal @code{Staff} context, not a
-@code{DrumStaff} context, to obtain the correct MIDI output.
+context and when notated in this way they are outputted correctly to
+MIDI channel@tie{}10, but some pitched percussion instruments, like the
+xylophone, marimba, vibraphone, timpani, etc., are treated like
+@qq{normal} instruments and music for these instruments should be
+entered in a normal @code{Staff} context, not a @code{DrumStaff}
+context, to obtain the correct MIDI output.
Some non-pitched percussion sounds included in the general MIDI
-standard, like melodic tom, taiko drum, synth drum, etc., cannot
-be reached via MIDI channel@tie{}10, so the notation for such
-instruments should also be entered in a normal @code{Staff}
-context, using suitable normal pitches.
+standard, like melodic tom, taiko drum, synth drum, etc., cannot be
+reached via MIDI channel@tie{}10, so the notation for such instruments
+should also be entered in a normal @code{Staff} context, using suitable
+normal pitches.
Many percussion instruments are not included in the general MIDI
-standard, e.g. castanets. The easiest, although unsatisfactory,
-method of producing some MIDI output when writing for such
-instruments is to substitute the nearest sound from the standard
-set.
+standard, e.g. castanets. The easiest, although unsatisfactory, method
+of producing some MIDI output when writing for such instruments is to
+substitute the nearest sound from the standard set.
@c TODO Expand with examples, and any other issues
-@knownissues
+@seealso
+Notation Reference:
+@ref{Percussion},
+@ref{Score layout}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+@knownissues
Because the general MIDI standard does not contain rim shots, the
sidestick is used for this purpose instead.
+
+@node The Articulate script
+@subsection The Articulate script
+
+A more realistic MIDI output is possible when using the Articulate
+script. It tries to take articulations (slurs, staccato, etc) into
+account, by replacing notes with sequential music of suitably
+time-scaled note plus skip. It also tries to unfold trills turns etc.,
+and take rallentando and accelerando into account.
+
+To use the Articulate script, you have to include it at the top of your
+input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+ all the rest of the score@dots{}
+>>
+@end example
+
+After altering your input file this way, the visual output is heavily
+altered, but the standard @code{\midi} block will produce a better
+MIDI file.
+
+Although not essential for the Articulate script to work, you may want
+to insert the @code{\unfoldRepeats} command as it appears in the
+example shown above as it enables performing abbreviatures such as
+@notation{trills}.
+
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
+Internals Reference:
+@rinternals{UnfoldedRepeatedMusic}.
+
+@knownissues
+Articulate shortens chords and some music (esp. organ music) could
+sound worse.
+
+
+@node Extracting musical information
+@section Extracting musical information
+
+In addition to creating graphical output and MIDI, LilyPond can
+display musical information as text.
+
+@menu
+* Displaying LilyPond notation::
+* Displaying scheme music expressions::
+* Saving music events to a file::
+@end menu
+
+@node Displaying LilyPond notation
+@subsection Displaying LilyPond notation
+
+@funindex \displayLilyMusic
+Displaying a music expression in LilyPond notation can be
+done with the music function @code{\displayLilyMusic}. To see the
+output, you will typically want to call LilyPond using the command
+line. For example,
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a,4 cis e fis g @}
+@end example
+
+By default, LilyPond will print these messages to the console
+along with all the other LilyPond compilation messages. To split
+up these messages and save the results of @code{\displayLilyMusic},
+redirect the output to a file.
+
+@example
+lilypond file.ly >display.txt
+@end example
+
+@funindex \void
+Note that Lilypond does not just display the music expression, but
+also interprets it (since @code{\displayLilyMusic} returns it in
+addition to displaying it). This is convenient since you can just
+insert @code{\displayLilyMusic} into existing music in order to get
+information about it. If you don't actually want Lilypond to
+interpret the displayed music as well as display it, use @code{\void}
+in order to have it ignored:
+
+@example
+@{
+ \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+
+@node Displaying scheme music expressions
+@subsection Displaying scheme music expressions
+
+See @rextend{Displaying music expressions}.
+
+
+@node Saving music events to a file
+@subsection Saving music events to a file
+
+Music events can be saved to a file on a per-staff basis by
+including a file in your main score.
+
+@example
+\include "event-listener.ly"
+@end example
+
+This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
+@file{FILENAME-unnamed-staff.notes} for each staff. Note that if
+you have multiple unnamed staves, the events for all staves will
+be mixed together in the same file. The output looks like this:
+
+@example
+0.000 note 57 4 p-c 2 12
+0.000 dynamic f
+0.250 note 62 4 p-c 7 12
+0.500 note 66 8 p-c 9 12
+0.625 note 69 8 p-c 14 12
+0.750 rest 4
+0.750 breathe
+@end example
+
+The syntax is a tab-delimited line, with two fixed fields on each
+line followed by optional parameters.
+
+@example
+@var{time} @var{type} @var{@dots{}params@dots{}}
+@end example
+
+This information can easily be read into other programs such as
+python scripts, and can be very useful for researchers wishing to
+perform musical analysis or playback experiments with LilyPond.
+
+
+@knownissues
+
+Not all lilypond music events are supported by
+@file{event-listener.ly}. It is intended to be a well-crafted
+@qq{proof of concept}. If some events that you want to see are
+not included, copy @file{event-listener.ly} into your lilypond
+directory and modify the file so that it outputs the information
+you want.
projects / lilypond.git / blobdiff