Clarify notation for slurs and beams

Clarify notation for slurs and beams

Note that the opening code for slurs and beams comes after
the first note of the slur or beam.

Also, add a section about notes containing pitches, durations,
and post-events.

[Be-3, 2018-04-30 11:37:09]

Hi Carl,

Concise, comprehensible, - LGTM!

Perhaps it should be explicitly pointed out that the duration shorthand does not
work for rests.
There have been some misconceptions lately on the user list, and so I think this
detail probably deserves special attendance.

Thanks,
Torsten

https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
Documentation/learning/fundamental.itely:487: \absolute {c'8-1--(~^\markup{"text
annotationi"} c' d')}
Shouldn't it be "text annotation"?

[Trevor Daniels, 2018-04-30 12:08:20]

Hi Carl

LGTM, with a couple of minor comments.

Trevor

https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
Documentation/learning/fundamental.itely:488: @end lilypond
I'd prefer \relative or nothing in this example. \absolute 
has not been introduced earlier, in fact it's not used at 
all in the LM.

https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
Documentation/learning/fundamental.itely:492: @ruser{Expressive marks},
Might be good to point to the relevant sections in the LM 
as well, in Section 2.1

[Carl, 2018-04-30 14:56:48]

On 2018/04/30 11:37:09, Be-3 wrote:
> Hi Carl,
> 
> Concise, comprehensible, - LGTM!
> 
> Perhaps it should be explicitly pointed out that the duration shorthand does
not
> work for rests.
> There have been some misconceptions lately on the user list, and so I think
this
> detail probably deserves special attendance.

I've added a sentence that should clarify.

>
https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
> Documentation/learning/fundamental.itely:487: \absolute
{c'8-1--(~^\markup{"text
> annotationi"} c' d')}
> Shouldn't it be "text annotation"?
Yes.  Now you know which editor I was using to create the patch -- it's vim
leftovers.

Thanks for the catch.

[Carl, 2018-04-30 15:03:35]

On 2018/04/30 12:08:20, Trevor Daniels wrote:

> 
>
https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
> Documentation/learning/fundamental.itely:488: @end lilypond
> I'd prefer \relative or nothing in this example. \absolute 
> has not been introduced earlier, in fact it's not used at 
> all in the LM.

Good idea.  I went with nothing.

> 
>
https://codereview.appspot.com/343060043/diff/1/Documentation/learning/fundam...
> Documentation/learning/fundamental.itely:492: @ruser{Expressive marks},
> Might be good to point to the relevant sections in the LM 
> as well, in Section 2.1

Also a good idea.  I've added the references.

Thanks,

Carl

[Carl, 2018-04-30 15:28:25]

Respond to Trevor and Torsten

[Trevor Daniels, 2018-04-30 15:47:26]

Hi Carl

Another minor nit!  Otherwise looks fine.

Trevor

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:495: @rlearning{Adding text}.
Not sure if it makes any difference but we usually use
@ref for references within the same manual.

[Carl, 2018-04-30 15:51:16]

Thanks for the feedback, Trevor.

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:495: @rlearning{Adding text}.
On 2018/04/30 15:47:26, Trevor Daniels wrote:
> Not sure if it makes any difference but we usually use
> @ref for references within the same manual.

Fundamentals is in a different source file than common notation.  If I use @ref,
it breaks the info build.  So I had to use @rlearning to get it to pass make
doc.

If I'm doing something wrong, and there's some way to get @ref to work, I'd be
happy to know about it.

[Trevor Daniels, 2018-04-30 17:04:02]

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/20001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:495: @rlearning{Adding text}.
On 2018/04/30 15:51:16, Carl wrote:
> On 2018/04/30 15:47:26, Trevor Daniels wrote:
> > Not sure if it makes any difference but we usually use
> > @ref for references within the same manual.
> 
> Fundamentals is in a different source file than common notation.  If I use
@ref,
> it breaks the info build.  So I had to use @rlearning to get it to pass make
> doc.
> 
> If I'm doing something wrong, and there's some way to get @ref to work, I'd be
> happy to know about it.

@ref definitely should work.  It may be that the heading for one
of them is "Articulation and dynamics", not "Articulations and
dynamics" - no "s".  Using @ruser bypasses the check, I think.

[c_sorensen, 2018-04-30 17:16:13]

On 4/30/18, 11:04 AM, "lilypond-devel on behalf of
tdanielsmusic@googlemail.com" <lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org
on behalf of tdanielsmusic@googlemail.com> wrote:
    
    @ref definitely should work.  It may be that the heading for one
    of them is "Articulation and dynamics", not "Articulations and
    dynamics" - no "s".  Using @ruser bypasses the check, I think.
    
OK, that's clearly the issue.

Now, how should it be fixed?  Should we stick with "Articulation and dynamics",
even though the next menu down is "Articulations"?  Or should we change to
"Articulations and dynamics"?  I can do either one.

Thanks,
Carl
 

[t.daniels_treda.co.uk, 2018-04-30 17:29:13]

Carl, you wrote 30/04/2018 18:16:05
>
>On 4/30/18, 11:04 AM, "lilypond-devel on behalf of 
>tdanielsmusic@googlemail.com" 
><lilypond-devel-bounces+c_sorensen=byu.edu@gnu.org on behalf of 
>tdanielsmusic@googlemail.com> wrote:
>
>    @ref definitely should work.  It may be that the heading for one
>    of them is "Articulation and dynamics", not "Articulations and
>    dynamics" - no "s".  Using @ruser bypasses the check, I think.
>
>OK, that's clearly the issue.
>
>Now, how should it be fixed?  Should we stick with "Articulation and 
>dynamics", even though the next menu down is "Articulations"?  Or 
>should we change to "Articulations and dynamics"?  I can do either one.
Well, I'd prefer adding the "s" to the title, as long as it doesn't 
break other references (I don't know if there are any, but if there are 
any in the LM they should show up as errors in a make doc.)  
Documentation/scripts/auxiliar/ref_check.py should check all refs for 
you, if it still works - it's a while since I used it.

Trevor

[Carl, 2018-04-30 19:18:42]

Adjust titles and menus

[thomasmorley651, 2018-04-30 21:49:37]

Hi Carl,

many thanks for your work.
Some remarks:

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:465: optionally followed by one or more
post-events.  Post-events add
I'd completely delete 'post-event'. 
From a musical thinking it makes no sense. An articulation is not performed
_after_ the note.
To explain it programmatical, this is not the right place, imho.

Why not simply:

"A note entry in LilyPond consists of a pitch, followed by a duration,
optionally followed by things such as articulations, fingerings, string numbers,
slurs, ties, explanatory text, etc."

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:481: Post-events follow the note to
which they are attached.  Suppose we

Here as well.

Also, I think it's important to drop a sentence about the "-"-signs, which
actually attach those optional elements to the note.

So my suggestion:

"Optional elements are added at the end of the initial note-duration-entry. 
Probably using a "-"-sign, which can be omitted, if no ambiguity occurs.
Suppose we ..."

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:488: {c'8-1--(~^\markup{"text
annotation"} c' d')}

For the sake of simplicity I'd not use direction-modifiers and enter the text
without explicit \markup, i.e.:
{c'8-1--(~-"text annotation" c' d')}

[Carl, 2018-04-30 22:19:12]

Harm,

Thanks for the input.  I'm not sure I agree with you on all this, but I'm
certainly open to being convinced.  I've got specific replies to your inline
comments.

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:465: optionally followed by one or more
post-events.  Post-events add
On 2018/04/30 21:49:37, thomasmorley651 wrote:
> I'd completely delete 'post-event'. 
> From a musical thinking it makes no sense. An articulation is not performed
> _after_ the note.
> To explain it programmatical, this is not the right place, imho.
> 
> Why not simply:
> 
> "A note entry in LilyPond consists of a pitch, followed by a duration,
> optionally followed by things such as articulations, fingerings, string
numbers,
> slurs, ties, explanatory text, etc."

We could do this.  But ultimately all the things that attach to notes like this
are called post-events in the internals reference.  So I don't think it's a bad
idea to introduce the LilyPond term here, just like we do for pitch and
duration.  All three terms (pitch, duration, post-event) are LilyPond terms, not
musical terms. 

We aren't explaining music in this section.  We are explaining LilyPond
constructs.

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:481: Post-events follow the note to
which they are attached.  Suppose we
On 2018/04/30 21:49:37, thomasmorley651 wrote:
> 
> Here as well.
> 
> Also, I think it's important to drop a sentence about the "-"-signs, which
> actually attach those optional elements to the note.
> 
> So my suggestion:
> 
> "Optional elements are added at the end of the initial note-duration-entry. 
> Probably using a "-"-sign, which can be omitted, if no ambiguity occurs.
> Suppose we ..."
> 
> 

I don't think I agree that things are attached with "-" signs.  For example,
\staccato, \mordent, \turn, \fermata, \prall, (, [. None of these are attached
with "-" signs, although they can have a direction indicator (-, _ , ^)
preceding them if desired.  At least, that is what the N.R. 5.4.2 says.

If we want to talk about direction indicators here, I think we can give a brief
introduction.  If not, I think we should leave them out completely.  In the LM
and the NR, the direction indicators are always included when we add the
post-events, if they are needed.

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:488: {c'8-1--(~^\markup{"text
annotation"} c' d')}
On 2018/04/30 21:49:37, thomasmorley651 wrote:
> 
> For the sake of simplicity I'd not use direction-modifiers and enter the text
> without explicit \markup, i.e.:
> {c'8-1--(~-"text annotation" c' d')}

I think it's actually nicer not to have so many "-" characters; they make it
confusing, in my opinion.

[thomasmorley651, 2018-04-30 22:55:35]

On 2018/04/30 22:19:12, Carl wrote:

>
https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
> File Documentation/learning/fundamental.itely (right):
> 
>
https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
> Documentation/learning/fundamental.itely:465: optionally followed by one or
more
> post-events.  Post-events add
> On 2018/04/30 21:49:37, thomasmorley651 wrote:
> > I'd completely delete 'post-event'. 
> > From a musical thinking it makes no sense. An articulation is not performed
> > _after_ the note.
> > To explain it programmatical, this is not the right place, imho.
> > 
> > Why not simply:
> > 
> > "A note entry in LilyPond consists of a pitch, followed by a duration,
> > optionally followed by things such as articulations, fingerings, string
> numbers,
> > slurs, ties, explanatory text, etc."
> 
> We could do this.  But ultimately all the things that attach to notes like
this
> are called post-events in the internals reference.  So I don't think it's a
bad
> idea to introduce the LilyPond term here, just like we do for pitch and
> duration.  All three terms (pitch, duration, post-event) are LilyPond terms,
not
> musical terms. 

Pitch and duration are surely terms every musician and every music-typesetter
will know, they are _musical_ terms as well.
Not so post-event.
Maybe it would be sufficient to reword:
"optionally followed by one or more elements, which are called "post-events".

> 
>
https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
> Documentation/learning/fundamental.itely:481: Post-events follow the note to
> which they are attached.  Suppose we
> On 2018/04/30 21:49:37, thomasmorley651 wrote:
> > 
> > Here as well.
> > 
> > Also, I think it's important to drop a sentence about the "-"-signs, which
> > actually attach those optional elements to the note.
> > 
> > So my suggestion:
> > 
> > "Optional elements are added at the end of the initial note-duration-entry. 
> > Probably using a "-"-sign, which can be omitted, if no ambiguity occurs.
> > Suppose we ..."
> > 
> > 
> 
> I don't think I agree that things are attached with "-" signs.  For example,
> \staccato, \mordent, \turn, \fermata, \prall, (, [. None of these are attached
> with "-" signs, although they can have a direction indicator (-, _ , ^)
> preceding them if desired.  At least, that is what the N.R. 5.4.2 says.

Here the NR is not entirely complete.
"_" and "^" _are_ direction-modifiers, ofcourse.
"-" _is_ the method to insert a post-event into a list of other post-events.
For convenience it can be omitted, if no ambiguity is present. (It can't be
omitted before a fingering, for example)
The direction of this post-event is the default-direction for said post-event.
But this more a side-effect.

Also, see:
{ \displayLilyMusic c'\tenuto }
=> c'4--

> 
> If we want to talk about direction indicators here, I think we can give a
brief
> introduction.  If not, I think we should leave them out completely.  

Agreed, direction-modifiers shouldn't be explained here in the fundamentals.

> In the LM
> and the NR, the direction indicators are always included when we add the
> post-events, if they are needed.
> 
>
https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
> Documentation/learning/fundamental.itely:488: {c'8-1--(~^\markup{"text
> annotation"} c' d')}
> On 2018/04/30 21:49:37, thomasmorley651 wrote:
> > 
> > For the sake of simplicity I'd not use direction-modifiers and enter the
text
> > without explicit \markup, i.e.:
> > {c'8-1--(~-"text annotation" c' d')}
> 
> I think it's actually nicer not to have so many "-" characters; they make it
> confusing, in my opinion.

Ofcourse, but I don't understand the relevance here.
{c'8-1--(~-"text annotation" c' d')} does not use more "-" than the other code.

Btw, maybe better to add a space after { and before }.

[thomasmorley651, 2018-04-30 23:47:56]

On 2018/04/30 22:55:35, thomasmorley651 wrote:
> On 2018/04/30 22:19:12, Carl wrote:

> > I don't think I agree that things are attached with "-" signs.  For example,
> > \staccato, \mordent, \turn, \fermata, \prall, (, [. None of these are
attached
> > with "-" signs, although they can have a direction indicator (-, _ , ^)
> > preceding them if desired.  At least, that is what the N.R. 5.4.2 says.
> 
> Here the NR is not entirely complete.
> "_" and "^" _are_ direction-modifiers, ofcourse.
> "-" _is_ the method to insert a post-event into a list of other post-events.
> For convenience it can be omitted, if no ambiguity is present. (It can't be
> omitted before a fingering, for example)
> The direction of this post-event is the default-direction for said post-event.
> But this more a side-effect.
> 
> Also, see:
> { \displayLilyMusic c'\tenuto }
> => c'4--

Well, I had a look in parser.yy. Although, I can't say I really understand it,
I'm not longer sure above is true.
Maybe David K can say more.

[Carl, 2018-05-01 02:47:20]

According to parser.yy:

In line 3259, a post_event is either:

1) post_event_nofinger, or
2) '-' plus a fingering

In line 3200, a post_event_nofinger is either

1) direction_less_event
2) script_dir plus a music_function
3,4 ) Lyric hyphen or lyric extender (Not relevant to this discussion).
5) script_dir plus a direction_reqd_event
6) script_dir plus a direction_less_event
7) '^' plus fingering
8) '_' plus fingering


In line 3275, a direction_less_event is either
1) string_number_event
2) tremolo
3)event_function_event

In line 3288, a direction_reqd_event is either
1) gen_text_def
2) script_abbreviation

In line 3387, a gen_text_def is either
1) full_markup
2) STRING
3) SYMBOL
4) embedded_scm

