Doc: NR - Issue 4677 - input.itely: Various improvements

A variety of nitpicks and
improvements reported by
Federico Bruni

Updated information and
included a new @lilypond
example for \KeepWithTag.

Some spelling corrections
and some simple rewording
of a few paragraphs for
clarity (deleted repeated
words, removed personal
pronouns etc.).

Moved a comment (@c) outside
of an @example so as to not
cause confusion to readers.

[pkx166h, 2016-02-18 10:45:20]

Additional corrections and updates by Federico B

[pkx166h, 2016-02-18 11:38:09]

Fix Typo that breaks make doc.

[fedelogy, 2016-02-18 22:51:46]

LGTM, except for one paragraph.
Thanks

https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2313: 
Sorry, I'm still confused. I cannot see any link between the explanation above
and the snippet below.

The snippet below explains \tagGroup, which is already explained (and much
better) immediately after. And the four strings example is more effective than
A, B, C, D.

The above paragraph is just about how to use \keepWithTag (it's a continuation
of the previous paragraph about \removeWithTag). It suggests using one command
(a single tag or a list of tag), and avoiding multiple \keepWithTag commands on
a single music expression, otherwise everything will be removed.

I must say that the original text is perfect, except for the last sentence. An
example is not really needed, but may help:

music = \relative c'' {
  \tag #'A { a4 a a a }
  \tag #'B { b4 b b b }
  \tag #'C { c4 c c c }
  \tag #'D { d4 d d d }
}

\new Staff {
  % print only A and B, not C and D
  \keepWithTag #'(A B)
  \music
}

[pkx166h, 2016-02-21 10:43:35]

With Federico B's comments and corrections.

[pkx166h, 2016-02-21 10:44:37]

Thanks Federico - see inline for my replies.

https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2313: 
On 2016/02/18 22:51:46, fedelogy wrote:
> Sorry, I'm still confused. I cannot see any link between the explanation above
> and the snippet below.
> 
> The snippet below explains \tagGroup, which is already explained (and much
> better) immediately after. And the four strings example is more effective than
> A, B, C, D.

OK I'll remove it. 

It wasn't clear in your request in the Tracker/email msg what exactly the point
of the example you gave was. As I saw no @lilypond (just an @example) that used
\tagGroup but we have @lilypond for all the other 'Tag' stuff (pushToTag,
appendToTag, removeWithTag etc.) I assumed that a reader would benfit from an
example of this command as well.
> 
> The above paragraph is just about how to use \keepWithTag (it's a continuation
> of the previous paragraph about \removeWithTag). 

Yes but as I said above, without a corresponding @lilypond (just an @example)
that I could see. For someone who doesn't *already* understand Tags I thought
this would be helpful.

> It suggests using one command
> (a single tag or a list of tag), and avoiding multiple \keepWithTag commands
on
> a single music expression, otherwise everything will be removed.

I don't understands this. My version just uses slightly different words as far
as I can tell and removes a lot of unnecessary repetition and adds the odd
article and adverb.

The para starts with the phrase 'Two or more..' (implies three, four, five
etc.), then in the example just uses first and second. What about third, fourth
and fifth? So I assumed that those third, fourth etc filters would do nothing
because the second filter would have cleared it all out (so to speak) hence the
word 'subsequent' to cope with the 'Two or more'. Getting rid of personal
pronouns and vague statements ("Usually you would rather want to ...") is all
that I can see that has been done with the last sentence.

> 
> I must say that the original text is perfect, 

Hardly. When I read the word 'Usually' at the start of a sentence, I expect to
see the cases when it isn't 'Usual'. I don't see that here. Perhaps it is just
some other person's idiomatic English, but that para is not perfect by any
stretch of the imagination. 

Too many uses of the word 'Tag' is another - trying not to use the word in the
explanation of that word (or in this case command) that you are defining helps
clarity. That was really what I was trying to do here.

> except for the last sentence. An
> example is not really needed, but may help:
> 
> music = \relative c'' {
>   \tag #'A { a4 a a a }
>   \tag #'B { b4 b b b }
>   \tag #'C { c4 c c c }
>   \tag #'D { d4 d d d }
> }
> 
> \new Staff {
>   % print only A and B, not C and D
>   \keepWithTag #'(A B)
>   \music
> }

Thanks. I've added that one instead.

