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

On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht [off-list ref] wrote:

The 21/05/09, Felipe Contreras wrote:

quoted

On Thu, May 21, 2009 at 7:15 AM, Jeff King [off-list ref] wrote:

quoted

On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:

quoted

quoted

quoted

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.

quoted

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.

Yes, I wanted delimit "example-master", just like quotation marks are
normally used, but after it has been denoted there's no more point in
doing that over an over.

For example:
He referred to his friend as "John". But unlike him, "John" was very quiet.

The quotes make sense on the first sentence, but not on the second.

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

No, asciidoc only has support for: emphazised, strong, monospace,
single-quoted and double-quoted. No colors or anything fancy.

Not all branch names are equal; "master" is not the same as
"mybranch". "master" has a special meaning, therefore it should be in
monospace, but "mybranch" is simply a branch name, therefore it should
be emphazied. If the branch name is complicated you might want to
delimit it with double quotes: "my-fooish-bar-branch", at least the
first time you mention it.

File names is a similar story; ".gitignore" is not the same as "test.c".

quoted

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 disagree. There are no absolutes when writing human-readable documents.

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?

I have a bunch of patches and this was supposed to be the uncontroversial one =/

-- 
Felipe Contreras