In line 3413, a fingering is
1) UNSIGNED

The way I read this, NR 5.4.2 is exactly right.  A direction indicator is
required for 
1) markups (gen_text_def case 1)
2) strings (gen_text_def case 2)
3) abbreviated forms of articulations (script_abbreviation)
4) fingerings (post_event case 2, direction_less_event case 7,
direction_less_event case 8)
5) \tweak or \tag (I'm not sure about this, but I think it's gen_text_def case
4)

Given this, I don't think we should say that '-' is what we use to insert
post_events.

I am of the opinion that we should not include '-' as a specific element in this
discussion.  I think it should say as-is.

Thanks,

Carl

[dak, 2018-05-01 03:26:24]

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
File Documentation/learning/fundamental.itely (right):

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:465: optionally followed by one or more
post-events.  Post-events add
On 2018/04/30 22:19:12, Carl wrote:
> On 2018/04/30 21:49:37, thomasmorley651 wrote:
> > I'd completely delete 'post-event'. 
> > From a musical thinking it makes no sense. An articulation is not performed
> > _after_ the note.
> > To explain it programmatical, this is not the right place, imho.
> > 
> > Why not simply:
> > 
> > "A note entry in LilyPond consists of a pitch, followed by a duration,
> > optionally followed by things such as articulations, fingerings, string
> numbers,
> > slurs, ties, explanatory text, etc."
> 
> We could do this.  But ultimately all the things that attach to notes like
this
> are called post-events in the internals reference.  So I don't think it's a
bad
> idea to introduce the LilyPond term here, just like we do for pitch and
> duration.  All three terms (pitch, duration, post-event) are LilyPond terms,
not
> musical terms. 
> 
> We aren't explaining music in this section.  We are explaining LilyPond
> constructs.

