[ << General input and output ]	[Top][Contents][Index]	[ Spacing issues >> ]
[ < Reference to page numbers ]	[ Up : Titles and headers ]	[ Working with input files > ]

---

3.3.7 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 preceding 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 ‘predefined’ 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 Markup construction in Scheme.

  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 text label))

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.

See also

Installed Files: ly/toc-init.ly.

Predefined commands

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