Re: [PATCH] termios.3: SPARC architecture has 4 different Bnnn constants

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/