Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.15.17"
@node General input and output
@chapter General input and output
* Working with input files::
* Controlling output::
* MIDI output::
+* Extracting musical information::
@end menu
@section Input structure
The main format of input for LilyPond are text files. By convention,
-these files end with @code{.ly}.
+these files end with @file{.ly}.
@menu
* Structure of a score::
* Multiple scores in a book::
+* Multiple output files from one input file::
+* Output file names::
* File structure::
@end menu
block, and inside or outside the single music expression within a
@code{\score} block.
+Remember that even in a file containing only a @code{\score} block, it
+is implicitly enclosed in a \book block. A \book block in a source
+file produces at least one output file, and by default the name of the
+output file produced is derived from the name of the input file, so
+@file{fandangoforelephants.ly} will produce
+@file{fandangoforelephants.pdf}.
+
+(For more details about @code{\book} blocks, see
+@ref{Multiple scores in a book},
+@ref{Multiple output files from one input file} @ref{File structure}.)
@seealso
Learning Manual:
@funindex \book
-All the movements and texts which appear in the same @code{.ly} file
+All the movements and texts which appear in the same @file{.ly} file
will normally be typeset in the form of a single output file.
@example
@}
@end example
-However, if you want multiple output files from the same @code{.ly}
-file, then you can add multiple @code{\book} blocks, where each such
-@code{\book} block will result in a separate output. If you do not
-specify any @code{\book} block in the file, LilyPond will implicitly
-treat the full file as a single @code{\book} block, see @ref{File
-structure}. One important exception is within lilypond-book documents,
+One important exception is within lilypond-book documents,
where you explicitly have to add a @code{\book} block, otherwise only
the first @code{\score} or @code{\markup} will appear in the output.
@}
@end example
+@node Multiple output files from one input file
+@subsection Multiple output files from one input file
+
+If you want multiple output files from the same @file{.ly} file,
+then you can add multiple @code{\book} blocks, where each
+such \book block will result in a separate output file.
+If you do not specify any @code{\book} block in the
+input file, LilyPond will implicitly treat the whole
+file as a single \book block, see
+@ref{File structure}.
+
+When producing multiple files from a single source file, Lilypond
+ensures that none of the output files from any @code{\book} block
+overwrites the output file produced by a preceding @code{\book} from
+the same input file.
+
+It does this by adding a suffix to the output name for each
+@code{\book} which uses the default output file name derived from the
+input source file.
+
+The default behaviour is to append a version-number suffix for each
+name which may clash, so
+
+@example
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+in source file @file{eightminiatures.ly}
+will produce
+
+@itemize
+@item
+@file{eightminiatures.pdf},
+@item
+@file{eightminiatures-1.pdf} and
+@item
+@file{eightminiatures-2.pdf}.
+@end itemize
+
+@node Output file names
+@subsection Output file names
+
+@funindex \bookOutputSuffix
+@funindex \bookOutputName
+
+Lilypond provides facilities to allow you to control what file names
+are used by the various back-ends when producing output files.
+
+In the previous section, we saw how Lilypond prevents name-clashes when
+producing several ouputs from a single source file. You also have the
+ability to specify your own suffixes for each @code{\book} block, so
+for example you can produce files called
+@file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
+and @file{eightminiatures-Nocturne.pdf} by adding a
+@code{\bookOutputSuffix} declaration inside each @code{\book} block.
+
+@example
+\book @{
+ \bookOutputSuffix "Romanze"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Menuetto"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Nocturne"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+You can also specify a different output filename for @code{book} block,
+by using @code{\bookOutputName} declarations
+
+@example
+\book @{
+ \bookOutputName "Romanze"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Menuetto"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Nocturne"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+The file above will produce these output files:
+
+@itemize
+@item
+@file{Romanze.pdf},
+@item
+@file{Menuetto.pdf} and
+@item
+@file{Nocturne.pdf}.
+@end itemize
+
+
@node File structure
@subsection File structure
@funindex \book
@funindex \bookpart
-A @code{.ly} file may contain any number of toplevel expressions, where a
+A @file{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
-@itemize @bullet
+@itemize
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
toplevel scores, and combined as a single @code{\book}.
This behavior can be changed by setting the variable
@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{../scm/lily.scm}.
@item
A @code{\book} block logically combines multiple movements
are a number of @code{\score}s, one output file will be created
for each @code{\book} block, in which all corresponding movements
are concatenated. The only reason to explicitly specify
-@code{\book} blocks in a @code{.ly} file is if you wish to create
+@code{\book} blocks in a @file{.ly} file is if you wish to create
multiple output files from a single input file. One exception is
within lilypond-book documents, where you explicitly have to add
a @code{\book} block if you want more than a single @code{\score}
or @code{\markup} in the same example. This behavior can be
changed by setting the variable @code{toplevel-book-handler} at
toplevel. The default handler is defined in the init file
-@file{../@/scm/@/lily@/.scm}.
+@file{../scm/lily.scm}.
@item
A @code{\bookpart} block. A book may be divided into several parts,
@{ c'4 d' e'2 @}
@}
@}
+ \layout @{ @}
@}
- \layout @{ @}
- \header @{ @}
+ \paper @{ @}
+ \header @{ @}
@}
@end example
This behavior can be changed by setting the variable
@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{../scm/lily.scm}.
@item
A markup text, a verse for example
@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::
-* Custom 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:
+
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+}
+@end lilypond
+
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
-@node Custom titles
-@subsection Custom titles
+@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
-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.
+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}.
-@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
+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 scoreTitleMarkup
-@item scoreTitleMarkup
- This is the title put over a @code{\score} block. Typically, it has
-the name of the movement (@code{piece} field).
+@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
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+It is also possible to create your own custom text fields, and refer to
+them in the markup definition.
-@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
+ \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
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+@seealso
+Notation Reference:
+@ref{Title blocks explained}.
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+@node Custom layout for headers and footers
+@unnumberedsubsubsec Custom layout for headers and footers
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@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:
-@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.
+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}:
-@verbatim
-\paper {
- bookTitleMarkup = \markup {
- \fill-line {
- \fromproperty #'header:title
- \fromproperty #'header:composer
- }
+@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 verbatim
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Title blocks explained},
+@ref{Default layout of book and score title blocks}.
+
@node Reference to page numbers
@subsection Reference to page numbers
referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.
-@lilypond[verbatim,line-width=11.0\cm]
+@lilypond[verbatim]
\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))
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
\tocItem \markup { Cesare. Presti omai l'Egizzia terra }
}
@end lilypond
+Dots can be added to fill the line between an item and its page number:
+
+@lilypond[verbatim,quote]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplist \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+
@seealso
-Init files: @file{../@/ly/@/toc@/-init@/.ly}.
+Init files: @file{../ly/toc-init.ly}.
@predefined
@menu
* Including LilyPond files::
* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Special characters::
@end menu
@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,
+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}
+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
+relative to the file containing that command. This behavior is
recommended and it will become the default behavior in a future
version of lilypond.
Some simple examples of using @code{\include} are shown in
@rlearning{Scores and parts}.
-
@seealso
Learning Manual:
@rlearning{Other sources of information},
@rlearning{Scores and parts}.
-
@knownissues
-
If an included file is given a name which is the same as one in
LilyPond's installation files, LilyPond's file from the
installation files takes precedence.
-
@node Different editions from one source
@subsection Different editions from one source
-Several mechanisms are available to facilitate the generation
-of different versions of a score from the same music source.
-Variables are perhaps most useful for combining lengthy sections
-of music and/or annotation in various ways, while tags are more
-useful for selecting one from several alternative shorter sections
-of music. Whichever method is used, separating the notation from
-the structure of the score will make it easier to change the
-structure while leaving the notation untouched.
+Several methods can be used to generate different versions of a score
+from the same music source. Variables are perhaps the most useful for
+combining lengthy sections of music and/or annotation. Tags are more
+useful for selecting one section from several alternative shorter
+sections of music, and can also be used for splicing pieces of music
+together at different points.
+
+Whichever method is used, separating the notation from the structure of
+the score will make it easier to change the structure while leaving the
+notation untouched.
@menu
* Using variables::
* Using tags::
+* Using global settings::
@end menu
@node Using variables
@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:
@end ignore
+@node Using global settings
+@unnumberedsubsubsec Using global settings
+
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+
+@node Special characters
+@subsection Special characters
+
+@cindex special characters
+@cindex non-ASCII characters
+
+@menu
+* Text encoding::
+* Unicode::
+* ASCII aliases::
+@end menu
+
+
@node Text encoding
-@subsection Text encoding
+@unnumberedsubsubsec Text encoding
-@cindex Unicode
@cindex UTF-8
-@cindex non-ASCII characters
LilyPond uses the character repertoire defined by the Unicode
consortium and ISO/IEC 10646. This defines a unique name and
\addlyrics { \portuguese }
@end lilypond
+
+@node Unicode
+@unnumberedsubsubsec Unicode
+
+@cindex Unicode
+
To enter a single character for which the Unicode code point is
known but which is not available in the editor being used, use
either @code{\char ##xhhhh} or @code{\char #dddd} within a
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2011" \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}.
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}.
it skips all events, including tempo and instrument changes. You have
been warned.
-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
- c8 d
- \set Score.skipTypesetting = ##t
- e8 e e e e e e e
- \set Score.skipTypesetting = ##f
- c8 d b bes a g c2
-}
+@lilypond[quote,relative=2,ragged-right,verbatim]
+c8 d
+\set Score.skipTypesetting = ##t
+e8 e e e e e e e
+\set Score.skipTypesetting = ##f
+c8 d b bes a g c2
@end lilypond
In polyphonic music, @code{Score.skipTypesetting} will affect all
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
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 oputput 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
see @ref{MIDI block}.
Due to some limitations on Windows, the default extension for
-MIDI files on Windows is @code{.mid}. Other operating systems still
-use the extension @code{.midi}. If a different extension is preferred,
+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:
@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
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},
+@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
@end example
MIDI output is created only when a @code{\midi} block is included
-within a score block defined with a @code{\score} command. If it
-is placed within an explicitly instantiated score context (i.e.
-within a @code{\new Score} block) the file will fail. To solve
-this, enclose the @code{\new Score} and the @code{\midi} commands
-in a @code{\score} block.
+within a score block defined with a @code{\score} command.
@example
\score @{
- \new Score @{ @dots{}notes@dots{} @}
+ @{ @dots{}notes@dots{} @}
\midi @{ @}
@}
@end example
@cindex MIDI, chord names
@cindex Rhythms in MIDI
@cindex MIDI, Rhythms
+@cindex Articlulate scripts
+@cindex MIDI, articulations
+@cindex articulations in MIDI
+@cindex trills in MIDI
+@cindex turns in MIDI
+@cindex rallentando in MIDI
+@cindex accelerando in MIDI
@c TODO etc
The following items of notation are reflected in the MIDI output:
@itemize
@item Pitches
-@item Microtones (See @ref{Accidentals}. Rendering needs a
+@item Microtones (See @ref{Accidentals}. Rendering needs a
player that supports pitch bend.)
@item Chords entered as chord names
@item Rhythms entered as note durations, including tuplets
@item 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,
MIDI volume range. The default fractions range from 0.25 for
@notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
marks and the associated fractions can be seen in
-@file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
+@file{../scm/midi.scm}, see @rlearning{Other sources of information}.
This set of fractions may be changed or extended by providing a
function which takes a dynamic mark as its argument and returns the
required fraction, and setting
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.
+@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
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}.
+in @file{../scm/midi.scm}.
This basic default equalizer can be replaced by setting
@code{instrumentEqualizer} in the @code{Score} context to a new
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.
+@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.
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