|
|
Created:
8 years, 4 months ago by pkx166h Modified:
7 years, 1 month ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionA 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.
Patch Set 1 #Patch Set 2 : Additional corrections and updates by Federico B #Patch Set 3 : Fix Typo that breaks make doc. #
Total comments: 2
Patch Set 4 : With Federico B's comments and corrections. #
Total comments: 7
Patch Set 5 : More for Federico B #Patch Set 6 : rebase with current master #MessagesTotal messages: 20
Additional corrections and updates by Federico B
Sign in to reply to this message.
Fix Typo that breaks make doc.
Sign in to reply to this message.
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 }
Sign in to reply to this message.
With Federico B's comments and corrections.
Sign in to reply to this message.
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.
Sign in to reply to this message.
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{}?)
Sign in to reply to this message.
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 :)
Sign in to reply to this message.
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.
Sign in to reply to this message.
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'. ;)
Sign in to reply to this message.
@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.
Sign in to reply to this message.
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.
Sign in to reply to this message.
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
Sign in to reply to this message.
----- 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
Sign in to reply to this message.
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.
Sign in to reply to this message.
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.
Sign in to reply to this message.
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.
Sign in to reply to this message.
More for Federico B
Sign in to reply to this message.
On 2016/03/01 20:09:58, pkx166h wrote: > More for Federico B LGTM, thanks
Sign in to reply to this message.
rebase with current master
Sign in to reply to this message.
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
Sign in to reply to this message.
|