From c20bed72fb602fabf67087649df283f1978a9d94 Mon Sep 17 00:00:00 2001
From: David Kastrup <dak@gnu.org>
Date: Thu, 17 May 2012 16:08:33 +0200
Subject: [PATCH] Manual changes to documentation and regtests for footnotes.

---
 Documentation/notation/input.itely            | 189 ++++++++++--------
 .../footnote-auto-numbering-page-reset.ly     |   7 +-
 .../footnote-auto-numbering-vertical-order.ly |  42 ++--
 input/regression/footnote-auto-numbering.ly   |   7 +-
 input/regression/footnote-footer-padding.ly   |  14 +-
 input/regression/footnote-spanner.ly          |  14 +-
 input/regression/footnote.ly                  |  10 +-
 input/regression/in-note.ly                   |   3 +-
 8 files changed, 154 insertions(+), 132 deletions(-)

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 7c161ca2db..f05f0fafea 100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -1030,50 +1030,89 @@ footnotes and manual footnotes.
 @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.
+Automatic footnotes create incrementing numerical indicators and manual
+footnotes allow a custom indicator to be created instead.  Footnotes are
+normally applied like @code{\tweak} and consequently can be placed
+directly on grobs (graphical objects) created by most music elements and
+post-events.  In cases where this does not work (like with bar lines and
+meter changes, where the grobs are produced as a consequence of property
+changes), footnotes can also be specified as a standalone music event
+affecting all grobs of a given type at a particular time step.
 
-The order in which each grob is drawn determines the order in which each
-indicator and so footnotes are created during compilation.
+The full form of a footnote command is
 
