Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Junio C Hamano <gitster@pobox.com>]

kristofferhaugsbakk@fastmail.com writes:

>     This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
>     patch-id: fix accidental literal blocks, 2025-09-29) merged into
>     v2.50.0 (because that’s what the topic is based on).
>     
>     (is there a “reference” convention for mentioning a topic + commit?)

The above is perfectly understandable.

>     This is part one of a multi-series effort focusing on this
>     documentation page. Technically that intent started with topic
>     kh/doc-patch-id-markup-fix, but I published that before I learned
>     about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
>     So this gets named “part one” in the cover letter (and maybe on the
>     topic name).
>     
>     The current plan for parts 2–5:
>     
>     2. Various smaller fixups (many small patches/commits)
>     3. Mention the two config variables in git-config(1)
>     4. Make it more clear that you can feed multiple diffs to this command
>     5. An “Examples” section

Quite honestly, this smells like making a mountain out of a
molehill.  5-patch topic that focuses on improving a single
documentation page is nothing unusual, but it is very unusual and
awkward to handle for a topic that focuses on improving a single
documentation page is spread across 5 separate topics, each building
on top of the previous one.

>     Why a multi-part series?  It started with the idea of (1) emphasizing
>     that this command can take multiple patches, and (2) making an
>     Examples. But then I saw other things to fix. And they ought to go
>     first... eventually I ended up with many commits or ideas.

Perhaps then after you built up the final shape, you'd need time to
ruminate over it and possibly reorganize to find the best order and
organization to present it as a N-patch single series?  Typically, a
collection of thoughts presented in the order they came to one's mind
is much harder to judge, relative to an effort to tell a coherent story
that moves to a goal.

But we'll see.