LilyPond Notation Reference: 3.2 Titles and headers

Each \book block in a single input file produces a separate output file, see File structure. Within each output file three types of titling areas are provided: Book Titles at the beginning of each book, Bookpart Titles at the beginning of each bookpart and Score Titles at the beginning of each score.

Values of titling fields such as title and composer are set in \header blocks. (For the syntax of \header blocks and a complete list of the fields available by default see Default layout of bookpart and score titles). Book Titles, Bookpart Titles and Score Titles can all contain the same fields, although by default the fields in Score Titles are limited to piece and opus.

\header blocks may be placed in four different places to form a descending hierarchy of \header blocks:

At the top of the input file, before all \book, \bookpart, and \score blocks.
Within a \book block but outside all the \bookpart and \score blocks within that book.
Within a \bookpart block but outside all \score blocks within that bookpart.
Within a \score block.

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are over-ridden by a value set lower in the hierarchy, so:

A Book Title is derived from fields set at the top of the input file, modified by fields set in the \book block. The resulting fields are used to print the Book Title for that book, providing that there is other material which generates a page at the start of the book, before the first bookpart. A single \pageBreak will suffice.
A Bookpart Title is derived from fields set at the top of the input file, modified by fields set in the \book block, and further modified by fields set in the \bookpart block. The resulting values are used to print the Bookpart Title for that bookpart.
A Score Title is derived from fields set at the top of the input file, modified by fields set in the \book block, further modified by fields set in the \bookpart block and finally modified by fields set in the \score block. The resulting values are used to print the Score Title for that score. Note, though, that only piece and opus fields are printed by default in Score Titles unless the \paper variable, print-all-headers, is set to #t.

It is not necessary to provide \header blocks in all four places: any or even all of them may be omitted. Similarly, simple input files may omit the \book and \bookpart blocks, leaving them to be created implicitly.

If the book has only a single score, the \header block should normally be placed at the top of the file so that just a Bookpart Title is produced, making all the titling fields available for use.

If the book has multiple scores a number of different arrangements of \header blocks are possible, corresponding to the various types of musical publications. For example, if the publication contains several pieces by the same composer a \header block placed at the top of the file specifying the book title and the composer with \header blocks in each \score block specifying the piece and/or opus would be most suitable, as here:

\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \new Staff \relative {
    \clef bass
    \key g \major
    \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
    \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
  }
  \header {
    piece = "Prélude."
  }
}

\score {
  \new Staff \relative {
    \clef bass
    \key g \major
    \partial 16 b16 |
    <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
    d16( b g fis) g( e d c) b(c d e) fis( g a b) |
  }
  \header {
    piece = "Allemande."
  }
}

More complicated arrangements are possible. For example, text fields from the \header block in a book can be displayed in all Score Titles, with some fields over-ridden and some manually suppressed:

\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Do not display the default LilyPond footer for this book
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \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
    }
  }
}

Default layout of bookpart and score titles

This example demonstrates all printed \header variables:

\book {
  \header {
      % The following fields are centered
    dedication = "Dedication"
    title = "Title"
    subtitle = "Subtitle"
    subsubtitle = "Subsubtitle"
      % The following fields are evenly spread on one line
      % the field "instrument" also appears on following pages
    instrument = \markup \with-color #green "Instrument"
    poet = "Poet"
    composer = "Composer"
      % The following fields are placed at opposite ends of the same line
    meter = "Meter"
    arranger = "Arranger"
      % The following fields are centered at the bottom
    tagline = "The tagline goes at the bottom of the last page"
    copyright = "The copyright goes at the bottom of the first page"
  }
  \score {
    { s1 }
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 1"
      opus = "Opus 1"
    }
  }
  \score {
    { s1 }
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 2 on the same page"
      opus = "Opus 2"
    }
  }
  \pageBreak
  \score {
    { s1 }
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 3 on a new page"
      opus = "Opus 3"
    }
  }
}

Note that

The instrument name will be repeated on every page.
Only piece and opus are printed in a \score when the paper variable print-all-headers is set to ##f (the default).
Text fields left unset in a \header block are replaced with \null markups so that the space is not wasted.
The default settings for scoreTitleMarkup place the piece and opus text fields at opposite ends of the same line.

