On 2016-08-12 03:07 AM, Philip Oakley wrote:
The revisions examples show the revison arguments and the selected
commits, but do not show the intermediate step of the expansion of
the special 'range' notations. Extend the examples, including an
all-parents multi-parent merge commit example.

Sort the examples and fix the alignment for those unaffected
in the next commit.

Signed-off-by: Philip Oakley <philipoak...@iee.org>
Cc: Jakub Narębski <jna...@gmail.com>
 Documentation/revisions.txt | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 70864d5..ac7dd8e 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -326,16 +326,23 @@ Revision Range Summary
   as giving commit '<rev>' and then all its parents prefixed with
   '{caret}' to exclude them (and their ancestors).

-Here are a handful of examples:
+Here are a handful of examples using the Loeliger illustration above:

+   Args   Expansion       Selection

I think "Result" would be better than "Selection" here.

Also, shouldn't all the ^ in these examples be {caret}? (I likely just don't understand the rationale for using {caret} in some places and ^ in others...)

    D                G H D
    D F              G H I J D F
    ^G D             H D
    ^D B             E I J F B
-   B..C             C
-   B...C            G H D E B C
+   B..C   = ^B C          C
+   B...C  = B ^F C        G H D E B C
    ^D B C           E I J F B C
    C                I J F C
-   C^@              I J F
-   C^!              C
-   F^! D            G H D F
+   C^@    = C^1

I have a mixed reaction to showing this "C^1" expansion, and the "B^1 B^2 B^3" one as well. I see the appeal of showing the parent notation, but really that was already explained to death in the first section. Here it's distracting. I think it's clearer for the reader to remove these expansions and just use the node names from the illustration.

+          = F             I J F
+   B^@    = B^1 B^2 B^3
+          = D E F         D G H E F I J
+   C^!    = C ^C^1

I think this expansion might be better expressed as "C ^C^@". It'll be the same for "B^! = B ^B^@" as well, which demonstrates a nice consistency and also helps to emphasize the meaning of the ^@ notation.

+          = C ^F          C
+   B^! = B ^B^1 ^B^2 ^B^3
+       = B ^D ^E ^F       B

The layout of these last two lines doesn't match the others. They should be:

   B^!    = B ^B^1 ^B^2   ^B^3
          = B ^D ^E ^F    B

I see that the next patch fixes the layout of the unchanged examples, but it leaves these two unaligned.


To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to