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

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

On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@gmx.fr> wrote:
> The 21/05/09, Felipe Contreras wrote:
>> 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.
>
>> 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".

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