"pitch" and "duration" are certainly valid musical terms outside of LilyPond and
describe musical entities even within LilyPond. "post-event" does not carry
meaning separate from the LilyPond grammar.

It might make sense to introduce it as a LilyPond term by putting it in quote
marks first mention:

one or more @q{post-events}.  Post-events are placed after a main event in the
input and constitute things such as ...

https://codereview.appspot.com/343060043/diff/40001/Documentation/learning/fu...
Documentation/learning/fundamental.itely:481: Post-events follow the note to
which they are attached.  Suppose we
On 2018/04/30 22:19:12, Carl wrote:
> I don't think I agree that things are attached with "-" signs.

It's more a less a matter of what one wants to declare the rule and what the
exception.  It's more of a semantic difference, so it's more the question of
which view might be more helpful.

I'd lean towards keeping your version here: I think it better matches what we
use elsewhere.

[thomasmorley651, 2018-05-01 20:14:34]

On 2018/05/01 02:47:20, Carl wrote:
> According to parser.yy:
> 
> In line 3259, a post_event is either:
> 
> 1) post_event_nofinger, or
> 2) '-' plus a fingering
> 
> In line 3200, a post_event_nofinger is either
> 
> 1) direction_less_event
> 2) script_dir plus a music_function
> 3,4 ) Lyric hyphen or lyric extender (Not relevant to this discussion).
> 5) script_dir plus a direction_reqd_event
> 6) script_dir plus a direction_less_event
> 7) '^' plus fingering
> 8) '_' plus fingering
> 
> 
> In line 3275, a direction_less_event is either
> 1) string_number_event
> 2) tremolo
> 3)event_function_event
> 
> In line 3288, a direction_reqd_event is either
> 1) gen_text_def
> 2) script_abbreviation
> 
> In line 3387, a gen_text_def is either
> 1) full_markup
> 2) STRING
> 3) SYMBOL
> 4) embedded_scm
> 
> In line 3413, a fingering is
> 1) UNSIGNED
> 
> The way I read this, NR 5.4.2 is exactly right.  A direction indicator is
> required for 
> 1) markups (gen_text_def case 1)
> 2) strings (gen_text_def case 2)
> 3) abbreviated forms of articulations (script_abbreviation)
> 4) fingerings (post_event case 2, direction_less_event case 7,
> direction_less_event case 8)
> 5) \tweak or \tag (I'm not sure about this, but I think it's gen_text_def case
> 4)
> 
> Given this, I don't think we should say that '-' is what we use to insert
> post_events.
> 
> I am of the opinion that we should not include '-' as a specific element in
this
> discussion.  I think it should say as-is.
> 
> Thanks,
> 
> Carl

