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

[Carl . D . Sorensen]

I think it's much clearer than it was, which is a definite improvement.

I also think some simple rearranging could make it even more accessible
for the user.

Thanks,

Carl



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#newcode1040
Documentation/notation/input.itely:1040: affecting all grobs of a given
type at a particular time step.
I think that this paragraph (showing the distinction between grob
footnotes and moment footnotes [my terminology]) should include an
@lilypond for each of the footnote types.  A picture is worth a thousand
words.  Even though the syntax hasn't yet been explained, the
demonstration will be clearer than the description.

http://codereview.appspot.com/6195098/diff/4023/Documentation/notation/input.itely#newcode1077
Documentation/notation/input.itely:1077:
On 2012/05/17 18:20:33, dak wrote:
> 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 think (hope) that James meant @lilypond  examples work better; and as
David mentions, they are there farther down.

> > 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.


When a command takes multiple arguments (like the footnote command
does), it seems to be to be perfectly reasonable to provide a
description of the syntax, together with examples.

When I was working on a similar problem with autobeaming, I took the
approach David took -- explain the the full syntax of the command, and
then show examples.  One of the readers thought I had it backwards, and
I inverted the presentation.  In autobeaming, that made sense, because
one can do lots with autobeams without ever getting to the full syntax
of defining an autobeam rule.  I'm not sure the same is true of
footnotes.

However, if there is a simple application of footnotes that will likely
be used most often, it might be preferable to have the overview just
mention that there are two types of footnotes, and describe the fact
that automatic footnotes will be marked with numbers that increase
throughout the score (or page, or book, or whatever the appropriate
scope is), as well as mentioning that manual footnotes let the user
choose the mark identifying the footnote.   Then have the automatic
footnotes largely as-is, and put the description of the manual footnote
syntax into the manual footnote section.

It might even be more digestible for non-programmers to introduce *two*
automatic footnote commands:  a three-argument form that will be the
general default, and a four-argument form that is a special case when a
particular grob is to be footnoted.  I realize that the four-argument
form with an optional second argument includes the three-argument form,
but there will be some who would rather have the simpler pattern and
never have to consider the optional argument.

http://codereview.appspot.com/6195098/