[simon.albrecht, 2016-02-21 12:17:12]

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2319: \tag #'D { d4 d d d }
I’d suggest having one untagged hunk as well, to clarify behaviour on these.

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2323: \keepWithTag #'(A B)
I do think we should advertise the proper LilyPond syntax of
\keepWithTag A.B
here. It’s quite easier to type and nicer. I’d also prefer
\tag A {}
over
\tag #'A {}
but I don’t know if this is enough of a ‘standard’ – David?

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2330: @code{#'D}.
I’d suggest

‘will only print music tagged @code{A} or @code{B} (and untagged music).’

(Is it overkill to mark single letters as @code{}?)

[fede_inventati.org, 2016-02-22 12:55:12]

Il giorno dom 21 feb 2016 alle 11:44, pkx166h@gmail.com ha scritto:
> Thanks Federico - see inline for my replies.
> 
> 
>
https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
> File Documentation/notation/input.itely (right):
> 
>
https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
> Documentation/notation/input.itely:2313:
> On 2016/02/18 22:51:46, fedelogy wrote:
>> Sorry, I'm still confused. I cannot see any link between the
> explanation above
>> and the snippet below.
> 
>> The snippet below explains \tagGroup, which is already explained (and
> much
>> better) immediately after. And the four strings example is more
> effective than
>> A, B, C, D.
> 
> OK I'll remove it.
> 
> It wasn't clear in your request in the Tracker/email msg what exactly
> the point of the example you gave was. As I saw no @lilypond (just an
> @example) that used \tagGroup but we have @lilypond for all the other
> 'Tag' stuff (pushToTag, appendToTag, removeWithTag etc.) I assumed 
> that
> a reader would benfit from an example of this command as well.

Indeed my mind was confused when I reported and discussed the problem 
with David in the mailing list.
I confused the two different paragraphs (one about how to use 
\keepWithTag, the other about \tagGroup).

Anyway, if you want to add a @lilypond example of \tagGroup, you should 
do it after it is explained and not before.
The \tagGroup item in the general index points to this paragraph:
http://lilypond.org/doc/v2.19/Documentation/notation/different-editions-from-...

So the @lilypond snippet - using violinI, violinII, viola, cello as 
example - should go after this sentence: "will then only be concerned 
with tags from violinI’s tag group: any element of the included music 
that is tagged with one or more of tags from this set but not with 
violinI will get removed."

For example:

@lilypond
music = \relative {
  \tagGroup #'(violinI violinII viola cello)
  \tag #'violinI { c''4^"violinI" c c c }
  \tag #'violinII { a2 a }
  \tag #'viola { e8 e e2. }
  \tag #'cello { d'2 d4 d }
  R1^"untagged"
}

\new Voice {
  % print only music tagged with violinI and any untagged music
  \keepWithTag #'violinI
  \music
}
@end lilypond

> 
>> The above paragraph is just about how to use \keepWithTag (it's a
> continuation
>> of the previous paragraph about \removeWithTag).
> 
> Yes but as I said above, without a corresponding @lilypond (just an
> @example) that I could see. For someone who doesn't *already* 
> understand
> Tags I thought this would be helpful.
> 
>> It suggests using one command
>> (a single tag or a list of tag), and avoiding multiple \keepWithTag
> commands on
>> a single music expression, otherwise everything will be removed.
> 
> I don't understands this. My version just uses slightly different 
> words
> as far as I can tell and removes a lot of unnecessary repetition and
> adds the odd article and adverb.

I read it again and you are right.. I don't know what I read few days 
ago.
Please forget this comment :)

[dak, 2016-02-22 17:05:13]

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2323: \keepWithTag #'(A B)
On 2016/02/21 12:17:12, simon.albrecht wrote:
> I do think we should advertise the proper LilyPond syntax of
> \keepWithTag A.B
> here. It’s quite easier to type and nicer. I’d also prefer
> \tag A {}
> over
> \tag #'A {}
> but I don’t know if this is enough of a ‘standard’ – David?

Tags tended to be chosen in ways not matching a LilyPond "word", for example
containing numbers.  Since they are not used as \word but only ever as symbols,
there was no incentive to choose them compatibly before x.y acquired a
Scheme-level meaning.

[pkx166h, 2016-02-24 06:54:43]

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2319: \tag #'D { d4 d d d }
On 2016/02/21 12:17:12, simon.albrecht wrote:
> I’d suggest having one untagged hunk as well, to clarify behaviour on these.

