Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text

On Mon, Nov 21, 2022 at 03:15:50PM +0100, Ævar Arnfjörð Bjarmason wrote:

But the end result of having some paragraphs use "<p>" in the HTML
output, and to have others wrapped in "<pre><code>" doesn't look
nice. The most minimal way to fix this is to de-indent the opening
line of paragraphs that don't start with another formatting
element (e.g. "*" or "-" would already format them as text). Let's do
that.

Is there any reason to just touch the opening line of the paragraphs,
and not change the indent of the whole thing? I understand that doing
the first line is sufficient to convince asciidoc to do what we want,
and the diff is technically fewer lines, but the result is rather
confusing for people who will work on the source in the future.

There's a lot more to fix in these gitformat-* docs (as their
formatting was funny before), but this is a minimal change to fix the
most major issues.

I briefly looked at doc-diff output here. Most of them looked obviously
correct (though since there isn't a lot of context in the doc-diff, it's
sometimes hard to tell), but a few were questionable:

This puts "A 16-bit flags field" at a different indent than the
paragraph before, but I think it is part of a list. It is less indented
than the follow-on paragraph ("1-bit assume-valid flag"), but I think
that is correct, as it is a sub-list of the 16-bit flags.

I know you said that formatting problems remain, and certainly this was
not right before your patch either. But I think your patch makes it
worse, because it pulls the touched line out of the list (and all of the
adjacent parts are still rendered as code blocks, making the structure
even less clear).

This is the same (it's the same list).

And I think this is supposed to be part of that same list, too, but now
is de-dented.

This is supposed to be a continuation of the earlier "Entry path name"
item, but now is at the same top-level. Which is not right, but arguably
is not worse than before your patch.

And this one is another top-level part of the list.

These are supposed to be list items of "The same trailer as..." above.
Now they're de-dented, which I think is worse than the state before your
patch.

I don't want to say "we must fix all format problems at once", but I
think in the cases I pointed out that trying to fix the code-block
problem is a losing battle, because the list-like nature is being made
worse. And they probably should remain untouched until somebody is
willing to turn them into actual list elements and continuation markers.

-Peff