Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.19.22"
@node General input and output
@chapter General input and output
* Titles and headers::
* Working with input files::
* Controlling output::
-* MIDI output::
+* Creating MIDI output::
+* Extracting musical information::
@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.
@example
\score @{
- @var{..music..}
+ @var{@dots{}music@dots{}}
@}
@end example
@example
\markup @{
- @var{..text..}
+ @var{@dots{}text@dots{}}
@}
@end example
@example
\score @{
- @var{..}
+ @var{@dots{}}
@}
\markup @{
- @var{..}
+ @var{@dots{}}
@}
\score @{
- @var{..}
+ @var{@dots{}}
@}
@end example
\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{}
@example
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
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
+producing several outputs 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}
\book @{
\bookOutputSuffix "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
\book @{
\bookOutputName "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
@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
@{ c'4 d' e'2 @}
@}
@}
+ \layout @{ @}
@}
- \layout @{ @}
- \header @{ @}
+ \paper @{ @}
+ \header @{ @}
@}
@end example
A single-line comment, introduced by a leading @code{%} sign.
@item
-A multi-line comment delimited by @code{%@{ .. %@}}.
+A multi-line comment delimited by @code{%@{ @dots{} %@}}.
@end itemize
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{#} sign.
+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} 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.
-@end itemize
+@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
+@cindex titles
+@cindex headers
+@cindex footers
+
Almost all printed music includes a title and the composer's name;
some pieces include a lot more information.
@menu
-* Creating titles::
-* Custom headers footers and titles::
+* Creating titles headers and footers::
+* Custom titles headers and footers::
+* Creating PDF metadata::
+* Creating footnotes::
* Reference to page numbers::
* Table of contents::
@end menu
-@node Creating titles
-@subsection Creating titles
+@node Creating titles headers and footers
+@subsection Creating titles headers and footers
-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).
+@menu
+* Titles explained::
+* Default layout of bookpart and score titles::
+* Default layout of headers and footers::
+@end menu
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
+@node Titles explained
+@unnumberedsubsubsec Titles explained
-@table @code
-@funindex dedication
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
+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.
-@funindex title
-@item title
-The title of the music, centered just below the dedication.
+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}.
-@funindex subtitle
-@item subtitle
-Subtitle, centered below the title.
+@code{\header} blocks may be placed in four different places to form
+a descending hierarchy of @code{\header} blocks:
-@funindex subsubtitle
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
+@itemize
-@funindex poet
-@item poet
-Name of the poet, flush-left below the subsubtitle.
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the subsubtitle. Also
-centered at the top of pages (other than the first page).
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
-@funindex composer
-@item composer
-Name of the composer, flush-right below the subsubtitle.
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
-@funindex meter
-@item meter
-Meter string, flush-left below the poet.
+@item
+After the music expression in a @code{\score} block.
-@funindex arranger
-@item arranger
-Name of the arranger, flush-right below the composer.
+@end itemize
-@funindex piece
-@item piece
-Name of the piece, flush-left below the meter.
+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:
-@funindex opus
-@item opus
-Name of the opus, flush-right below the arranger.
+@itemize
-@cindex page breaks, forcing
-@funindex breakbefore
-@item breakbefore
-This forces the title to start on a new page (set to ##t or ##f).
+@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.
-@funindex copyright
-@item copyright
-Copyright notice, centered at the bottom of the first page. To
-insert the copyright symbol, see @ref{Text encoding}.
+@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.
-@funindex tagline
-@item tagline
-Centered at the bottom of the last page.
+@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 table
+@end itemize
-Here is a demonstration of the fields available. Note that you
-may use any @ref{Formatting text}, commands in the header.
+@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."
+}
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\paper {
- line-width = 9.0\cm
- paper-height = 10.0\cm
+\score {
+ \new Staff \relative {
+ \clef bass
+ \key g \major
+ \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
+ \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
+ }
+ \header {
+ piece = "Prélude."
+ }
}
-\book {
+\score {
+ \new Staff \relative {
+ \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 {
- 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"
+ 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 default LilyPond footer for this book
+ tagline = ##f
+ }
+ \markup { \vspace #1 }
\score {
- { c'1 }
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
\header {
- piece = "piece1"
- opus = "opus1"
+ title = "PRAELUDIUM I"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
}
}
- \markup {
- and now...
- }
\score {
- { c'1 }
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
\header {
- piece = "piece2"
- opus = "opus2"
+ title = "FUGA I"
+ subsubtitle = "A 4 VOCI"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
}
}
}
@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.
+@seealso
+Notation Reference:
+@ref{File structure},
+@ref{Default layout of bookpart and score titles},
+@ref{Custom layout for titles}.
+
-@example
-\header @{
- composer = "Composer"
-@}
-\header @{
- piece = "Piece"
-@}
-\score @{
- \new Staff @{ c'4 @}
- \header @{
- piece = "New piece" % overwrite previous one
- @}
-@}
-@end example
+@node Default layout of bookpart and score titles
+@unnumberedsubsubsec Default layout of bookpart and score titles
-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}.
+This example demonstrates all printed @code{\header} variables:
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\score {
- { c'4 }
+@lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
+\book {
\header {
- title = "title" % not printed
- piece = "piece"
- opus = "opus"
+ % 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 = "The tagline goes at the bottom of the last page"
+ copyright = "The 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
-@funindex print-all-headers
-@noindent
-You may change this behavior (and print all the headers when defining
-@code{\header} inside @code{\score}) by using
-
-@example
-\paper@{
- print-all-headers = ##t
-@}
-@end example
+Note that
-@cindex copyright
-@cindex tagline
+@itemize
+@item
+The instrument name will be repeated on every page.
-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.}
+@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).
-Headers may be completely removed by setting them to false.
+@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.
-@example
-\header @{
- tagline = ##f
- composer = ##f
-@}
-@end example
+@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
-@node Custom headers footers and titles
-@subsection Custom headers, footers, and titles
+To change the default layout see @ref{Custom layout for titles}.
-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.
+@cindex breakbefore
-@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
+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.
-@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).
+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.
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+@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
-@funindex evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work},
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+Notation Reference:
+@ref{Custom layout for titles},
+@ref{File structure}.
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+Installed Files:
+@file{ly/titling-init.ly}.
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@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:
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+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:
-@example
-\paper @{
- bookTitleMarkup = \markup @{
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- @}
-@}
-@end example
+@itemize
-The header and footer are created by the functions
-@code{make-header} and @code{make-footer}, defined in
-@code{\paper}. The default implementations are in
-@file{ly/paper-defaults-init.ly} and
-@file{ly/titling-init.ly}.
+@item
+page numbers are automatically placed on the top far left (if even) or
+top far right (if odd), starting from the second page.
-This example centers page numbers at the bottom of every page.
+@item
+the @code{instrument} text field is placed in the center of every
+page, starting from the second page.
-@example
-\paper @{
- print-page-number = ##t
- print-first-page-number = ##t
- oddHeaderMarkup = \markup \fill-line @{ " " @}
- evenHeaderMarkup = \markup \fill-line @{ " " @}
- oddFooterMarkup = \markup @{
- \fill-line @{
- \bold \fontsize #3
- \on-the-fly #print-page-number-check-first
- \fromproperty #'page:page-number-string
- @}
- @}
- evenFooterMarkup = \markup @{
- \fill-line @{
- \bold \fontsize #3
- \on-the-fly #print-page-number-check-first
- \fromproperty #'page:page-number-string
- @}
- @}
-@}
-@end example
+@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.
-@node Reference to page numbers
-@subsection Reference to page numbers
+@end itemize
-A particular place of a score can be marked using the @code{\label}
-command, either at top-level or inside music. This label can then be
-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.
+The default LilyPond footer text can be changed by adding a
+@code{tagline} in the top-level @code{\header} block.
-@lilypond[verbatim,line-width=11.0\cm]
-\header { tagline = ##f }
+@lilypond[papersize=a8landscape,verbatim]
\book {
- \label #'firstScore
+ \header {
+ tagline = "... music notation for Everyone"
+ }
\score {
- {
- c'1
- \pageBreak \mark A \label #'markA
- c'1
+ \relative {
+ c'4 d e f
}
}
-
- \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
- \markup { Mark A is on page \page-ref #'markA "0" "?" }
}
@end lilypond
-The @code{\page-ref} markup command takes three arguments:
-@enumerate
-@item the label, a scheme symbol, eg. @code{#'firstScore};
-@item a markup that will be used as a gauge to estimate the dimensions
-of the markup;
-@item a markup that will be used in place of the page number if the label
-is not known;
-@end enumerate
+To remove the default LilyPond footer text, the @code{tagline} can be
+set to @code{##f}.
-The reason why a gauge is needed is that, at the time markups are
-interpreted, the page breaking has not yet occurred, so the page numbers
-are not yet known. To work around this issue, the actual markup
-interpretation is delayed to a later time; however, the dimensions of
-the markup have to be known before, so a gauge is used to decide these
-dimensions. If the book has between 10 and 99 pages, it may be "00",
-ie. a two digit number.
+@node Custom titles headers and footers
+@subsection Custom titles headers and footers
-@predefined
-@funindex \label
-@code{\label},
-@funindex \page-ref
-@code{\page-ref}.
-@endpredefined
+@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 Table of contents
-@subsection Table of contents
-A table of contents is included using the @code{\markuplines \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
-\pageBreak
+@node Custom text formatting for titles
+@unnumberedsubsubsec Custom text formatting for titles
-\tocItem \markup "First score"
-\score {
- {
- c'4 % ...
- \tocItem \markup "Some particular point in the first score"
- d'4 % ...
- }
-}
+Standard @code{\markup} commands can be used to customize any header,
+footer and title text within the @code{\header} block.
-\tocItem \markup "Second score"
+@lilypond[quote,verbatim,noragged-right]
\score {
- {
- e'4 % ...
+ { s1 }
+ \header {
+ piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
+ opus = \markup { \italic "BWV 846" }
}
}
-@end verbatim
+@end lilypond
-The markups which are used to format the table of contents are defined
-in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
-for formatting the title of the table, and @code{tocItemMarkup}, for
-formatting the toc elements, composed of the element title and page
-number. These variables may be changed by the user:
+@seealso
+Notation Reference:
+@ref{Formatting text}.
-@verbatim
-\paper {
- %% Translate the toc title into French:
- tocTitleMarkup = \markup \huge \column {
- \fill-line { \null "Table des matières" \null }
- \hspace #1
- }
- %% use larger font size
- tocItemMarkup = \markup \large \fill-line {
- \fromproperty #'toc:text \fromproperty #'toc:page
- }
-}
-@end verbatim
-Note how the toc element text and page number are referred to in
-the @code{tocItemMarkup} definition.
+@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:
-New commands and markups may also be defined to build more elaborated
-table of contents:
@itemize
-@item first, define a new markup variable in the @code{\paper} block
-@item then, define a music function which aims at adding a toc element
-using this markup paper variable.
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
@end itemize
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
-
-@verbatim
-\paper {
- tocActMarkup = \markup \large \column {
- \hspace #1
- \fill-line { \null \italic \fromproperty #'toc:text \null }
- \hspace #1
- }
-}
+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}.
-tocAct =
-#(define-music-function (parser location text) (markup?)
- (add-toc-item! 'tocActMarkup text))
-@end verbatim
+The default settings for @code{scoreTitleMarkup} as defined in
+@file{ly/titling-init.ly} are:
-@lilypond[line-width=11.0\cm]
-\header { tagline = ##f }
-\paper {
- tocActMarkup = \markup \large \column {
- \hspace #1
- \fill-line { \null \italic \fromproperty #'toc:text \null }
- \hspace #1
- }
-}
+@example
+scoreTitleMarkup = \markup @{ \column @{
+ \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \fill-line @{
+ \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ @}
+@}
+@}
+@end example
-tocAct =
-#(define-music-function (parser location text) (markup?)
- (add-toc-item! 'tocActMarkup text))
+This places the @code{piece} and @code{opus} text fields at opposite
+ends of the same line:
-\book {
- \markuplines \table-of-contents
- \tocAct \markup { Atto Primo }
- \tocItem \markup { Coro. Viva il nostro Alcide }
- \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
- \tocAct \markup { Atto Secondo }
- \tocItem \markup { Sinfonia }
- \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
- \markup \null
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
}
@end lilypond
-Dots can be added to fill the line between an item and its page number:
-
-@lilypond[verbatim,quote]
-\header { tagline = ##f }
-\paper {
- tocItemMarkup = \tocItemWithDotsMarkup
-}
+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 {
- \markuplines \table-of-contents
- \tocItem \markup { Allegro }
- \tocItem \markup { Largo }
- \markup \null
+ \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 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 multitable
+@end quotation
+
+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}:
+
+@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
+
+Several @code{\on-the-fly} conditions can be combined with an
+@q{and} operation, for example,
+
+@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
+Notation Reference:
+@ref{Titles explained},
+@ref{Default layout of bookpart and score titles}.
+
+Installed Files:
+@file{../ly/titling-init.ly}.
+
+@node Creating PDF metadata
+@subsection Creating PDF metadata
+
+@cindex PDF metadata
+
+In addition to being shown in the printed output, @code{\header} variables
+are also used to set PDF metadata (the information displayed by PDF readers
+as the @code{properties} of the PDF file). For example, setting the
+@code{title} property of the @code{header} block @q{Symphony I} will also give
+this title to the PDF document.
+
+@example
+ @code{\header@{}
+ @code{title = "Symphony I"}
+ @code{@}}
+@end example
+
+If you want to set the title of the printed output to one value, but have the
+title property of the PDF to have a different value, you can use
+@code{pdftitle}, as below.
+
+@example
+ @code{\header@{}
+ @code{title = "Symphony I"}
+ @code{pdftitle = "Symphony I by Beethoven"}
+ @code{@}}
+@end example
+
+The variables @code{title}, @code{subject}, @code{keywords},
+@code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
+and @code{copyright} all set PDF properties and can all be prefixed with
+@q{pdf} to set a PDF property to a value different from the printed output.
+
+The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
+the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
+both set to the current date and time. @code{ModDate} can be overridden by
+setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
+valid PDF date string.
+
+@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
+* Footnotes in music expressions::
+* Footnotes in stand-alone text::
+@end menu
+
+@node Footnotes in music expressions
+@unnumberedsubsubsec Footnotes in music expressions
+
+@cindex footnotes in music expressions
+@funindex \footnote
+
+@subsubsubheading Music footnotes overview
+
+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:
+
+@example
+[@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@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.
+
+A time-based footnote allows such layout objects to be annotated
+without referring to an event. The general form for Time-based
+footnotes is:
+
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
+@end example
+
+@end table
+
+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.
+
+@end table
+
+@subsubsubheading Event-based footnotes
+
+@cindex footnotes, event-based
+
+A footnote may be attached to a layout object directly caused
+by the event corresponding to @var{music} with the syntax:
+
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@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
+
+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:
+
+@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
+
+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:
+
+@example
+@var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative {
+ a'4_\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 { 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
+
+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
+
+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
+
+@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
+
+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,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
+
+More examples of custom marks are shown in
+@ref{Footnotes in stand-alone text}.
+
+
+@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.
+
+Footnotes to stand-alone text with automatic and custom marks are
+created in different ways.
+
+@subsubsubheading Footnotes in stand-alone text with automatic marks
+
+The syntax of a footnote in stand-alone text with automatic marks is
+
+@example
+\markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
+@end example
+
+The elements are:
+
+@table @var
+
+@item text
+is the markup or string to be marked.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the bottom
+of the page.
+
+@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 {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
+
+@subsubsubheading Footnotes in stand-alone text with custom marks
+
+The syntax of a footnote in stand-alone text with custom marks is
+
+@example
+\markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
+@end example
+
+The elements are:
+
+@table @var
+
+@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}.
+
+@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}):
+
+@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 {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
+
+Unicode character codes may also be used to specify marks
+(see @ref{Unicode}):
+
+@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 {
+ a'4 b8 e c4 d
+ }
+}
+@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
+
+A particular place of a score can be marked using the @code{\label}
+command, either at top-level or inside music. This label can then be
+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,papersize=a8landscape]
+\header { tagline = ##f }
+\book {
+ \label #'firstScore
+ \score {
+ {
+ c'1
+ \pageBreak \mark A \label #'markA
+ c'1
+ }
+ }
+ \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
+ \markup { Mark A is on page \page-ref #'markA "0" "?" }
+}
+@end lilypond
+
+The @code{\page-ref} markup command takes three arguments:
+@enumerate
+@item the label, a scheme symbol, eg. @code{#'firstScore};
+@item a markup that will be used as a gauge to estimate the dimensions
+of the markup;
+@item a markup that will be used in place of the page number if the label
+is not known;
+@end enumerate
+
+The reason why a gauge is needed is that, at the time markups are
+interpreted, the page breaking has not yet occurred, so the page numbers
+are not yet known. To work around this issue, the actual markup
+interpretation is delayed to a later time; however, the dimensions of
+the markup have to be known before, so a gauge is used to decide these
+dimensions. If the book has between 10 and 99 pages, it may be "00",
+ie. a two digit number.
-@seealso
-Init files: @file{../ly/toc-init.ly}.
-
+
+@predefined
+@funindex \label
+@code{\label},
+@funindex \page-ref
+@code{\page-ref}.
+@endpredefined
+
+
+@node Table of contents
+@subsection 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
+\markuplist \table-of-contents
+\pageBreak
+
+\tocItem \markup "First score"
+\score {
+ {
+ c'4 % ...
+ \tocItem \markup "Some particular point in the first score"
+ d'4 % ...
+ }
+}
+
+\tocItem \markup "Second score"
+\score {
+ {
+ e'4 % ...
+ }
+}
+@end verbatim
+
+Markups used for formatting the table of contents are defined in the
+@code{\paper} block. There are two @q{pre-defined} markups already
+available;
+
+@itemize
+
+@item
+@code{tocTitleMarkup}
+
+@noindent
+Used for formatting the title of the table of contents.
+
+@verbatim
+tocTitleMarkup = \markup \huge \column {
+ \fill-line { \null "Table of Contents" \null }
+ \null
+}
+@end verbatim
+
+@item
+@code{tocItemMarkup}
+
+@noindent
+Used for formatting the elements within the table of contents.
+
+@verbatim
+tocItemMarkup = \markup \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+@end itemize
+
+@noindent
+Both of these variables can be changed.
+
+Here is an example changing the table of contents' title into French;
+
+@verbatim
+\paper {
+ tocTitleMarkup = \markup \huge \column {
+ \fill-line { \null "Table des matières" \null }
+ \hspace #1
+ }
+@end verbatim
+
+Here is an example changing the font-size of the elements in the table
+of contents;
+
+@verbatim
+tocItemMarkup = \markup \large \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+Note how the element text and page numbers are referred to in the
+@code{tocItemMarkup} definition.
+
+The @code{\tocItemWithDotsMarkup} command can be included within the
+@code{tocItemMarkup} to fill the line, between a table of contents item
+and its corresponding page number, with dots;
+
+@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
+
+Custom commands with their own markups can also be defined to build a
+more complex table of contents. In the following example, a new style
+is defined for entering act names in a table of contents of an opera;
+
+@noindent
+A new markup variable (called @code{tocActMarkup}) is defined in the
+@code{\paper} block;
+
+@verbatim
+\paper {
+ tocActMarkup = \markup \large \column {
+ \hspace #1
+ \fill-line { \null \italic \fromproperty #'toc:text \null }
+ \hspace #1
+ }
+}
+@end verbatim
+
+@noindent
+A custom music function (@code{tocAct}) is then created -- which uses
+the new @code{tocActMarkup} markup definition.
+
+@verbatim
+tocAct =
+ #(define-music-function (text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
+@end verbatim
+
+@noindent
+A LilyPond input file, using these customer definitions, could look
+something like this;
+
+@lilypond[line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+ tocActMarkup = \markup \large \column {
+ \hspace #1
+ \fill-line { \null \italic \fromproperty #'toc:text \null }
+ \hspace #1
+ }
+}
+
+tocAct =
+#(define-music-function (text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
+
+\book {
+ \markuplist \table-of-contents
+ \tocAct \markup { Atto Primo }
+ \tocItem \markup { Coro. Viva il nostro Alcide }
+ \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
+ \tocAct \markup { Atto Secondo }
+ \tocItem \markup { Sinfonia }
+ \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
+ \markup \null
+}
+@end lilypond
+
+
+Here is an example of the @code{\fill-with-pattern} command used within
+the context of a table of contents;
+
+@verbatim
+\paper {
+ tocItemMarkup = \markup { \fill-line {
+ \override #'(line-width . 70)
+ \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
+ }
+ }
+}
+@end verbatim
+
+@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
one directory higher than the current working directory, use
@example
-\include "../stuff.ly"
+\include "../stuff.ly"
+@end example
+
+@noindent
+or if the included orchestral parts files are all located in a
+subdirectory called @file{parts} within the current directory, use
+
+@example
+\include "parts/VI.ly"
+\include "parts/VII.ly"
+@dots{} etc
+@end example
+
+Files which are to be included can also contain @code{\include}
+statements of their own. By default, these second-level
+@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 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).
+
+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
-@noindent
-or if the included orchestral parts files are all located in a
-subdirectory called @file{parts} within the current directory, use
+Any @file{.ly} file can then include the entire library simply with
@example
-\include "parts/VI.ly"
-\include "parts/VII.ly"
-... etc
+\include "~/libA/libA.ly"
@end example
-Files which are to be included can also contain @code{\include}
-statements of their own. By default, these second-level
-@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
-(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.
+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::
Here is an example:
@lilypond[verbatim,quote]
-sopranoMusic = \relative c'' { a4 b c b8( a) }
-altoMusic = \relative g' { e4 e e f }
-tenorMusic = \relative c' { c4 b e d8( c) }
-bassMusic = \relative c' { a4 gis a d, }
-allLyrics = \lyricmode {King of glo -- ry }
+sopranoMusic = \relative { a'4 b c b8( a) }
+altoMusic = \relative { e'4 e e f }
+tenorMusic = \relative { c'4 b e d8( c) }
+bassMusic = \relative { a4 gis a d, }
+allLyrics = \lyricmode { King of glo -- ry }
<<
\new Staff = "Soprano" \sopranoMusic
\new Lyrics \allLyrics
\new Lyrics \allLyrics
\new PianoStaff <<
\new Staff = "RH" {
- \set Staff.printPartCombineTexts = ##f
- \partcombine
- \sopranoMusic
- \altoMusic
+ \partcombine \sopranoMusic \altoMusic
}
\new Staff = "LH" {
- \set Staff.printPartCombineTexts = ##f
\clef "bass"
- \partcombine
- \tenorMusic
- \bassMusic
+ \partcombine \tenorMusic \bassMusic
}
>>
>>
@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
explicitly expanded:
@lilypond[verbatim,quote]
-music = \relative g' {
- g8. c32 d
+music = \relative {
+ g'8. c32 d
\tag #'trills { d8.\trill }
\tag #'expand { \repeat unfold 3 { e32 d } }
c32 d
Alternatively, it is sometimes easier to exclude sections of music:
@lilypond[verbatim,quote]
-music = \relative g' {
- g8. c32 d
+music = \relative {
+ g'8. c32 d
\tag #'trills { d8.\trill }
\tag #'expand {\repeat unfold 3 { e32 d } }
c32 d
@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}.
-
-@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
+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.
-Multiple rests are not merged if you create a score with more
-than one tagged section at the same place.
-
-@end ignore
@node Using global settings
@unnumberedsubsubsec Using global settings
@cindex include-settings
-Global settings can be incuded from a separate file:
+Global settings can be included from a separate file:
@example
lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
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
+
+
@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
@lilypond[quote]
%c No verbatim here as the code does not display correctly in PDF
+% Font settings for Cyrillic and Hebrew
+% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
+\paper {
+ #(define fonts
+ (set-global-fonts
+ #:roman "Linux Libertine O,serif"
+ #:sans "Linux Biolinum O,sans-serif"
+ #:typewriter "Linux Libertine Mono O,monospace"
+ ))
+}
+
% Cyrillic
bulgarian = \lyricmode {
Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
à vo -- cê uma can -- ção legal
}
-\relative c' {
- c2 d e f g f e
+\relative {
+ c'2 d e f g f e
}
\addlyrics { \bulgarian }
\addlyrics { \hebrew }
\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
@lilypond[quote,verbatim]
\score {
- \relative c'' {
- c1 \mark \markup { \char ##x03EE }
+ \relative {
+ c''1 \mark \markup { \char ##x03EE }
c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2011" \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
-@example
-@{
- \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
-@}
-@end example
+A list of ASCII aliases for special characters can be included:
-will display
+@lilypond[quote,verbatim]
+\paper {
+ #(include-special-characters)
+}
-@example
-@{ a,4 cis e fis g @}
-@end example
+\markup "&flqq; – &OE;uvre incomplète… &frqq;"
-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.
+\score {
+ \new Staff { \repeat unfold 9 a'4 }
+ \addlyrics {
+ This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
+ }
+}
-@example
-lilypond file.ly >display.txt
-@end example
+\markup \column {
+ "The replacement can be disabled:"
+ "– &OE; …"
+ \override #'(replacement-alist . ()) "– &OE; …"
+}
+@end lilypond
+
+You can also make your own aliases, either globally:
+
+@lilypond[quote,verbatim]
+\paper {
+ #(add-text-replacements!
+ '(("100" . "hundred")
+ ("dpi" . "dots per inch")))
+}
+\markup "A 100 dpi."
+@end lilypond
+or locally:
+
+@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
* Replacing the notation font::
@end menu
+@funindex clip-regions
+@cindex Fragments, music
+@cindex Music fragments
+
@node Extracting fragments of music
@subsection Extracting fragments of music
-It is possible to quote small fragments of a large score directly from
-the output. This can be compared to clipping a piece of a paper score
-with scissors.
+It is possible to output one or more fragments of a score by defining
+the explicit location of the music to be extracted within the
+@code{\layout} block of the input file using the @code{clip-regions}
+function, and then running LilyPond with the @option{-dclip-systems}
+option;
-This is done by defining the measures that need to be cut out
-separately. For example, including the following definition
-
-
-@verbatim
-\layout {
+@example
+\layout @{
clip-regions
= #(list
(cons
(make-rhythmic-location 5 1 2)
(make-rhythmic-location 7 3 4)))
-}
-@end verbatim
+@}
+@end example
@noindent
-will extract a fragment starting halfway the fifth measure, ending in
-the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
-in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
+This example will extract a single fragment of the input file
+@emph{starting} after a half-note duration in fifth measure
+(@code{5 1 2}) and @emph{ending} after the third quarter-note in the
+seventh measure (@code{7 3 4}).
+
+Additional fragments can be extracted by adding more pairs of
+@code{make-rhythmic-location} entries to the @code{clip-regions} list in
+the @code{\layout} block.
+
+By default, each music fragment will be output as a separate @code{EPS}
+file, but other formats such as @code{PDF} or @code{PNG} can also be
+created if required. The extracted music is output as if had been
+literally @q{cut} from the original printed score so if a fragment runs
+over one or more lines, a separate output file for each line will be
+generated.
+
+@seealso
+Notation Reference:
+@ref{The layout block}.
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+Application Usage
+@rprogram{Command-line usage}.
-In order to use this feature, LilyPond must be invoked with
-@code{-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}.
@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,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
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ c1
+ \set Score.skipTypesetting = ##t
+ \tempo 4 = 80
+ c4 c c c
+ \set Score.skipTypesetting = ##f
+ d4 d d d
+}
@end lilypond
In polyphonic music, @code{Score.skipTypesetting} will affect all
@cindex EPS output
The default output formats for the printed score are Portable
-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}.
+Document Format (PDF) and PostScript (PS). Portable
+Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated
+PostScript (EPS) output is available through the command line option,
+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}.
+
+@knownissues
+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 Creating MIDI output
+@section Creating MIDI output
+
+@cindex Sound
+@cindex MIDI
+
+LilyPond can produce files that conform to the MIDI (Musical Instrument
+Digital Interface) standard and so allow for the checking of the music
+output aurally (with the help of an application or device that
+understands MIDI). Listening to MIDI output may also help in spotting
+errors such as notes that have been entered incorrectly or are missing
+accidentals and so on.
+
+MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
+require additional software to produce sound from them.
+
+@menu
+* Supported notation for MIDI::
+* Unsupported notation for MIDI::
+* The MIDI block::
+* Controlling MIDI dynamics::
+* Using MIDI instruments::
+* Using repeats with MIDI::
+* MIDI channel mapping::
+* Context properties for MIDI effects::
+* Enhancing MIDI output::
+@end menu
+
+@cindex MIDI, Supported notation
+
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
+
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
+
+@itemize
+@item Breath marks
+@item Chords entered as chord names
+@item Crescendi, decrescendi over multiple notes. The volume is altered
+linearly between the two extremes
+@item Dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf}
+@item Microtones but @emph{not} microtonal chords. A MIDI player that
+supports pitch bending will also be required.
+@item Lyrics
+@item Pitches
+@item Rhythms entered as note durations, including tuplets
+@item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
+and portato
+@item Tempo changes using the @code{\tempo} function
+@item Ties
+@item Tremolos that are @emph{not} entered with a
+@q{@code{:}[@var{number}]} value
+@end itemize
+
+Panning, balance, expression, reverb and chorus effects can also be
+controlled by setting context properties,
+see @ref{Context properties for MIDI effects}.
+
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
+
+@itemize
+@item Appogiaturas. These are made to take half the value of the note
+following (without taking dots into account). For example;
+
+@example
+\appoggiatura c8 d2.
+@end example
+
+@noindent
+The c will take the value of a crotchet.
+
+@item Ornaments (i.e. mordents, trills and turns et al.)
+@item Rallentando, accelerando, ritardando and a tempo
+@item Slurs, including phrasing slurs
+@item Tenuto
+@end itemize
+
+@noindent
+See @ref{Enhancing MIDI output}.
+
+@cindex MIDI, Unsupported notation
+
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
+
+The following items of musical notation cannot be output to MIDI;
+
+@itemize
+@item Articulations other than staccato, staccatissimo, accent, marcato
+and portato
+@item Crescendi and decrescendi over a @emph{single} note
+@item Fermata
+@item Figured bass
+@item Glissandi
+@item Falls and doits
+@item Microtonal chords
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes without @code{\tempo} (e.g. entered as annotations)
+@item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
+value
+@end itemize
+
+
+@node The MIDI block
+@subsection The MIDI block
+
+@cindex MIDI block
+
+To create a MIDI output file from a LilyPond input file, insert a
+@code{\midi} block, which can be empty, within the @code{\score} block;
+
+@example
+\score @{
+ @var{@dots{} music @dots{}}
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+@warning{ A @code{@bs{}score} block that, as well as the music, contains
+only a @code{@bs{}midi} block (i.e. @emph{without} the @code{@bs{}layout}
+block), will only produce MIDI output files. No notation will be
+printed.}
+
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
+
+@example
+lilypond -dmidi-extension=mid MyFile.ly
+@end example
+
+Alternatively, add the following Scheme expression before the start of
+either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
+@ref{File structure}.
+
+@example
+#(ly:set-option 'midi-extension "mid")
+@end example
+
+@seealso
+Notation Reference:
+@ref{File structure}.
+
+Installed Files:
+@file{scm/midi.scm}.
+
+@knownissues
+There are fifteen MIDI channels available and one additional channel
+(#10) for drums. Staves are assigned to channels in sequence, so a
+score that contains more than fifteen staves will result in the extra
+staves sharing (but not overwriting) the same MIDI channel. This may be
+a problem if the sharing staves have conflicting, channel-based, MIDI
+properties -- such as different MIDI instruments -- set.
+
+
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
+
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
+
+Dynamic marks translate automatically into volume levels in the
+available MIDI volume range whereas crescendi and decrescendi vary the
+volume linearly between their two extremes. It is possible to control
+the relative volume of dynamic markings, and the overall volume levels
+of different instruments.
+
+@menu
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
+@end menu
+
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
+
+
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
+
+Only the dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf} have values assigned to them. This
+value is then applied to the value of the overall MIDI volume range to
+obtain the final volume included in the MIDI output for that particular
+dynamic marking. The default fractions range from 0.25 for
+@notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
+dynamic marks and their associated fractions can be found in
+@file{scm/midi.scm}.
+
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{creating-custom-dynamics-in-midi-output.ly}
+
+Installed Files:
+@file{ly/script-init.ly}
+@file{scm/midi.scm}.
+
+Snippets:
+@rlsr{MIDI}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+
+@node Setting MIDI volume
+@unnumberedsubsubsec Setting 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 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
+@end example
+
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range @code{0.2} - @code{0.5}.
+
+@example
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{
+ \context @{
+ \Score
+ midiMinimumVolume = #0.2
+ midiMaximumVolume = #0.5
+ @}
+ @}
+@}
+@end example
+
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
+
+@example
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
-@seealso
-Learning Manual: @rlearning{Other sources of information}.
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
-@knownissues
+@example
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ \set Staff.midiMinimumVolume = #0.3
+ \set Staff.midiMaximumVolume = #0.6
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{ @}
+@}
+@end example
-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.
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
+If these volumes properties are not set then LilyPond still applies a
+@q{small degree} of equalization to certain instruments. See
+@file{scm/midi.scm}.
-@node MIDI output
-@section MIDI output
+Installed Files:
+@file{scm/midi.scm}.
-@cindex Sound
-@cindex MIDI
+@seealso
+Notation Reference:
+@ref{Score layout}.
-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.
+Internals Reference:
+@rinternals{Dynamic_performer}.
-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.
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
-@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.
+@knownissues
+Changes in the MIDI volume take place only on starting a note, so
+crescendi and decrescendi cannot affect the volume of a single note.
-@menu
-* Creating MIDI files::
-* MIDI block::
-* What goes into the MIDI output?::
-* Repeats in MIDI::
-* Controlling MIDI dynamics::
-* Percussion in MIDI::
-@end menu
-@node Creating MIDI files
-@subsection Creating MIDI files
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
-To create a MIDI output file from a LilyPond input file, add a
-@code{\midi} block to a score, for example,
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
@example
\score @{
- @var{...music...}
- \midi @{ @}
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \tempo 4 = 72
+ @}
@}
@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.
+Here the tempo is set to 72 quarter-note beats per minute. The tempo
+mark in the @code{\midi} block will not appear in the printed score.
+Although any other @code{\tempo} indications specified within the
+@code{\score} block will also be reflected in the MIDI output.
+
+In a @code{\midi} block the @code{\tempo} command is setting properties
+during the interpretation of the music and in the context of output
+definitions; so it is interpreted @emph{as if} it were a context
+modification.
+
+@cindex MIDI context definitions
+@cindex context definitions with MIDI
+
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
@example
\score @{
- @var{...music...}
- \midi @{ @}
- \layout @{ @}
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+ @}
@}
@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}.
+This example removes the effect of dynamics from the MIDI output. Note:
+LilyPond's translation modules used for sound are called @q{performers}.
-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 initial or overall MIDI tempo is described below,
-see @ref{MIDI block}.
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-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:
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
-@example
-#(ly:set-option 'midi-extension "midi")
-@end example
+Installed Files:
+@file{ly/performer-init.ly}.
-The line above will set the default extension for MIDI files to
-@code{.midi}.
+Snippets:
+@rlsr{MIDI}.
-Alternatively, this option can also be supplied on the command line:
+Internals Reference:
+@rinternals{Dynamic_performer}.
-@example
-lilypond … -dmidi-extension=midi lilyFile.ly
-@end example
+@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
+Changes to the @code{midiInstrument}, as well as some MIDI options, at
+the @emph{beginning} of a staff may appear twice in the MIDI output.
-@unnumberedsubsubsec Instrument names
-@cindex instrument names
-@funindex Staff.midiInstrument
-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}.
+@node Using MIDI instruments
+@subsection Using MIDI instruments
+
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{...notes...}
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
@}
@end example
+or
+
@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{...notes...}
+\score @{
+ \new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
@}
@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.
+If the instrument name does not match any of the instruments listed in
+the @q{MIDI instruments} section, the @code{acoustic grand} instrument
+will be used instead. See @ref{MIDI instruments}.
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-@snippets
+Notation Reference:
+@ref{MIDI instruments},
+@ref{Score layout}.
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+Installed Files:
+@file{scm/midi.scm}.
@knownissues
+Percussion instruments that are notated in a @code{DrumStaff}
+context will be output, correctly, to MIDI channel@tie{}10 but some
+pitched, percussion instruments like the xylophone, marimba, vibraphone
+or timpani, are treated as @qq{normal} instruments so the music for
+these should be entered in a @code{Staff} (not @code{DrumStaff}) context
+to obtain correct MIDI output. A full list of
+@code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
+See @rlearning{Other sources of information}.
-@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,
+
+@node Using repeats with MIDI
+@subsection Using repeats with MIDI
+
+@cindex repeats in MIDI
+@cindex MIDI using repeats
+@funindex \unfoldRepeats
+
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
@example
-@{ a4\< b c d\f @}
+\score @{
+ \unfoldRepeats @{
+ \repeat tremolo 8 @{ c'32 e' @}
+ \repeat percent 2 @{ c''8 d'' @}
+ \repeat volta 2 @{ c'4 d' e' f' @}
+ \alternative @{
+ @{ g' a' a' g' @}
+ @{ f' e' d' c' @}
+ @}
+ @}
+ \midi @{ @}
+@}
@end example
-@noindent
-will not work properly but
+In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
+output only, while also generating printable scores, it is necessary to
+make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
+repeats) and one for the notation (with volta, tremolo, and percent
+repeats);
@example
-@{ a4\< b c d\!\f @}
+\score @{
+ @var{@dots{} music @dots{}}
+ \layout @{ @}
+@}
+\score @{
+ \unfoldRepeats @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
@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.
+When using multiple voices, each of the voices must contain completely
+unfolded repeats for correct MIDI output.
-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}.
+@seealso
+Notation Reference:
+@ref{Repeats}.
+
+
+@node MIDI channel mapping
+@subsection MIDI channel mapping
+
+@cindex MIDI Channels
+@cindex MIDI Tracks
+@funindex midiChannelMapping
+
+When generating a MIDI file from a score, LilyPond will automatically
+assign every note in the score to a MIDI channel, the one on which it
+should be played when it is sent to a MIDI device. A MIDI channel has
+a number of controls available to select, for example, the instrument
+to be used to play the notes on that channel, or to request the MIDI
+device to apply various effects to the sound produced on the channel.
+At all times, every control on a MIDI channel can have only a single
+value assigned to it (which can be modified, however, for example,
+to switch to another instrument in the middle of a score).
+
+The MIDI standard supports only 16 channels per MIDI device. This
+limit on the number of channels also limits the number of different
+instruments which can be played at the same time.
+
+LilyPond creates separate MIDI tracks for each staff, (or discrete
+instrument or voice, depending on the value of
+@code{Score.midiChannelMapping}), and also for each lyrics context.
+There is no limit to the number of tracks.
+
+To work around the limited number of MIDI channels, LilyPond supports
+a number of different modes for MIDI channel allocation, selected using
+the @code{Score.midiChannelMapping} context property. In each case,
+if more MIDI channels than the limit are required, the allocated
+channel numbers wrap around back to 0, possibly causing the incorrect
+assignment of instruments to some notes. This context property can be
+set to one of the following values:
+
+@table @var
+
+@item @code{'staff}
+
+Allocate a separate MIDI channel to each staff in the score (this is
+the default). All notes in all voices contained within each staff will
+share the MIDI channel of their enclosing staff, and all are encoded
+in the same MIDI track.
+
+The limit of 16 channels is applied to the total number of staff and
+lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
+
+@item @code{'instrument}
+
+Allocate a separate MIDI channel to each distinct MIDI instrument
+specified in the score. This means that all the notes played with the
+same MIDI instrument will share the same MIDI channel (and track), even
+if the notes come from different voices or staves.
+
+In this case the lyrics contexts do not count towards the MIDI channel
+limit of 16 (as they will not be assigned to a MIDI instrument), so
+this setting may allow a better allocation of MIDI channels when the
+number of staves and lyrics contexts in a score exceeds 16.
+
+@item @code{'voice}
+
+Allocate a separate MIDI channel to each voice in the score that has a
+unique name among the voices in its enclosing staff. Voices in
+different staves are always assigned separate MIDI channels, but any two
+voices contained within the same staff will share the same MIDI channel
+if they have the same name. Because @code{midiInstrument} and the
+several MIDI controls for effects are properties of the staff context,
+they cannot be set separately for each voice. The first voice will be
+played with the instrument and effects specified for the staff, and
+voices with a different name from the first will be assigned the default
+instrument and effects.
+
+Note: different instruments and/or effects can be assigned to several
+voices on the same staff by moving the @code{Staff_performer} from the
+@code{Staff} to the @code{Voice} context, and leaving
+@code{midiChannelMapping} to default to @code{'staff} or set to
+@code{'instrument}; see the snippet below.
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+@end table
-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:
+For example, the default MIDI channel mapping of a score can be changed
+to the @code{'instrument} setting as shown:
@example
\score @{
- @var{...music...}
+ ...music...
\midi @{
\context @{
\Score
- tempoWholesPerMinute = #(ly:make-moment 72 4)
+ midiChannelMapping = #'instrument
@}
@}
@}
@end example
-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:
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
-@cindex MIDI context definitions
+@node Context properties for MIDI effects
+@subsection Context properties for MIDI effects
-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.
-
-@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
-@}
-@end example
+@cindex Effects in MIDI
+@cindex Pan position in MIDI
+@cindex Stereo balance in MIDI
+@cindex Balance in MIDI
+@cindex Expression in MIDI
+@cindex Reverb in MIDI
+@cindex Chorus level in MIDI
+@funindex midiPanPosition
+@funindex midiBalance
+@funindex midiExpression
+@funindex midiReverbLevel
+@funindex midiChorusLevel
-MIDI output is created only when a @code{\midi} block is included
-within a score block defined with a @code{\score} command.
+The following context properties can be used to apply various MIDI
+effects to notes played on the MIDI channel associated with the
+current staff, MIDI instrument or voice (depending on the value of the
+@code{Score.midiChannelMapping} context property and the context in
+which the @code{Staff_performer} is located; see
+@ref{MIDI channel mapping}).
-@example
-\score @{
- @{ @dots{}notes@dots{} @}
- \midi @{ @}
-@}
-@end example
+Changing these context properties will affect all notes played on the
+channel after the change, however some of the effects may even apply
+also to notes which are already playing (depending on the
+implementation of the MIDI output device).
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
+The following context properties are supported:
-@c TODO Check grace notes - timing is suspect?
+@table @var
-@unnumberedsubsubsec Supported in MIDI
+@item @code{Staff.midiPanPosition}
-@cindex Pitches in MIDI
-@cindex MIDI, Pitches
-@cindex Quarter tones in MIDI
-@cindex MIDI, quarter tones
-@cindex Microtones in MIDI
-@cindex MIDI, microtones
-@cindex Chord names in MIDI
-@cindex MIDI, chord names
-@cindex Rhythms in MIDI
-@cindex MIDI, Rhythms
-@c TODO etc
+The pan position controls how the sound on a MIDI channel is
+distributed between left and right stereo outputs. The context
+property accepts a number between -1.0 (@code{#LEFT}) and 1.0
+(@code{#RIGHT}); the value -1.0 will put all sound power to the left
+stereo output (keeping the right output silent), the value 0.0
+(@code{#CENTER}) will distribute the sound evenly between the left and
+right stereo outputs, and the value 1.0 will move all sound to the
+right stereo output. Values between -1.0 and 1.0 can be used to obtain
+mixed distributions between left and right stereo outputs.
-The following items of notation are reflected in the MIDI output:
+@item @code{Staff.midiBalance}
-@itemize
-@item Pitches
-@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 Tremolos entered without @q{@code{:}[@var{number}]}
-@item Ties
-@item Dynamic marks
-@item Crescendi, decrescendi over multiple notes
-@item Tempo changes entered with a tempo marking
-@item Lyrics
-@end itemize
+The stereo balance of a MIDI channel. Similarly to the pan position,
+this context property accepts a number between -1.0 (@code{#LEFT}) and
+1.0 (@code{#RIGHT}). It varies the relative volume sent to the two
+stereo speakers without affecting the distribution of the stereo
+signals.
-@unnumberedsubsubsec Unsupported in MIDI
+@item @code{Staff.midiExpression}
-@c TODO index as above
+Expression level (as a fraction of the maximum available level) to
+apply to a MIDI channel. A MIDI device combines the MIDI channel's
+expression level with a voice's current dynamic level (controlled using
+constructs such as @code{\p} or @code{\ff}) to obtain the total volume
+of each note within the voice. The expression control could be used, for
+example, to implement crescendo or decrescendo effects over single
+sustained notes (not supported automatically by LilyPond).
-The following items of notation have no effect on the MIDI output:
+@c Issue 4059 contains an attached snippet which shows how this might
+@c be done, but this is too large and complex for the NR, even as a
+@c referenced snippet. It could be added to the LSR.
-@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 Crescendi, decrescendi over a single note
-@item Tremolos entered with @q{@code{:}[@var{number}]}
-@item Figured bass
-@item Microtonal chords
-@end itemize
+The expression level ranges from 0.0 (no expression, meaning zero
+volume) to 1.0 (full expression).
+@item @code{Staff.midiReverbLevel}
-@node Repeats in MIDI
-@subsection Repeats in MIDI
+Reverb level (as a fraction of the maximum available level) to apply
+to a MIDI channel. This property accepts numbers between 0.0 (no
+reverb) and 1.0 (full effect).
-@cindex repeats in MIDI
-@funindex \unfoldRepeats
+@item @code{Staff.midiChorusLevel}
-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.
+Chorus level (as a fraction of the maximum available level) to apply to
+a MIDI channel. This property accepts numbers between 0.0 (no chorus
+effect) and 1.0 (full effect).
-@lilypond[quote,verbatim]
-\unfoldRepeats {
- \repeat tremolo 8 { c'32 e' }
- \repeat percent 2 { c''8 d'' }
- \repeat volta 2 { c'4 d' e' f' }
- \alternative {
- { g' a' a' g' }
- { f' e' d' c' }
- }
-}
-\bar "|."
-@end lilypond
+@end table
-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,
-@example
-\score @{
- @var{..music..}
- \layout @{ .. @}
-@}
-\score @{
- \unfoldRepeats @var{..music..}
- \midi @{ .. @}
-@}
-@end example
+@knownissues
-@node Controlling MIDI dynamics
-@subsection Controlling MIDI dynamics
+As MIDI files do not contain any actual audio data, changes in these
+context properties translate only to requests for changing MIDI channel
+controls in the outputted MIDI files. Whether a particular MIDI device
+(such as a software MIDI player) can actually handle any of these
+requests in a MIDI file is entirely up to the implementation of the
+device: a device may choose to ignore some or all of these requests.
+Also, how a MIDI device will interpret different values for these
+controls (generally, the MIDI standard fixes the behavior only at the
+endpoints of the value range available for each control), and whether a
+change in the value of a control will affect notes already playing on
+that MIDI channel or not, is also specific to the MIDI device
+implementation.
+
+When generating MIDI files, LilyPond will simply transform the
+fractional values within each range linearly into values in a
+corresponding (7-bit, or 14-bit for MIDI channel controls which support
+fine resolution) integer range (0-127 or 0-32767, respectively),
+rounding fractional values towards the nearest integer away from zero.
+The converted integer values are stored as-is in the generated MIDI
+file. Please consult the documentation of your MIDI device for
+information about how the device interprets these values.
+
+
+@node Enhancing MIDI output
+@subsection Enhancing MIDI output
-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.
-
-@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
-@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}.
-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.
+@menu
+* The articulate script::
+@end menu
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
- (if (equal? dynamic "rfz")
- 0.9
- (default-dynamic-absolute-volume dynamic)))
+The default MIDI output is basic but can be improved by setting MIDI
+instruments, @code{\midi} block properties and/or using the
+@file{articulate} script.
-\score {
- \new Staff {
- \set Staff.midiInstrument = #"cello"
- \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
- \new Voice {
- \relative c'' {
- a4\pp b c-\rfz
- }
- }
- }
- \layout {}
- \midi {}
-}
-@end lilypond
+@cindex instrument names
+@cindex MIDI, instruments
+@cindex articulate script
+@cindex articulate.ly
+@funindex Staff.midiInstrument
-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.
-@unnumberedsubsubsec Overall MIDI volume
+@node The articulate script
+@unnumberedsubsubsec The @file{articulate} script
-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
+To use the @file{articulate} script add the appropriate @code{\include}
+command at the top of the input file;
@example
-midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+\include "articulate.ly"
@end example
-In the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+The script creates MIDI output into appropriately @q{time-scaled} notes
+to match many articulation and tempo indications. Engraved output
+however, will also be altered to literally match the MIDI output.
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
+@example
+\score @{
+ \articulate <<
+ @var{@dots{} music @dots{}}
>>
- \layout {}
- \midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- midiMinimumVolume = #0.2
- midiMaximumVolume = #0.5
- }
- }
-}
-@end lilypond
+ \midi @{ @}
+@}
+@end example
-@unnumberedsubsubsec Equalizing different instruments (i)
+The @code{\articulate} command enables abbreviatures (such as trills and
+turns) to be processed. A full list of supported items can be found in
+the script itself. See @file{ly/articulate.ly}.
-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.
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-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.
+Notation Reference:
+@ref{Score layout}.
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \set Staff.midiMinimumVolume = #0.7
- \set Staff.midiMaximumVolume = #0.9
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \set Staff.midiMinimumVolume = #0.3
- \set Staff.midiMaximumVolume = #0.6
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout {}
- \midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
- }
-}
-@end lilypond
+Installed Files:
+@file{ly/articulate.ly}.
-@unnumberedsubsubsec Equalizing different instruments (ii)
+@warning{The @file{articulate} script may shorten chords, which might
+not be appropriate for some types of instrument, such as organ music.
+Notes that do not have any articulations attached to them may also be
+shortened; so to compensate for this, restrict the use of the
+@code{\articulate} function to shorter segments of music or modify the
+values of the variables defined in the @file{articulate} script to
+compentate for the note-shortening behavior.}
-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.
+@node Extracting musical information
+@section Extracting musical information
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+In addition to creating graphical output and MIDI, LilyPond can
+display musical information as text.
-#(set! my-instrument-equalizer-alist
- (append
- '(
- ("flute" . (0.7 . 0.9))
- ("clarinet" . (0.3 . 0.6)))
- my-instrument-equalizer-alist))
+@menu
+* Displaying LilyPond notation::
+* Displaying scheme music expressions::
+* Saving music events to a file::
+@end menu
-#(define (my-instrument-equalizer s)
- (let ((entry (assoc s my-instrument-equalizer-alist)))
- (if entry
- (cdr entry))))
+@node Displaying LilyPond notation
+@subsection Displaying LilyPond notation
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Score.instrumentEqualizer = #my-instrument-equalizer
- \set Staff.midiInstrument = #"flute"
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout { }
- \midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
- }
-}
-@end lilypond
+@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,
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a,4 cis4 e4 fis4 g4 @}
+@end example
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+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.
-@cindex microtones in MIDI
+@example
+lilypond file.ly >display.txt
+@end example
-Microtones consisting of half sharps and half flats are exported
-to the MIDI file and render correctly in MIDI players which support
-pitch bending. See @ref{Note names in other languages}. Here is
-an example showing all the half sharps and half flats. It can be
-copied out and compiled to test microtones in your MIDI player.
+@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:
-@lilypond[verbatim,quote]
-\score {
- \relative c' {
- c4 cih cis cisih
- d4 dih ees eeh
- e4 eih f fih
- fis4 fisih g gih
- gis4 gisih a aih
- bes4 beh b bih
- }
- \layout {}
- \midi {}
-}
-@end lilypond
-@end ignore
+@example
+@{
+ \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
-@node Percussion in MIDI
-@subsection Percussion in MIDI
+@node Displaying scheme music expressions
+@subsection Displaying scheme music expressions
-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.
+See @rextend{Displaying music expressions}.
-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.
-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.
+@node Saving music events to a file
+@subsection Saving music events to a file
-@c TODO Expand with examples, and any other issues
+Music events can be saved to a file on a per-staff basis by
+including a file in your main score.
-@knownissues
+@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
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
+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.