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

El 21/5/2009, a las 17:47, Felipe Contreras escribió:

On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@gmx.fr 

quoted

wrote:
The 21/05/09, Felipe Contreras wrote:

quoted

On Thu, May 21, 2009 at 7:15 AM, Jeff King [off-list ref] wrote:

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

quoted

quoted

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.

It is human-readable, but for the purposes of this discussion it is  
much more relevant that it is a _technical_ document.

All good technical documentation that I've seen adheres to consistent  
standards for display types. A "how to read this book" section in  
which the formatting of the different types appears is extremely  
widespread, standard practice.

Here's a very brief sampling for you:

http://svnbook.red-bean.com/nightly/en/svn.preface.conventions.html
"Conventions used in this book", from the SVN Book

http://www.freebsd.org/doc/en/books/handbook/book-preface.html
"Conventions used in this book", from the FreeBSD Handbook

http://oreilly.com/catalog/debian/chapter/book/prf1_02.html
"Conventions used in this book", from O'Reilly's "Learning Debian" book

If you're interested, a Google search for "Conventions used in this  
book" will net you about 58,000 results to persuse.

Not only are people used to understanding texts written using this  
kind of guideline, but it makes it easier for contributors as well if  
their a clear-cut conventions for different display types. They  
obviate the need for you to explain your reasoning about why "master"  
is somehow different from "mybranch", and why it should be formatted  
differently etc.

Cheers,
Wincent