To change the default layout see Custom layout for titles.

If a \book block starts immediately with a \bookpart block, no Book Title will be printed, as there is no page on which to print it. If a Book Title is required, begin the \book block with some markup material or a \pageBreak command.

Use the breakbefore variable inside a \header block that is itself in a \score block, to make the higher-level \header block titles appear on the first page on their own, with the music (defined in the \score block) starting on the next.

\book {
  \header {
    title = "This is my Title"
    subtitle = "This is my Subtitle"
    copyright = "This is the bottom of the first page"
  }
  \score {
    \repeat unfold 4 { e'' e'' e'' e'' }
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
  }
}

Default layout of headers and footers

Headers and 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 \paper variables:

oddHeaderMarkup
evenHeaderMarkup
oddFooterMarkup
evenFooterMarkup

These markup variables can only access text fields from top-level \header blocks (which apply to all scores in the book) and are defined in ‘ly/titling-init.ly’. By default:

page numbers are automatically placed on the top far left (if even) or top far right (if odd), starting from the second page.
the instrument text field is placed in the center of every page, starting from the second page.
the copyright text is centered on the bottom of the first page.
the tagline is centered on the bottom of the last page, and below the copyright text if there is only a single page.

The default LilyPond footer text can be changed by adding a tagline in the top-level \header block.

\book {
  \header {
    tagline = "... music notation for Everyone"
  }
  \score {
    \relative {
      c'4 d e f
    }
  }
}

To remove the default LilyPond footer text, the tagline can be set to ##f.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2.2 Custom titles headers and footers

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Custom text formatting for titles

Standard \markup commands can be used to customize any header, footer and title text within the \header block.

\score {
  { s1 }
  \header {
    piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
    opus = \markup { \italic "BWV 846" }
  }
}

Custom layout for titles

\markup commands in the \header block are useful for simple text formatting, but they do not allow precise control over the placement of titles. To customize the placement of the text fields, change either or both of the following \paper variables:

bookTitleMarkup
scoreTitleMarkup

The placement of titles when using the default values of these \markup variables is shown in the examples in Default layout of bookpart and score titles.

The default settings for scoreTitleMarkup as defined in ‘ly/titling-init.ly’ are:

scoreTitleMarkup = \markup { \column {
  \on-the-fly \print-all-headers { \bookTitleMarkup \hspace #1 }
  \fill-line {
    \fromproperty #'header:piece
    \fromproperty #'header:opus
  }
}
}

This places the piece and opus text fields at opposite ends of the same line:

\score {
  { s1 }
  \header {
    piece = "PRAELUDIUM I"
    opus = "BWV 846"
  }
}

This example redefines scoreTitleMarkup so that the piece text field is centered and in a large, bold font.

\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"
    }
  }
}

Text fields not normally effective in score \header blocks can be printed in the Score Title area if print-all-headers is placed inside the \paper block. A disadvantage of using this method is that text fields that are intended specifically for the Bookpart Title area need to be manually suppressed in every \score block. See Titles explained.

To avoid this, add the desired text field to the scoreTitleMarkup definition. In the following example, the composer text field (normally associated with bookTitleMarkup) is added to scoreTitleMarkup, allowing each score to list a different composer:

\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"
    }
  }
}

It is also possible to create your own custom text fields, and refer to them in the markup definition.

\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"
    }
  }
}

Custom layout for headers and footers

\markup commands in the \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 \paper variables:

oddHeaderMarkup
evenHeaderMarkup
oddFooterMarkup
evenFooterMarkup

The \markup command \on-the-fly can be used to add markup conditionally to header and footer text defined within the \paper block, using the following syntax:

variable = \markup {
  …
  \on-the-fly  \procedure  markup
  …
}

The procedure is called each time the \markup command in which it appears is evaluated. The procedure should test for a particular condition and interpret (i.e., print) the markup argument if and only if the condition is true.

A number of ready-made procedures for testing various conditions are provided:

Procedure name Condition tested

print-page-number-check-first should this page number be printed?

create-page-number-stencil print-page-numbers true?

print-all-headers print-all-headers true?

first-page first page in the book?

not-first-page not first page in the book?

