Dear Patrick, I made a mistake in pushing your patch, because I did not verify first that it met the LilyPond documentation standards.
The documentation standards are found in sections 4.4 and 4.5 of the Contributor's Guide. <http://lilypond.org/doc/v2.13/Documentation/contributor/tips-for-writing-do cs> I've responded to Graham's comments below. I have made the changes that I discuss. On 1/30/10 9:38 PM, "Graham Percival" <gra...@percival-music.ca> wrote: > Carl, why did you push the recent change to Clef? > > 1. no contractions, please. I'm not convinced about the new > language there, anyway -- what about "(but are not required to > be)" ? I have eliminated the contraction, and changed the language to "do not need to be". > > 2. we have a policy of "show, don't tell". Why did we remove > \clef G, F, C from the example? I have restored the clefs to the examples. > If there's a desire to emphasize the abbreviated nature -- and > really, "abbreviated" is not the right word, since G is not an > abbreviation of "treble" -- a comment in the @lilypond would do > this. Instead of "abbreviated", I've used the word "synonym". And instead of explaining it in the text, I've commented it in the example, which is a verbatim example so the user can see it. Patrick, we have a policy to mostly keep LilyPond syntax in the examples, where convert_ly can take care of them. I didn't review your patch carefully for this. > > 3. wrap lines at 72 chars, please. That's not always possible > with scheme code, but it's definitely doable with normal texinfo. > I missed the one place this was done. I have now fixed it. Patrick, I should have caught this when you asked about soft returns. I'm sorry I missed it. No soft returns in the doc files, please. > > 5. don't refer to an "example above" if at all possible; the > referred format is "text, verbatim, image". I'm not conviced we > need to specifically need to mention g^8; I mean, we don't > specifically mention treble^8, do we? Instead of describing it in text following the example, I just added a couple of the equivalent transposing texts to the example. And I changed the statement about "underscores, circumflexes, and numbers" to "non-alphabetic characters", which I think is both simpler and more correct. I hope I haven't frustrated you by doing this. Thanks for your concern for improving the docs, especially for those areas related to tablature. I'll do a better job reviewing next time. Thanks, Carl _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
