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

[Michael J Gruber <git@drmicha.warpmail.net>]

Felipe Contreras venit, vidit, dixit 21.05.2009 17:57:
> 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 am sorry but I don't think you fully comprehend the documentation tool
chain. Asciidoc translates the *.txt according to config files which
come with asciidoc and can be (and are, in our case) modified. It
translates into xml (for man pages) which is semantic markup. Even at
that step, there are more options - the standard asciidoc.conf (asciidoc
8) has:

[quotes]
# Constrained quotes.
*=strong
'=emphasis
`=monospaced
``|''=quoted
ifdef::asciidoc7compatible[]
\##=unquoted
endif::asciidoc7compatible[]
ifndef::asciidoc7compatible[]
\#=unquoted
_=emphasis
+=monospaced
# Unconstrained quotes.
**=#strong
__=#emphasis
++=#monospaced
\##=#unquoted
^=#superscript
~=#subscript
endif::asciidoc7compatible[]

So, you see we could use quite a few more quote designators if we wished
to. We only needed ' and _ to be different, for example.

Backend specific config files determine what "emphasis" is translated
into: an <emphasis> tag for docbook-xml, an <em> tag (with attributes)
for xhtml.

Then, for man page format, docbook style sheets are applied (using
xsltproc or such) to the xml files. The final appearance is determined
by those sheets. (For html, it's merely css applied by the browser.)

The asciidoc manual really only explains example usage with the default,
unmodified config files.

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

Yes, which is why I said "for example", and why a guide needs some
thinking. Or I would have come up with one...

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

I guess you completely misunderstood my remark (and I may very well be
the one to blame for that), and it doesn't matter in the context of this
thread. I have no problems formatting the user-manual, thanks to the
recent addition of ASCIIDOC_NO_ROFF ;)

Michael