Hi, Branden, Pali,
On 8/1/21 1:22 PM, G. Branden Robinson wrote:
Hi, Pali!
At 2021-07-31T16:55:01+0200, Pali Rohár wrote:
SPARC is special, it does not have Bnnn constants for baud rates above
2000000. Instead it defines 4 Bnnn constants with smaller baud rates.
This difference between SPARC and non-SPARC architectures is present
in both glibc API (termios.h) and also kernel ioctl API
(asm/termbits.h).
[...]
B1500000
B2000000
+.ft P
I see you're following existing termios(3) page practice here, so this
feedback may be more for Alex and Michael than you; it's not a
criticism.
I would discourage the use of the *roff 'ft' request in man pages.
Here, it is redunant because the following PP macro will set the font
style back to roman anyway.
I also discourage the use of tab characters in man page sources (outside
of tbl(1) tables).
I'll show my recommendation in a few lines.
Agreed.
When I saw the patch, I had no idea what those .ft/.fi things do, and
guessed that they're correct based on existing context. I think your
replacement suggestion below is better.
+.fi
+.PP
+On SPARC architecture are additionally supported these constants:
+.PP
+.nf
+.ft B
+ B76800
+ B153600
+ B307200
+ B614400
+.ft P
+.fi
Here's how I'd do that:
.P
On the SPARC architecture,
the following additional constants are supported.
.RS
.TP
.B B76800
.TQ
.B B153600
.TQ
.B B307200
.TQ
.B B614400
.RE
Why would I do it this way? I'm trying to keep the size of the language
we ask man page writers to learn as small as possible, and I especially
try to keep the number of *roff requests they have to know as close to
zero as possible. There are already two ways to change fonts: through
macros and escape sequences. Personally, I'd like to protect casual man
page writers from having to learn the third. (And, again, outside of
tbl(1) tables, I'd prefer they not have to know the second [escapes].)
Can you please send a more detailed email about what the current
implementation does and how compatible is the solution and any
differences there may be (if any)?
I'd like to be able to fix that.
Pali, you don't need to fix your patch (except for the wording issues I
pointed out). In fact I prefer that you don't in this case, so the
changes are separate.
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
