Re: Footnote documentation error

[David Kastrup]

James <address@hidden> writes:

> Hello,
>
> On 20 April 2012 00:40, Nick Payne <address@hidden> wrote:
>> The documentation at
>> http://lilypond.org/doc/v2.15/Documentation/notation/creating-footnotes for
>> both automatic and manual footnotes says that the \footnote command must
>> come *before* the grob to which the footnote is being attached. This doesn't
>> seem to be the case. Here the \footnote commands are after the notes to
>> which they are attached, and they work fine:
>
> I think this was to do with David's additional work on Mike's a few
> months ago when what he did changed the requirement from the original
> footnote document in earlier versions of 2.15. We did re-write much of
> the examples and obviously missed this.
>
> Before I create a tracker, I'll wait for a confirmation from
> David/Mike that this is technically correct.

Well, I basically just changed the DOC strings from something that did
not make sense at all ("Use this like \tweak" or so) to something that
actually made a bit of sense and was somewhat related to the original
text.  I think I repeatedly stated that I had no clue whether the new
text was correct, but at least it was clear enough that people could
read it and complain if it was wrong, something which the previous text
was not really making possible, being total handwaving.

Variants of the previous texts are still in the DOC strings for balloon
helps.  Since I did not touch the _code_ of those _and_ I don't have a
clue about how they are supposed to work, I did not correct the DOC
strings there.  For the footnotes, I pulled the preexisting interfaces
into one new interface, and I _had_ to write a DOC string there.

I know that the new interface does the job of the various old
interfaces, and have been able to write nice convert-ly rules for them
in consequence.  But it was impossible to guess from the old DOC strings
(Mike basically said "oh, I just copied them over from the balloon
help") what the old footnote macros did.  I still had to write a new DOC
string.  Most certainly somebody actually _using_ those functions should
proofread them.  That's what our reviews are for.

-- 
David Kastrup