Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.32"
+@c \version "2.17.6"
@node General input and output
@chapter General input and output
\book @{
\bookOutputSuffix "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
\book @{
\bookOutputName "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
-book-wide settings. If more than one such definition of
-the same type is entered at the top level any definitions in the later
-expressions have precedence.
+book-wide settings. If more than one such definition of the same type
+is entered at the top level the definitions are combined, but in
+conflicting situations the later definitions take precedence. For
+details of how this affects the @code{\layout} block see
+@ref{The \layout block}.
@item
A direct scheme expression, such as
@code{#(ly:set-option 'point-and-click #f)}.
@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
+A @code{\header} block. This sets the global (i.e. the top of
+file) header block. This is the block containing the default
+settings of titling fields like composer, title, etc. for all
+books within the file (see @ref{Titles explained}).
@item
A @code{\score} block. This score will be collected with other
circumstances to avoid errors:
@itemize
+
@item Around every opening and closing curly bracket.
+
@item After every command or variable, i.e. every item that
begins with a @code{\} sign.
+
@item After every item that is to be interpreted as a Scheme
expression, i.e. every item that begins with a @code{#}@tie{}sign.
+
@item To separate all elements of a Scheme expression.
-@item In @code{lyricmode} to separate all the terms in both
-@code{\override} and @code{\set} commands. In particular, spaces
-must be used around the dot and the equals sign in commands like
-@code{\override Score . LyricText #'font-size = #5} and before and
-after the entire command.
-@end itemize
+@item In @code{lyricmode} before and after @code{\set} and
+@code{\override} commands.
+@end itemize
@seealso
Learning Manual:
@rlearning{How LilyPond input files work}.
+Notation Reference:
+@ref{Titles explained},
+@ref{The \layout block}.
+
@node Titles and headers
@section Titles and headers
@menu
* Creating titles headers and footers::
-* Custom headers footers and titles::
+* Custom titles headers and footers::
* Creating footnotes::
* Reference to page numbers::
* Table of contents::
@subsection Creating titles headers and footers
@menu
-* Title blocks explained::
-* Default layout of book and score title blocks::
+* Titles explained::
+* Default layout of bookpart and score titles::
* Default layout of headers and footers::
@end menu
-@node Title blocks explained
-@unnumberedsubsubsec Title blocks explained
+@node Titles explained
+@unnumberedsubsubsec Titles explained
+
+Each @code{\book} block in a single input file produces a separate
+output file, see @ref{File structure}. Within each output file
+two types of titling areas are provided: @emph{Bookpart Titles} at
+the beginning of each bookpart and @emph{Score Titles} at the
+beginning of each score.
+
+Values of titling fields such as @code{title} and @code{composer}
+are set in @code{\header} blocks. (For the syntax of @code{\header}
+blocks and a complete list of the fields available by default see
+@ref{Default layout of bookpart and score titles}). Both Bookpart
+Titles and Score Titles can contain the same fields, although by
+default the fields in Score Titles are limited to @code{piece} and
+@code{opus}.
+
+@code{\header} blocks may be placed in four different places to form
+a descending hierarchy of @code{\header} blocks:
+
+@itemize
+
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
+
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
+
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
+
+@item
+After the music expression in a @code{\score} block.
-@c TODO: figure out how \bookpart titles work
+@end itemize
-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.
+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:
-If the book only has a single score, the @code{\header} block may be
-placed inside or outside of the @code{\score} block.
+@itemize
-@warning{Remember when adding a @bs{}@code{header} block inside a
+@item
+ A Bookpart Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, and further
+modified by fields set in the @code{\bookpart} block. The resulting
+values are used to print the Bookpart Title for that bookpart.
+
+@item
+A Score Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, further
+modified by fields set in the @code{\bookpart} block and finally
+modified by fields set in the @code{\score} block. The resulting
+values are used to print the Score Title for that score. Note,
+though, that only @code{piece} and @code{opus} fields are printed
+by default in Score Titles unless the @code{\paper} variable,
+@code{print-all-headers}, is set to @code{#t}.
+
+@end itemize
+
+@warning{Remember when placing a @bs{}@code{header} block inside a
@bs{}@code{score} block, that the music expression must come before the
@bs{}@code{header} block.}
+It is not necessary to provide @code{\header} blocks in all four
+places: any or even all of them may be omitted. Similarly, simple
+input files may omit the @code{\book} and @code{\bookpart} blocks,
+leaving them to be created implicitly.
+
+If the book has only a single score, the @code{\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 @code{\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 @code{\header} block
+placed at the top of the file specifying the book title and the
+composer with @code{\header} blocks in each @code{\score} block
+specifying the @code{piece} and/or @code{opus} would be most
+suitable, as here:
+
@lilypond[papersize=a5,quote,verbatim,noragged-right]
\header {
title = "SUITE I."
}
@end lilypond
-Text fields from the main title block of a book can be displayed in all
-@code{\score} blocks, or manually suppressed:
+More complicated arrangements are possible. For example, text
+fields from the @code{\header} block in a book can be displayed in
+all Score Titles, with some fields over-ridden and some manually
+suppressed:
@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
@seealso
Notation Reference:
@ref{File structure},
-@ref{Custom layout for title blocks}.
-
+@ref{Default layout of bookpart and score titles},
+@ref{Custom layout for titles}.
-@node Default layout of book and score title blocks
-@unnumberedsubsubsec Default layout of book and score title blocks
-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}.
+@node Default layout of bookpart and score titles
+@unnumberedsubsubsec Default layout of bookpart and score titles
-@lilypond[papersize=a6,quote,verbatim,noragged-right]
-\header {
- % The following fields are centered
- dedication = "Dedication"
- title = "Title"
- subtitle = "Subtitle"
- subsubtitle = "Subsubtitle"
- instrument = "Instrument"
-
- % The following fields are left-aligned on the left side
- poet = "Poet"
- meter = "Meter"
-
- % The following fields are right-aligned on the right side
- composer = "Composer"
- arranger = "Arranger"
-}
+This example demonstrates all @code{\header} variables:
-\score {
- { s1 }
+@lilypond[papersize=a7,quote,verbatim,noragged-right]
+\book {
\header {
- % The following fields are placed at opposite ends of the same line
- piece = "Piece"
- opus = "Opus"
+ % 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 = "tagline goes at the bottom of the last page"
+ copyright = "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"
+ }
}
}
@end lilypond
-@c Is the bit about \null markups true? -mp
+Note that
+
+@itemize
+@item
+The instrument name will be repeated on every page.
+@item
+Only @code{piece} and @code{opus} are printed in a @code{\score}
+when the paper variable @code{print-all-headers} is set to
+@code{##f} (the default).
+
+@item
+@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.
+@item
The default settings for @code{scoreTitleMarkup} place the @code{piece}
and @code{opus} text fields at opposite ends of the same line.
+@end itemize
+
+To change the default layout see @ref{Custom layout for titles}.
+
@cindex breakbefore
Use the @code{breakbefore} variable inside a @code{\header} block
@rlearning{How LilyPond input files work},
Notation Reference:
+@ref{Custom layout for titles},
@ref{File structure}.
Installed Files:
@file{ly/titling-init.ly}.
+
@node Default layout of headers and footers
@unnumberedsubsubsec Default layout of headers and footers
To remove the @code{tagline} set the value to @code{##f}.
-@node Custom headers footers and titles
-@subsection Custom headers footers and titles
+@node Custom titles headers and footers
+@subsection Custom titles headers and footers
@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 text formatting for titles::
+* Custom layout for titles::
* Custom layout for headers and footers::
@end menu
-@node Custom text formatting for title blocks
-@unnumberedsubsubsec Custom text formatting for title blocks
+@node Custom text formatting for titles
+@unnumberedsubsubsec Custom text formatting for titles
Standard @code{\markup} commands can be used to customize any header,
footer and title text within the @code{\header} block.
@ref{Formatting text}.
-@node Custom layout for title blocks
-@unnumberedsubsubsec Custom layout for title blocks
+@node Custom layout for titles
+@unnumberedsubsubsec Custom layout for titles
+
+@cindex bookTitleMarkup
+@cindex scoreTitleMarkup
+@funindex bookTitleMarkup
+@funindex scoreTitleMarkup
@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:
+change either or both of the following @code{\paper} variables:
@itemize
@item @code{bookTitleMarkup}
@item @code{scoreTitleMarkup}
@end itemize
-These markup variables are discussed in
-@ref{Default layout of book and score title blocks}.
+The placement of titles when using the default values of these
+@code{\markup} variables is shown in the examples in
+@ref{Default layout of bookpart and score titles}.
The default settings for @code{scoreTitleMarkup} as defined in
@file{ly/titling-init.ly} are:
}
@end lilypond
-Text fields normally reserved for the main title block can be included
-in individual score title blocks with the @code{print-all-headers}
+Text fields not normally effective in score @code{\header} blocks
+can be printed in the Score Title area if @code{print-all-headers} is
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}.
+method is that text fields that are intended specifically for the
+Bookpart Title area need to be manually suppressed in every
+@code{\score} block. See @ref{Titles explained}.
To avoid this, add the desired text field to the @code{scoreTitleMarkup}
definition. In the following example, the @code{composer} text field
@seealso
Notation Reference:
-@ref{Title blocks explained}.
+@ref{Titles explained}.
@node Custom layout for headers and footers
@item @code{evenFooterMarkup}
@end itemize
+@cindex markup, conditional
+@cindex on-the-fly
+@funindex \on-the-fly
+
+The @code{\markup} command @code{\on-the-fly} can be used to add
+markup conditionally to header and footer text defined within the
+@code{\paper} block, using the following syntax:
+
+@example
+@code{variable} = @code{\markup} @{
+ ...
+ @code{\on-the-fly} #@var{procedure} @var{markup}
+ ...
+@}
+@end example
+
+The @var{procedure} is called each time the @code{\markup} command
+in which it appears is evaluated. The @var{procedure} should test
+for a particular condition and interpret (i.e. print) the
+@var{markup} argument if and only if the condition is true.
+
+A number of ready-made procedures for testing various conditions are
+provided:
+
+@quotation
+@multitable {print-page-number-check-first-----} {should this page be printed-----}
+
+@headitem Procedure name @tab Condition tested
+
+@item print-page-number-check-first @tab should this page number be printed?
+@item create-page-number-stencil @tab print-page-numbers true?
+@item print-all-headers @tab print-all-headers true?
+@item first-page @tab first page in the book?
+@item (on-page nmbr) @tab page number = nmbr?
+@item last-page @tab last page in the book?
+@item not-first-page @tab not first page in the book?
+@item part-first-page @tab first page in the book part?
+@item part-last-page @tab last page in the book part?
+@item not-single-page @tab pages in book part > 1?
+
+@end multitable
+@end quotation
+
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}
}
@end lilypond
+Several @code{\on-the-fly} conditions can be combined with an
+@q{and} operation, for example,
+
+@example
+ @code{\on-the-fly #first-page}
+ @code{\on-the-fly #last-page}
+ @code{@{ \markup ... \fromproperty #'header: ... @}}
+@end example
+
+determines if the output is a single page.
+
@seealso
Notation Reference:
-@ref{Title blocks explained},
-@ref{Default layout of book and score title blocks}.
+@ref{Titles explained},
+@ref{Default layout of bookpart and score titles}.
+
+Installed Files:
+@file{../ly/titling-init.ly}.
+
@node Creating footnotes
@subsection Creating footnotes
-There are two types of footnotes that can be created; automatic
-footnotes and manual footnotes.
+@cindex footnotes
+
+Footnotes may be used in many different situations. In all cases,
+a @q{footnote mark} is placed as a reference in text or music, and
+the corresponding @q{footnote text} appears at the bottom of the
+same page.
+
+Footnotes within music expressions and footnotes in stand-alone text
+outside music expressions are created in different ways.
@menu
-* Footnotes overview::
-* Automatic footnotes::
-* Manual footnotes::
+* Footnotes in music expressions::
+* Footnotes in stand-alone text::
@end menu
-@node Footnotes overview
-@unnumberedsubsubsec Footnotes overview
+@node Footnotes in music expressions
+@unnumberedsubsubsec Footnotes in music expressions
+
+@cindex footnotes in music expressions
+@funindex \footnote
-Automatic footnotes create incrementing, numerical indicators and
-manual footnotes allow a custom indicator to be created instead. All
-grobs, top-level @code{\markup} and chorded notes can be annotated.
+@subsubsubheading Music footnotes overview
-The order in which each grob is drawn determines the order in which each
-indicator and so footnotes are created during compilation.
+Footnotes in music expressions fall into two categories:
+@table @emph
+@item 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:
-@node Automatic footnotes
-@unnumberedsubsubsec Automatic footnotes
+@example
+[@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-Automatic footnotes take three arguments; the @var{Layout Object} to be
-annotated, the @samp{(x . y)} position of the indicator and a
-@code{\markup} that will appear in the footnote at the bottom of the
-page.
+@item Time-based footnotes
+are bound to a particular point of time in a musical context. Some
+commands like @code{\time} and @code{\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.
-The command @code{\footnote} must come @emph{before} the grob that the
-footnote is being attached to:
+A time-based footnote allows such layout objects to be annotated
+without referring to an event. The general form for Time-based
+footnotes is:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
+@end example
+
+@end table
+
+The elements for both forms are:
+
+@table @var
+
+@item direction
+If (and only if) the @code{\footnote} is being applied to a
+post-event or articulation, it must be preceded with a direction
+indicator (@code{-, _, ^}) in order to attach @var{music} (with
+a footnote mark) to the preceding note or rest.
+
+@item 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
+@code{\default}) in which case a number in sequence will be generated
+automatically. Such numerical sequences restart on each page
+containing a footnote.
+
+@item offset
+is a number pair such as @samp{#(2 . 1)} specifying the X and
+Y@tie{}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.
+
+@item 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
+@code{Voice} context.
+
+@item GrobName
+specifies a type of grob to mark (like @samp{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.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the
+bottom of the page.
+
+@item music
+is the music event or post-event or articulation
+that is being annotated.
+
+@end table
+
+@subsubsubheading Event-based footnotes
+
+@cindex footnotes, event-based
+
+A footnote may be attached to a layout object directly caused
+by the event corresponding to @var{music} with the syntax:
+
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c' {
- \footnote #'(0.5 . -2) #'NoteHead
- \markup { The first note }
- a'4 b8
- \footnote #'(0.5 . 1) #'NoteHead
- \markup { The third note }
- e c4 d4
+ \relative c'' {
+ \footnote #'(-1 . 3) "A note" a4
+ a4
+ \footnote #'(2 . 2) "A rest" r4
+ a4
}
}
@end lilypond
-To annotate chorded notes, the @code{\footnote} must come @emph{after}
-the note to which the footnote is being attached as a @code{TextScript}:
+Marking a @emph{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 @emph{inside} of the chord can be marked:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c' {
- <
- c-\footnote #'(1 . -1.25) "Here is a C"
- es-\footnote #'(2 . -0.25) \markup { \italic "An E-flat" }
- g-\footnote #'(2 . 3) \markup { \bold "This is a G" }
- >1
+ \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
}
}
@end lilypond
-@warning {When footnotes have the same vertical position, the footnotes
-are printed in order of descendancy; the higher the footnote, the
-higher up in the list.}
+If the footnote is to be attached to a post-event or articulation
+the @code{\footnote} command @emph{must} be preceded by a direction
+indicator, @code{-, _, ^}, and followed by the post-event or
+articulation to be annotated as the @var{music} argument. In this
+form the @code{\footnote} can be considered to be simply a copy of
+its last argument with a footnote mark attached to it. The syntax
+is:
-Here are some more examples of footnoted grobs, also showing the
-relative position of the footnotes to the tagline and copyright.
+@example
+@var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
- \header { copyright = \markup { "Copyright 1970" } }
- \relative c' {
- \footnote #'(-3 . 0) #'DynamicText
- \markup { \bold Forte }
-
- \footnote #'(0 . 1.5) #'Slur
- \markup { A slur }
- a'4\f(
+ \header { tagline = ##f }
+ \relative c'' {
+ a4_\footnote #'(0 . -1) "A slur forced down" (
+ b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
+ b8 ]
+ c4 )
+ c-\footnote #'(1 . 1) "Tenuto" --
+ }
+}
+@end lilypond
- \footnote #'(0 . -2) #'Beam
- \markup { Beam }
- b8)[ e]
+@subsubsubheading Time-based footnotes
- \footnote #'(1 . -1) #'Stem
- \markup { \teeny { This is a stem } }
- c4
+@cindex footnotes, time-based
- \footnote #'(0 . 0.5) #'AccidentalCautionary
- \markup \italic { A cautionary accidental }
+If the layout object being footmarked is @emph{indirectly} caused by
+an event (like an @code{Accidental} or @code{Stem} caused by a
+@code{NoteHead} event), the @var{GrobName} of the layout object
+is required after the footnote text instead of @var{music}:
- \footnote #'(0.5 . -0.5) #'TextScript
- \markup \italic { Slow Down }
- dis?4_"rit."
+@lilypond[quote,verbatim,papersize=a8landscape]
+\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
}
}
@end lilypond
-For top-level @code{\markup}, the @code{\auto-footnote} command is
-required:
+Note, however, that when a GrobName is specified, a footnote
+will be attached to all grobs of that type at the current time step:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \markup { \auto-footnote "A simple tune" \italic "By me" }
\relative c' {
- a'4 b8 e c4 d
+ \footnote #'(-1 . 3) "A flat" Accidental
+ <ees ges bes>4
+ \footnote #'(2 . 0.5) "Articulation" Script
+ c'->-.
}
}
@end lilypond
+A note inside of a chord can be given an individual (event-based)
+footnote. A @samp{NoteHead} is the only grob directly caused
+from a chord note, so an event-based footnote command is
+@emph{only} suitable for adding a footnote to the @samp{NoteHead}
+within a chord. All other chord note grobs are indirectly caused.
+The @code{\footnote} command itself offers no syntax for
+specifying @emph{both} a particular grob type @emph{as well as} a
+particular event to attach to. However, one can use a time-based
+@code{\footnote} command for specifying the grob type, and then
+prefix this command with @code{\single} in order to have it
+applied to just the following event:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\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
+ }
+}
+@end lilypond
-@node Manual footnotes
-@unnumberedsubsubsec Manual footnotes
-
-@cindex footnotes, manual
-
-Manual footnotes takes four arguments; the @var{Layout Object} to be
-annotated, the @samp{(x . y)} position of the indicator and two
-@code{\markup} commands; the first is the indicator attached to the note
-or grob and the second is the footnote at the bottom of the page.
+@warning {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 @emph{chords}: while
+such per-chord features are nominally assigned to @emph{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.
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\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
+ }
+}
+@end lilypond
-Like automatic footnotes, manual @code{\footnote} commands must come
-@emph{after} the grob that the footnote is annotating and attached as a
-@code{TextScript}:
+Custom marks can be used as alternatives to numerical marks, and the
+annotation line joining the marked object to the mark can be
+suppressed:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
\relative c' {
- a'4-\footnote
- "1" #'(0.5 . -2) #'NoteHead \markup { \italic "1. The first note" }
+ \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
b8
- e-\footnote
- \markup { \bold "2" } #'(0.5 . 1) #'NoteHead "2. The second note"
+ \footnote \markup { \super "$" } #'(0.5 . 1)
+ \markup { \super "$" \italic " The second note" } e
c4
- d\p-\footnote "3" #'(0.5 . -1) #'DynamicText "3. Piano"
+ \once \override Score.FootnoteItem.annotation-line = ##f
+ b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
+ \markup { \super "+" \italic " Editorial" } \p
}
}
@end lilypond
-To annotate chorded notes with manual footnotes:
+More examples of custom marks are shown in
+@ref{Footnotes in stand-alone text}.
+
+
+@node Footnotes in stand-alone text
+@unnumberedsubsubsec Footnotes in stand-alone text
+
+@cindex 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.
+
+@subsubsubheading Footnotes in stand-alone text with automatic marks
+
+The syntax of a footnote in stand-alone text with automatic marks is
+
+@example
+\markup @{ ... \auto-footnote @var{text} @var{footnote} ... @}
+@end example
+
+The elements are:
+
+@table @var
+
+@item text
+is the markup or string to be marked.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the bottom
+of the page.
+
+@end table
+
+For example:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
\header { tagline = ##f }
+ \markup {
+ "A simple"
+ \auto-footnote "tune" \italic " By me"
+ "is shown below. It is a"
+ \auto-footnote "recent" \italic " Aug 2012"
+ "composition."
+ }
\relative c' {
- <
- c-\footnote "1" #'(1 . -1.25) "1. C"
- es-\footnote
- \markup { \bold "b" } #'(2 . -0.25) "b. E-flat"
- g-\footnote "3" #'(2 . 3) \markup { \italic "iii. G" }
- >1
+ a'4 b8 e c4 d
}
}
@end lilypond
-@warning {When footnotes have the same vertical position, the footnotes
-are printed in order of descendancy; the higher the footnote, the
-higher up in the list.}
+@subsubsubheading Footnotes in stand-alone text with custom marks
+
+The syntax of a footnote in stand-alone text with custom marks is
+
+@example
+\markup @{ ... \footnote @var{mark} @var{footnote} ... @}
+@end example
-Here are some examples of manually footnoted grobs, also showing
-the relative position of the footnotes to the tagline and copyright
+The elements are:
+
+@table @var
+
+@item mark
+is a markup or string specifying the footnote mark which is used for
+marking the reference point. Note that this mark is @emph{not}
+inserted automatically before the footnote itself.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the
+bottom of the page, preceded by the @var{mark}.
+
+@end table
+
+Any easy-to-type character such as * or + may be used as a mark, as
+shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
+aliases may be used (see @ref{ASCII aliases}):
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\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 † \concat {
+ \super † \italic " Aug 2012"
+ }
+ "composition."
+ }
\relative c' {
- \footnote
- \markup { \teeny 1 } #'(-3 . 0) #'DynamicText
- \markup { 1. \bold Forte }
-
- \footnote
- \markup { \teeny b } #'(0 . 1.5) #'Slur
- \markup { b. A slur }
- a'4\f(
-
- \footnote
- \markup { \teeny 3 } #'(0 . -2) #'Beam
- \markup { 3. Beam }
- b8)[ e]
-
- \footnote
- \markup { 4 } #'(1 . -1) #'Stem
- \markup { \bold 4. { This is a stem } }
- c4
-
- \footnote
- \markup \concat \teeny { "sharp (v)" }
- #'(0 . 0.5) #'AccidentalCautionary
- \markup \italic { v. A cautionary accidental }
-
- \footnote
- \markup \concat \teeny { "a" } #'(0.5 . -0.5) #'TextScript
- \markup \italic { a. Slow Down }
- dis?4_"rit."
-
- \breathe
- \footnote
- \markup { \teeny \musicglyph #"rests.4" }
- #'(1.5 . -0.25) #'BreathingSign
- \markup { \null }
+ a'4 b8 e c4 d
}
}
@end lilypond
-To manually footnote a top-level @code{\markup}:
+Unicode character codes may also be used to specify marks
+(see @ref{Unicode}):
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
\header { tagline = ##f }
- \markup { "A simple tune" \footnote "*" \italic "* By me" }
+ \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 c' {
- a'4 b8 e c4 d4
+ a'4 b8 e c4 d
}
}
@end lilypond
@rlearning{Objects and interfaces}.
Notation Reference:
+@ref{ASCII aliases},
@ref{Balloon help},
-@ref{Page layout},
+@ref{List of special characters},
@ref{Text marks},
@ref{Text scripts},
-@ref{Titles and headers}.
+@ref{Unicode}.
Internals Reference:
@rinternals{FootnoteEvent},
@rinternals{Footnote_engraver}.
@knownissues
-Multiple footnotes for the same page can only be stacked, one on top of
-the other, and cannot be printed on the same line. Footnotes cannot be
-attached to @code{MultiMeasureRests} and may collide with @code{Staff},
-@code{\markup} objects and other @code{footnote} annotations. When
-using any manual @code{footnote} command a @code{\paper} block
-containing @code{footnote-auto-number = ##f} is required.
+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 @code{MultiMeasureRests} or
+automatic beams or lyrics.
+
+Footnote marks may collide with staves, @code{\markup} objects, other
+footnote marks and annotation lines.
@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]
+@lilypond[verbatim,papersize=a8landscape]
\header { tagline = ##f }
\book {
\label #'firstScore
(add-toc-item! 'tocActMarkup text))
@end verbatim
-@lilypond[line-width=11.0\cm]
+@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
tocActMarkup = \markup \large \column {
Dots can be added to fill the line between an item and its page number:
-@lilypond[verbatim,quote]
+@lilypond[verbatim,line-width=10.0\cm]
\header { tagline = ##f }
\paper {
tocItemMarkup = \tocItemWithDotsMarkup
}
@end lilypond
-
@seealso
-Init files: @file{../ly/toc-init.ly}.
-
+Installed Files:
+@file{ly/toc-init.ly}.
@predefined
@funindex \table-of-contents
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
not the directory containing the included file. However,
-this behavior can be changed by passing the option
+this behavior can be changed globally by passing the option
@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
-at the top of the main input file). With @code{relative-includes}
-set, the path for each @code{\include} command will be taken
-relative to the file containing that command. This behavior is
-recommended and it will become the default behavior in a future
-version of lilypond.
+at the top of the main input file).
+
+When @code{relative-includes} is set to @code{#t}, the path for each
+@code{\include} command will be taken relative to the file containing
+that command. This behavior is recommended and it will become the
+default behavior in a future version of lilypond.
+
+Files relative to the main directory and files relative to some other
+directory may both be @code{\include}d by setting
+@code{relative-includes} to @code{#t} or @code{#f} at appropriate
+places in the files. For example, if a general library, libA, has
+been created which itself uses sub-files which are @code{\include}d
+by the entry file of that library, those @code{\include} statements
+will need to be preceded by
+@code{#(ly:set-option #relative-includes #t)} so they are interpreted
+correctly when brought into the main @code{.ly} file, like this:
+
+@example
+libA/
+ libA.ly
+ A1.ly
+ A2.ly
+ ...
+@end example
+
+@noindent
+then the entry file, @code{libA.ly}, will contain
+
+@example
+#(ly:set-option 'relative-includes #t)
+\include "A1.ly"
+\include "A2.ly"
+...
+% return to default setting
+#(ly:set-option 'relative-includes #f)
+@end example
+
+Any @file{.ly} file can then include the entire library simply with
+
+@example
+\include "~/libA/libA.ly"
+@end example
+
+More complex file structures may be devised by switching at
+appropriate places.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
@headitem Filter
@tab Result
@item
-Tagged music preceded by @code{\keepWithTag #'@var{name}}
- @tab Untagged music and music tagged with @var{name} is included;
- music tagged with any other tag name is excluded.
+Tagged music preceded by @code{\keepWithTag #'@var{name}} or
+ @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music tagged with any of the given tag
+ names is included;
+ music tagged with any other tag name is excluded.
@item
-Tagged music preceded by @code{\removeWithTag #'@var{name}}
-@tab Untagged music and music tagged with any tag name other than
- @var{name} is included; music tagged with @var{name} is
+Tagged music preceded by @code{\removeWithTag #'@var{name}} or
+ @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music not tagged with any of the given tag names
+ is included; music tagged with any of the given tag names is
excluded.
@item
Tagged music not preceded by either @code{\keepWithTag} or
@end example
Multiple tags may be placed on expressions with multiple
-@code{\tag} entries:
+@code{\tag} entries, or by combining multiple tags into one symbol
+list:
@lilypond[quote,verbatim]
music = \relative c'' {
\tag #'a \tag #'both { a4 a a a }
- \tag #'b \tag #'both { b4 b b b }
+ \tag #'(b both) { b4 b b b }
}
<<
\keepWithTag #'a \music
@end lilypond
Multiple @code{\removeWithTag} filters may be applied to a single
-music expression to remove several differently named tagged sections:
+music expression to remove several differently named tagged
+sections. Alternatively, you can use a single
+@code{\removeWithTag} with a list of tags.
@lilypond[verbatim,quote]
music = \relative c'' {
\removeWithTag #'B
\removeWithTag #'C
\music
+\removeWithTag #'(B C)
+\music
}
@end lilypond
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.
Sometimes you want to splice some music at a particular place in an
existing music expression. You can use @code{\pushToTag} and
@ref{Automatic part combining},
@ref{Including LilyPond files}.
-
-@ignore
-@c This warning is more general than this placement implies.
-@c Rests are not merged whether or not they come from tagged sections.
-@c Should be deleted? -td
-
@knownissues
+Calling @code{\relative} on a music expression obtained by filtering
+music through @code{\keepWithTag} or @code{\removeWithTag} might cause
+the octave relations to change, as only the pitches actually
+remaining in the filtered expression will be considered. Applying
+@code{\relative} first, before @code{\keepWithTag} or
+@code{\removeWithTag}, avoids this danger as @code{\relative} then
+acts on all the pitches as-input.
-Multiple rests are not merged if you create a score with more
-than one tagged section at the same place.
-
-@end ignore
@node Using global settings
@unnumberedsubsubsec Using global settings
Notation Reference:
@ref{Including LilyPond files}.
+
@node Special characters
@subsection Special characters
@file{ly/text-replacements.ly}.
-
@node Controlling output
@section Controlling output
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{Command line options for
-lilypond}.
+command line options, see
+@rprogram{Basic command line options for LilyPond}.
@node Replacing the notation font
reverse the process.
@seealso
-Learning Manual: @rlearning{Other sources of information}.
+Learning Manual:
+@rlearning{Other sources of information}.
@knownissues
Gonville cannot be used to typeset @q{Ancient Music} notation and it is
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
-Standard MIDI oputput is somewhat crude; optionally, an enhanced and
+Standard MIDI output is somewhat crude; optionally, an enhanced and
more realistic MIDI output is available by means of
@ref{The Articulate script}.
@menu
* Creating MIDI files::
+* MIDI Instruments::
* MIDI block::
* What goes into the MIDI output?::
* Repeats in MIDI::
@end example
-@unnumberedsubsubsec Instrument names
-
-@cindex instrument names
-@funindex Staff.midiInstrument
-
-The MIDI instrument to be used is specified by setting the
-@code{Staff.midiInstrument} property to the instrument name.
-The name should be chosen from the list in @ref{MIDI instruments}.
-
-@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{...notes...}
-@}
-@end example
-
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{...notes...}
-@}
-@end example
-
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
-
-
@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
output. Players that are known to work include MS Windows Media
Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+@node MIDI Instruments
+@subsection MIDI Instruments
+
+@cindex instrument names
+@cindex MIDI, instruments
+@funindex Staff.midiInstrument
+
+The MIDI instrument to be used is specified by setting the
+@code{Staff.midiInstrument} property to the instrument name.
+The name should be chosen from the list in @ref{MIDI instruments}.
+
+@example
+\new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{...notes...}
+@}
+@end example
+
+@example
+\new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{...notes...}
+@}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
@node MIDI block
@subsection MIDI block
@cindex MIDI block
@end example
In this example the tempo is set to 72 quarter note
-beats per minute. This kind of tempo specification cannot take
-a dotted note length as an argument. If one is required, break
-the dotted note into smaller units. For example, a tempo of 90
-dotted quarter notes per minute can be specified as 270 eighth
-notes per minute:
-
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
+beats per minute. @code{\tempo} is actually a music command for
+setting properties during the interpretation of music: in the
+context of output definitions like a @code{\midi} block, as a matter of
+courtesy those are reinterpreted as if they were context modifications.
@cindex MIDI context definitions
@c TODO Check grace notes - timing is suspect?
+@menu
+* Supported in MIDI::
+* Unsupported in MIDI::
+@end menu
+
+@node Supported in MIDI
@unnumberedsubsubsec Supported in MIDI
@cindex Pitches in MIDI
@end itemize
+@node Unsupported in MIDI
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
overall MIDI volume, the relative volume of dynamic markings and
the relative volume of different instruments.
+@menu
+* Dynamic marks::
+* Overall MIDI volume::
+* Equalizing different instruments (i)::
+* Equalizing different instruments (ii)::
+@end menu
+
+@node Dynamic marks
@unnumberedsubsubsec Dynamic marks
Dynamic marks are translated to a fixed fraction of the available
@file{../scm/midi.scm} and the associated table as a model.
The final example in this section shows how this might be done.
+@node Overall MIDI volume
@unnumberedsubsubsec Overall MIDI volume
The minimum and maximum overall volume of MIDI dynamic markings is
>>
\layout {}
\midi {
+ \tempo 2 = 72
\context {
\Score
- tempoWholesPerMinute = #(ly:make-moment 72 2)
midiMinimumVolume = #0.2
midiMaximumVolume = #0.5
}
}
@end lilypond
+@node Equalizing different instruments (i)
@unnumberedsubsubsec Equalizing different instruments (i)
If the minimum and maximum MIDI volume properties are set in
}
@end lilypond
+
+@node Equalizing different instruments (ii)
@unnumberedsubsubsec Equalizing different instruments (ii)
If the MIDI minimum and maximum volume properties are not set
projects / lilypond.git / blobdiff