Line-breaking style in documentation source (was Re: [PATCH v2 1/3] proc_pid_fdinfo.5: Reduce indent for most of the page)

[Dave Kemper]

On Sat, Nov 2, 2024 at 5:08 AM G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:
> At 2024-11-01T21:07:29+0100, Alejandro Colomar wrote:
> > No, this isn't outdated, since that reduces the quality of the diff.
> > Also, I review a lot of patches in the mail client, without running
> > git(1).  And it's not just for reviewing diffs, but also for writing
> > them.  Semantic newlines reduce the amount of work for producing the
> > diffs.
>
> It's a real win for diffs.
>
> Here's a very recent example from groff.
>
> diff --git a/man/groff.7.man b/man/groff.7.man
> index 1fb635f2b..1d248b237 100644
> --- a/man/groff.7.man
> +++ b/man/groff.7.man
> @@ -1281,6 +1281,7 @@ .SH Identifiers
>  typeface,
>  color,
>  special character or character class,
> +hyphenation language code,
>  environment,
>  or stream.

Every time I look at a diff in groff.texi, and I have to spend some
time figuring out what *actually* changed versus what merely got
reflowed, I wish that that manual used manpage-style line breaking
internally.  Is there a reason for it not to, besides historical
practice?

Going through the entire manual and changing its format would be a
slog (though perhaps at least partly automatable), and would make "git
blame" useless for tracking down any particular change from before
that point--but might make diffs after that point enough easier to
follow to be a net win.

Alternately, everyone[1] who hacks on the manual could agree to use
the new format for any future edits.  This would make the formatting
change more gradual and manageable, but would also result in
inconsistent line-breaking style within the manual for, realistically,
decades (or at least until AI takes over all content creation, and no
humans need use groff ever again).  This, too, might be worth
tolerating for the readability of diffs going forward.

[1] Yeah, "everyone" is pretty much just Branden, credited for 1255 of
the 1272 commits in the last five years (and even that is an
undercount, as several of those commits are credited to me but
actually applied and sometimes refined by Branden).