Re: [PATCH v3] merge-options.txt: clarify meaning of various ff-related options

[Eric Sunshine <sunshine@sunshineco.com>]

On Fri, Aug 30, 2019 at 3:57 PM Junio C Hamano <gitster@pobox.com> wrote:
> If we want to dedicate one paragraph for each of these options, we
> can and should make the introductory paragraph lighter by saying
> something like
>
>         Specifies how a merge is handled when the merged-in history
>         is already a descendant of the current history.  `--ff` is
>         the default unless merging an annotated or signed tag that
>         is not stored in the `refs/tags/` hierarchy, in which case
>         `--no-ff` is the default.
>
> Alternatively, we could sprinkle the actual option name in the first
> paragraph and drop the last three paragraphs, while fattening the
> description as necessary, e.g.
>
>         Whether to prefer resolving the merge as a fast-forward and
>         update the branch pointer to match the merged branch without
>         creating an extra merge commit (`--ff`), never allow fast-forward
>         and always creating an extra merge commit (`--no-ff`), or to
>         only allow fast forward updates and reject when a merge
>         commit needs to be created (`--ff-only`).  The default is ...
>
> I think either approach shown above would reduce the redundancy.  I
> do not care too deeply which one of these approaches is used myself,
> but the redundancy feels a bit disturbing.

I have not been paying close attention to this thread, but upon
reading your suggested rewrites, I find the lighter paragraph (the
first of your options), followed by the three short paragraphs -- each
dedicated to a distinct option -- easier to follow and grok. I think
that's because the lighter/shorter arrangement keeps the three cases
reasonably separate -- thus the reader is able to absorb and
understand each distinct option in isolation -- rather than having to
manually pluck out the meaning of each option from one long, run-on
sentence.