Re: [PATCH v2 1/2] user-manual: general quoting improvements (p1)

[Daniel <mjucde@o2.pl>]

> This standarizes the way quotes are handled following semantic rules,
> that make the final text easier to read.
> 
> Here are the general rules:
> 
>  * A command (something that the user must type), goes in backticks. So
>    that the final text appears in monospaced text. e.g. `git clone
>    <repo>`
> 
>  * A common concept (or git lingo), also goes in backticks. So that it
>    appears uniquely different from the rest of the text. e.g. `HEAD`
> 
>  * An example (something that can be easily replaced), goes into
>    typewriter quotes. The final text is not formatted further, so they
>    still appear as typewriter quotes. e.g. "linux-2.6"
> 
>  * A text that can be confused with normal text also goes into
>    typewriter quotes. e.g. "path/to/file" "A"
> 
>  * Text that needs to be emphasized goes in single typewriter quotes. So
>    that it's not confused as normal text. e.g. we often just use the
>    term 'branch'.
> 
>  * Something that needs proper quotation goes into proper double quotes.
>    So that it gets a dramatic effect, as in sombody is using his four
>    quoting fingers. e.g. ``the index''
> 
>  * Something that needs strong emphasis so that the reader can't
>    possibly miss it goes enclosed in asterisks. e.g. *not* tracking
> 
> These rules are not automatic, which one to use depends on the context,
> and often they can be used together. For example, consider this:
> 
> 	The branch 'test' is short for '"refs/heads/test"'
> 
> In this case we want to highligh 'test' and 'refs/heads/test' so they go
> in single typewriter quotes, but also, we want to make clear the full
> refname is not confused as multiple words, so it goes inside double
> typewriter quotes.
> 
> Also, sometimes a text can be both a command, and an example, but only
> one quoting format must be chosen.
> 
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>

Maybe [regardless of its meritorical corectness) this is worth putting
in a separate file in Documentation/ so that people sending patches to
documentation will at least have a chance to read quoting rules and not
use quotes randomly.

-- Daniel