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