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

[G. Branden Robinson]

At 2024-11-24T23:04:23-0600, Dave Kemper wrote:
> 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.

You might be interested in or amused by a recent patch series to GNU
Bash, starting here:

https://lists.gnu.org/archive/html/bug-bash/2024-11/msg00161.html

> Is there a reason for it not to, besides historical practice?

Not to my knowledge.

> 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).

I happen to have a change pending to our Texinfo manual.  I'll pilot
this and see what happens.  (It _does_ happen to warrant a parallel
change to one of our man pages.)

Regards,
Branden

signature.asc
Description: PGP signature