Please DO NOT add issues directly to this tracker unless you are certain that they correspond to our preferred format.

Please keep attachments as small as possible. Google has a very small limit on the total size of attachments in the tracker. If you need to post a larger file (>50 kByte - really) please use a link.

Sorry about leaving the original text in the issue.

Documentation needs to be improved (shown, not told) as identified in Rietveld issue 6195098.

Documentation/changes.tely does not contain any hint regarding footnotes yet. I think that they have come after 2.14, so they should get some mention there as well.

The code for the footnote issues including the sub-standard but factually correct documentation has now been submitted to staging.

I just posted a reference to the footnote documentation and needed to consult the web search for finding it.

It is in http://lilypond.org/doc/v2.15/Documentation/notation/creating-footnotes> as part of the general page layout (header/footer etc).

In my opinion, that does not make sense (except for the layout variables concerned with the formatting and placement of the footnote text block). Instead, it belongs with http://lilypond.org/doc/v2.15/Documentation/notation/editorial-annotations>.

Does that sound reasonable?

I am currently in a rewrite of the footnote docs. This is going painfully slow since for one thing, writing text is much worse for an obsessor than code (there is something like optimal code to converge to and move on). For another, I am crafting examples that fit the text best, and in the process find out that they have a tendency not to match reality all that well. So I have to adapt reality, and that takes time.

I am taking ownership of this issue for now: while I had already communicated privately that I am doing some stuff in parallel with Carl, the extent of apparent inactivity might still look strange without notice.

Preliminary work on issue 2547

This is unfinished work for now. I think the node/chapter structure is good and educational, and the examples written up should be reasonably simple. There are blanks that still need to get filled in, and the old version (with rather extensive examples that might be a good attention grabber for the intro page) is commented out with @ignore for now since it might still get harvested for content.

The rewrite needs to get finished, but it turns out that I currently have writer's block about this and do a lot of things rather than continuing it. So I am offering this in its current state in case somebody (Carl) wants to pick up, in order to get productive on something else again.

I apologize for my somewhat haphazard working style, but nobody has anything to gain from myself deadlocking on an actually quite simple task.

http://codereview.appspot.com/6261048

Sigh. This was supposed to be "somebody (Carl?)". Namely putting out a suggestion (since you already worked on it previously) rather than what looks like bossing around. I am not in a position to do that.

Not even on my birthday.

I'm happy to pick this up, but I'd like to make a few changes to David's suggested patch. If people agree with these I'll make a new patch.

a) Because the syntax for text-based footnotes and those for music is so different I think the two should be quite separate. That would enable the general syntax of each to be presented first, in keeping with the rest of the manual.

b) It is easier to deal with the optional mark within the general text, rather than have a separate section for this.

c) Some of the explanation is too deep. In general users want to know /how/ to do something rather than understand /why/ it is done this way. Lengthening an already very long manual needs to be avoided if possible.

To these ends I propose the following alternative structure:

@subsection Creating footnotes @unnumberedsubsubsec Footnotes to music @subsubsubheading Music footnotes overview @subsubsubheading Event-based footnotes @subsubsubheading Time-based footnotes @unnumberedsubsubsec Footnotes to top-level text

The text will be drawn largely from David's patch, moved around to fit the new headings.

Views?

Trevor

Sounds like a plan. Feel free to go ahead, as far as I am concerned.

Build results are available at

http://grenouille.lilynet.net/patches-tests/2547/test-results

13:56:31 (UTC) Begin LilyPond compile, previous commit at 1cdcb2f73f35834fef5cbbc2a6647a11ae468f85 13:56:38 From git.savannah.gnu.org:/srv/git/lilypond 1cdcb2f..66a7c3e master -> master 13:56:49 Merged master, now at: 66a7c3e925cbc1a34eaad04f80d4bc42ad9834ac 13:56:51 Success: sudo -u lilybuild ./autogen.sh --noconfigure 13:57:28 Success: sudo -u lilybuild /home/lilybuild/master/configure --disable-optimising 13:57:38 Success: sudo -u lilybuild nice make clean 14:13:02 Success: sudo -u lilybuild nice make -j2 CPU_COUNT=2 ANTI_ALIAS_FACTOR=1 14:34:46 Success: sudo -u lilybuild nice make test-baseline -j2 CPU_COUNT=2 ANTI_ALIAS_FACTOR=1

00:18:44 Issue 2547: Fix documentation of making footnotes work via tweak. 00:18:44 Issue 2547: Testing patch issue6261048_1_diff 00:18:44 Success: sudo -u lilybuild git apply --index /home/jmandereau/lily-test-patches/issue6261048_1.diff 00:18:46 Success: sudo -u lilybuild ./autogen.sh --noconfigure 00:19:12 Success: sudo -u lilybuild /home/lilybuild/master/configure --disable-optimising 00:19:21 Success: sudo -u lilybuild nice make clean 00:34:47 Success: sudo -u lilybuild nice make -j2 CPU_COUNT=2 ANTI_ALIAS_FACTOR=1 00:57:29 Success: sudo -u lilybuild nice make check -j2 CPU_COUNT=2 ANTI_ALIAS_FACTOR=1

One of the examples in http://codereview.appspot.com/6261048 is \version "2.16.0" \book { \header { tagline = ##f } \relative c'' { < \footnote #'(-1 . -3) #'Accidental "Flat" aes c ees >4 \footnote #'(0 . -2) #'Beam "A beam" d8 d \footnote #'(-1 . 2) #'Stem "A stem" ees2 } } The line from the footnote mark to the beam does not connect to the actual beam. It seems to think it is extended further than it is. It's ironic that an example supposedly showing what footnote can do should demonstrate a bug.

Doc: improve footnote documentation (2547)

• clearer headings, separating footnotes in music expressions from those in stand-alone text

• distinguish Event- and Time-based footnotes (thanks David)

• explain how offsets are measured from grob boundary

• use examples that cover just single points for clarity

• explain how to create footnotes in stand-alone text with automatic and with manual marks

  This continues the work begun in 6261048 by David

http://codereview.appspot.com/6498109

Patchy the autobot says: passes tests.

Counted down to 20120911, please push.

Pushed to staging as 0fc20deb5b706498d328b1c69836a44a00abec9d

Pushed to stable/2.16 as commit bcd8bd5d98a2fd2f11a085ccd12584de2d7bfe95 Author: Trevor Daniels Date: Sun Sep 9 10:23:22 2012 +0100

Doc: improve footnote documentation (2547)

 - clearer headings, separating footnotes in music
   expressions from those in stand-alone text

 - distinguish Event- and Time-based footnotes (thanks
   David)

 - explain how offsets are measured from grob boundary

 - use examples that cover just single points for clarity

 - explain how to create footnotes in stand-alone text
   with automatic and with manual marks

Issue 2792 has been merged into this issue.