Re: [PATCH v5 11/12] doc: revisions: show revision expansion in examples

From: Marc Branchaud <marcnarc@xiplink.com>
Date: Aug 12, 2016, 15:22 UTC
Message-ID: <f418c41b-f590-0b6a-236a-c109a7296434@xiplink.com>
In-Reply-To: <20160812070749.2920-12-philipoakley@iee.org>

On 2016-08-12 03:07 AM, Philip Oakley wrote:

Show 28 quoted lines

> 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 <philipoakley@iee.org>
> ---
> new
> Cc: Jakub Narębski <jnareb@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...)

Show 14 quoted lines

>     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.

M.