Re: [PATCH v2 1/4] man/man3*: document the glibc 2.42+ baud_t termios interface

"G. Branden Robinson" <[email protected]> Tue, 30 Jun 2026 17:50:12 -0500

Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260630225012.ybdxl7amx7seplfb@illithid>

Hi Peter,

At 2026-06-30T13:37:25-0700, H. Peter Anvin wrote:
> On 2026-06-30 03:39, Alejandro Colomar wrote:
> > This text isn't really being added.  The weirdness of this diff is
> > in part because of including too many changes in a single commit.
> > In this case, it seems to be a movement of text from elsewhere.
> > Separating commits would improve the diff significantly. 
>
[...]
> However, doing that using the broken-up diffs that you want would be
> very difficult at least for me, as I'm neither particularly
> comfortable with troff nor a good technical writer, plus that this is
> a "spare time" project for me.  I would be willing to try to submit
> such a rewrite, but if that means refactoring it into small diffs it
> isn't going to happen.

Don't worry about lack of troff comfort being a barrier.  Members of
this mailing list can fill in any gaps in your expertise.

That said, you don't need to know much troff to write a man page, and as
a rule, great expertise in troff (especially of the "old school")
seduces a man page author into writing man pages that are _less_
portable and thus render less reliably then they otherwise would.

If you're running groff 1.23 or later, your system should have a
groff_man_style(7) man page that explains only the essentials of troff
knowledge, presents the man(7) macros in detail with examples, and
offers much advice to assist the writer.

I'm acutely interested in any feedback you have on that document.

Pre-rendered versions are available here:

https://man7.org/linux/man-pages/man7/groff_man_style.7.html

...and in PDF as part of the collected groff man pages...

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

...there.

Regards,
Branden

signature.asc (application/pgp-signature, 833 B)