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
+producing several outputs 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}
@node Titles and headers
@section Titles and headers
+@cindex titles
+@cindex headers
+@cindex footers
+
Almost all printed music includes a title and the composer's name;
some pieces include a lot more information.
@menu
* Creating titles headers and footers::
* Custom titles headers and footers::
+* Creating PDF metadata::
* Creating footnotes::
* Reference to page numbers::
* Table of contents::
\header {
title = "DAS WOHLTEMPERIRTE CLAVIER"
subtitle = "TEIL I"
- % Do not display the tagline for this book
+ % Do not display the default LilyPond footer for this book
tagline = ##f
}
\markup { \vspace #1 }
@node Default layout of bookpart and score titles
@unnumberedsubsubsec Default layout of bookpart and score titles
-This example demonstrates all @code{\header} variables:
+This example demonstrates all printed @code{\header} variables:
@lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
\book {
meter = "Meter"
arranger = "Arranger"
% The following fields are centered at the bottom
- tagline = "tagline goes at the bottom of the last page"
- copyright = "copyright goes at the bottom of the first page"
+ tagline = "The tagline goes at the bottom of the last page"
+ copyright = "The copyright goes at the bottom of the first page"
}
\score {
{ s1 }
@end itemize
-The default tagline can be changed by adding a @code{tagline} in the
-top-level @code{\header} block.
+The default LilyPond footer text can be changed by adding a
+@code{tagline} in the top-level @code{\header} block.
@lilypond[papersize=a8landscape,verbatim]
\book {
}
@end lilypond
-To remove the @code{tagline} set the value to @code{##f}.
+To remove the default LilyPond footer text, the @code{tagline} can be
+set to @code{##f}.
@node Custom titles headers and footers
@code{\paper} block, using the following syntax:
@example
-@code{variable} = @code{\markup} @{
+variable = \markup @{
@dots{}
- @code{\on-the-fly} \@var{procedure} @var{markup}
+ \on-the-fly \@var{procedure} @var{markup}
@dots{}
@}
@end example
@q{and} operation, for example,
@example
- @code{\on-the-fly \first-page}
- @code{\on-the-fly \last-page}
+ \on-the-fly \first-page
+ \on-the-fly \last-page
@code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
@end example
Installed Files:
@file{../ly/titling-init.ly}.
+@node Creating PDF metadata
+@subsection Creating PDF metadata
+
+@cindex PDF metadata
+
+In addition to being shown in the printed output, @code{\header} variables
+are also used to set PDF metadata (the information displayed by PDF readers
+as the @code{properties} of the PDF file). As metadata are applied per
+output file, only @code{\header} blocks located at top level or within an
+explicit @code{\book} block will be used to generate PDF metadata; while
+@code{\header} variables in a @code{\bookpart} or @code{\score} block
+will be reflected in the printed output of the respective blocks, the
+document-wide PDF metadata will not be affected by headers at that level.
+
+For example, setting the @code{title} property of the @code{header} block
+@q{Symphony I} will also give this title to the PDF document.
+
+@example
+\header@{
+ title = "Symphony I"
+@}
+@end example
+
+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
+@code{pdftitle}, as below.
+
+@example
+\header@{
+ title = "Symphony I"
+ pdftitle = "Symphony I by Beethoven"
+@}
+@end example
+
+The variables @code{title}, @code{subject}, @code{keywords},
+@code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
+and @code{copyright} all set PDF properties and can all be prefixed with
+@q{pdf} to set a PDF property to a value different from the printed output.
+
+The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
+the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
+both set to the current date and time. @code{ModDate} can be overridden by
+setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
+valid PDF date string.
@node Creating footnotes
@subsection Creating footnotes
@node Table of contents
@subsection 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.
+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
\markuplist \table-of-contents
}
@end verbatim
-The markups which are used to format the table of contents are defined
-in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
-for formatting the title of the table, and @code{tocItemMarkup}, for
-formatting the toc elements, composed of the element title and page
-number. These variables may be changed by the user:
+Markups used for formatting the table of contents are defined in the
+@code{\paper} block. There are two @q{pre-defined} markups already
+available;
+
+@itemize
+
+@item
+@code{tocTitleMarkup}
+
+@noindent
+Used for formatting the title of the table of contents.
+
+@verbatim
+tocTitleMarkup = \markup \huge \column {
+ \fill-line { \null "Table of Contents" \null }
+ \null
+}
+@end verbatim
+
+@item
+@code{tocItemMarkup}
+
+@noindent
+Used for formatting the elements within the table of contents.
+
+@verbatim
+tocItemMarkup = \markup \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+@end itemize
+
+@noindent
+Both of these variables can be changed.
+
+Here is an example changing the table of contents' title into French;
@verbatim
\paper {
- %% Translate the toc title into French:
tocTitleMarkup = \markup \huge \column {
\fill-line { \null "Table des matières" \null }
\hspace #1
}
- %% use larger font size
- tocItemMarkup = \markup \large \fill-line {
- \fromproperty #'toc:text \fromproperty #'toc:page
- }
+@end verbatim
+
+Here is an example changing the font-size of the elements in the table
+of contents;
+
+@verbatim
+tocItemMarkup = \markup \large \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
}
@end verbatim
-Note how the toc element text and page number are referred to in
-the @code{tocItemMarkup} definition.
+Note how the element text and page numbers are referred to in the
+@code{tocItemMarkup} definition.
-New commands and markups may also be defined to build more elaborated
-table of contents:
-@itemize
-@item first, define a new markup variable in the @code{\paper} block
-@item then, define a music function which aims at adding a toc element
-using this markup paper variable.
-@end itemize
+The @code{\tocItemWithDotsMarkup} command can be included within the
+@code{tocItemMarkup} to fill the line, between a table of contents item
+and its corresponding page number, with dots;
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
+@lilypond[verbatim,line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplist \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+
+Custom commands with their own markups can also be defined to build a
+more complex table of contents. In the following example, a new style
+is defined for entering act names in a table of contents of an opera;
+
+@noindent
+A new markup variable (called @code{tocActMarkup}) is defined in the
+@code{\paper} block;
@verbatim
\paper {
\hspace #1
}
}
+@end verbatim
+@noindent
+A custom music function (@code{tocAct}) is then created -- which uses
+the new @code{tocActMarkup} markup definition.
+
+@verbatim
tocAct =
-#(define-music-function (text) (markup?)
- (add-toc-item! 'tocActMarkup text))
+ #(define-music-function (text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
@end verbatim
+@noindent
+A LilyPond input file, using these customer definitions, could look
+something like this;
+
@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
\markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
- \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
+ \tocItem \markup { Cesare. Presti omai l'Egizia terra }
\tocAct \markup { Atto Secondo }
\tocItem \markup { Sinfonia }
\tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
}
@end lilypond
-Dots can be added to fill the line between an item and its page number:
-@lilypond[verbatim,line-width=10.0\cm]
-\header { tagline = ##f }
-\paper {
- tocItemMarkup = \tocItemWithDotsMarkup
-}
+Here is an example of the @code{\fill-with-pattern} command used within
+the context of a table of contents;
-\book {
- \markuplist \table-of-contents
- \tocItem \markup { Allegro }
- \tocItem \markup { Largo }
- \markup \null
+@verbatim
+\paper {
+ tocItemMarkup = \markup { \fill-line {
+ \override #'(line-width . 70)
+ \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
+ }
+ }
}
-@end lilypond
+@end verbatim
@seealso
Installed Files:
altoMusic = \relative { e'4 e e f }
tenorMusic = \relative { c'4 b e d8( c) }
bassMusic = \relative { a4 gis a d, }
-allLyrics = \lyricmode {King of glo -- ry }
+allLyrics = \lyricmode { King of glo -- ry }
<<
\new Staff = "Soprano" \sopranoMusic
\new Lyrics \allLyrics
\new Lyrics \allLyrics
\new PianoStaff <<
\new Staff = "RH" {
- \set Staff.printPartCombineTexts = ##f
- \partcombine
- \sopranoMusic
- \altoMusic
+ \partcombine \sopranoMusic \altoMusic
}
\new Staff = "LH" {
- \set Staff.printPartCombineTexts = ##f
\clef "bass"
- \partcombine
- \tenorMusic
- \bassMusic
+ \partcombine \tenorMusic \bassMusic
}
>>
>>
Multiple @code{\removeWithTag} filters may be applied to a single
music expression to remove several differently named tagged
-sections. Alternatively, you can use a single
-@code{\removeWithTag} with a list of tags.
+sections. Alternatively, you can use a single @code{\removeWithTag}
+with a list of tags.
@lilypond[verbatim,quote]
music = \relative c'' {
}
@end lilypond
-Two or more @code{\keepWithTag} filters applied to a single music
-expression will cause @emph{all} tagged sections to be removed, as
-the first filter will remove all tagged sections except the one
-named, and the second filter will remove even that tagged section.
-Usually you would rather want to use a single @code{\keepWithTag}
-command with a list of multiple tags: this will only remove tagged
-sections not given in @emph{any} of the tags.
+Using two or more @code{\keepWithTag} filters on a single music
+expression will cause @emph{all} of the tagged sections to be removed.
+The first filter will remove all except the one named and any subsequent
+filters will remove the rest. Using one @code{\keepWithTag} command
+with a list of multiple tags will only remove tagged sections that are
+not specified in that list.
+
+@lilypond[verbatim,quote]
+music = \relative c'' {
+ \tag #'violinI { a4 a a a }
+ \tag #'violinII { b4 b b b }
+ \tag #'viola { c4 c c c }
+ \tag #'cello { d4 d d d }
+}
+
+\new Staff {
+ \keepWithTag #'(violinI violinII)
+ \music
+}
+@end lilypond
+
+@noindent
+will print @code{\tag}s @var{violinI} and @var{violinII} but not
+@var{viola} or @var{cello}.
@cindex tag groups
@funindex \tagGroup
-While @code{\keepWithTag} is convenient when dealing with
-@emph{one} set of alternatives, the removal of music tagged with
-@emph{unrelated} tags is problematic when using tags for more than
-one purpose. For that reason, @q{tag groups} of related tags can
-be declared:
+
+While @code{\keepWithTag} is convenient when dealing with @emph{one} set
+of alternatives, the removal of music tagged with @emph{unrelated} tags
+is problematic when using them for more than one purpose. In that case
+@q{groups} of tags can be declared:
@example
\tagGroup #'(violinI violinII viola cello)
@end example
-declares the respective tags as belonging to one tag group.
+@noindent
+Now all the different tags belong to a single @q{tag group}. Note that
+individual tags cannot be members of more than one @emph{tag group}.
@example
\keepWithTag #'violinI @dots{}
@end example
-will then only be concerned with tags from @code{violinI}'s tag
-group: any element of the included music that is tagged with one
-or more of tags from this set but @emph{not} with @code{violinI}
-will get removed.
+@noindent
+will now only show music tagged from @code{violinI}'s tag group and any
+music tagged with one of the @emph{other} tags will removed.
-To any @code{\keepWithTag} command, only tags from the tag groups
-of the tags given in the command are visible.
+@lilypond[verbatim,quote]
+music = \relative {
+ \tagGroup #'(violinI violinII viola cello)
+ \tag #'violinI { c''4^"violinI" c c c }
+ \tag #'violinII { a2 a }
+ \tag #'viola { e8 e e2. }
+ \tag #'cello { d'2 d4 d }
+ R1^"untagged"
+}
-Tags cannot be members of more than one tag group.
+\new Voice {
+ \keepWithTag #'violinI
+ \music
+}
+@end lilypond
+
+When using the @code{\keepWithTag} command, only tags from the tag
+groups of the tags given in the command are visible.
@funindex \pushToTag
@funindex \appendToTag
safe bets:
@lilypond[verbatim,quote]
-test = { \tag #'here { \tag #'here <<c''>> } }
+music = { \tag #'here { \tag #'here <<c''>> } }
{
\pushToTag #'here c'
\pushToTag #'here e'
- \pushToTag #'here g' \test
+ \pushToTag #'here g' \music
\appendToTag #'here c'
\appendToTag #'here e'
- \appendToTag #'here g' \test
+ \appendToTag #'here g' \music
}
@end lilypond
UTF-8. The easiest way to enter such text is by using a
Unicode-aware editor and saving the file with UTF-8 encoding. Most
popular modern editors have UTF-8 support, for example, vim, Emacs,
-jEdit, and GEdit do. All MS Windows systems later than NT use
+jEdit, and Gedit do. All MS Windows systems later than NT use
Unicode as their native character encoding, so even Notepad can
edit and save a file in UTF-8 format. A more functional
alternative for Windows is BabelPad.
Here is an example showing Cyrillic, Hebrew and Portuguese
text:
+@c NOTE: No verbatim in the following example as the code does not
+@c display correctly in PDF Font settings for Cyrillic and Hebrew
+
@lilypond[quote]
-%c No verbatim here as the code does not display correctly in PDF
-% Font settings for Cyrillic and Hebrew
% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
\paper {
#(define fonts
It is possible to output one or more fragments of a score by defining
the explicit location of the music to be extracted within the
-@code{\layout} block of the the input file using the @code{clip-regions}
+@code{\layout} block of the input file using the @code{clip-regions}
function, and then running LilyPond with the @option{-dclip-systems}
option;
file, but other formats such as @code{PDF} or @code{PNG} can also be
created if required. The extracted music is output as if had been
literally @q{cut} from the original printed score so if a fragment runs
-over one or more lines, a separate ouput file for each line will be
+over one or more lines, a separate output file for each line will be
generated.
@seealso
Notation Reference:
@ref{The layout block}.
-Application Usage
+Application Usage:
@rprogram{Command-line usage}.
@cindex EPS output
The default output formats for the printed score are Portable
-Document Format (PDF) and PostScript (PS). Scalable Vector
-Graphics (SVG), Encapsulated PostScript (EPS) and Portable
-Network Graphics (PNG) output formats are also available through
-command line options, see
-@rprogram{Basic command line options for LilyPond}.
+Document Format (PDF) and PostScript (PS). Portable
+Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated
+PostScript (EPS) output is available through the command line option,
+see @rprogram{Basic command line options for LilyPond}.
@node Replacing the notation font
additional musical notation can be output to MIDI;
@itemize
-@item Appogiaturas. These are made to take half the value of the note
+@item Appoggiaturas. These are made to take half the value of the note
following (without taking dots into account). For example;
@example
@warning{The @file{articulate} script may shorten chords, which might
not be appropriate for some types of instrument, such as organ music.
Notes that do not have any articulations attached to them may also be
-shortened; so to compensate for this, restrict the use of the
-@code{\articulate} function to shorter segments of music or modify the
+shortened; so to allow for this, restrict the use of the
+@code{\articulate} function to shorter segments of music, or modify the
values of the variables defined in the @file{articulate} script to
-compenstate for the note-shortening behavior.}
+compensate for the note-shortening behavior.}
@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:
+addition to displaying it). Just insert @code{\displayLilyMusic} into
+the existing music in order to get information about it.
+
+To interpret and display a music section in the console but, at the same
+time, remove it from the output file use the @code{\void} command.
@example
@{
\void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+ c1
@}
@end example
projects / lilypond.git / blobdiff