Peter Kjellerstedt venit, vidit, dixit 28.06.2010 12:03: >> -----Original Message----- >> From: git-owner@xxxxxxxxxxxxxxx [mailto:git-owner@xxxxxxxxxxxxxxx] On >> Behalf Of Michael J Gruber >> Sent: den 28 juni 2010 10:18 >> To: git@xxxxxxxxxxxxxxx >> 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@xxxxxxxxx> >> Signed-off-by: Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> >> --- >> 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. > >> 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. > >> 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html