Doc: Clarify documentation of footnotes (2971)

Doc: Clarify documentation of footnotes (2971)

  Review thoroughly

[dak, 2012-11-22 09:39:54]

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

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1250: [@var{direction}] \footnote
[@var{mark}] @var{offset} @var{footnote} @var{music}
It is not really a "further form", and if you consider it a "further form", the
@var{direction} would not be optional.

This is a syntactic wart slated to go away eventually (you can already write
xxx=\footnote ... -4
and then use
  c\xxx
without further ado, but it does not yet work in situ.  This is the same issue
as with -\tweak.

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1333: both a grob-name and a direction
indicator will generate an error.}
This warning is extremely misleading since footnotes with a grob-name are never
attached to anything in the music but rather to a moment of time.

@warning {If you use a grob specification, the footnote affects everything at
the current time step like @code{\once \override} would.  Just like an override,
it has to occur between @emph{complete} rhythmic events without a directional
modifier of its own and will affect all grobs produced by the following event,
whether caused by the basic event or one of its articulations.}

[Trevor Daniels, 2012-11-22 11:04:00]

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

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1250: [@var{direction}] \footnote
[@var{mark}] @var{offset} @var{footnote} @var{music}
On 2012/11/22 09:39:54, dak wrote:
> It is not really a "further form", and if you consider it a "further form",
the
> @var{direction} would not be optional.

Of course - I forgot to remove the brackets. 

> This is a syntactic wart slated to go away eventually 

OK, but for now we need to document the current behaviour.

http://codereview.appspot.com/6845078/diff/1/Documentation/notation/input.ite...
Documentation/notation/input.itely:1333: both a grob-name and a direction
indicator will generate an error.}
On 2012/11/22 09:39:54, dak wrote:
> This warning is extremely misleading since footnotes with a grob-name are
never
> attached to anything in the music but rather to a moment of time.
> 
> @warning {If you use a grob specification, the footnote affects everything at
> the current time step like @code{\once \override} would.  Just like an
override,
> it has to occur between @emph{complete} rhythmic events without a directional
> modifier of its own and will affect all grobs produced by the following event,
> whether caused by the basic event or one of its articulations.}

With this understanding rather more invasive changes
are needed to present an absolutely accurate description.
That's always the problem when you try to explain rather
than just showing what to do, especially with a messy
interface like this one.  I'll need to think about
this further.  I might chop the explanations - users in
general don't need this level of understanding.

[dak, 2012-11-22 11:17:36]

On 2012/11/22 11:04:00, Trevor Daniels wrote:
>
> That's always the problem when you try to explain rather
> than just showing what to do, especially with a messy
> interface like this one.

Basically we got one interface now, with two essentially different behaviors
depending on whether the last argument is music or a grob specification.

It's less messy than it used to be, but that does not mean that it is trivial.

> I'll need to think about
> this further.  I might chop the explanations - users in
> general don't need this level of understanding.

Well, the documentation writers are in the unfortunate situation of needing a
more complete picture of the situation than what they end up writing, starting
from a point where the available information is less than what they end up
writing.  It is hardly surprising that this often results in several iterations.

[thomasmorley65, 2012-11-22 11:39:30]

On 2012/11/22 11:04:00, Trevor Daniels wrote:
[...]
>   I might chop the explanations - users in
> general don't need this level of understanding.

Well, in the past I sometimes was beaten by the not explained "why?" and "how?"
in the docs.
So I'd always vote for deeper explanations in an additional paragraph. Might be
@warning{...} or sth else.

[Trevor Daniels, 2012-11-22 12:42:04]

On 2012/11/22 11:39:30, thomasmorley65 wrote:

> So I'd always vote for deeper explanations in an additional paragraph. Might
be

I have some sympathy with this view, but the primary purpose
of the Notation Reference is to tell users /how to engrave/
their music in as simple and straightforward way as possible,
not how LilyPond works.  The NR is already 816 pages long,
which hardly is commensurate with "simple".

The Extending Manual is the place for explanations useful to
developers.  Granted this is rather embryonic at present, due
mainly to a dearth of knowledgeable people willing to contribute
to it.  It would benefit greatly from further input ;)

Trevor

[thomasmorley65, 2012-11-25 23:52:51]

On 2012/11/22 12:42:04, Trevor Daniels wrote:
[...]
> The Extending Manual is the place for explanations useful to
> developers.  Granted this is rather embryonic at present, due
> mainly to a dearth of knowledgeable people willing to contribute
> to it.  It would benefit greatly from further input ;)

With other words: patches are welcome.
:)

