Re: changes to Clef

[Carl Sorensen]

On 1/31/10 11:55 AM, "Patrick Schmidt" <address@hidden> wrote:

> 
> 
> -------- Original-Nachricht --------
>> Datum: Sat, 30 Jan 2010 23:52:31 -0700
>> Von: Carl Sorensen <address@hidden>
>> An: "address@hidden" <address@hidden>, Patrick Schmidt
>> <address@hidden>
>> CC: Graham Percival <address@hidden>
>> Betreff: Re: changes to Clef
> 
>> Dear Patrick,
>> 
>> I made a mistake in pushing your patch, because I did not verify first
>> that
>> it met the LilyPond documentation standards.
>> 
> I'm sorry for that.

No problem. It's not your fault, it's mine.
>>> 
>>> 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.
> OK, so how about placing them closer to the treble, alto and bass clefs to
> show that they can be used alternatively?

I'd be fine to have \treble \G \tenor \C \bass  \F.  If you'd like to
prepare a patch with this, go ahead.
>>> 
>>> 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.
> This is something I haven't understood. Before I edited the file with (GNU
> Emacs 22.3.1) I activated "Hard word wrap" thus deactivating "Soft word wrap"
> because I thought that this would solve the problem of soft returns. (You had
> mentioned this problem in context with a patch I committed a couple of months
> ago.) I checked the settings for the number of chars per line and Emacs
> returned that the value of fill-column is 70. Is it possible that I just have
> to remember to *always* press Enter at the end of a paragraph and Emacs will
> wrap the lines automatically at 70 chars?

I'm sorry, but I can't help you with this, as I don't use emacs.

We need to have a setting in emacs that will lead to \n characters at the
end of each line of about 70 characters.  You should be able to test this by
editing a file, then opening up a very wide window and typing

cat myfile

to display the file in the terminal window. If lines are longer than 70
characters, then the setting isn't right yet.

>> 
>>> 
>>> 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?
> Well, *I* did not mention G^8!

Right.  The main idea here is that we put an explanation, then put the
needed information in the examples following the explanation.  We try never
to put text *after* an example that refers back to the example.
>> 
>> 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.
> I'm not frustrated because I need your feedback to improve. I'm awfully sorry
> for increasing your workload instead of reducing it. I just wanted to help but
> maybe I do the opposite. Some of Graham's comments also make me doubt whether
> my english is up to standard.
> 
> So should I proceed as discussed?

Your english is definitely up to standard.  None of the problems were
problems of improper english (except maybe the "abbreviation" vs. "synonym"
difference).

Had I been doing my job properly, I'd have given a review similar to the one
Graham gave, and then you'd have learned, and your next patch would be
better.

Instead, I prematurely pushed the patch.  Graham caught it, and because I
had pushed it, I felt like I should fix it instead of sending it back to you
for another revision.  Maybe I should have just reverted it, and sent it
back to you for your comments.

Please do proceed as discussed, and I'll be more careful in my future
reviews.  You will come to understand what we're looking for, and then your
patches will be excellent, and you'll save us tremendous amounts of time.

Thanks,

Carl