Index: Documentation/notation/input.itely |
diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely |
index a162c0ecce7326429288388e47b2380b6312d69f..beff141bda7c159c2c69f09394a9f81e4dc24fc9 100644 |
--- a/Documentation/notation/input.itely |
+++ b/Documentation/notation/input.itely |
@@ -519,6 +519,7 @@ some pieces include a lot more information. |
@menu |
* Creating titles headers and footers:: |
* Custom headers footers and titles:: |
+* Creating footnotes:: |
* Reference to page numbers:: |
* Table of contents:: |
@end menu |
@@ -1013,6 +1014,215 @@ Notation Reference: |
@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 default superscript numbers which indicate |
+the footnote at the bottom of the page, whereas manual footnotes allow a |
+custom indicator to be created instead. |
+ |
+@example |
+\autoFootnoteGrob #'@var{Layout Object} #'@var{(x . y)} |
+ \markup @{footnote@} |
+@end example |
+ |
+All grobs, top-level @code{\markup} and chorded notes can be annotated. |
+When annotating grobs, the command that you use must come @emph{before} |
+the grob that the footnote is being attached to. The order in which |
+each grob is drawn determines the order in which each footnote is |
+created during compilation. |
+ |
+Offset values of zero are taken from the center of the grob that is |
+being footnoted whereas negative and positive values are taken from the |
+@qq{bottom left} and @qq{top right} of the grob respectively. |
+ |
+@node Automatic footnotes |
+@unnumberedsubsubsec Automatic footnotes |
+ |
+The two commands used to create automatic footnotes are |
+@code{\autoFootnote} for chorded notes and @code{\autoFootnoteGrob} for |
+individual grobs (i.e. note heads, stems and slurs) including |
+@code{\markup} when using @code{TextScripts}. |
+ |
+To annotate chorded notes: |
+ |
+@lilypond[verbatim,quote,ragged-right,papersize=a8] |
+\book { |
+ \header { tagline = ##f } |
+ \relative c' { |
+ < |
+ c-\autoFootnote #'(1 . -1.25) "This is a C" |
+ es-\autoFootnote #'(2 . -0.25) \markup \italic "Here is an E-flat" |
+ g-\autoFootnote #'(2 . 3) \markup \bold "This is a G" |
+ >1 |
+ } |
+} |
+@end lilypond |
+ |
+Here is an example of a variety of automatically footnoted grobs showing |
+the relative position of the footnotes to the default tagline and the |
+copyright line. |
+ |
+@lilypond[verbatim,quote,ragged-right,papersize=a8] |
+\book { |
+ \header { copyright = \markup { "Copyright 1970" } } |
+ \relative c' { |
+ \autoFootnoteGrob #'DynamicText #'(-3 . 0) |
+ \markup { \bold Forte } |
+ |
+ \autoFootnoteGrob #'Slur #'(0 . 1.5) |
+ \markup { A slur } |
+ a'4\f( |
+ |
+ \autoFootnoteGrob #'Beam #'(0 . -2) |
+ \markup { Beam } |
+ b8)[ e] |
+ |
+ \autoFootnoteGrob #'Stem #'(1 . -1) |
+ \markup { \teeny { This is a stem } } |
+ c4 |
+ |
+ \autoFootnoteGrob #'AccidentalCautionary #'(0 . 0.5) |
+ \markup \italic { A cautionary accidental } |
+ \autoFootnoteGrob #'TextScript #'(0.5 . -0.5) |
+ \markup \italic { Slow Down } |
+ dis?4_"rit." |
+ } |
+} |
+@end lilypond |
+ |
+Automatic footnotes cannot be used for top-level @code{\markup}; in this |
+case use @ref{Manual footnotes}. |
+ |
+@node Manual footnotes |
+@unnumberedsubsubsec Manual footnotes |
+ |
+@funindex \footnote |
+@funindex \footnoteGrob |
+@cindex footnotes, manual |
+ |
+There are two commands used to create manual footnotes; @code{\footnote} |
+for top-level @code{\markup} and chorded notes, and @code{\footnoteGrob} |
+for individual grobs (including @code{\markup} when using |
+@code{TextScripts}). |
+ |
+@example |
+\footnote @var{indicator} @var{footnote} |
+@end example |
+ |
+This example shows how to manually footnote top-level markups; |
+ |
+@lilypond[verbatim,quote,ragged-right,papersize=a8] |
+\book { |
+ \markup { |
+ \bold \italic { Andante } |
+ \footnote \super 1 "At walking pace" |
+ } |
+ \relative c' { |
+ a'4\f( b8)[ e] c4_"rit." dis?4 |
+ \breathe |
+ } |
+} |
+@end lilypond |
+ |
+To annotate chorded notes; |
+ |
+@lilypond[verbatim,quote,ragged-right,papersize=a8] |
+\book { |
+ \header { tagline = ##f } |
+ \relative c' { |
+ < |
+ c-\footnote #'(1 . -1.25) \markup "1" "1. C" |
+ es-\footnote #'(2 . -0.25) \markup "2" "2. E-flat" |
+ g-\footnote #'(2 . 3) \markup "3" "3. G" |
+ >1 |
+ } |
+} |
+@end lilypond |
+ |
+@example |
+\footnoteGrob #'@var{Layout Object} #'@var{(x . y)} |
+ \markup @{indicator@} \markup @{footnote@} |
+@end example |
+ |
+Here is an example of a variety of manually footnoted grobs; |
+ |
+@lilypond[verbatim,quote,ragged-right,papersize=a8] |
+\book { |
+ \header { tagline = ##f } |
+ \relative c' { |
+ \footnoteGrob #'DynamicText #'(-3 . 0) |
+ \markup { \teeny 1 } |
+ \markup { 1. \bold Forte } |
+ |
+ \footnoteGrob #'Slur #'(0 . 1.5) |
+ \markup { \teeny b } |
+ \markup { b. A slur } |
+ a'4\f( |
+ |
+ \footnoteGrob #'Beam #'(0 . -2) |
+ \markup { \teeny 3 } |
+ \markup { 3. Beam } |
+ b8)[ e] |
+ |
+ \footnoteGrob #'Stem #'(1 . -1) |
+ \markup { \teeny 4 } |
+ \markup { 4. \teeny { This is a stem } } |
+ c4 |
+ |
+ \footnoteGrob #'AccidentalCautionary #'(0 . 0.5) |
+ \markup \concat \teeny { "sharp (v)" } |
+ \markup \italic { v. A cautionary accidental } |
+ \footnoteGrob #'TextScript #'(0.5 . -0.5) |
+ \markup \concat \teeny { "a" } |
+ \markup \italic { a. Slow Down } |
+ dis?4_"rit." |
+ |
+ \breathe |
+ \footnoteGrob #'BreathingSign #'(1.5 . -0.25) |
+ \markup { \teeny \musicglyph #"rests.4" } |
+ \markup { \null } |
+ } |
+} |
+@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 staff, markup |
+objects and even other footnote annotations. When using any manual |
+footnote command a @code{@bs{}paper} block containing |
+@code{footnote-auto-number = ##f} is required. |
+ |
@node Reference to page numbers |
@subsection Reference to page numbers |