Re: Be more explicit about footnotes on chord constituents (issue 7038047)

[dak]

Reviewers: J_lowe, Trevor Daniels,

Message:
I hate it when I discover I had unpublished draft comments on an issue
that has been closed long ago.  I am flushing out these comments
nevertheless for the record so that reviewers don't think I ignored
their feedback (rather than being of different opinion on most points,
and having changed the text where I agree).

If it turns out that the disagreement was not satisfactorily addressed
by those comments, we can still put out another iteration.

Sorry.


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

https://codereview.appspot.com/7038047/diff/1/Documentation/notation/input.itely#newcode1338
Documentation/notation/input.itely:1338:
On 2013/01/02 12:51:05, J_lowe wrote:
> Hello, I'd rather put all this as an @KNOWNISSUE only because the
document
> should say what does work no[t] what doesn't (if you see what I mean).

It is not a "known issue" since everything works perfectly according to
design and intent, and so the user deserves to know what this design
entails.

It is not a side-effect or bug that you can't annotate a chord as a
whole, but entirely intentional.  As one consequence of this design, you
can put together a chord using parallel music, namely <<...>> (moving
durations and articulations inside) instead of <...>.

You don't need a chord construct in the input to hold notes together.

A "known issue" is something for cases where there would be good reason
for things to be different.

But there is, for example, no way where we could write
<<\tweak font-size #-3 <c e> <g a> >>
and ever have the font size tweak apply only to the first two notes and
not to the last two notes: all of them will be assembled into a single
chord.

https://codereview.appspot.com/7038047/diff/1/Documentation/notation/input.itely#newcode1403
Documentation/notation/input.itely:1403: footnote.  A @samp{NoteHead} is
the (only) grob directly caused
On 2013/01/02 12:51:05, J_lowe wrote:
> Don't see the point of the parenthesis here for '(only)' - I don't
think we need
> to pussy-foot here.

Fair 'nuff.  Will do, but does not warrant a new upload on its own.

https://codereview.appspot.com/7038047/diff/1/Documentation/notation/input.itely#newcode1422
Documentation/notation/input.itely:1422: ees fis
On 2013/01/02 12:51:05, J_lowe wrote:
> I know this wasn't a part of what you changed but Hmm...

> is this just semantics or are we including what is effectively a
'snippet' here
> by using \single (now that I understand single better - which is just
a
> collection of overrides), if \single didn't exist today would we do
this
> \footnote example by using \override and so break our
'kind-of-sort-of' rule for
> not using overrides in @lilypond examples.

> I.e move this whole example and the para you added as a snippet?

"\single" is not a "collection of overrides", it is a collection of
overrides (including a single override) converted into a collection of
tweaks.

It is somewhat wartish that you need to employ it for some special case
of footnote, but since that case is rather common, I don't think it
makes sense to ban it into snippets, like we also don't ban any example
making use of "\once\override" instead of just "\override" into
snippets.

Yes, our manuals are too large, but I don't think that removing this
usage (which incidentally was originally covered by a different syntax
getting along without \single) is worth the trouble caused by the
removal.  People are already having enough of a problem using footnotes
with confidence.

Description:
Be more explicit about footnotes on chord constituents

This tries to deal with the suggestions stemming from the
<URL:http://lists.gnu.org/archive/html/lilypond-user/2013-01/msg00021.html>
discussion.  It also rewords a bit of following documentation.

Please review this at https://codereview.appspot.com/7038047/

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  
238f90d450647d1743127c4e18190819e053755d..0954923c1bd1479ce585a5e9f65ece1745a53611  
100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -1320,6 +1320,22 @@ by the event corresponding to @var{music} with the  
syntax:
 }
 @end lilypond

+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:
+
address@hidden,verbatim,papersize=a8landscape]
+\book {
+  \header { tagline = ##f }
+  \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
+  }
+}
address@hidden lilypond
+
 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
@@ -1383,12 +1399,17 @@ will be attached to all grobs of that type at the  
current time step:
 }
 @end lilypond

-A chord constituent can be given an individual footnote.  A
address@hidden is the (only) grob directly caused from a chord
-constituent, so an Event-based footnote command should be used to
-add a footnote to a @code{NoteHead} within a chord.  All other
-grobs within a chord are indirectly caused and should be footnoted
-with a Time-based footnote command, prefixed with @code{\single}:
+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
address@hidden 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
address@hidden 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 {