Re: changes to Clef

[Carl Sorensen]

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