+@example
+\footnote @var{mark} @var{offset} @var{grob-name} @var{footnote}
+@var{music}
+@end example
+
+The elements are as follows:
+
+@table @var
+@item mark
+is a markup or string specifying the footnote mark which is used for
+both marking the reference point as well as the footnote itself at the
+bottom of the page.  It can be omitted (or equivalently replaced with
+@code{\default}) in which case a number in sequence will be generated.
+@item offset
+is a number pair such as @samp{#(2 . 1)} specifying the X and Y offset
+from the reference point where the mark will be placed.
+@item grob-name
+specifies a type of grob to mark (like @samp{#'Flag}).  If it is given,
+the respective grob will be used as a reference point even in case that
+its @q{cause} is not the referenced @var{music} itself but a grob
+created from it.  It can be omitted (or replaced with @code{\default}),
+and then only a directly created grob will be annotated.
+@item footnote
+This markup or string specifies the footnote text to use at the bottom
+of the page.
+@item music
+This is the item, a music event or chord constituent or post-event, that
+is being annotated.  While it cannot be omitted, it @emph{can} be
+replaced by @code{\default} in which case the footnote is not attached
+to a music expression in particular, but rather to a moment of time.  It
+is mandatory in this case to use the @var{grob-name} argument for
+selecting an affected grob type, like @samp{#'TimeSignature}.
+@end table
+
+Like with @code{\tweak}, if your @code{\footnote} is applied to a
+post-event or articulation, it will itself have to be preceded with
+@code{-} to make the parser attach the result to the preceding note or
+rest.
 
 @node Automatic footnotes
 @unnumberedsubsubsec Automatic footnotes
 
-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.
-
-The command @code{\footnote} must come @emph{before} the grob that the
-footnote is being attached to:
+Automatic footnotes take four arguments: the @samp{(x . y)} position of
+the indicator, the optional @var{grob-name} specifying the layout object
+to be annotated, the @var{footnote} markup itself that will appear at
+the bottom of the page, and of course the @var{music} to attach the
+footnote to.
 
 @lilypond[verbatim,quote,ragged-right,papersize=a8]
 \book {
   \header { tagline = ##f }
   \relative c' {
-    \footnote #'(0.5 . -2) #'NoteHead
-      \markup { The first note } \default
+    \footnote #'(0.5 . -2)
+      \markup { The first note }
     a'4 b8
-    \footnote #'(0.5 . 1) #'NoteHead
-      \markup { The third note } \default
-    e c4 d4
+    \footnote #'(0.5 . 1) #'Flag
+      \markup { The third note }
+    e\noBeam 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}:
+Chorded notes pose no particular difficulty:
 
 @lilypond[verbatim,quote,ragged-right,papersize=a8]
 \book {
   \header { tagline = ##f }
   \relative c' {
     <
-    c-\footnote #'(1 . -1.25) "Here is a C" \default
-    es-\footnote #'(2 . -0.25) \markup { \italic "An E-flat" } \default
-    g-\footnote #'(2 . 3) \markup { \bold "This is a G" } \default
+    \footnote #'(1 . -1.25) "Here is a C" c
+    \footnote #'(2 . -0.25) \markup { \italic "An E-flat" } es
+    \footnote #'(2 . 3) \markup { \bold "This is a G" } g
     >1
   }
 }
@@ -1090,27 +1129,17 @@ relative position of the footnotes to the tagline and copyright.
 \book {
   \header { copyright = \markup { "Copyright 1970" } }
   \relative c' {
-    \footnote #'(-3 . 0) #'DynamicText
-      \markup { \bold Forte } \default
-
-    \footnote #'(0 . 1.5) #'Slur
-      \markup { A slur } \default
-    a'4\f(
-
-    \footnote #'(0 . -2) #'Beam
-      \markup { Beam } \default
-    b8)[ e]
-
+    a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
+    -\footnote #'(0 . 1.5) \markup { A slur } (
+    b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
     \footnote #'(1 . -1) #'Stem
-      \markup  { \teeny { This is a stem } } \default
+      \markup  { \teeny { This is a stem } }
     c4
-
     \footnote #'(0 . 0.5) #'AccidentalCautionary
-      \markup \italic { A cautionary accidental } \default
-
-    \footnote #'(0.5 . -0.5) #'TextScript
-      \markup \italic { Slow Down } \default
-    dis?4_"rit."
+      \markup \italic { A cautionary accidental }
+    \footnote #'(1 . 1) "The note itself"
+    dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
+         _"rit."
   }
 }
 @end lilypond
@@ -1134,26 +1163,31 @@ required:
 
 @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.
+Manually marked footnotes take an additional first markup argument
+@var{mark} for making the reference mark.  In contrast to automatically
+generated footnote marks, they will not appear before the @var{footnote}
+markup at the bottom of the page: establishing the visual connection is
+left to the user.  LilyPond will only make sure that the corresponding
+markup appears on the bottom of the same page.
 
-Like automatic footnotes, manual @code{\footnote} commands must come
-@emph{before} the grob that the footnote is annotating and attached as a
-@code{TextScript}:
+Other than that, the use is identical to that of automatically numbered
+footnotes.
 
 @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" } \default
+    \footnote
+          "1" #'(0.5 . -2)
+          \markup { \italic "1. The first note" }
+    a'4
     b8
-    e-\footnote
-          \markup { \bold "2" } #'(0.5 . 1) #'NoteHead "2. The second note" \default
+    \footnote
+          \markup { \bold "2" } #'(0.5 . 1)
+          "2. The second note"
+    e
     c4
-    d\p-\footnote "3" #'(0.5 . -1) #'DynamicText "3. Piano" \default
+    d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
   }
 }
 @end lilypond
@@ -1165,10 +1199,10 @@ To annotate chorded notes with manual footnotes:
   \header { tagline = ##f }
   \relative c' {
     <
-    c-\footnote "1" #'(1 . -1.25) "1. C" \default
-    es-\footnote
-       \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" \default
-    g-\footnote "3" #'(2 . 3) \markup { \italic "iii. G" } \default
+    \footnote "1" #'(1 . -1.25) "1. C" c
+    \footnote
+       \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
+    \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
     >1
   }
 }
@@ -1185,40 +1219,31 @@ the relative position of the footnotes to the tagline and copyright
 \book {
   \header { tagline = ##f }
   \relative c' {
-    \footnote
-      \markup { \teeny 1 } #'(-3 . 0) #'DynamicText
-      \markup { 1. \bold Forte } \default
-
-    \footnote
-      \markup { \teeny b } #'(0 . 1.5) #'Slur
-      \markup { b. A slur } \default
-    a'4\f(
-
-    \footnote
-      \markup { \teeny 3 } #'(0 . -2) #'Beam
-      \markup { 3. Beam } \default
-    b8)[ e]
-
+    a'4-\footnote
+      \markup { \teeny 1 } #'(-3 . 0)
+      \markup { 1. \bold Forte } \f
+    -\footnote
+      \markup { \teeny b } #'(0 . 1.5)
+      \markup { b. A slur } (
+    b8)-\footnote
+      \markup { \teeny 3 } #'(0 . -2)
+      \markup { 3. Beam } [
+    e]
     \footnote
       \markup { 4 } #'(1 . -1) #'Stem
-      \markup  { \bold 4. { This is a stem } } \default
+      \markup  { \bold 4. { This is a stem } }
     c4
-
     \footnote
       \markup \concat \teeny { "sharp (v)" }
           #'(0 . 0.5) #'AccidentalCautionary
-      \markup \italic { v. A cautionary accidental } \default
-
-    \footnote
-      \markup \concat \teeny { "a" } #'(0.5 . -0.5) #'TextScript
-      \markup \italic { a. Slow Down } \default
-    dis?4_"rit."
-
-    \breathe
+      \markup \italic { v. A cautionary accidental }
+    dis?4-\footnote
+      \markup \concat \teeny { "a" } #'(0.5 . -0.5)
+      \markup \italic { a. Slow Down } _"rit."
     \footnote
       \markup { \teeny \musicglyph #"rests.4" }
-          #'(1.5 . -0.25) #'BreathingSign
-      \markup { \null } \default
+          #'(1.5 . -0.25)
+      \markup { \null } \breathe
   }
 }
 @end lilypond