(on-page nmbr) page number = nmbr?

last-page last page in the book?

part-first-page first page in the book part?

not-part-first-page not first page in the book part?

part-last-page last page in the book part?

not-single-page pages in book part > 1?

Procedure name	Condition tested
print-page-number-check-first	should this page number be printed?
create-page-number-stencil	print-page-numbers true?
print-all-headers	print-all-headers true?
first-page	first page in the book?
not-first-page	not first page in the book?
(on-page nmbr)	page number = nmbr?
last-page	last page in the book?
part-first-page	first page in the book part?
not-part-first-page	not first page in the book part?
part-last-page	last page in the book part?
not-single-page	pages in book part > 1?

The following example centers page numbers at the bottom of every page. First, the default settings for oddHeaderMarkup and evenHeaderMarkup are removed by defining each as a null markup. Then, oddFooterMarkup is redefined with the page number centered. Finally, evenFooterMarkup is given the same layout by defining it as \oddFooterMarkup:

\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 }
  }
}

Several \on-the-fly conditions can be combined with an ‘and’ operation, for example,

  \on-the-fly \first-page
  \on-the-fly \last-page
  { \markup … \fromproperty #'header: … }

determines if the output is a single page.

3.2.3 Creating output file metadata

In addition to being shown in the printed output, \header variables are also used to set metadata for output files. For example, with PDF files, this metadata could be displayed by PDF readers as the properties of the PDF file. For each type of output file, only the \header definitions of blocks that define separate files of that type, and blocks higher in the block hierarchy, will be consulted. Therefore, for PDF files, only the \book level and the top level \header definitions affect the document-wide PDF metadata, whereas for MIDI files, all headers above or at the \score level are used.

For example, setting the title property of the header block to ‘Symphony I’ will also give this title to the PDF document, and use it as the sequence name of the MIDI file.

\header {
  title = "Symphony I"
}

If you want to set the title of the printed output to one value, but have the title property of the PDF to have a different value, you can use pdftitle, as below.

\header {
  title = "Symphony I"
  pdftitle = "Symphony I by Beethoven"
}

The variables title, subject, keywords, subtitle, composer, arranger, poet, author and copyright all set PDF properties and can all be prefixed with ‘pdf’ to set a PDF property to a value different from the printed output.

The PDF property Creator is automatically set to ‘LilyPond’ plus the current LilyPond version, and CreationDate and ModDate are both set to the current date and time. ModDate can be overridden by setting the header variable moddate (or pdfmoddate) to a valid PDF date string.

The title variable sets also the sequence name for MIDI. The midititle variable can be used to set the sequence name independently of the value used for typeset output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2.4 Creating footnotes

Footnotes may be used in many different situations. In all cases, a ‘footnote mark’ is placed as a reference in text or music, and the corresponding ‘footnote text’ appears at the bottom of the same page, separated from the music by a horizontal line. The appearance of this separator can be changed by setting the paper variable footnote-separator-markup, see Miscellaneous \paper variables.

Footnotes within music expressions and footnotes in stand-alone text outside music expressions are created in different ways.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Footnotes in music expressions

Music footnotes overview

Footnotes in music expressions fall into two categories:

Event-based footnotes

are attached to a particular event. Examples for such events are single notes, articulations (like fingering indications, accents, dynamics), and post-events (like slurs and manual beams). The general form for event-based footnotes is as follows:

[direction] \footnote [mark] offset footnote music

Time-based footnotes

are bound to a particular point of time in a musical context. Some commands like \time and \clef don’t actually use events for creating objects like time signatures and clefs. Neither does a chord create an event of its own: its stem or flag is created at the end of a time step (nominally through one of the note events inside). Exactly which of a chord’s multiple note events will be deemed the root cause of a stem or flag is undefined. So for annotating those, time-based footnotes are preferable as well.

A time-based footnote allows such layout objects to be annotated without referring to an event. The general form for Time-based footnotes is:

\footnote [mark] offset footnote [Context].GrobName

The elements for both forms are:

direction: If (and only if) the \footnote is being applied to a post-event or articulation, it must be preceded with a direction indicator (-, _, ^) in order to attach music (with a footnote mark) to the preceding note or rest.
mark: is a markup or string specifying the footnote mark which is used for marking both the reference point and the footnote itself at the bottom of the page. It may be omitted (or equivalently replaced with \default) in which case a number in sequence will be generated automatically. Such numerical sequences restart on each page containing a footnote.
offset: is a number pair such as ‘#(2 . 1)’ specifying the X and Y offsets in units of staff-spaces from the boundary of the object where the mark should be placed. Positive values of the offsets are taken from the right/top edge, negative values from the left/bottom edge and zero implies the mark is centered on the edge.
Context: is the context in which the grob being footnoted is created. It may be omitted if the grob is in a bottom context, e.g., a Voice context.
GrobName: specifies a type of grob to mark (like ‘Flag’). If it is specified, the footnote is not attached to a music expression in particular, but rather to all grobs of the type specified which occur at that moment of musical time.
footnote: is the markup or string specifying the footnote text to use at the bottom of the page.
music: is the music event or post-event or articulation that is being annotated.

Event-based footnotes

A footnote may be attached to a layout object directly caused by the event corresponding to music with the syntax:

\footnote [mark] offset footnote music

\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . 3) "A note" a4
    a4
    \footnote #'(2 . 2) "A rest" r4
    a4
  }
}