Hi Carl,

in the light of your findings and David's reply (#17) I changed my mind about
those "-"-signs and now agree we should not make them a topic here.
Anyway, I found the discussion very instructive, helping me to get a deeper
understanding. I hope it was not too tedious for you.

So two suggestions remaining:
I'd like to second David with putting quotation marks around the first
mentioning of post-events.
Spaces after/before {}. If I've counted correctly it's emphasized three times in
the LM...

Otherwise 
LGTM

Thanks,
  Harm

[dak, 2018-05-01 20:31:36]

On 2018/05/01 20:14:34, thomasmorley651 wrote:

> in the light of your findings and David's reply (#17) I changed my mind about
> those "-"-signs and now agree we should not make them a topic here.
> Anyway, I found the discussion very instructive, helping me to get a deeper
> understanding. I hope it was not too tedious for you.

One really has to understand that the rules in the grammar describe what
constructs are accepted and interpreted in what manner.  They don't assign a
logic or meaning to them.  It makes the grammar easier to read when the rules
are laid according to a higher-level plan, but the restrictions of an LALR(1)
parser generator (which is what the rules are written for) don't leave a lot of
leeway of expressing the concepts of LilyPond straightforwardly.

In addition, quite a bit of the "inherent logic" has been designed after the
fact and then those rules/productions not matching that logic have been meddled
with.

The grammar is the ultimate source of information about how LilyPond will
behave, but not what that means.  That's ultimately for the documentation
writers to decide.

[Carl, 2018-05-02 23:13:54]

Adjust description of post-events