Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.14.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 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
some pieces include a lot more information.
@menu
-* Creating titles::
+* Creating titles headers and footers::
* Custom headers footers and titles::
* 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).
-
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
+@menu
+* Title blocks explained::
+* Default layout of book and score title blocks::
+* Default layout of headers and footers::
+@end menu
-@table @code
-@funindex dedication
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
+@node Title blocks explained
+@unnumberedsubsubsec Title blocks explained
-@funindex title
-@item title
-The title of the music, centered just below the dedication.
+@c TODO: figure out how \bookpart titles work
-@funindex subtitle
-@item subtitle
-Subtitle, centered below the title.
+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 subsubtitle
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
+If the book only has a single score, the @code{\header} block may be
+placed inside or outside of the @code{\score} block.
-@funindex poet
-@item poet
-Name of the poet, flush-left below the subsubtitle.
+@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 instrument
-@item instrument
-Name of the instrument, centered below the subsubtitle. Also
-centered at the top of pages (other than the first page).
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\header {
+ title = "SUITE I."
+ composer = "J. S. Bach."
+}
-@funindex composer
-@item composer
-Name of the composer, flush-right below the subsubtitle.
+\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."
+ }
+}
-@funindex meter
-@item meter
-Meter string, flush-left below the poet.
+\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 arranger
-@item arranger
-Name of the arranger, flush-right below the composer.
+Text fields from the main title block of a book can be displayed in all
+@code{\score} blocks, or manually suppressed:
-@funindex piece
-@item piece
-Name of the piece, flush-left below the meter.
+@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 opus
-@item opus
-Name of the opus, flush-right below the arranger.
+@seealso
+Notation Reference:
+@ref{File structure},
+@ref{Custom layout for 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).
-@funindex copyright
-@item copyright
-Copyright notice, centered at the bottom of the first page. To
-insert the copyright symbol, see @ref{Text encoding}.
+@node Default layout of book and score title blocks
+@unnumberedsubsubsec Default layout of book and score title blocks
-@funindex tagline
-@item tagline
-Centered at the bottom of the last page.
+The layout and formatting of title blocks are controlled by two
+@code{\paper} variables; @code{bookTitleMarkup} for the main
+@code{\header} title block and @code{scoreTitleMarkup} for individual
+@code{\header} blocks within a @code{\score}.
-@end table
+@lilypond[papersize=a6,quote,verbatim,noragged-right]
+\header {
+ % The following fields are centered
+ dedication = "Dedication"
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ instrument = "Instrument"
-Here is a demonstration of the fields available. Note that you
-may use any @ref{Formatting text}, commands in the header.
+ % The following fields are left-aligned on the left side
+ poet = "Poet"
+ meter = "Meter"
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\paper {
- line-width = 9.0\cm
- paper-height = 10.0\cm
+ % The following fields are right-aligned on the right side
+ composer = "Composer"
+ arranger = "Arranger"
}
-\book {
+\score {
+ { s1 }
\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"
+ % The following fields are placed at opposite ends of the same line
piece = "Piece"
+ opus = "Opus"
}
+}
+@end lilypond
+
+@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.
+
+The default settings for @code{scoreTitleMarkup} place the @code{piece}
+and @code{opus} text fields at opposite ends of the same line.
+
+@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 {
+ 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{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}.
-@example
-\header @{
- composer = "Composer"
-@}
-\header @{
- piece = "Piece"
-@}
-\score @{
- \new Staff @{ c'4 @}
- \header @{
- piece = "New piece" % overwrite previous one
- @}
-@}
-@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}.
+@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
+
-@lilypond[quote,verbatim,line-width=11.0\cm]
+@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 {
- { c'4 }
+ { s1 }
\header {
- title = "title" % not printed
- piece = "piece"
- opus = "opus"
+ piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
+ subtitle = \markup { \italic "(Excerpt)" }
}
}
@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
+@seealso
+Notation Reference:
+@ref{Formatting text}.
-@example
-\paper@{
- print-all-headers = ##t
-@}
-@end example
-@cindex copyright
-@cindex tagline
+@node Custom layout for title blocks
+@unnumberedsubsubsec Custom layout for title blocks
-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.}
+@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,
+use either or both of the following @code{\paper} variables:
-Headers may be completely removed by setting them to false.
+@itemize
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
+@end itemize
+
+These markup variables are discussed 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 @{
- tagline = ##f
- composer = ##f
+scoreTitleMarkup = \markup @{ \column @{
+ \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \fill-line @{
+ \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ @}
+@}
@}
@end example
+This places the @code{piece} and @code{opus} text fields at opposite
+ends of the same line:
-@node Custom headers footers and titles
-@subsection Custom headers, footers, and titles
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+}
+@end lilypond
-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.
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
-@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
+@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
-@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).
+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}.
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+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:
-@funindex evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@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
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+It is also possible to create your own custom text fields, and refer to
+them in the markup definition.
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+@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
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+@seealso
+Notation Reference:
+@ref{Title blocks explained}.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@node Custom layout for headers and footers
+@unnumberedsubsubsec Custom layout for headers and footers
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@c can make-header and make-footer be removed from
+@c paper-defaults-init.ly? -mp
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+@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:
-@example
-\paper @{
- bookTitleMarkup = \markup @{
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- @}
-@}
-@end example
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end 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}.
+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}:
-This example centers page numbers at the bottom of every page.
+@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
-@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
+@seealso
+Notation Reference:
+@ref{Title blocks explained},
+@ref{Default layout of book and score title blocks}.
@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]
\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" "?" }
}
* Including LilyPond files::
* Different editions from one source::
* Text encoding::
-* Displaying LilyPond notation::
@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
@}
@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,
-
-@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
-
@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}.
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. 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
\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,
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} but only when
+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
+
+
+@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.