Doc: NR Added new node for Custom Footnotes

Doc: NR Added new node for Custom Footnotes

This is for Tracker issue 1567

[pkx166h, 2011-10-25 19:30:51]

There are a few non-standard indents to show more clearly the footnote syntax in
the @lilypond examples.

[MikeSol, 2011-10-25 19:36:51]

Thanks for your work on this James!

Cheers,
MS

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

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1025: All grobs, top-level @code{\markup} and
chorded notes and can be
and chorded notes can be

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1026: annotated.  When annotating grobs the
command that you use must come
When annotating grobs,

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1033: 
This is not entirely accurate - it is the center only if the offset is 0.  If
the offset is negative it is DOWN/LEFT, and if positive it is UP/RIGHT.

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1097: 
I believe they can (sorry if I ever indicated anything to the contrary!).  Try
\auto-footnote.

[pkx166h, 2011-10-26 20:21:22]

second draft

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

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1025: All grobs, top-level @code{\markup} and
chorded notes and can be
On 2011/10/25 19:36:51, MikeSol wrote:
> and chorded notes can be

Done.

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1026: annotated.  When annotating grobs the
command that you use must come
On 2011/10/25 19:36:51, MikeSol wrote:
> When annotating grobs,

Done.

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1033: 
On 2011/10/25 19:36:51, MikeSol wrote:
> This is not entirely accurate - it is the center only if the offset is 0.  If
> the offset is negative it is DOWN/LEFT, and if positive it is UP/RIGHT.

Changed the wording here. Hope this is better/clearer.

http://codereview.appspot.com/5315053/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1097: 
On 2011/10/25 19:36:51, MikeSol wrote:
> I believe they can (sorry if I ever indicated anything to the contrary!).  Try
> \auto-footnote.

Then you are going to need to help here.

Here is the example I am using for \footnote

\book {
  \markup {
    \bold \italic { Poco }
      \footnote \super 1 \italic "1. Little"
    \bold \italic { a }
      \footnote \super 2 \bold "2. by"
    \bold \italic { poco }
      \footnote \super 3 "3. little"
  }
  \relative c' {
    a'4\f( b8)[ e] c4_"rit." dis?4
    \breathe
  }
}

How can I convert it to use \autoFootnote. Obviously you can get rid of the
\super 1 2 3 bits but I'd like to keep the rest and cannot do without failure of
compilation.

Thanks

[Graham Percival (old account), 2011-10-27 01:56:26]

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

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1020: There are two types of footnotes that
can be used; automatic footnotes
people don't read stuff in @subsection in html.  Move this into @unnumbered
Footnote overview

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1064: \autoFootnoteGrob #'@var{Layout Object}
#'@var{(x . y)}
what is this @example doing here?  don't the @lilypond[]s show how to use it?

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1107: for top-level @code{\markup} & chorded
notes, and @code{\footnoteGrob}
avoid & since non-english speakers might think it's input syntax.  Write out
"and" in full.

[pkx166h, 2011-10-29 17:09:11]

Third Draft. Thanks so far. James

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

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1020: There are two types of footnotes that
can be used; automatic footnotes
On 2011/10/27 01:56:26, Graham Percival wrote:
> people don't read stuff in @subsection in html.  Move this into @unnumbered
> Footnote overview

Done. I hope this was what you meant.

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1064: \autoFootnoteGrob #'@var{Layout Object}
#'@var{(x . y)}
On 2011/10/27 01:56:26, Graham Percival wrote:
> what is this @example doing here?  don't the @lilypond[]s show how to use it?

Yes they do. Although personally I don't think unless I pepper the @lilypond
examples with '\markup' as well which might make them look messy/complicated,
that it is that clear.

If you take the @lilypond above you can see I have avoided the \markup function
as it is implied (?) by the \autoFootnote however I *could* have one if I wanted
(as shown by using the \bold markup which requires \markup to be explicitly
stated.

So that was why I put the whole command syntax in. So what do you think?

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1097: case use the manual @code{\footnote}
command below.
NB: Still waiting on mike to show me an example that I use in the \footnote
command below that I can use for top-level markup with \autoFootnote. As I
cannot seem to be able to reconstruct the example I use with manual footnotes
for automatic footnotes.

http://codereview.appspot.com/5315053/diff/5001/Documentation/notation/input....
Documentation/notation/input.itely:1107: for top-level @code{\markup} & chorded
notes, and @code{\footnoteGrob}
On 2011/10/27 01:56:26, Graham Percival wrote:
> avoid & since non-english speakers might think it's input syntax.  Write out
> "and" in full.

Done. Left the comma in after the 'list' so that the other 'and' doesn't look to
cumbersome to non-non English speakers. :)

