Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Felipe Contreras <felipe.contreras@gmail.com>]

On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> wrote:
> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:
>
>> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/
>> >
>> > Thank you very much Felipe to take the time to upload the patches there.
>> > I already have a copy there and I'll look at it soon.
>>
>> Has anybody looked at this?  It's a bit large-ish and touches all over the
>> place, so I am finding it a bit hard to concentrate on it myself really
>> nitpicking, but from the cursory look after formatting the result looked
>> Ok.
>
> I started to, but the first commit message is lacking something that I
> think would make reviewing much simpler: what are the general classes of
> changes that are being made?
>
> I see some doublequotes becoming backticks, and some becoming single
> quotes. And some becoming tex-quotes (``...''), and even some becoming
> doublequotes _with_ single quotes. It would be easier to verify that
> they are doing the right thing if the commit message briefly described
> the rules it followed for changing each one. I think they are something
> like:
>
>  - tex-quotes if it was really a prose-style quotation
>
>  - backticks (causing monospace) for branch names, commands, etc in
>    prose
>
> but that leaves me confused. Some things which I thought should be in
> monospace backticks are in single-quotes (causing emphasis). Like
> 'master' or 'linux-2.6'. And some things are emphasized and in double
> quotes in the prose, like '"o"' or '"branch A"'. What is the rule to
> decide which text should have visible doublequotes but also be
> emphasized, as opposed to just having double-quotes or just being
> emphasized?
>
> Maybe this was even discussed earlier in the thread (I didn't go back to
> look), but it should definitely be part of the commit message.

The rule I followed is: change it to whatever looks best.

I followed some guidelines such as: make common text monospace, such
as gitk and master. And emphasize whatever needs emphasizing, such as
fb47ddb2db. Examples are both monospace *and* emphasized.

Sometimes the end result still didn't look good so I just used
whatever looked best.

Have you actually looked at the end result?

-- 
Felipe Contreras