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@xxxxxx
> wrote:
The 21/05/09, Felipe Contreras wrote:
On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@xxxxxxxx> 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".
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html