-Harm

[Trevor Daniels, 2012-12-10 09:48:10]

Revise documentation thoroughly

[dak, 2012-12-10 15:43:47]

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

http://codereview.appspot.com/6845078/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1240: Although notes inside a chord do cause
events, time-based footnotes
That is confusing: stems and flags are not events.  I'd rather write something
like:
"Exactly which of a chord's multiple note events will be deemed the root cause
of a stem or flag is undefined.  So for annotating those, time-based footnotes
are preferable as well."

http://codereview.appspot.com/6845078/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1388: < \single \footnote #'(-1 . -3) "An A"
NoteHead
This is unnecessarily contorted: a NoteHead is the (only) directly caused grob
from a chord note, so just writing
\footnote #'(-1 . -3) "An A" a
will work fine.  \single is only necessary when you _need_ to specify a
particular grobname for a footnote attached to an event because the grob in
question is not directly attached to the event as well as the only such grob.

[Trevor Daniels, 2012-12-11 17:12:51]

Thanks for the review David.  Revised patch-set on
its way ...

Trevor

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

http://codereview.appspot.com/6845078/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1240: Although notes inside a chord do cause
events, time-based footnotes
On 2012/12/10 15:43:47, dak wrote:
> That is confusing: stems and flags are not events.  I'd rather write something
> like:
> "Exactly which of a chord's multiple note events will be deemed the root cause
> of a stem or flag is undefined.  So for annotating those, time-based footnotes
> are preferable as well."

Done.

http://codereview.appspot.com/6845078/diff/8001/Documentation/notation/input....
Documentation/notation/input.itely:1388: < \single \footnote #'(-1 . -3) "An A"
NoteHead
On 2012/12/10 15:43:47, dak wrote:
> This is unnecessarily contorted: a NoteHead is the (only) directly caused grob
> from a chord note, so just writing
> \footnote #'(-1 . -3) "An A" a
> will work fine.  \single is only necessary when you _need_ to specify a
> particular grobname for a footnote attached to an event because the grob in
> question is not directly attached to the event as well as the only such grob.

Ah, OK.  I'd misunderstood that.  Changed text and
example.

[Trevor Daniels, 2012-12-11 17:23:28]

Respond to David's comments

[dak, 2012-12-11 17:43:26]

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

http://codereview.appspot.com/6845078/diff/15001/Documentation/notation/input...
Documentation/notation/input.itely:1280: specifies a type of grob to mark (like
@samp{Flag}).  If it is
At the time this text was written originally, grob-name was pretty accurate. 
But now we probably should call it something like "grob-spec" (or whatever we
use for overrides) instead: if you want to put a footnote on a time signature,
you'll need to write @samp{Staff.TimeSignature} as a spec: with
@samp{TimeSignature} alone the footnote will not apply (as the time signature is
announced at Staff level), quite similar to how overrides behave.

So we should at least give one example including a context name.

[Trevor Daniels, 2012-12-11 23:04:15]

On 2012/12/11 17:43:26, dak wrote:
> At the time this text was written originally, grob-name was pretty accurate. 
> But now we probably should call it something like "grob-spec" (or whatever we
> use for overrides) instead: if you want to put a footnote on a time signature,

Good call.  I'll modify the text and syntax definition.

> So we should at least give one example including a context name.

There already is an example of modifying a TimeSignature,
BarLine and KeySignature, all at the Staff level.

Trevor

[Trevor Daniels, 2012-12-11 23:06:56]

Add optional Context to syntax

[Graham Percival, 2012-12-16 01:10:02]

LGTM

https://codereview.appspot.com/6845078/diff/19001/Documentation/notation/inpu...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/6845078/diff/19001/Documentation/notation/inpu...
Documentation/notation/input.itely:1332: direction \footnote [@var{mark}]
@var{offset} @var{footnote} @var{music}
I think you want @var{direction} here, but no need for another patch.

[Trevor Daniels, 2012-12-16 08:35:51]

https://codereview.appspot.com/6845078/diff/19001/Documentation/notation/inpu...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/6845078/diff/19001/Documentation/notation/inpu...
Documentation/notation/input.itely:1332: direction \footnote [@var{mark}]
@var{offset} @var{footnote} @var{music}
On 2012/12/16 01:10:02, Graham Percival wrote:
> I think you want @var{direction} here, but no need for another patch.

Quite right.  And so does the earlier example.
Will do.  Thanks.

[Trevor Daniels, 2012-12-20 09:17:24]

Pushed to staging as
178e3c0e4806989a6120f92059047a0330f7c7fa
Closing ...