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/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