[Graham Percival, 2011-10-31 06:37:04]

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

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1019: 
technically there should be a 1-2 sentence introduction here.  Something useless
and uninformative, but making the pdf (and the rare person who clicks on this in
html) look a little bit friendlier.

you can add this after it's pushed, or just before it's pushed.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1067: @example
move this @example up to immediately after the first paragraph.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1072:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
what does this example show?  could we have a 1-2 sentence introduction?

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1074: \header { copyright = \markup {
"Copyright" \char ##x00A9 "1970" } }
why do you want the tagline visible here?  and why do you want the copyright
symbol?  does that seriously aid in demonstrating how footnotes work?

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1101: case use the manual @code{\footnote}
command below.
replace with "in this case, use @ref{Manual footnotes}." since we might possibly
want to reorder the chapters/sections/etc.

highly unlikely in this case, but you still shouldn't assume that material is
"above" or "below" anything else.  not in Notation, at least; you can do that in
Learning if you must.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1119:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
1-2 intro for this @lilypond?  even if it's obvious, we want a visual division
between the @example and the verbatim commands.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1121: \markup {
why do you want a tagline in this @lilypond?

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1156:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
introduce this @lilypond as well

[pkx166h, 2011-11-02 06:10:38]

4th Draft. Thanks Graham.

@Mike Solomon: 

I'd still like an example on how to autofootnote top-level markup if you can, so
I can remove that technically inaccurate statement.

Just in case you missed it, I'd like to use the same example as I use for
\footnote in this patch but for \autofootnote as I cannot get it working after
trying a few permutations, without error.

Merci B.

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

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1019: 
On 2011/10/31 06:37:05, Graham Percival wrote:
> technically there should be a 1-2 sentence introduction here.  Something
useless
> and uninformative, but making the pdf (and the rare person who clicks on this
in
> html) look a little bit friendlier.
> 
> you can add this after it's pushed, or just before it's pushed.

I took the first sentence of the next following para below and put it here.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1067: @example
On 2011/10/31 06:37:05, Graham Percival wrote:
> move this @example up to immediately after the first paragraph.

Done.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1072:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
On 2011/10/31 06:37:05, Graham Percival wrote:
> what does this example show?  could we have a 1-2 sentence introduction?

Done.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1074: \header { copyright = \markup {
"Copyright" \char ##x00A9 "1970" } }
On 2011/10/31 06:37:05, Graham Percival wrote:
> why do you want the tagline visible here?

This is the first time that users would see a footnote and see how it fits in
relation to the tagline and copyright (i.e. above it not below as might be
expected - if we're having to use \book (because we need to use 'papersize=',
might as well use tagline.

>and why do you want the copyright symbol?  does that seriously aid in
demonstrating how footnotes work?

I guess not, it's just if I am using 'copyright' field in the example it seemed
appropriate. But I'll remove the \char as it does look extraneous now you
mention it.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1101: case use the manual @code{\footnote}
command below.
On 2011/10/31 06:37:05, Graham Percival wrote:
> replace with "in this case, use @ref{Manual footnotes}." since we might
possibly
> want to reorder the chapters/sections/etc.
> 
> highly unlikely in this case, but you still shouldn't assume that material is
> "above" or "below" anything else.  not in Notation, at least; you can do that
in
> Learning if you must.

Done.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1119:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
On 2011/10/31 06:37:05, Graham Percival wrote:
> 1-2 intro for this @lilypond?  even if it's obvious, we want a visual division
> between the @example and the verbatim commands.

Done.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1121: \markup {
On 2011/10/31 06:37:05, Graham Percival wrote:
> why do you want a tagline in this @lilypond?

No particular reason. Just less lines in the @lilypond. I have removed it though
as there is no need now that we have showed this in the first @lilypond of this
section and tagline = ##f has been discussed at length elsewhere.

http://codereview.appspot.com/5315053/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1156:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
On 2011/10/31 06:37:05, Graham Percival wrote:
> introduce this @lilypond as well

Done.

[Graham Percival, 2011-11-02 08:17:42]

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

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1032: Automatic footnotes create default
superscript numbers which flag the
Is the term "flag" often used to refer to footnote numbers?  This seems
confusing to me; quite apart from musical confusion about not flags, I'm simply
not familiar with that use of the term as a native English speaker.

Can you say this simpler?  Maybe using "symbol"?  "automatic footnotes create
symbols (generally numbers) which indicate relevant footnote; manual footnotes
allow a custom symbol to be used isntead."

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1049: @qq{bottom left} and @qq{top right} of
the grob respectively.
lolwut ?  why didn't Mike just pick one value (either the center or top-left
corner) and stick with it?!

this is unnecessarily confusing.

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1059: To annotate chorded notes;
full colon : not semicolon.  And are chorded notes really the easiest thing to
describe?  What about just doing
  a4-\autoFootnote #'(0 . 0) "A note"
first, and _then_ breaking out the complicated stuff?

(and yes, I deliberately chose a4 instead of the more usual c4)


also, in your overview you stated that the command comes *before* the grob, but
in this case the footnote command seems to come after ?

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1132: \footnote \super 1 \italic "1. Little"
I'm lost.  it'd probably be easier to understand if I saw the graphical output
as well, but don't forget that we have blind users.

I want a simple example.
@lilypond
\book{
   \relative c' {
      a4-\customFootnote "a note"
   }
}
or whatever the syntax is.


Remember that @example is basically useless; if you think that you've explained
something by using @example, then you're wrong.  Sure, people with a bachelor
degree in math, CS, or physics can decypher the meaning, but we don't want want
to write the docs only for such people.


Simple, working, @lilypond[]s.  That's what I'm missing here.

[dak, 2011-11-02 08:37:11]

Oh, by the way, I suggest that you wait for Issue 2003 to go through before
investing too much effort in documenting your interfaces.  Then you don't need a
separate interface for "manual" and "automatic" footnotes, but can just use
something like \footnote\default for autogeneration of footnote marks, in strict
analogy to \mark (which is changed to be a music function in Issue 2003).

I think that would be quite more natural for the user.

[MikeSol, 2011-11-02 09:34:11]

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

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1049: @qq{bottom left} and @qq{top right} of
the grob respectively.
On 2011/11/02 08:17:42, Graham Percival wrote:
> lolwut ?  why didn't Mike just pick one value (either the center or top-left
> corner) and stick with it?!
> 
> this is unnecessarily confusing.

The Balloon grob has been like this ever since it has existed in LilyPond, and
footnote just uses the balloon print function.  I actually like the way this
works, as it allows the footnote to be aligned to any corner or edge of the grob
(not unlike ly:stencil-combine-at-edge).

So that's my reasoning.  But the question "why didn't Mike..." should be
addressed to Han-Wen: as he was the one who created it, he may have answers that
I don't.

[MikeSol, 2011-11-02 09:35:54]

On 2011/11/02 06:10:38, J_lowe wrote:
> 4th Draft. Thanks Graham.
> 
> @Mike Solomon: 
> 
> I'd still like an example on how to autofootnote top-level markup if you can,
so
> I can remove that technically inaccurate statement.
> 
> Just in case you missed it, I'd like to use the same example as I use for
> \footnote in this patch but for \autofootnote as I cannot get it working after
> trying a few permutations, without error.
> 
> Merci B.

\version "2.15.0"

\markup { \auto-footnote a b }

Cheers,
MS

[dak, 2011-11-02 09:42:22]

> \markup { \auto-footnote a b }

Oh.  \auto-footnote is a markup command.  I haven't got my claws into those yet
regarding optional arguments.

I suppose I have to take a closer look before suggesting things.

[Graham Percival, 2011-11-03 09:13:46]

On Wed, Nov 02, 2011 at 09:34:12AM +0000, mtsolo@gmail.com wrote:
> 
> So that's my reasoning.  But the question "why didn't Mike..." should be
> addressed to Han-Wen: as he was the one who created it, he may have
> answers that I don't.

ok, good answer.

- Graham

[pkx166h, 2011-11-04 23:10:43]

This still needs work but I need some decisions err.. decided and some more
input from Mike.

James

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

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1032: Automatic footnotes create default
superscript numbers which flag the
On 2011/11/02 08:17:42, Graham Percival wrote:
> Is the term "flag" often used to refer to footnote numbers?  

Actually there is no consensus on this term after doing some research.

> This seems
> confusing to me; quite apart from musical confusion about not flags, I'm
simply
> not familiar with that use of the term as a native English speaker.
> 
> Can you say this simpler?  Maybe using "symbol"?  "automatic footnotes create
> symbols (generally numbers) which indicate relevant footnote; manual footnotes
> allow a custom symbol to be used isntead."

I prefer 'indicator' in this case I think. Symbol doesn't denote a 'number' as
opposed to say a '\char' (where that \char could be a 'dagger' or 'asterix' or
some other customer 'pictogram'.

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1049: @qq{bottom left} and @qq{top right} of
the grob respectively.
On 2011/11/02 09:34:12, MikeSol wrote:
> On 2011/11/02 08:17:42, Graham Percival wrote:
> > lolwut ?  why didn't Mike just pick one value (either the center or top-left
> > corner) and stick with it?!
> > 
> > this is unnecessarily confusing.
> 
> The Balloon grob has been like this ever since it has existed in LilyPond, and
> footnote just uses the balloon print function.  I actually like the way this
> works, as it allows the footnote to be aligned to any corner or edge of the
grob
> (not unlike ly:stencil-combine-at-edge).
> 
> So that's my reasoning.  But the question "why didn't Mike..." should be
> addressed to Han-Wen: as he was the one who created it, he may have answers
that
> I don't.

I've left this for now.

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1059: To annotate chorded notes;
On 2011/11/02 08:17:42, Graham Percival wrote:
> full colon : not semicolon.  

Done.

> And are chorded notes really the easiest thing to
> describe?  What about just doing
>   a4-\autoFootnote #'(0 . 0) "A note"
> first, and _then_ breaking out the complicated stuff?
> 
> (and yes, I deliberately chose a4 instead of the more usual c4)
> 
> 
> also, in your overview you stated that the command comes *before* the grob,
but
> in this case the footnote command seems to come after ?

I guess because we are not indicating a grob i.e.

c-\autoFootnote #'(1 . -1.25)

vs

\autoFootnote #'NoteHead #'(1 . -1.25)
c4

Which does the same thing.

Mike any comment on this?

It seems to infer, now that Graham has phrased it like this, that note head
grobs in this case are 'assumed' and not needed to be specified like a slur or
beam grob etc.

http://codereview.appspot.com/5315053/diff/14001/Documentation/notation/input...
Documentation/notation/input.itely:1132: \footnote \super 1 \italic "1. Little"
On 2011/11/02 08:17:42, Graham Percival wrote:
> I'm lost.  it'd probably be easier to understand if I saw the graphical output
> as well, but don't forget that we have blind users.
> 
> I want a simple example.
> @lilypond
> \book{
>    \relative c' {
>       a4-\customFootnote "a note"
>    }
> }
> or whatever the syntax is.

OK but this is for top-level \markup (I don't think we call it anything else do
we?) and not for notes or anything in the staff. So I've simplified the markup
to just a single string that has one footnote.

The music underneath gives it context but also is the same music expression that
I move on to in the next example to show how to footnote all the 'other' non
top-level markup. So I was trying to keep it consistent.

The most simple example I suppose is

\book {
  \markup {
    \bold \italic { Andante }
    \footnote \super 1 "1. At walking pace"
  }
}

But I thought that looked silly just like that as a printed example. Hence the
extra music expression at the end.

> Simple, working, @lilypond[]s.  That's what I'm missing here.

I can remove the music expression completely if you think it will still work,
and just have the \book { \markup { } } construction.

[mike_apollinemike.com, 2011-11-07 07:31:11]

On Nov 4, 2011, at 4:10 PM, pkx166h@gmail.com wrote:

> This still needs work but I need some decisions err.. decided and some
> more input from Mike.
> 
> James
> 

Sorry for the delay!  I missed this e-mail.

>> 
> 
> I guess because we are not indicating a grob i.e.
> 
> c-\autoFootnote #'(1 . -1.25)
> 
> vs
> 
> \autoFootnote #'NoteHead #'(1 . -1.25)
> c4
> 
> Which does the same thing.
> 
> Mike any comment on this?

Yup - exactly.  The postfix operator only ever works in chords and will apply to
NoteHeads.
{ <a^\espressivo-\autoFootnote #'(1 . 1) "a" > }

> 
> It seems to infer, now that Graham has phrased it like this, that note
> head grobs in this case are 'assumed' and not needed to be specified
> like a slur or beam grob etc.
> 

It'd be nice if this were more robust so that it could apply to other things
like scripts, but for now, it only works with notes.  This could be a known
issue if you'd like.

Cheers,
MS

[dak, 2011-11-07 12:20:54]

"mike@apollinemike.com" <mike@apollinemike.com> writes:

>     I guess because we are not indicating a grob i.e.
>     
>     c-\autoFootnote #'(1 . -1.25)
>     
>     vs
>     
>     \autoFootnote #'NoteHead #'(1 . -1.25)
>     c4
>     
>     Which does the same thing.
>     
>     Mike any comment on this?
>     
>
> Yup - exactly.  The postfix operator only ever works in chords and
> will apply to NoteHeads.
> { <a^\espressivo-\autoFootnote #'(1 . 1) "a" > }
>
>     
>     It seems to infer, now that Graham has phrased it like this, that
>     note
>     head grobs in this case are 'assumed' and not needed to be
>     specified
>     like a slur or beam grob etc.
>     
>     
>
> It'd be nice if this were more robust so that it could apply to other
> things like scripts, but for now, it only works with notes.  This
> could be a known issue if you'd like.

It is not clear to me whether this "known issue" is due to limitations
of music functions.  Would a changed behavior of music functions help?
I still have to tackle music functions inside of chords in order to make
the music function set reasonably orthogonal, so if you have suggestions
in that area...

-- 
David Kastrup

[pkx166h, 2011-11-19 14:30:50]

Having a rethink on this section, after Graham's comments.

Currently trying to simplify some of the examples and explanations. Also need to
include the \markup function \auto-footnote as well. I'll close the Reitveld and
open a new one when I'm done (hopefully in the next day or so).

James