Re: [PATCH] doc: patch-id: fix accidental literal blocks

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 28, 2025, 19:37 UTC
Message-ID: <xmqqv7l25pxa.fsf@gitster.g>
In-Reply-To: <b7ded038-fc91-41cc-b241-1ace6b46069c@app.fastmail.com>

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

Show 13 quoted lines

> ...
>>> This is kind of subtle since only the last paragraph of each option gets
>>> rendered in an unintended way, namely as literal blocks.  This is easier
>>> to see in the HTML output since the man page output just has a slightly
>>> larger indentation on these paragraphs.
>>
>> Hmph, I've always thought that the practice breaks every paragraph
>> except for the first one (which is the same as "only the last",
>> only when you have exactly 2 paragraphs; when you have more than 2,
>> it makes a difference).
>
> I don’t understand why but `doc-diff` agrees that these last ones are
> the only ones affected by this change.

But in this patch, you are not dealing with a section with three or more paragraphs, are you? I think there is nothing doc-diff can show you in this particular fix.

For example, the first hunk deals with

	--verbatim::
		Calculate the patch-id of the input as it is given, do not strip
		any whitespace.

		This is the default if patchid.verbatim is true.

two paragraphs, "Calculate...", and "This is the default...". It is correct that the second paragraph needs to be treated, like so:

	--verbatim::
		Calculate the patch-id of the input as it is given, do not strip
		any whitespace.
	+
	This is the default if patchid.verbatim is true.

and that is what your patch does.

But if you had three or more, e.g.,

	--verbatim::
		Calculate the patch-id of the input as it is given, do not strip
		any whitespace.

		This is the default if patchid.verbatim is true.

		For fun, we add a third paragraph.

would it render the first two paragraph correctly, and only the "For fun, ..." paragraph gets shown incorrectly? And would it give us a good rendition to fix only the last paragraph, like so:

	--verbatim::
		Calculate the patch-id of the input as it is given, do not strip
		any whitespace.

		This is the default if patchid.verbatim is true.
	+
	For fun, we add a third paragraph.

That is what your proposed log message said, and that is what I wanted to double check, as from memory and experience, I am reasonably sure that in such a case, I had to correct it more like

	--verbatim::
		Calculate the patch-id of the input as it is given, do not strip
		any whitespace.
	+
	This is the default if patchid.verbatim is true.
	+
	For fun, we add a third paragraph.

i.e., the second and subsequent paragraphs needed the "a + on a line byitself before the paragraph, and paragraph itself dedented" treatment.

Thanks.