Can you give me the full example you'd like?

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2323: \keepWithTag #'(A B)
On 2016/02/22 17:05:13, dak wrote:
> On 2016/02/21 12:17:12, simon.albrecht wrote:
> > I do think we should advertise the proper LilyPond syntax of
> > \keepWithTag A.B
> > here. It’s quite easier to type and nicer. I’d also prefer
> > \tag A {}
> > over
> > \tag #'A {}
> > but I don’t know if this is enough of a ‘standard’ – David?
> 
> Tags tended to be chosen in ways not matching a LilyPond "word", for example
> containing numbers.  Since they are not used as \word but only ever as
symbols,
> there was no incentive to choose them compatibly before x.y acquired a
> Scheme-level meaning.

Sigh.

OK that means nothing to me (gobbledygook) and now I don't know what to do with
this information and the Patch remains stuck.

From what I *think* this means you are saying that unless I use a naming
convention for my Tags that are 'simple' and without numbers or spaces or
something else I have to use #' i.e.

\keepWithTag #'(violin2) {a b c d} 

versus just 

\keepWithTag violin {a b c d}

?

It doesn't hurt to explain when someone needs to use '# and I can figure out how
to express that in the doc but I don't really understand fully what is being
discussed here.

https://codereview.appspot.com/279140043/diff/60001/Documentation/notation/in...
Documentation/notation/input.itely:2330: @code{#'D}.
On 2016/02/21 12:17:12, simon.albrecht wrote:
> I’d suggest
> 
> ‘will only print music tagged @code{A} or @code{B} (and untagged music).’
> 
> (Is it overkill to mark single letters as @code{}?)

No. Users don't read the 'source' for doc and if we'd need to (for example)
italicize the text we'd need to use markups for that too. 

But I should perhaps use @var instead of @code as these are ..what does the CG
call them? Ah yes.. 'metasyntactic variables'.

;)

[pkx166h, 2016-02-27 11:22:56]

@David or Federico

Could one or you (or some other kind soul) explain the comment from David
regarding his explanation of when (not) to use


\fooTag A {a b c d}
over
\fooTag #'A {a b c d}

and when (not) to use

\fooTag A.B {a b c d}
\fooTag #'(A B) {a b c d}

I assume the reasons are the same, but David's explanation is a little over my
head.

I can then perhaps re-work some of the examples in this section to make it
easier for users to understand and send us emails when they use the 'wrong' case
for either of the possible \fooTag syntaxes.

Thanks.

[dak, 2016-02-27 12:10:57]

On 2016/02/27 11:22:56, pkx166h wrote:
> @David or Federico
> 
> Could one or you (or some other kind soul) explain the comment from David
> regarding his explanation of when (not) to use
> 
> 
> \fooTag A {a b c d}
> over
> \fooTag #'A {a b c d}
> 
> and when (not) to use
> 
> \fooTag A.B {a b c d}
> \fooTag #'(A B) {a b c d}
> 
> I assume the reasons are the same, but David's explanation is a little over my
> head.

I was pointing out that historically we have not bothered choosing tag names
compatible with LilyPond names.  So if one wants to propose _not_ using #'... in
the documentation, one would need to go through the whole code base and make
sure that it actually uses LilyPond-compatible tag names everywhere in order not
to confuse people.

[pkx166h, 2016-02-27 12:21:48]

On 2016/02/27 12:10:57, dak wrote:
> On 2016/02/27 11:22:56, pkx166h wrote:
> > @David or Federico
> > 
> > Could one or you (or some other kind soul) explain the comment from David
> > regarding his explanation of when (not) to use
> > 
> > 
> > \fooTag A {a b c d}
> > over
> > \fooTag #'A {a b c d}
> > 
> > and when (not) to use
> > 
> > \fooTag A.B {a b c d}
> > \fooTag #'(A B) {a b c d}
> > 
> > I assume the reasons are the same, but David's explanation is a little over
my
> > head.
> 
> I was pointing out that historically we have not bothered choosing tag names
> compatible with LilyPond names.  So if one wants to propose _not_ using #'...
in
> the documentation, one would need to go through the whole code base and make
> sure that it actually uses LilyPond-compatible tag names everywhere in order
not
> to confuse people.

Thank you.