diff --git a/input/regression/footnote-auto-numbering-page-reset.ly b/input/regression/footnote-auto-numbering-page-reset.ly
index ae48d86ef5..45a41fe716 100644
--- a/input/regression/footnote-auto-numbering-page-reset.ly
+++ b/input/regression/footnote-auto-numbering-page-reset.ly
@@ -35,10 +35,9 @@ a b c d }
 
 \relative c' {
   d4 e
-  < f  a-\footnote #'(1 . -1) \markup { n } \default c >
-  \footnote #'(1 . 1) #'Beam \markup { o } \default
-  \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-  a8\< [ b c d ] a4 b c |
+  < f  \footnote #'(1 . -1) \markup { n } a c >
+  a8-\footnote #'(1 . 1) \markup { p } \<
+  -\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c |
   d a b c |
   d a b c |
   d a b c\f |
diff --git a/input/regression/footnote-auto-numbering-vertical-order.ly b/input/regression/footnote-auto-numbering-vertical-order.ly
index a7eaa23dd2..462858b122 100644
--- a/input/regression/footnote-auto-numbering-vertical-order.ly
+++ b/input/regression/footnote-auto-numbering-vertical-order.ly
@@ -32,64 +32,58 @@ in the correct vertical order.
         d4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 0))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 2 4)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c\f |
+        a8-\footnote #'(1 . 1) \markup { p } \<
+	-\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c\f |
         d a b c |\break
         d,4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 6))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 8 10)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c |
+        a8-\footnote #'(1 . 1) \markup { p } \<
+	-\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c |
         d a b c\f |\pageBreak
         d,4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 12))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f  \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 14 16)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c |
+        a8-\footnote #'(1 . 1) \markup { p } \<
+	-\footnote #'(1 . 1) #'Beam \markup { o } [ b c d ] a4 b c |
         d a b c\! |\break
       }
       \new Staff \relative c' {
         d4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 1))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 3 5)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c\f |
+        a8-\footnote #'(1 . 1) #'Hairpin \markup { p } \<
+	-\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c\f |
         d a b c |\break
         d,4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 7))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 9 11)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c |
+        a8-\footnote #'(1 . 1) \markup { p } \<
+	-\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c |
         d a b c\f |\pageBreak
         d,4 e
         \once \override FootnoteItem #'numbering-assertion-function =
           #(lambda (grob) (make-footnote-numbering-assertion-function 13))
-        < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+        < f \footnote #'(1 . -1) \markup { n } a c >
         \once \override FootnoteSpanner #'numbering-assertion-function =
           #(simultaneous-footnote-numbering-assertion-function 15 17)
-        \footnote #'(1 . 1) #'Beam \markup { o } \default
-        \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-        a8\< [ b c d ] a4 b c |
+        a8-\footnote #'(1 . 1) #'Hairpin \markup { p } \<
+	-\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c |
         d a b c\! |\break
       }
     >>
diff --git a/input/regression/footnote-auto-numbering.ly b/input/regression/footnote-auto-numbering.ly
index 4d08f2e57e..1d60c5e89b 100644
--- a/input/regression/footnote-auto-numbering.ly
+++ b/input/regression/footnote-auto-numbering.ly
@@ -54,12 +54,11 @@ footnotes.
   d4 e
   \once \override FootnoteItem #'numbering-assertion-function =
     #(lambda (grob) (make-footnote-numbering-assertion-function 5))
-  < f  a-\footnote #'(1 . -1) \markup { n } \default c >
+  < f \footnote #'(1 . -1) \markup { n } a c >
   \once \override FootnoteSpanner #'numbering-assertion-function =
     #(simultaneous-footnote-numbering-assertion-function 6 7)
-  \footnote #'(1 . 1) #'Beam \markup { o } \default
-  \footnote #'(1 . 1) #'Hairpin \markup { p } \default
-  a8\< [ b c d ] a4 b c |
+  a8-\footnote #'(1 . 1) \markup { p } \<
+  -\footnote #'(1 . 1) \markup { o } [ b c d ] a4 b c |
   d a b c |
   d a b c |
   d a b c\f |
