Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.15.25"
@node General input and output
@chapter General input and output
@menu
* Creating titles headers and footers::
* Custom headers footers and titles::
+* Creating footnotes::
* Reference to page numbers::
* Table of contents::
@end menu
@ref{Title blocks explained},
@ref{Default layout of book and score title blocks}.
+@node Creating footnotes
+@subsection Creating footnotes
+
+There are two types of footnotes that can be created; automatic
+footnotes and manual footnotes.
+
+@menu
+* Footnotes overview::
+* Automatic footnotes::
+* Manual footnotes::
+@end menu
+
+@node Footnotes overview
+@unnumberedsubsubsec Footnotes overview
+
+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.
+
+The order in which each grob is drawn determines the order in which each
+indicator and so footnotes are created during compilation.
+
+
+@node Automatic footnotes
+@unnumberedsubsubsec Automatic footnotes
+
+Automatic footnotes take three arguments; the @var{Layout Object} to be
+annotated, the @var{(x . y)} position of the indicator and a
+@code{\markup} that will appear in the footnote at the bottom of the
+page.
+
+The command @code{\footnote} must come @emph{before} the grob that the
+footnote is being attached to:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\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
+ }
+}
+@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}:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\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
+ }
+}
+@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.}
+
+Here are some more examples of footnoted grobs, also showing the
+relative position of the footnotes to the tagline and copyright.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\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(
+
+ \footnote #'(0 . -2) #'Beam
+ \markup { Beam }
+ b8)[ e]
+
+ \footnote #'(1 . -1) #'Stem
+ \markup { \teeny { This is a stem } }
+ c4
+
+ \footnote #'(0 . 0.5) #'AccidentalCautionary
+ \markup \italic { A cautionary accidental }
+
+ \footnote #'(0.5 . -0.5) #'TextScript
+ \markup \italic { Slow Down }
+ dis?4_"rit."
+ }
+}
+@end lilypond
+
+For top-level @code{\markup}, the @code{\auto-footnote} command is
+required:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup { \auto-footnote "A simple tune" \italic "By me" }
+ \relative c' {
+ a'4 b8 e c4 d
+ }
+}
+@end lilypond
+
+
+@node Manual footnotes
+@unnumberedsubsubsec Manual footnotes
+
+@cindex footnotes, manual
+
+Manual footnotes takes four arguments; the @var{Layout Object} to be
+annotated, the @var{(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.
+
+Like automatic footnotes, manual @code{\footnote} commands must come
+@emph{after} the grob that the footnote is annotating and attached as a
+@code{TextScript}:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ a'4-\footnote
+ "1" #'(0.5 . -2) #'NoteHead \markup { \italic "1. The first note" }
+ b8
+ e-\footnote
+ \markup { \bold "2" } #'(0.5 . 1) #'NoteHead "2. The second note"
+ c4
+ d\p-\footnote "3" #'(0.5 . -1) #'DynamicText "3. Piano"
+ }
+}
+@end lilypond
+
+To annotate chorded notes with manual footnotes:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \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
+ }
+}
+@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.}
+
+Here are some examples of manually footnoted grobs, also showing
+the relative position of the footnotes to the tagline and copyright
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \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 }
+ }
+}
+@end lilypond
+
+To manually footnote a top-level @code{\markup}:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+ \header { tagline = ##f }
+ \markup { "A simple tune" \footnote "*" \italic "* By me" }
+ \relative c' {
+ a'4 b8 e c4 d4
+ }
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{Objects and interfaces}.
+
+Notation Reference:
+@ref{Balloon help},
+@ref{Page layout},
+@ref{Text marks},
+@ref{Text scripts},
+@ref{Titles and headers}.
+
+Internals Reference:
+@rinternals{FootnoteEvent},
+@rinternals{FootnoteItem},
+@rinternals{FootnoteSpanner},
+@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.
+
@node Reference to page numbers
@subsection Reference to page numbers
@node Table of contents
@subsection Table of contents
-A table of contents is included using the @code{\markuplines \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.
@verbatim
-\markuplines \table-of-contents
+\markuplist \table-of-contents
\pageBreak
\tocItem \markup "First score"
(add-toc-item! 'tocActMarkup text))
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
\tocItem \markup { Cesare. Presti omai l'Egizzia terra }
}
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocItem \markup { Allegro }
\tocItem \markup { Largo }
\markup \null
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2011" \char ##x00A9 }
+\markup { "Copyright 2008--2012" \char ##x00A9 }
@end lilypond
@cindex copyright sign
more realistic MIDI output is available by means of
@ref{The Articulate script}.
-@c TODO Check this
-The midi output allocates a channel for each staff, and one for global
-settings. Therefore the midi file should not have more than 15 staves
-(or 14 if you do not use drums). Other staves will remain silent.
+The MIDI output allocates a channel for each staff, and reserves channel
+10 for drums. There are only 16 MIDI channels per device, so if the
+score contains more than 15 staves, MIDI channels will be reused.
@menu
* Creating MIDI files::
@funindex \displayLilyMusic
Displaying a music expression in LilyPond notation can be
-done with the music function @code{\displayLilyMusic} but only when
-using the command line. For example,
+done with the music function @code{\displayLilyMusic}. To see the
+output, you will typically want to call LilyPond using the command
+line. For example,
@example
@{
lilypond file.ly >display.txt
@end example
+@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:
+
+@example
+@{
+ \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
@node Displaying scheme music expressions
@subsection Displaying scheme music expressions
projects / lilypond.git / blobdiff