Marking a whole chord with an event-based footnote is not possible: a chord, even one containing just a single note, does not produce an actual event of its own. However, individual notes inside of the chord can be marked:

\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(2 . 3) "Does not work" <a-3>2
    <\footnote #'(-2 . -3) "Does work" a-3>4
    <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
  }
}

If the footnote is to be attached to a post-event or articulation the \footnote command must be preceded by a direction indicator, -, _, ^, and followed by the post-event or articulation to be annotated as the music argument. In this form the \footnote can be considered to be simply a copy of its last argument with a footnote mark attached to it. The syntax is:

direction \footnote [mark] offset footnote music

\book {
  \header { tagline = ##f }
  \relative {
    a'4_\footnote #'(0 . -1) "A slur forced down" (
    b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
    b8 ]
    c4 )
    c-\footnote #'(1 . 1) "Tenuto" --
  }
}

Time-based footnotes

If the layout object being footmarked is indirectly caused by an event (like an Accidental or Stem caused by a NoteHead event), the GrobName of the layout object is required after the footnote text instead of music:

\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . -3) "A flat" Accidental
    aes4 c
    \footnote #'(-1 . 0.5) "Another flat" Accidental
    ees
    \footnote #'(1 . -2) "A stem" Stem
    aes
  }
}

Note, however, that when a GrobName is specified, a footnote will be attached to all grobs of that type at the current time step:

\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote #'(-1 . 3) "A flat" Accidental
    <ees ges bes>4
    \footnote #'(2 . 0.5) "Articulation" Script
    c'->-.
  }
}

A note inside of a chord can be given an individual (event-based) footnote. A ‘NoteHead’ is the only grob directly caused from a chord note, so an event-based footnote command is only suitable for adding a footnote to the ‘NoteHead’ within a chord. All other chord note grobs are indirectly caused. The \footnote command itself offers no syntax for specifying both a particular grob type as well as a particular event to attach to. However, one can use a time-based \footnote command for specifying the grob type, and then prefix this command with \single in order to have it applied to just the following event:

\book {
  \header { tagline = ##f }
  \relative c'' {
    < \footnote #'(1 . -2) "An A" a
      \single \footnote #'(-1 . -1) "A sharp" Accidental
      cis
      \single \footnote #'(0.5 . 0.5) "A flat" Accidental
      ees fis
    >2
  }
}

Note: When footnotes are attached to several musical elements at the same musical moment, as they are in the example above, the footnotes are numbered from the higher to the lower elements as they appear in the printed output, not in the order in which they are written in the input stream.

Layout objects like clefs and key-change signatures are mostly caused as a consequence of changed properties rather than actual events. Others, like bar lines and bar numbers, are a direct consequence of timing. For this reason, footnotes on such objects have to be based on their musical timing. Time-based footnotes are also preferable when marking features like stems and beams on chords: while such per-chord features are nominally assigned to one event inside the chord, relying on a particular choice would be imprudent.

The layout object in question must always be explicitly specified for time-based footnotes, and the appropriate context must be specified if the grob is created in a context other than the bottom context.

\book {
  \header { tagline = ##f }
  \relative c'' {
    r1 |
    \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
    \time 3/4
    \footnote #'(1 . -1) "Chord stem" Stem
    <c e g>4 q q
    \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
    q q
    \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
    \key c \minor
    q
  }
}

Custom marks can be used as alternatives to numerical marks, and the annotation line joining the marked object to the mark can be suppressed:

\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
    b8
    \footnote \markup { \super "$" } #'(0.5 . 1)
      \markup { \super "$" \italic " The second note" } e
    c4
    \once \override Score.FootnoteItem.annotation-line = ##f
    b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
      \markup { \super "+" \italic " Editorial" } \p
  }
}