So, just to finish this off, the examples in the document use mainly 'A', 'B',
'C' etc. instead of 'real-world' strings (ViolinI, ViolinII and so on). I'd like
to put some real-world examples in there instead. I assume that if I want to use
labels with spaces in them (Violin I) I could put them in 'quotes' ("Violin I")?
I have had a (very) quick scan through the NR and LM where we state limitations
or rather requirements of allowed 'string' syntax for things like this.

Instrument names jumps out

Staff.instrumentName = #"Piccolo"

I know this is not the same as using a  '\' command and I don't need some
explanation here, but I also can find

\cueDuring #"flute"

In essence if we used quotes in the examples for the \Tag commands (assuming it
is valid to do so) would that cover all the possible use cases of how people
could write out tag labels?

I hope that made sense.

James

[mail_philholmes.net, 2016-02-27 12:30:56]

----- Original Message ----- 
From: <dak@gnu.org>
To: <pkx166h@gmail.com>; <fedelogy@gmail.com>; <simon.albrecht@mail.de>; 
<fede@inventati.org>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Saturday, February 27, 2016 12:10 PM
Subject: Re: Doc: NR: 3.x Clarification for \keepWithTag and fix Typo 
inexample (issue 279140043 by pkx166h@gmail.com)


> On 2016/02/27 11:22:56, pkx166h wrote:
>> @David or Federico
>
>> Could one or you (or some other kind soul) explain the comment from
> David
>> regarding his explanation of when (not) to use
>
>
>> \fooTag A {a b c d}
>> over
>> \fooTag #'A {a b c d}
>
>> and when (not) to use
>
>> \fooTag A.B {a b c d}
>> \fooTag #'(A B) {a b c d}
>
>> I assume the reasons are the same, but David's explanation is a little
> over my
>> head.
>
> I was pointing out that historically we have not bothered choosing tag
> names compatible with LilyPond names.  So if one wants to propose _not_
> using #'... in the documentation, one would need to go through the whole
> code base and make sure that it actually uses LilyPond-compatible tag
> names everywhere in order not to confuse people.
>
>
> https://codereview.appspot.com/279140043/

Or to give an example:

\tag #'Ex1
\tag Ex

are both OK, but

\tag Ex1

isn't, since the use of the digit makes the tagname not compatible with 
Lilypond naming.  So if you changed every example of \tag #' to \tag, you'd 
also need to be sure to check that the tagnames are compatible with Lilypond 
naming rules.

--
Phil Holmes

[dak, 2016-02-27 12:58:44]

On 2016/02/27 12:30:56, mail_philholmes.net wrote:

> \tag #'Ex1
> \tag Ex
> 
> are both OK, but
> 
> \tag Ex1
> 
> isn't, since the use of the digit makes the tagname not compatible with 
> Lilypond naming.  So if you changed every example of \tag #' to \tag, you'd 
> also need to be sure to check that the tagnames are compatible with Lilypond 
> naming rules.

The following command may be helpful:

git grep "#'[-_a-zA-A]\\+[^-_a-zA-Z \\n}]"

It turns out that most of the non-LilyPondable symbols contain a colon.  There
is also vaticana.punctum and friends.

fretted-headword.el strangely quotes lots of literal numbers.  There are things
like #'solo1 for the partcombiner.  With regard to actual tags,
string-quartet-template-with-separate-parts.ly contains vn1 and vn2 tags.

[HoangMinh, 2016-02-28 05:39:41]

On 2016/02/27 12:58:44, dak wrote:
> On 2016/02/27 12:30:56, http://mail_philholmes.net wrote:
> 
> > \tag #'Ex1
> > \tag Ex
> > 
> > are both OK, but
> > 
> > \tag Ex1
> > 
> > isn't, since the use of the digit makes the tagname not compatible with 
> > Lilypond naming.  So if you changed every example of \tag #' to \tag, you'd 
> > also need to be sure to check that the tagnames are compatible with Lilypond

> > naming rules.
> 
> The following command may be helpful:
> 
> git grep "#'[-_a-zA-A]\\+[^-_a-zA-Z \\n}]"
> 
> It turns out that most of the non-LilyPondable symbols contain a colon.  There
> is also vaticana.punctum and friends.
> 
> fretted-headword.el strangely quotes lots of literal numbers.  There are
things
> like #'solo1 for the partcombiner.  With regard to actual tags,
> string-quartet-template-with-separate-parts.ly contains vn1 and vn2 tags.

