Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.16.0"
@node General input and output
@chapter General input and output
* Working with input files::
* Controlling output::
* MIDI output::
+* Extracting musical information::
@end menu
@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}.
@item
A direct scheme expression, such as
@{ c'4 d' e'2 @}
@}
@}
+ \layout @{ @}
@}
- \layout @{ @}
- \header @{ @}
+ \paper @{ @}
+ \header @{ @}
@}
@end example
@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
@end itemize
-
@seealso
Learning Manual:
@rlearning{How LilyPond input files work}.
+Notation Reference:
+@ref{The \layout block}.
+
@node Titles and headers
@section Titles and headers
some pieces include a lot more information.
@menu
-* Creating titles::
+* Creating titles headers and footers::
* Custom headers footers and titles::
+* 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
+* Title blocks explained::
+* Default layout of book and score title blocks::
+* 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 Title blocks explained
+@unnumberedsubsubsec Title blocks explained
-@table @code
-@funindex dedication
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
+@c TODO: figure out how \bookpart titles work
-@funindex title
-@item title
-The title of the music, centered just below the dedication.
+There are two types of title blocks: the main title block that appears
+above of the first @code{\score} of a book, and individual title
+blocks that appear within each @code{\score} block. Text fields for
+both types are entered using a @code{\header} block.
-@funindex subtitle
-@item subtitle
-Subtitle, centered below the title.
+If the book only has a single score, the @code{\header} block may be
+placed inside or outside of the @code{\score} block.
-@funindex subsubtitle
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
+@warning{Remember when adding a @bs{}@code{header} block inside a
+@bs{}@code{score} block, that the music expression must come before the
+@bs{}@code{header} block.}
-@funindex poet
-@item poet
-Name of the poet, flush-left below the subsubtitle.
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\header {
+ title = "SUITE I."
+ composer = "J. S. Bach."
+}
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the subsubtitle. Also
-centered at the top of pages (other than the first page).
+\score {
+ \new Staff \relative g, {
+ \clef bass
+ \key g \major
+ \repeat unfold 2 { g16( d' b') a b d, b' d, } |
+ \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
+ }
+ \header {
+ piece = "Prélude."
+ }
+}
+
+\score {
+ \new Staff \relative b {
+ \clef bass
+ \key g \major
+ \partial 16 b16 |
+ <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
+ d16( b g fis) g( e d c) b(c d e) fis( g a b) |
+ }
+ \header {
+ piece = "Allemande."
+ }
+}
+@end lilypond
-@funindex composer
-@item composer
-Name of the composer, flush-right below the subsubtitle.
+Text fields from the main title block of a book can be displayed in all
+@code{\score} blocks, or manually suppressed:
-@funindex meter
-@item meter
-Meter string, flush-left below the poet.
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ print-all-headers = ##t
+ }
+ \header {
+ title = "DAS WOHLTEMPERIRTE CLAVIER"
+ subtitle = "TEIL I"
+ % Do not display the tagline for this book
+ tagline = ##f
+ }
+ \markup { \vspace #1 }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "PRAELUDIUM I"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "FUGA I"
+ subsubtitle = "A 4 VOCI"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+}
+@end lilypond
-@funindex arranger
-@item arranger
-Name of the arranger, flush-right below the composer.
+@seealso
+Notation Reference:
+@ref{File structure},
+@ref{Custom layout for title blocks}.
-@funindex piece
-@item piece
-Name of the piece, flush-left below the meter.
-@funindex opus
-@item opus
-Name of the opus, flush-right below the arranger.
+@node Default layout of book and score title blocks
+@unnumberedsubsubsec Default layout of book and score title blocks
-@cindex page breaks, forcing
-@funindex breakbefore
-@item breakbefore
-This forces the title to start on a new page (set to ##t or ##f).
+This example demonstrates all @code{\header} variables:
-@funindex copyright
-@item copyright
-Copyright notice, centered at the bottom of the first page. To
-insert the copyright symbol, see @ref{Text encoding}.
+@lilypond[papersize=a7,quote,verbatim,noragged-right]
+\book {
+ \header {
+ % The following fields are centered
+ dedication = "Dedication"
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ % The following fields are evenly spread on one line
+ % the field "instrument" also appears on following pages
+ instrument = \markup \with-color #green "Instrument"
+ poet = "Poet"
+ composer = "Composer"
+ % The following fields are placed at opposite ends of the same line
+ meter = "Meter"
+ arranger = "Arranger"
+ % The following fields are centered at the bottom
+ tagline = "tagline goes at the bottom of the last page"
+ copyright = "copyright goes at the bottom of the first page"
+ }
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 1"
+ opus = "Opus 1"
+ }
+ }
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 2 on the same page"
+ opus = "Opus 2"
+ }
+ }
+ \pageBreak
+ \score {
+ { s1 }
+ \header {
+ % The following fields are placed at opposite ends of the same line
+ piece = "Piece 3 on a new page"
+ opus = "Opus 3"
+ }
+ }
+}
+@end lilypond
-@funindex tagline
-@item tagline
-Centered at the bottom of the last page.
+Note that
-@end table
+@itemize
+@item
+The instrument name will be repeated on every page.
-Here is a demonstration of the fields available. Note that you
-may use any @ref{Formatting text}, commands in the header.
+@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).
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\paper {
- line-width = 9.0\cm
- paper-height = 10.0\cm
-}
+@item
+@c Is the bit about \null markups true? -mp
+Text fields left unset in a @code{\header} block are replaced with
+@code{\null} markups so that the space is not wasted.
+
+@item
+The default settings for @code{scoreTitleMarkup} place the @code{piece}
+and @code{opus} text fields at opposite ends of the same line.
+
+@end itemize
+
+To change the default layout see @ref{Custom layout for title blocks}.
+
+@cindex breakbefore
+
+Use the @code{breakbefore} variable inside a @code{\header} block
+that is itself in a @code{\score} block, to make the top-level
+@code{\header} block titles appear on the first page on their own, with
+the music (defined in the @code{\score} block) starting on the next.
+@lilypond[papersize=a8landscape,verbatim,noragged-right]
\book {
\header {
- dedication = "dedicated to me"
- title = \markup \center-column { "Title first line" "Title second line,
-longer" }
- subtitle = "the subtitle,"
- subsubtitle = #(string-append "subsubtitle LilyPond version "
-(lilypond-version))
- poet = "Poet"
- composer = \markup \center-column { "composer" \small "(1847-1973)" }
- texttranslator = "Text Translator"
- meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
-"r" }
- arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
-#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
- instrument = \markup \bold \italic "instrument"
- piece = "Piece"
+ title = "This is my Title"
+ subtitle = "This is my Subtitle"
+ copyright = "This is the bottom of the first page"
}
-
\score {
- { c'1 }
+ \repeat unfold 4 { e'' e'' e'' e'' }
\header {
- piece = "piece1"
- opus = "opus1"
+ piece = "This is the Music"
+ breakbefore = ##t
+ }
+ }
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work},
+
+Notation Reference:
+@ref{Custom layout for title blocks},
+@ref{File structure}.
+
+Installed Files:
+@file{ly/titling-init.ly}.
+
+
+@node Default layout of headers and footers
+@unnumberedsubsubsec Default layout of headers and footers
+
+@emph{Headers} and @emph{footers} are lines of text appearing at
+the top and bottom of pages, separate from the main text of a book.
+They are controlled by the following @code{\paper} variables:
+
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
+
+These markup variables can only access text fields from top-level
+@code{\header} blocks (which apply to all scores in the book) and are
+defined in @file{ly/titling-init.ly}. By default:
+
+@itemize
+
+@item
+page numbers are automatically placed on the top far left (if even) or
+top far right (if odd), starting from the second page.
+
+@item
+the @code{instrument} text field is placed in the center of every
+page, starting from the second page.
+
+@item
+the @code{copyright} text is centered on the bottom of the first page.
+
+@item
+the @code{tagline} is centered on the bottom of the last page, and below
+the @code{copyright} text if there is only a single page.
+
+@end itemize
+
+@lilypond[papersize=a8landscape]
+\book {
+ \score {
+ \relative c' {
+ c4 d e f
}
}
- \markup {
- and now...
+}
+@end lilypond
+
+The default tagline can be changed by adding a @code{tagline} in the
+top-level @code{\header} block.
+
+@lilypond[papersize=a8landscape,verbatim]
+\book {
+ \header {
+ tagline = "... music notation for Everyone"
}
\score {
- { c'1 }
- \header {
- piece = "piece2"
- opus = "opus2"
+ \relative c' {
+ c4 d e 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.
+To remove the @code{tagline} set the value to @code{##f}.
+
+
+@node Custom headers footers and titles
+@subsection Custom headers footers and titles
+
+@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 title blocks::
+* Custom layout for title blocks::
+* Custom layout for headers and footers::
+@end menu
+
+
+@node Custom text formatting for title blocks
+@unnumberedsubsubsec Custom text formatting for title blocks
+
+Standard @code{\markup} commands can be used to customize any header,
+footer and title text within the @code{\header} block.
+
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
+ subtitle = \markup { \italic "(Excerpt)" }
+ }
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Formatting text}.
+
+
+@node Custom layout for title blocks
+@unnumberedsubsubsec Custom layout for title blocks
+
+@cindex bookTitleMarkup
+@cindex scoreTitleMarkup
+@funindex bookTitleMarkup
+@funindex scoreTitleMarkup
+
+@code{\markup} commands in the @code{\header} block are useful for
+simple text formatting, but they do not allow precise control over the
+placement of titles. To customize the placement of the text fields,
+change either or both of the following @code{\paper} variables:
+
+@itemize
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
+@end itemize
+
+The placement of titles when using the default values of these
+@code{\markup} variables is shown in the examples in
+@ref{Default layout of book and score title blocks}.
+
+The default settings for @code{scoreTitleMarkup} as defined in
+@file{ly/titling-init.ly} are:
@example
-\header @{
- composer = "Composer"
-@}
-\header @{
- piece = "Piece"
-@}
-\score @{
- \new Staff @{ c'4 @}
- \header @{
- piece = "New piece" % overwrite previous one
+scoreTitleMarkup = \markup @{ \column @{
+ \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \fill-line @{
+ \fromproperty #'header:piece
+ \fromproperty #'header:opus
@}
@}
+@}
@end example
-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 places the @code{piece} and @code{opus} text fields at opposite
+ends of the same line:
-@lilypond[quote,verbatim,line-width=11.0\cm]
+@lilypond[quote,verbatim,noragged-right]
\score {
- { c'4 }
+ { s1 }
\header {
- title = "title" % not printed
- piece = "piece"
- opus = "opus"
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
}
}
@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
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
+
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \fontsize #4 \bold \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
+
+Text fields normally reserved for the main title block can be included
+in individual score title blocks with the @code{print-all-headers}
+placed inside the @code{\paper} block. A disadvantage of using this
+method is that the text fields that are intended specifically for the
+top-level @code{\header} block need to be manually suppressed in every
+@code{\score} block. See @ref{Title blocks 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{Title blocks 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
-\paper@{
- print-all-headers = ##t
+@code{variable} = @code{\markup} @{
+ ...
+ @code{\on-the-fly} #@var{procedure} @var{markup}
+ ...
@}
@end example
-@cindex copyright
-@cindex tagline
+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}:
-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.}
+@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
-Headers may be completely removed by setting them to false.
+Several @code{\on-the-fly} conditions can be combined with an
+@q{and} operation, for example,
@example
-\header @{
- tagline = ##f
- composer = ##f
-@}
+ @code{\on-the-fly #first-page}
+ @code{\on-the-fly #last-page}
+ @code{@{ \markup ... \fromproperty #'header: ... @}}
@end example
+determines if the output is a single page.
-@node Custom headers footers and titles
-@subsection Custom headers, footers, and titles
+@seealso
+Notation Reference:
+@ref{Title blocks explained},
+@ref{Default layout of book and score title blocks}.
-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.
+Installed Files:
+@file{../ly/titling-init.ly}.
-@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
-@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).
+@node Creating footnotes
+@subsection Creating footnotes
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+There are two types of footnotes that can be created; automatic
+footnotes and manual footnotes.
-@funindex evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@menu
+* Footnotes overview::
+* Automatic footnotes::
+* Manual footnotes::
+@end menu
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+@node Footnotes overview
+@unnumberedsubsubsec Footnotes overview
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+Automatic footnotes create incrementing numerical indicators and manual
+footnotes allow a custom indicator to be created instead. Footnotes are
+normally applied like @code{\tweak} and consequently can be placed
+directly on grobs (graphical objects) created by most music elements and
+post-events. In cases where this does not work (like with bar lines and
+meter changes, where the grobs are produced as a consequence of property
+changes), footnotes can also be specified as a standalone music event
+affecting all grobs of a given type at a particular time step.
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+The full form of a footnote command is
+
+@example
+\footnote @var{mark} @var{offset} @var{grob-name} @var{footnote}
+@var{music}
+@end example
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
+The elements are as follows:
+
+@table @var
+@item mark
+is a markup or string specifying the footnote mark which is used for
+both marking the reference point as well as the footnote itself at the
+bottom of the page. It can be omitted (or equivalently replaced with
+@code{\default}) in which case a number in sequence will be generated.
+@item offset
+is a number pair such as @samp{#(2 . 1)} specifying the X and Y offset
+from the reference point where the mark will be placed.
+@item grob-name
+specifies a type of grob to mark (like @samp{#'Flag}). If it is given,
+the respective grob will be used as a reference point even in case that
+its @q{cause} is not the referenced @var{music} itself but a grob
+created from it. It can be omitted (or replaced with @code{\default}),
+and then only a directly created grob will be annotated.
+@item footnote
+This markup or string specifies the footnote text to use at the bottom
+of the page.
+@item music
+This is the item, a music event or chord constituent or post-event, that
+is being annotated. While it cannot be omitted, it @emph{can} be
+replaced by @code{\default} in which case the footnote is not attached
+to a music expression in particular, but rather to a moment of time. It
+is mandatory in this case to use the @var{grob-name} argument for
+selecting an affected grob type, like @samp{#'TimeSignature}.
@end table
+Like with @code{\tweak}, if your @code{\footnote} is applied to a
+post-event or articulation, it will itself have to be preceded with
+@code{-} to make the parser attach the result to the preceding note or
+rest.
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@node Automatic footnotes
+@unnumberedsubsubsec Automatic footnotes
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+Automatic footnotes take four arguments: the @samp{(x . y)} position of
+the indicator, the optional @var{grob-name} specifying the layout object
+to be annotated, the @var{footnote} markup itself that will appear at
+the bottom of the page, and of course the @var{music} to attach the
+footnote to.
-@example
-\paper @{
- bookTitleMarkup = \markup @{
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- @}
-@}
-@end example
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote #'(0.5 . -2)
+ \markup { The first note }
+ a'4 b8
+ \footnote #'(0.5 . 1) #'Flag
+ \markup { The third note }
+ e\noBeam c4 d4
+ }
+}
+@end lilypond
-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}.
+Chorded notes pose no particular difficulty:
-This example centers page numbers at the bottom of every page.
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ <
+ \footnote #'(1 . -1.25) "Here is a C" c
+ \footnote #'(2 . -0.25) \markup { \italic "An E-flat" } es
+ \footnote #'(2 . 3) \markup { \bold "This is a G" } g
+ >1
+ }
+}
+@end lilypond
-@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
+@warning {When footnotes have the same vertical position, the footnotes
+are printed in order of descendancy; the higher the footnote, the
+higher up in the list.}
+
+Here are some more examples of footnoted grobs, also showing the
+relative position of the footnotes to the tagline and copyright.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { copyright = \markup { "Copyright 1970" } }
+ \relative c' {
+ a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
+ -\footnote #'(0 . 1.5) \markup { A slur } (
+ b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
+ \footnote #'(1 . -1) #'Stem
+ \markup { \teeny { This is a stem } }
+ c4
+ \footnote #'(0 . 0.5) #'AccidentalCautionary
+ \markup \italic { A cautionary accidental }
+ \footnote #'(1 . 1) "The note itself"
+ dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
+ _"rit."
+ }
+}
+@end lilypond
+
+For top-level @code{\markup}, the @code{\auto-footnote} command is
+required:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup { \auto-footnote "A simple tune" \italic "By me" }
+ \relative c' {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
+
+
+@node Manual footnotes
+@unnumberedsubsubsec Manual footnotes
+
+@cindex footnotes, manual
+
+Manually marked footnotes take an additional first markup argument
+@var{mark} for making the reference mark. In contrast to automatically
+generated footnote marks, they will not appear before the @var{footnote}
+markup at the bottom of the page: establishing the visual connection is
+left to the user. LilyPond will only make sure that the corresponding
+markup appears on the bottom of the same page.
+
+Other than that, the use is identical to that of automatically numbered
+footnotes.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote
+ "1" #'(0.5 . -2)
+ \markup { \italic "1. The first note" }
+ a'4
+ b8
+ \footnote
+ \markup { \bold "2" } #'(0.5 . 1)
+ "2. The second note"
+ e
+ c4
+ d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
+ }
+}
+@end lilypond
+
+To annotate chorded notes with manual footnotes:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ <
+ \footnote "1" #'(1 . -1.25) "1. C" c
+ \footnote
+ \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
+ \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
+ >1
+ }
+}
+@end lilypond
+
+@warning {When footnotes have the same vertical position, the footnotes
+are printed in order of descendancy; the higher the footnote, the
+higher up in the list.}
+
+Here are some examples of manually footnoted grobs, also showing
+the relative position of the footnotes to the tagline and copyright
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ a'4-\footnote
+ \markup { \teeny 1 } #'(-3 . 0)
+ \markup { 1. \bold Forte } \f
+ -\footnote
+ \markup { \teeny b } #'(0 . 1.5)
+ \markup { b. A slur } (
+ b8)-\footnote
+ \markup { \teeny 3 } #'(0 . -2)
+ \markup { 3. Beam } [
+ e]
+ \footnote
+ \markup { 4 } #'(1 . -1) #'Stem
+ \markup { \bold 4. { This is a stem } }
+ c4
+ \footnote
+ \markup \concat \teeny { "sharp (v)" }
+ #'(0 . 0.5) #'AccidentalCautionary
+ \markup \italic { v. A cautionary accidental }
+ dis?4-\footnote
+ \markup \concat \teeny { "a" } #'(0.5 . -0.5)
+ \markup \italic { a. Slow Down } _"rit."
+ \footnote
+ \markup { \teeny \musicglyph #"rests.4" }
+ #'(1.5 . -0.25)
+ \markup { \null } \breathe
+ }
+}
+@end lilypond
+
+To manually footnote a top-level @code{\markup}:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup { "A simple tune" \footnote "*" \italic "* By me" }
+ \relative c' {
+ a'4 b8 e c4 d4
+ }
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{Objects and interfaces}.
+
+Notation Reference:
+@ref{Balloon help},
+@ref{Page layout},
+@ref{Text marks},
+@ref{Text scripts},
+@ref{Titles and headers}.
+
+Internals Reference:
+@rinternals{FootnoteEvent},
+@rinternals{FootnoteItem},
+@rinternals{FootnoteSpanner},
+@rinternals{Footnote_engraver}.
+
+@knownissues
+Multiple footnotes for the same page can only be stacked, one on top of
+the other, and cannot be printed on the same line. Footnotes cannot be
+attached to @code{MultiMeasureRests} and may collide with @code{Staff},
+@code{\markup} objects and other @code{footnote} annotations. When
+using any manual @code{footnote} command a @code{\paper} block
+containing @code{footnote-auto-number = ##f} is required.
@node Reference to page numbers
referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.
-@lilypond[verbatim,line-width=11.0\cm]
+@lilypond[verbatim,papersize=a8landscape]
\header { tagline = ##f }
\book {
\label #'firstScore
c'1
}
}
-
\markup { The first score begins on page \page-ref #'firstScore "0" "?" }
\markup { Mark A is on page \page-ref #'markA "0" "?" }
}
@node Table of contents
@subsection Table of contents
-A table of contents is included using the @code{\markuplines \table-of-contents}
+A table of contents is included using the @code{\markuplist \table-of-contents}
command. The elements which should appear in the table of contents are
entered with the @code{\tocItem} command, which may be used either at
top-level, or inside a music expression.
@verbatim
-\markuplines \table-of-contents
+\markuplist \table-of-contents
\pageBreak
\tocItem \markup "First score"
(add-toc-item! 'tocActMarkup text))
@end verbatim
-@lilypond[line-width=11.0\cm]
+@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
tocActMarkup = \markup \large \column {
(add-toc-item! 'tocActMarkup text))
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
\tocItem \markup { Cesare. Presti omai l'Egizzia terra }
Dots can be added to fill the line between an item and its page number:
-@lilypond[verbatim,quote]
+@lilypond[verbatim,line-width=10.0\cm]
\header { tagline = ##f }
\paper {
tocItemMarkup = \tocItemWithDotsMarkup
}
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocItem \markup { Allegro }
\tocItem \markup { Largo }
\markup \null
}
@end lilypond
-
@seealso
-Init files: @file{../ly/toc-init.ly}.
-
+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
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
+@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
at the top of the main input file). With @code{relative-includes}
set, the path for each @code{\include} command will be taken
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::
@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
+@funindex \pushToTag
+@funindex \appendToTag
@cindex tag
@cindex keep tagged music
@cindex remove tagged music
+@cindex splice into tagged music
The @code{\tag #'@var{partA}} command marks a music expression
with the name @var{partA}.
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
+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. The commands make sure to
+copy everything that they change so that the original @code{\test}
+retains its meaning.
@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
-
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
\addlyrics { \portuguese }
@end lilypond
+
+@node Unicode
+@unnumberedsubsubsec Unicode
+
+@cindex Unicode
+
To enter a single character for which the Unicode code point is
known but which is not available in the editor being used, use
either @code{\char ##xhhhh} or @code{\char #dddd} within a
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2011" \char ##x00A9 }
+\markup { "Copyright 2008--2012" \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
rhythmic-locations to the list.
In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}. The clips are output as EPS files, and are
+@option{-dclip-systems}. The clips are output as EPS files, and are
converted to PDF and PNG if these formats are switched on as well.
For more information on output formats, see @rprogram{Invoking lilypond}.
Document Format (PDF) and PostScript (PS). Scalable Vector
Graphics (SVG), Encapsulated PostScript (EPS) and Portable
Network Graphics (PNG) output formats are also available through
-command line options, see @rprogram{Command line options for
-lilypond}.
+command line options, see
+@rprogram{Basic command line options for LilyPond}.
@node Replacing the notation font
Download and extract the zip file. Copy the @code{lilyfonts}
directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
-information, see @rlearning{Other sources of information}.
-Move the existing @code{fonts} directory to @code{fonts_orig} and
-move the @code{lilyfonts} directory to @code{fonts}. Simply move
-@code{fonts_orig} back to @code{fonts} to revert back to Feta.
+information, see @rlearning{Other sources of information}. Rename the
+existing @code{fonts} directory to @code{fonts_orig} and the
+@code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
+reverse the process.
@seealso
-Learning Manual: @rlearning{Other sources of information}.
+Learning Manual:
+@rlearning{Other sources of information}.
@knownissues
-
-Gonville cannot be used to typeset @q{Ancient Music} notation. Please
-refer to the author's website for more information on this and other
-specifics including licensing of Gonville.
+Gonville cannot be used to typeset @q{Ancient Music} notation and it is
+likely newer glyphs in later releases of LilyPond may not exist in the
+Gonville font family. Please refer to the author's website for more
+information on these and other specifics, including licensing of
+Gonville.
@node MIDI output
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
-@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.
+Standard MIDI output is somewhat crude; optionally, an enhanced and
+more realistic MIDI output is available by means of
+@ref{The Articulate script}.
+
+The MIDI output allocates a channel for each staff, and reserves channel
+10 for drums. There are only 16 MIDI channels per device, so if the
+score contains more than 15 staves, MIDI channels will be reused.
@menu
* Creating MIDI files::
* Repeats in MIDI::
* Controlling MIDI dynamics::
* Percussion in MIDI::
+* The Articulate script::
@end menu
@node Creating MIDI files
@snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{changing-midi-output-to-one-channel-per-voice.ly}
@knownissues
\score @{
@var{...music...}
\midi @{
- \context @{
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 4)
- @}
+ \tempo 4 = 72
@}
@}
@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:
-
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
+beats per minute. @code{\tempo} is actually a music command for
+setting properties during the interpretation of music: in the
+context of output definitions like a @code{\midi} block, as a matter of
+courtesy those are reinterpreted as if they were context modifications.
@cindex MIDI context definitions
@cindex MIDI, chord names
@cindex Rhythms in MIDI
@cindex MIDI, Rhythms
+@cindex Articlulate scripts
+@cindex MIDI, articulations
+@cindex articulations in MIDI
+@cindex trills in MIDI
+@cindex turns in MIDI
+@cindex rallentando in MIDI
+@cindex accelerando in MIDI
@c TODO etc
The following items of notation are reflected in the MIDI output:
@item Lyrics
@end itemize
+Using @ref{The Articulate script}, a number of items are added to the
+above list:
+
+@itemize
+@item Articulations (slurs, staccato, etc)
+@item Trills, turns
+@item Rallentando and accelerando
+@end itemize
+
+
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output,
+unless you use @ref{The Articulate script}:
@itemize
@item Rhythms entered as annotations, e.g. swing
\bar "|."
@end lilypond
+In scores containing multiple voices, unfolding of repeats in MIDI
+output will only occur correctly if @emph{each} voice contains fully
+notated repeat indications.
+
When creating a score file using @code{\unfoldRepeats} for MIDI,
it is necessary to make two @code{\score} blocks: one for MIDI
(with unfolded repeats) and one for notation (with volta, tremolo,
>>
\layout {}
\midi {
+ \tempo 2 = 72
\context {
\Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
midiMinimumVolume = #0.2
midiMaximumVolume = #0.5
}
>>
\layout {}
\midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
+ \tempo 2 = 72
}
}
@end lilypond
>>
\layout { }
\midi {
- \context {
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
- }
+ \tempo 2 = 72
}
}
@end lilypond
Because the general MIDI standard does not contain rim shots, the
sidestick is used for this purpose instead.
+@node The Articulate script
+@subsection The Articulate script
+
+A more realistic MIDI output is possible when using the Articulate
+script. It tries to take articulations (slurs, staccato, etc) into
+account, by replacing notes with sequential music of suitably
+time-scaled note plus skip. It also tries to unfold trills turns
+etc., and take rallentando and accelerando into account.
+
+To use the Articulate script, you have to include it at the top of
+your input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+ all the rest of the score...
+>>
+@end example
+
+After altering your input file this way, the visual output is heavily
+altered, but the standard @code{\midi} block will produce a better
+MIDI file.
+
+Although not essential for the Articulate script to work, you may want
+to insert the @code{\unfoldRepeats} command as it appears in the
+example shown above as it enables performing abbreviatures such as
+@notation{trills}.
+
+@knownissues
+
+Articulate shortens chords and some music (esp. organ music) could
+sound worse.
+
+
+@node Extracting musical information
+@section Extracting musical information
+
+In addition to creating graphical output and MIDI, LilyPond can
+display musical information as text.
+
+@menu
+* Displaying LilyPond notation::
+* Displaying scheme music expressions::
+* Saving music events to a file::
+@end menu
+
+@node Displaying LilyPond notation
+@subsection Displaying LilyPond notation
+
+@funindex \displayLilyMusic
+Displaying a music expression in LilyPond notation can be
+done with the music function @code{\displayLilyMusic}. To see the
+output, you will typically want to call LilyPond using the command
+line. For example,
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a,4 cis e fis g @}
+@end example
+
+By default, LilyPond will print these messages to the console
+along with all the other LilyPond compilation messages. To split
+up these messages and save the results of @code{\display@{STUFF@}},
+redirect the output to a file.
+
+@example
+lilypond file.ly >display.txt
+@end example
+
+@funindex \void
+Note that Lilypond does not just display the music expression, but
+also interprets it (since @code{\displayLilyMusic} returns it in
+addition to displaying it). This is convenient since you can just
+insert @code{\displayLilyMusic} into existing music in order to get
+information about it. If you don't actually want Lilypond to
+interpret the displayed music as well as display it, use @code{\void}
+in order to have it ignored:
+
+@example
+@{
+ \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+
+@node Displaying scheme music expressions
+@subsection Displaying scheme music expressions
+
+See @rextend{Displaying music expressions}.
+
+
+@node Saving music events to a file
+@subsection Saving music events to a file
+
+Music events can be saved to a file on a per-staff basis by
+including a file in your main score.
+
+@example
+\include "event-listener.ly"
+@end example
+
+This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
+@file{FILENAME-unnamed-staff.notes} for each staff. Note that if
+you have multiple unnamed staves, the events for all staves will
+be mixed together in the same file. The output looks like this:
+
+@example
+0.000 note 57 4 p-c 2 12
+0.000 dynamic f
+0.250 note 62 4 p-c 7 12
+0.500 note 66 8 p-c 9 12
+0.625 note 69 8 p-c 14 12
+0.750 rest 4
+0.750 breathe
+@end example
+
+The syntax is a tab-delimited line, with two fixed fields on each
+line followed by optional parameters.
+
+@example
+@var{time} @var{type} @var{...params...}
+@end example
+
+This information can easily be read into other programs such as
+python scripts, and can be very useful for researchers wishing to
+perform musical analysis or playback experiments with LilyPond.
+
+
+@knownissues
+Not all lilypond music events are supported by
+@file{event-listener.ly}. It is intended to be a well-crafted
+@qq{proof of concept}. If some events that you want to see are
+not included, copy @file{event-listener.ly} into your lilypond
+directory and modify the file so that it outputs the information
+you want.
projects / lilypond.git / blobdiff