More examples of custom marks are shown in Footnotes in stand-alone text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Footnotes in stand-alone text

These are for use in markup outside of music expressions. They do not have a line drawn to their point of reference: their marks simply follow the referenced markup. Marks can be inserted automatically, in which case they are numerical. Alternatively, custom marks can be provided manually.

Footnotes to stand-alone text with automatic and custom marks are created in different ways.

Footnotes in stand-alone text with automatic marks

The syntax of a footnote in stand-alone text with automatic marks is

\markup { … \footnote text footnote … }

The elements are:

text: is the markup or string to be marked.
footnote: is the markup or string specifying the footnote text to use at the bottom of the page.

For example:

\book {
  \header { tagline = ##f }
  \markup {
    "A simple"
    \footnote "tune" \italic " By me"
    "is shown below.  It is a"
    \footnote "recent" \italic " Aug 2012"
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

Footnotes in stand-alone text with custom marks

The syntax of a footnote in stand-alone text with custom marks is

\markup { … \footnote mark footnote … }

The elements are:

mark: is a markup or string specifying the footnote mark which is used for marking the reference point. Note that this mark is not inserted automatically before the footnote itself.
footnote: is the markup or string specifying the footnote text to use at the bottom of the page, preceded by the mark.

Any easy-to-type character such as * or + may be used as a mark, as shown in Footnotes in music expressions. Alteratively, ASCII aliases may be used (see ASCII aliases):

\book {
  \paper { #(include-special-characters) }
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote "*" \italic "* By me"
    "is shown below.  It is a recent"
    \footnote \super &dagger; \concat {
      \super &dagger; \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

Unicode character codes may also be used to specify marks (see Unicode):

\book {
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote \super \char##x00a7 \concat {
      \super \char##x00a7 \italic " By me"
    }
    "is shown below.  It is a recent"
    \footnote \super \char##x00b6 \concat {
      \super \char##x00b6 \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}

Known issues and warnings

Multiple footnotes for the same page can only be stacked, one above the other; they cannot be printed on the same line.

Footnotes cannot be attached to MultiMeasureRests or automatic beams or lyrics.

Footnote marks may collide with staves, \markup objects, other footnote marks and annotation lines.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2.5 Reference to page numbers

A particular place of a score can be marked using the \label command, either at top-level or inside music. This label can then be referred to in a markup, to get the number of the page where the marked point is placed, using the \page-ref markup command.

\header { tagline = ##f }
\book {
  \label #'firstScore
  \score {
    {
      c'1
      \pageBreak \mark A \label #'markA
      c'1
    }
  }
  \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
  \markup { Mark A is on page \page-ref #'markA "0" "?" }
}

The \page-ref markup command takes three arguments:

the label, a Scheme symbol, for example #'firstScore;
a markup that will be used as a gauge to estimate the dimensions of the markup;
a markup that will be used in place of the page number if the label is not known.

The reason why a gauge is needed is that, at the time markups are interpreted, the page breaking has not yet occurred, so the page numbers are not yet known. To work around this issue, the actual markup interpretation is delayed to a later time; however, the dimensions of the markup have to be known before, so a gauge is used to decide these dimensions. If the book has between 10 and 99 pages, it may be "00", ie. a two digit number.

Predefined commands

\label, \page-ref.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2.6 Table of contents

A table of contents is included using the \markuplist \table-of-contents command. The elements which should appear in the table of contents are entered with the \tocItem command, which may be used either at top-level, or inside a music expression.

\markuplist \table-of-contents
\pageBreak

\tocItem \markup "First score"
\score {
  {
    c'4  % ...
    \tocItem \markup "Some particular point in the first score"
    d'4  % ...
  }
}

\tocItem \markup "Second score"
\score {
  {
    e'4 % ...
    \tocItem actI \markup "Act I"
    f'4 % ...
    \tocItem actI.sceneI \markup "Scene 1"
    g'4 % ...
    \tocItem actI.sceneI.recitativo \markup "Recit."
    a'4 % ...
  }
}

Optionally, a label can be associated with a particular item, or a hierarchical list of existing labels, finishing with that item’s label. That latter case allows to mark the item as a ‘child’ of the preceeding labeled items, thus making the score’s structure apparent in the table of contents.

Markups used for formatting the table of contents are defined in the \paper block. There are three ‘pre-defined’ markups already available;

tocTitleMarkup

Used for formatting the title of the table of contents.

tocTitleMarkup = \markup \huge \column {
  \fill-line { \null "Table of Contents" \null }
  \null
}

tocItemMarkup

Used for formatting the elements within the table of contents.

tocItemMarkup = \markup \fill-line {
  \fromproperty #'toc:text \fromproperty #'toc:page
}

tocFormatMarkup
How the table’s top level entries will be formatted (if there are several hierarchical levels). This is actually a procedure, as explained in (extending)Markup construction in Scheme section ‘Markup construction in Scheme’ in Extending.
```
tocFormatMarkup = #make-bold-markup
```
tocIndentMarkup
Used to define how the outline’s hierarchy will be made apparent. This markup is printed zero, one or several times depending on the level of each entry.
```
tocIndentMarkup = \markup \hspace #4
```

Any of these variables can be changed.

Here is an example translating the table of contents’ title into French:

\paper {
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }

Here is an example changing the font-size of the elements in the table of contents:

tocItemMarkup = \markup \large \fill-line {
  \fromproperty #'toc:text \fromproperty #'toc:page
}

Note how the element text and page numbers are referred to in the tocItemMarkup definition.

The \tocItemWithDotsMarkup command can be included within the tocItemMarkup to fill the line, between a table of contents item and its corresponding page number, with dots:

\header { tagline = ##f }
\paper {
  tocItemMarkup = \tocItemWithDotsMarkup
}

\book {
  \markuplist \table-of-contents
  \tocItem \markup { Allegro }
  \tocItem \markup { Largo }
  \markup \null
}

In addition to the built-in outline mechanism, custom commands can also be defined to build a more personalized table of contents with different markups In the following example, a new style is defined for entering act and scenes in the table of contents of an opera:

A new markup variable (called tocActMarkup) is defined in the \paper block:

\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

A custom music function (tocAct) is then created – which uses the new tocActMarkup markup definition, and allows to specify a label for each act.

tocAct =
  #(define-music-function (label text) (symbol? markup?)
     (add-toc-item! 'tocActMarkup label text))

Using these custom definitions and modifying some of the existing definitions, the source file could then be written as follows:

The previous example also demonstrates how to use the \fill-with-pattern markup command within the context of a table of contents.

Predefined commands

\table-of-contents, \tocItem, tocItemMarkup, tocTitleMarkup, tocFormatMarkup, tocIndentMarkup.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Jiné jazyky: català, deutsch, español, français, italiano, 日本語.
O automatickém výběru řeči.

3.2 Titles and headers

3.2.1 Creating titles headers and footers

Titles explained

See also

Default layout of bookpart and score titles

See also

Default layout of headers and footers

3.2.2 Custom titles headers and footers

Custom text formatting for titles

See also

Custom layout for titles

See also

Custom layout for headers and footers

See also

3.2.3 Creating output file metadata

3.2.4 Creating footnotes

Footnotes in music expressions

Music footnotes overview

Event-based footnotes

Time-based footnotes

Footnotes in stand-alone text

Footnotes in stand-alone text with automatic marks

Footnotes in stand-alone text with custom marks

See also

Known issues and warnings

3.2.5 Reference to page numbers

Predefined commands

3.2.6 Table of contents

See also

Predefined commands