Re: [PATCH] git-rev-parse.txt: Add more examples for caret and colon

Peter Kjellerstedt venit, vidit, dixit 28.06.2010 12:03:

quoted

-----Original Message-----
From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
Behalf Of Michael J Gruber
Sent: den 28 juni 2010 10:18
To: git@vger.kernel.org
Cc: Junio C Hamano; Matthieu Moy
Subject: [PATCH] git-rev-parse.txt: Add more examples for caret and
colon

Several items in the caret, colon and friends section contain examples
already. Make sure they all come with examples, and that examples come
early so that they serve as a visual guide, as well.

Suggested-by: Junio C Hamano <redacted>
Signed-off-by: Michael J Gruber <redacted>
---
This is on top of the ":path" patch to git-rev-parse.txt.

I chose not to rewrap the paragraphs so that the diff is clearer,
especially with --color-words.
I don't know what the best patch workflow guideline is here. Maybe
rewrapping a v2?

 Documentation/git-rev-parse.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-

parse.txt
index d525e57..da5cdf4 100644

--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt

@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the

`$GIT_DIR/packed-refs` file.
   the branch the ref is set to build on top of.  Missing ref defaults
   to the current branch.

-* A suffix '{caret}' to a revision parameter means the first parent of
+* A suffix '{caret}' to a revision parameter (e.g. "HEAD^") means the first parent of

Shouldn't that be

* A suffix '{caret}' to a revision parameter (e.g. `HEAD{caret}`) means the first parent of

for consistency?

Both of them render the same with my asciidoc. I don't mind making it
consistent.

~ and ^ are dangerous with asciidoc 8, but we compile with
asciidoc7compatible, so this is a non-issue.

quoted

   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
   'rev{caret}'
   is equivalent to 'rev{caret}1').  As a special rule,

@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   and dereference the tag recursively until a non-tag object is
   found.

-* A colon, followed by a slash, followed by a text: this names
+* A colon, followed by a slash, followed by a text (e.g. ":/fix nasty bug"): this names

Most examples in this file seem to use `` rather than "".

I did not do the statistics, many use `, many use ', and many use ".
The first two often render in the same way.

quoted

   a commit whose commit message starts with the specified text.
   This name returns the youngest matching commit which is
   reachable from any ref.  If the commit message starts with a
   '!', you have to repeat that;  the special sequence ':/!',
   followed by something else than '!' is reserved for now.

-* A suffix ':' followed by a path; this names the blob or tree
+* A suffix ':' followed by a path (e.g. "HEAD:README"); this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon. ":path" (with an empty part before the colon)
+  before the colon.
+  ":path" (with an empty part before the colon, e.g. ":README")
   is a special case of the syntax described next: content
   recorded in the index at the given path.

 * A colon, optionally followed by a stage number (0 to 3) and a
-  colon, followed by a path; this names a blob object in the
-  index at the given path.  Missing stage number (and the colon
-  that follows it) names a stage 0 entry. During a merge, stage
+  colon, followed by a path (e.g. ":0:README"); this names a blob object in the
+  index at the given path. Missing stage number (and the colon
+  that follows it, e.g. ":README") names a stage 0 entry. During a merge, stage
   1 is the common ancestor, stage 2 is the target branch's version
   (typically the current branch), and stage 3 is the version from
   the branch being merged.
--
1.7.1.621.g01d76

I tried to find a document describing documentation standards for 
git (i.e., something similar to Documentation/CodingGuidelines),
but could not find any such document. Did I just miss it, or does
it not exist?

Ironically, I have tried to suggest something like that, together with a
series of patches implementing that. Feel free to try again ;)

As a general practical rule, I think we try to stay "locally
consistent", i.e. within the surrounding context.

For current asciidoc:
'foo' is emphasized
`foo` is monospaced and literal (not expanded)
`foo' is enclosed in single quotation marks
``foo'' is enclosed in double quotation marks

(In fact, for us `foo` is not foo because we compile with
no-inline-literal to shut off asciidoc 8.4 changes for inline literals.)

Michael