Fwd: [PATCH] Man page section reference should be in uppercase

From: Nazri Ramliy <ayiehere@gmail.com>
Date: May 26, 2010, 08:33 UTC
Message-ID: <AANLkTingglKSMHOcHXTg3hGF_czcFsnWLTd3GuSp-Mm6@mail.gmail.com>
In-Reply-To: <AANLkTilKSLCGMgHwB4TdojtemnxYLrGsAJGHQcLJNVwL@mail.gmail.com>

I forgot to reply to the list as well when sending the (now forwarded) message below.

Apparently only Dévai Tamás received it, and replied to me:

Dévai Tamás wrote to me:

> I didn't know that. Thanks for pointing out.

Apology for the top-posting-ish nature of this email.

I guess when forwarding an email verbatim, it's ok to top post it with a header of some sort?

nazri.

---------- Forwarded message ----------
From: Nazri Ramliy <ayiehere@gmail.com>
Date: Wed, May 26, 2010 at 9:52 AM
Subject: Re: [PATCH] Man page section reference should be in uppercase
To: Dévai Tamás <devait@vnet.hu>

On Wed, May 26, 2010 at 2:45 AM, Dévai Tamás <devait@vnet.hu> wrote:

Show 10 quoted lines

> I don't really agree with this, but it might be only my personal
> preference. Reasons:
>
> The section title in the man page is "typeset" in a "different font" to
> be easily distinguishable from the surrounding text -- therefore it's
> all capital. On the other hand, changing the reference in the advice
> given by git-push to be all uppercase will give a needless emphasis on
> the referred section title. This is wrong IMHO, because the main point
> of the advice is not this reference, but the earlier sentences (i.e. the
> push was rejected).

Keeping the reference to be in lowercase goes against what is currently practiced the man pages of git commands. Have a look at the output of

       $ git grep '"[A-z ]\+" section'

See how all of them use all-caps when referring to man page sections.

If the user is already familiar with the non-fast-forward push issue, they would know how to proceed and ignored the 'needless' emphasis.

But for a user who is clueless about the non-fast-forward push issue the emphasis is good and even more important than that is that it is spelled out in the same exact form as how it will be rendered when the user run 'git push --help', IMHO.

nazri.