[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: changes to Clef
From: |
Carl Sorensen |
Subject: |
Re: changes to Clef |
Date: |
Sat, 30 Jan 2010 23:52:31 -0700 |
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" <address@hidden> 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