[pkx166h, 2016-03-01 20:08:56]

On 2016/02/22 12:55:12, fede_inventati.org wrote:
> Il giorno dom 21 feb 2016 alle 11:44, mailto:pkx166h@gmail.com ha scritto:
> > Thanks Federico - see inline for my replies.
> > 
> > 
> >
>
https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
> > File Documentation/notation/input.itely (right):
> > 
> >
>
https://codereview.appspot.com/279140043/diff/40001/Documentation/notation/in...
> > Documentation/notation/input.itely:2313:
> > On 2016/02/18 22:51:46, fedelogy wrote:
> >> Sorry, I'm still confused. I cannot see any link between the
> > explanation above
> >> and the snippet below.
> > 
> >> The snippet below explains \tagGroup, which is already explained (and
> > much
> >> better) immediately after. And the four strings example is more
> > effective than
> >> A, B, C, D.
> > 
> > OK I'll remove it.
> > 
> > It wasn't clear in your request in the Tracker/email msg what exactly
> > the point of the example you gave was. As I saw no @lilypond (just an
> > @example) that used \tagGroup but we have @lilypond for all the other
> > 'Tag' stuff (pushToTag, appendToTag, removeWithTag etc.) I assumed 
> > that
> > a reader would benfit from an example of this command as well.
> 
> Indeed my mind was confused when I reported and discussed the problem 
> with David in the mailing list.
> I confused the two different paragraphs (one about how to use 
> \keepWithTag, the other about \tagGroup).
> 
> Anyway, if you want to add a @lilypond example of \tagGroup, you should 
> do it after it is explained and not before.
> The \tagGroup item in the general index points to this paragraph:
>
http://lilypond.org/doc/v2.19/Documentation/notation/different-editions-from-...
> 
> So the @lilypond snippet - using violinI, violinII, viola, cello as 
> example - should go after this sentence: "will then only be concerned 
> with tags from violinI’s tag group: any element of the included music 
> that is tagged with one or more of tags from this set but not with 
> violinI will get removed."
> 
> For example:
> 
> @lilypond
> music = \relative {
>   \tagGroup #'(violinI violinII viola cello)
>   \tag #'violinI { c''4^"violinI" c c c }
>   \tag #'violinII { a2 a }
>   \tag #'viola { e8 e e2. }
>   \tag #'cello { d'2 d4 d }
>   R1^"untagged"
> }
> 
> \new Voice {
>   % print only music tagged with violinI and any untagged music
>   \keepWithTag #'violinI
>   \music
> }
> @end lilypond
> 
> > 
> >> The above paragraph is just about how to use \keepWithTag (it's a
> > continuation
> >> of the previous paragraph about \removeWithTag).
> > 
> > Yes but as I said above, without a corresponding @lilypond (just an
> > @example) that I could see. For someone who doesn't *already* 
> > understand
> > Tags I thought this would be helpful.
> > 
> >> It suggests using one command
> >> (a single tag or a list of tag), and avoiding multiple \keepWithTag
> > commands on
> >> a single music expression, otherwise everything will be removed.
> > 
> > I don't understands this. My version just uses slightly different 
> > words
> > as far as I can tell and removes a lot of unnecessary repetition and
> > adds the odd article and adverb.
> 
> I read it again and you are right.. I don't know what I read few days 
> ago.
> Please forget this comment :)
> 
> 
> 

OK I have attempted to figure out what you meant. It may still need some
polishing. It was difficult to parse as it was (too many uses of the word 'tag'
frankly) so I have tried to make it less 'taggy'. I hope it is still correct.

[pkx166h, 2016-03-01 20:09:58]

More for Federico B

[fedelogy, 2016-03-03 11:53:51]

On 2016/03/01 20:09:58, pkx166h wrote:
> More for Federico B

LGTM, thanks

[pkx166h, 2016-04-23 08:56:51]

rebase with current master

[pkx166h, 2017-03-12 18:35:00]

author James Lowe pkx166h@gmail.com
Thu, 18 Feb 2016 10:43:09 +0000 (10:43 +0000)
committer James Lowe pkx166h@gmail.com
Thu, 28 Apr 2016 06:41:48 +0000 (07:41 +0100)
commit c5847c9329abba798fb15bb336c7247ab149660b