Re: [PATCH 7/7] rev-list-options.txt

[Derrick Stolee <stolee@gmail.com>]

On 5/17/2020 2:52 PM, Martin Ågren wrote:
> The explanation of the `--show-pulls` option added in commit 8d049e182e
> ("revision: --show-pulls adds helpful merges", 2020-04-10) consists of
> several paragraphs and we use "+" throughout to tie them together in one
> long chain of list continuations. Only thing is, we're not in any kind
> of list, so these pluses end up being rendered literally.
> 
> The preceding few paragraphs describe `--ancestry-path` and there we
> *do* have a list, since we've started one with `--ancestry-path::`. But
> we don't have a similar list running here. We could tie all our
> paragraphs from 8d049e182e to that list, but that doesn't make much
> sense: We aim to describe another option entirely.
> 
> We could start a new list item:
> 
>  --show-pulls:
>     Before discussing another option, `--show-pulls`, we need to
>     create a new example history.
>  +
>     ...
> 
> That reads somewhat awkwardly to me. Not to mention that the chain of
> paragraphs that follows is fairly long, introducing a new example
> history and discussing it in quite some detail. Let's make this run
> along without any kind of indentation. It effectively means that we're
> treating "Before discussing..." as a paragraph on the same level as
> "There is another simplification mode available:" which precedes the
> `--ancestry-path::` list.
> 
> If we really want a `--show-pulls::` list somewhere, we could perhaps
> let it begin around "The `--show-pulls` option helps with both of these
> issues ..." further down. But for now, let's just focus on getting rid
> of those literal pluses.

I think the way you adjusted the preamble is good. It matches this prior
work before --ancestry-path:

	Finally, there is a fifth simplification mode available:

	--ancestry-path::
		(description)
	+
	(example)
	+
	...

And you're right, we do drop the "--show-pulls::" itemization. Will that
make it hard to link to that exact option? Probably.

What about the fixup below, to create this list item?

Thanks,
-Stolee

-- >8 --

From 6416bbc14fbdb21868c6f3b609f66e5fe5607265 Mon Sep 17 00:00:00 2001
From: Derrick Stolee <dstolee@microsoft.com>
Date: Mon, 18 May 2020 10:55:59 -0400
Subject: [PATCH] fixup! rev-list-options.txt

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/rev-list-options.txt | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 48e37e2456..b01b2b6773 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -672,25 +672,28 @@ into the important branch. This commit may have information about why
 the change `X` came to override the changes from `A` and `B` in its
 commit message.
 
-The `--show-pulls` option helps with both of these issues by adding more
-merge commits to the history results. If a merge is not TREESAME to its
-first parent but is TREESAME to a later parent, then that merge is
+--show-pulls::
+	In addition to the commits shown in the default history, show
+	each merge commit that is not TREESAME to its first parent but
+	is TREESAME to a later parent.
++
+When a merge commit is included by `--show-pulls`, the merge is
 treated as if it "pulled" the change from another branch. When using
 `--show-pulls` on this example (and no other options) the resulting
 graph is:
-
++
 -----------------------------------------------------------------------
 	I---X---R---N
 -----------------------------------------------------------------------
-
++
 Here, the merge commits `R` and `N` are included because they pulled
 the commits `X` and `R` into the base branch, respectively. These
 merges are the reason the commits `A` and `B` do not appear in the
 default history.
-
++
 When `--show-pulls` is paired with `--simplify-merges`, the
 graph includes all of the necessary information:
-
++
 -----------------------------------------------------------------------
 	  .-A---M--.   N
 	 /     /    \ /
@@ -699,7 +702,7 @@ graph includes all of the necessary information:
 	  \ /      /
 	   `---X--'
 -----------------------------------------------------------------------
-
++
 Notice that since `M` is reachable from `R`, the edge from `N` to `M`
 was simplified away. However, `N` still appears in the history as an
 important commit because it "pulled" the change `R` into the main
-- 
2.27.0.rc0