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

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

On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Felipe Contreras venit, vidit, dixit 21.05.2009 09:17:
>> 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.
>>
>> 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.
>
> I think that's a bit of a "quick and dirty" approach. Man pages and user
> manual should use semantic markup. The matter of "looks" is up to the
> documentation tool chain, i.e. the style sheets etc. for the various
> backends.
>
> So we would need:
>
> - a documentation "style guide" which tells you how to do the semantic
> markup, such as `cmd` for commands, 'foo' for emphasis etc.
>
> - maybe some changes to the style sheets etc. which make the semantic
> markup "look good"
>
> The standard transformations which come with asciidoc/docbook can serve
> as a guide.

There's already a guide: the asciidoc user-guide... you can only go as
far as asciidoc lets you. `` for monospace, '' for emphasis, ``'' for
double quotes.

I have a problem with clear-cut rules such as: `cmd` for commands.

Do you think all these are the same?
The `git clone` command allows you to...
You can do that by doing '"git commit -a -m Example"'
Please refer to linkgit:git-add[1]

If you are reading the text you'll see that the 3 usages have different intents.

>> Have you actually looked at the end result?
>>
>
> No. My attempts at doing systematic changes (rather than modifying
> single pages without a clear target) have failed, so I've been keeping
> out of this business...

It's one click away:
http://people.freedesktop.org/~felipec/git/user-manual/user-manual.html

-- 
Felipe Contreras