From: Jeff King <peff@peff.net>
Date: Sat, 14 Mar 2009 20:34:35 GMT
Subject: Re: [PATCH] git-push.txt: describe how to default to pushing only current branch
Message-ID: <20090314203434.GA15444@coredump.intra.peff.net>
In-Reply-To: <7vd4cjc3da.fsf@gitster.siamese.dyndns.org>

On Fri, Mar 13, 2009 at 08:27:31PM -0500, Chris Johnsen wrote:

> In the resulting manpage the inline commands are not very
> obvious (the HTML looks OK though). There is some sort of
> formatting in there, but it does not seem to display any
> differently from the surrounding text when I use man to view it
> on my system.  Would it be better to do something like wrap
> double quotes around the inline commands to help readers viewing
> the manpage?

The problem is that they are supposed to set in a monospaced font, but
most terminals are already monospaced. This is actually a problem
throughout the documentation, although it is usually only for
single-word phrases (like `git-foo`), which don't look nearly as bad as
multi-word ones.

Actually, looking closer, the information seems to be lost entirely.
Asciidoc renders this to <literal> in the XML, but docbook seems to
throw it away when converting to a manpage. In theory it's possible to
apply our own xsl style to turn this into something else, and I think
that is a better solution than just trying to fix this one spot.

The question is how it _should_ be rendered. Monospace isn't really
useful for terminals. Maybe simply putting quotation marks around it
would cover all situations (I'm worried it will look funny for
single-word instances).


On Sat, Mar 14, 2009 at 12:26:41PM -0700, Junio C Hamano wrote:

> The new text looks reasonable.  Sign-off?
> 
> Any improvement suggestions from others?

It looks fine to me; my only concern is the typesetting, but I think
that should be fixed elsewhere, as outlined above.

-Peff