diff --git a/input/regression/footnote-footer-padding.ly b/input/regression/footnote-footer-padding.ly
index 43970a6b11..2af561c42c 100644
--- a/input/regression/footnote-footer-padding.ly
+++ b/input/regression/footnote-footer-padding.ly
@@ -3,6 +3,8 @@
   texidoc = "The padding between a footnote and the footer can be tweaked."
 }
 
+% TODO: then why isn't it tweaked?
+
 #(set-default-paper-size "a6")
 
 \book {
@@ -10,19 +12,19 @@
   \relative c' {
     \footnote
                   \markup { \tiny 1 }
-                  #'(1 . -1) #'NoteHead
-                  \markup { 1. Tiny space below. } \default
+                  #'(1 . -1)
+                  \markup { 1. Tiny space below. }
     e1
 
     \footnote
                   \markup { \tiny 2 }
-                  #'(1 . -1) #'NoteHead
-                  \markup { 2. Tiny space below. } \default
+                  #'(1 . -1)
+                  \markup { 2. Tiny space below. }
     e1
 
     \footnote
                   \markup { \tiny 3 }
-                  #'(1 . -1) #'NoteHead
-                  \markup { 3. Big space below. } \default
+                  #'(1 . -1)
+                  \markup { 3. Big space below. }
     e1
 }}
diff --git a/input/regression/footnote-spanner.ly b/input/regression/footnote-spanner.ly
index 3d0705ebdb..7897f784f7 100644
--- a/input/regression/footnote-spanner.ly
+++ b/input/regression/footnote-spanner.ly
@@ -13,11 +13,12 @@ annotation goes to the correct page."
 \book {
 
 \relative c'' {
-\footnote
+b4-\footnote
               \markup { \tiny "1." }
               #'(0.5 . 0.5) #'Hairpin
-              \markup { 1. \justify { Goes to the first broken spanner. } } \default
-b4\< c d a
+              \markup { 1. \justify { Goes to the first broken spanner. } }
+   \<
+c d a
 b c d a
 b c d a
 b c d a
@@ -37,11 +38,12 @@ b c d a
 b c d a\!
 
 \once \override FootnoteSpanner #'spanner-placement = #RIGHT
-\footnote
+b4-\footnote
               \markup { \tiny "2." }
               #'(0.5 . 0.5) #'Hairpin
-              \markup { 2. \justify { Goes to the last broken spanner. } } \default
-b4\< c d a
+              \markup { 2. \justify { Goes to the last broken spanner. } }
+   \<
+c d a
 b c d a
 b c d a
 b c d a
diff --git a/input/regression/footnote.ly b/input/regression/footnote.ly
index 4d6e2ab9a5..88e0d2c952 100644
--- a/input/regression/footnote.ly
+++ b/input/regression/footnote.ly
@@ -15,7 +15,7 @@
 \markup { h i }
 
 \relative c' {
-\footnote \markup { \tiny 4 } #'(1 . -1) #'NoteHead \markup { 4. j } \default
+\footnote \markup { \tiny 4 } #'(1 . -1) \markup { 4. j }
 a b c d }
 
 \pageBreak
@@ -26,8 +26,8 @@ a b c d }
 
 \relative c' {
   d4 e
-  < f  a-\footnote \markup { \tiny 6 } #'(1 . -1) \markup { 6. n } \default c >
-  \footnote \markup { \tiny 7 } #'(1 . 1) #'Beam \markup { 7. o } \default
-  \footnote \markup { \tiny 8 } #'(1 . 1) #'Hairpin \markup { 8. p } \default
-  a8\< [ b c d\f ] r2. |
+  < f \footnote \markup { \tiny 6 } #'(1 . -1) \markup { 6. n } a c >
+  a8-\footnote \markup { \tiny 8 } #'(1 . 1) \markup { 8. p } \<
+  -\footnote \markup { \tiny 7 } #'(1 . 1) \markup { 7. o }
+  [ b c d\f ] r2. |
 }}
diff --git a/input/regression/in-note.ly b/input/regression/in-note.ly
index 6aeab18cd0..c8e4a03d68 100644
--- a/input/regression/in-note.ly
+++ b/input/regression/in-note.ly
@@ -11,7 +11,8 @@
     \repeat unfold 5 {
       \once \override FootnoteItem #'footnote = ##f
       \footnote
-                    "" #'(0 . 0) #'NoteHead \markup { \box \fill-line { "this is a test" } } \default
+         "" #'(0 . 0) #'NoteHead
+         \markup { \box \fill-line { "this is a test" } } \default
       \repeat unfold 5 { a\< b c d\! }
       \footnote #'(-1 . 1) #'NoteHead "foobar" \default
       \repeat unfold 5 { a\< b c d\! }
-- 
2.39.2