Re: Doc: Clarify footnotes as articulations (2971) (issue 6845078)

[tdanielsmusic]

Reviewers: dak,


http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.itely
File Documentation/notation/input.itely (right):

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.itely#newcode1250
Documentation/notation/input.itely:1250: address@hidden \footnote
address@hidden @var{offset} @var{footnote} @var{music}
On 2012/11/22 09:39:54, dak wrote:
> It is not really a "further form", and if you consider it a "further
form", the
> @var{direction} would not be optional.

Of course - I forgot to remove the brackets.

> This is a syntactic wart slated to go away eventually

OK, but for now we need to document the current behaviour.

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.itely#newcode1333
Documentation/notation/input.itely:1333: both a grob-name and a
direction indicator will generate an error.}
On 2012/11/22 09:39:54, dak wrote:
> This warning is extremely misleading since footnotes with a grob-name
are never
> attached to anything in the music but rather to a moment of time.

> @warning {If you use a grob specification, the footnote affects
everything at
> the current time step like @code{\once \override} would.  Just like an
override,
> it has to occur between @emph{complete} rhythmic events without a
directional
> modifier of its own and will affect all grobs produced by the
following event,
> whether caused by the basic event or one of its articulations.}

With this understanding rather more invasive changes
are needed to present an absolutely accurate description.
That's always the problem when you try to explain rather
than just showing what to do, especially with a messy
interface like this one.  I'll need to think about
this further.  I might chop the explanations - users in
general don't need this level of understanding.

Description:
Doc: Clarify footnotes as articulations (2971)

  Footnotes don't work as articulations on
  indirectly created grobs.

Please review this at http://codereview.appspot.com/6845078/

Affected files:
  M Documentation/notation/input.itely


Index: Documentation/notation/input.itely
diff --git a/Documentation/notation/input.itely  
b/Documentation/notation/input.itely
index  
9de53e0190021d7f8477798da0f5e9484c0a3648..e3f6b26bada95c7bafabc9cba18d0bac0b65b3a2  
100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -1236,11 +1236,18 @@ annotating such layout objects without referring to  
an event.

 @end table

-The full form of a footnote command for both Event- and Time-based
-footnotes is
+The main form of the footnote command may be used for both Event- and
+Time-based footnotes:

 @example
address@hidden \footnote address@hidden @var{offset} address@hidden  
@var{footnote} @var{music}
+\footnote address@hidden @var{offset} address@hidden @var{footnote}  
@var{music}
address@hidden example
+
+A further form is available for attaching footnotes to articulations
+or post-events:
+
address@hidden
address@hidden \footnote address@hidden @var{offset} @var{footnote}  
@var{music}
 @end example

 The elements are:
@@ -1321,6 +1328,10 @@ 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.

address@hidden {Footnotes cannot be attached to indirectly created grobs
+when using this form of the footnote command.  Attempts to specify
+both a grob-name and a direction indicator will generate an error.}
+
 @lilypond[quote,verbatim,papersize=a8landscape]
 \book {
   \header { tagline = ##f }