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;

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
}

[image of music]

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:

[image of music]

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

See also

Installed Files: ‘ly/toc-init.ly’.

Predefined commands

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


LilyPond — Notation Reference v2.23.4 (development-branch).