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

From: Nicolas Sebrecht <nicolas.s.dev@gmx.fr>
Date: May 21, 2009, 13:18 UTC
Message-ID: <20090521131802.GA13840@vidovic>
In-Reply-To: <94a0d4530905210017x1ce3e32bk3b1fbf9044377763@mail.gmail.com>

The 21/05/09, Felipe Contreras wrote:

Show 39 quoted lines

> 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.

Agreed.

Show 8 quoted lines

> 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.

IHMO, "what looks best" is not the best way to enhance the user manual because it may be somewhat confusing.

Without being as strict as in the manpages we should have good rules to display the commands, branch names, etc to the end-users all over the manual (think SYNOPSIS). For example, all branch names in the text could be "italic, green, without quotes". Now, in the paragraph "Fetching individual branches" we have

  will create a new branch named '"example-master"' and store in it the
  branch named '"master"' from the repository at the given URL.  If you
  already have a branch named 'example-master', it will attempt to

where the branch name /example-master/ has two different occurences _with_ and _without_ quotes.

This is for the end user part. For the contributers, the commit could say:

" - branch names: uses the form 'branch-name' to appear in green,
    italic.
  - file names: uses [...] to appear in [...]
  - refspec: uses [...] to appear in [...]
  - etc.
"

> Have you actually looked at the end result?

Yes, I think it's much better with your patch but "display-types" should follow the same rules all over the text.

I'm missing of time theses days. I think I'll could help you in one or two weeks I you want. It's an ant work. :-) AFAICT, some people here want to rewrite the manual, right? Maybe it could be done with this rewriting?

-- 
Nicolas Sebrecht