Peter Kjellerstedt venit, vidit, dixit 28.06.2010 12:03:
quoted text
>> -----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 <gitster@pobox.com>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> 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 text
> 
>>    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 text
> 
>>    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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html