Git Mailing List Archive on lore.kernel.org
 help / color / Atom feed
From: "Martin Ågren" <martin.agren@gmail.com>
To: Derrick Stolee <stolee@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>
Subject: Re: [PATCH 7/7] rev-list-options.txt
Date: Mon, 18 May 2020 20:37:14 +0200
Message-ID: <CAN0heSo_Y2Esp8X_amPXKaGaOVbP5rnJAyXiuUuW5BFSmwzhwA@mail.gmail.com> (raw)
In-Reply-To: <34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com>

Hi Stolee,

(I realize now that the subject/oneliner of this patch is completely
broken. Hmpf.)

On Mon, 18 May 2020 at 16:57, Derrick Stolee <stolee@gmail.com> wrote:
>
> On 5/17/2020 2:52 PM, Martin Ågren wrote:
> > 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?

I considered creating the list item, but like you, I figured it required
more surgery to the text than I felt like pursuing. Thanks for making a
concrete suggestion.

> -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 currently have the commit message below for my patch plus your fixup.

Thanks,
Martin

    rev-list-options.txt: start a list for `show-pulls`

    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::`. In
    fact, we have several such lists for all the various history-simplifying
    options we're discussing earlier in this file.

    Thus, we're missing a list both from a consistency point of view and
    from a practical rendering standpoint.

    Let's start a list for `--show-pulls` where we start actually discussing
    the option, and keep the paragraphs preceding it out of that list. That
    is, drop all those pluses before the new list we're adding here.

    Helped-by: Derrick Stolee <stolee@gmail.com>
    Signed-off-by: Martin Ågren <martin.agren@gmail.com>

  reply index

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-17 18:52 [PATCH 0/7] Documentation fixes for v2.27.0-rc0 Martin Ågren
2020-05-17 18:52 ` [PATCH 1/7] date-formats.txt: fix list continuation Martin Ågren
2020-05-17 18:52 ` [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3) Martin Ågren
2020-05-17 19:23   ` Eric Sunshine
2020-05-17 19:27     ` Martin Ågren
2020-05-18 10:54       ` Jean-Noël Avila
2020-05-18 11:15         ` Martin Ågren
2020-05-17 18:52 ` [PATCH 3/7] git-commit-graph.txt: fix grammo Martin Ågren
2020-05-18 14:46   ` Derrick Stolee
2020-05-17 18:52 ` [PATCH 4/7] git-commit-graph.txt: fix list rendering Martin Ågren
2020-05-17 18:52 ` [PATCH 5/7] git-credential.txt: use list continuation Martin Ågren
2020-05-18 23:06   ` Carlo Marcelo Arenas Belón
2020-05-17 18:52 ` [PATCH 6/7] git-sparse-checkout.txt: add missing ' Martin Ågren
2020-05-18 14:46   ` Derrick Stolee
2020-05-17 18:52 ` [PATCH 7/7] rev-list-options.txt Martin Ågren
2020-05-18 14:57   ` Derrick Stolee
2020-05-18 18:37     ` Martin Ågren [this message]
2020-05-18 20:22       ` Junio C Hamano
2020-05-25 17:06         ` [PATCH v2] rev-list-options.txt: start a list for `show-pulls` Martin Ågren
2020-05-26 12:24           ` Derrick Stolee
2020-05-26 19:18             ` Martin Ågren
2020-05-26 15:16           ` Junio C Hamano
2020-05-26 17:01             ` Derrick Stolee
2020-05-26 19:20               ` Martin Ågren

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAN0heSo_Y2Esp8X_amPXKaGaOVbP5rnJAyXiuUuW5BFSmwzhwA@mail.gmail.com \
    --to=martin.agren@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=stolee@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Git Mailing List Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/git/0 git/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 git git/ https://lore.kernel.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.git


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git