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
}
}
- \markup {
- and now...
+}
+@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
+ }
+ }
+}
+@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
+
+@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:
+
+@itemize
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
+@end itemize
-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.}
+These markup variables are discussed in
+@ref{Default layout of book and score title blocks}.
-Headers may be completely removed by setting them to false.
+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
-
-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.
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+}
+@end lilypond
-@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
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
-@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:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+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 evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+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:
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+@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 oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+It is also possible to create your own custom text fields, and refer to
+them in the markup definition.
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer 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, 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}.
+These markup variables are discussed in
+@ref{Default layout of book and score title blocks}.
-This example centers page numbers at the bottom of every page.
+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}:
-@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
+@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
@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" "?" }
}
projects / lilypond.git / commitdiff