Re: Make \footnote work via \tweak (issue 6195098)

[dak]

Reviewers: J_lowe,


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

http://codereview.appspot.com/6195098/diff/4023/Documentation/notation/input.itely#newcode1077
Documentation/notation/input.itely:1077:
On 2012/05/17 17:53:17, J_lowe wrote:
> I'm not comfortable with tables/lists like this in the NR. Yes I am
sure it
> works for those that think like that, but for a user it's too
complicated.
> @examples work much better.

> I'm not disparaging the work you've done but from a documentation
point of view
> I think 'we' (royal or otherwise) can do better for users.

I have a hard time understanding what should be wrong with explaining
the arguments of the command one by one.  The actual examples follow,
and one can cross-check with the itemized overview.  What you propose is
omitting the complete and concise information, and forcing the user to
gather and deduce this information manually from the examples.

I don't see how this should be more helpful.

> If this were the Application Usage manual then sure, but not the NR.
Examples
> are much better.

The examples are _there_.

> I spent an age getting this right personally from a doc point of view
last week
> and I just don't think this is in the 'spirit' of the NR. Happy to get
another
> opinion.

I don't presume that I have made a good match for the 'spirit' of the
NR: I just have tried to make sure that the information is complete and
correct.

The interface to the functionality now is reasonably straightforward and
logical, and the description is reasonably complete.  For that reason, I
would strongly suggest that you start a rewrite from _this_ data point
instead of the previous state of the documentation, even if that means
that you have to rework the style into everything.  I think that is less
error-prone than if you rework the technical details into the previous
existing style.

> If you don;t mind (because I know how personal this <> stuff had
become) I can
> look at this part again over the weekend and use this to make a new
patch for
> the doc myself?

Sure.  But I would strongly suggest that the more technically inclined
readers do not have to go treasure-hunting through a heap of examples in
order to deduce the real deal.  It is ok if the heap of examples is
around for those who prefer that style.

Description:
Make \footnote work via \tweak


Allow Tweak_engraver to take a (grob.property) pair as tweak address


Revert "Merge branch 'footnote' into HEAD"

This reverts commit 2ec0cd55d55c49dee4e5604903dfab8ff4a089c4, reversing
changes made to 0a0274a3bf5792dfb7ce3719f5dfaef36059affe.



Those are the three commits currently making up this issue.  The music
function \footnote, in addition to the arguments it already takes, now
takes an additional music argument, either a chord constituent, or a
music event on its own, or a postevent (in which case, like \tweak,
you should invoke \footnote with an explicit event character - in
front of it).  The footnote is visible on any Grob directly caused by
the following event in the source code (the additional music
argument), unless a grob-name is specified, in which case it will
appear on any grob of that type _ultimately_ caused by the following
event (a Flag is directly caused by a NoteHead grob, but ultimately by
a NoteEvent).

I had been considering placing the anchoring Music event as first
argument of \footnote.  However, that makes for totally awful nesting
syntax in case you attach several footnotes to the same Music.

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

Affected files:
  M Documentation/de/notation/input.itely
  M Documentation/es/notation/input.itely
  M Documentation/fr/notation/input.itely
  M Documentation/ja/notation/input.itely
  M Documentation/notation/input.itely
  M input/regression/footnote-auto-numbering-page-reset.ly
  M input/regression/footnote-auto-numbering-vertical-order.ly
  M input/regression/footnote-auto-numbering.ly
  M input/regression/footnote-break-visibility.ly
  M input/regression/footnote-footer-padding.ly
  M input/regression/footnote-spanner.ly
  M input/regression/footnote.ly
  M input/regression/in-note.ly
  M lily/footnote-engraver.cc
  M lily/grob.cc
  M lily/parser.yy
  M lily/tweak-engraver.cc
  M ly/music-functions-init.ly
  M python/convertrules.py
  M scm/define-grob-properties.scm
  M scm/define-music-types.scm