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

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

[Pali Rohár]

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

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man3/termios.3 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/man3/termios.3 b/man3/termios.3
index 7b195c95912b..2ff8cc80e9eb 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -952,15 +952,38 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 	B1000000
 	B1152000
 	B1500000
 	B2000000
+.ft P
+.fi
+.PP
+On SPARC architecture are additionally supported these constants:
+.PP
+.nf
+.ft B
+	B76800
+	B153600
+	B307200
+	B614400
+.ft P
+.fi
+.PP
+On non-SPARC architectures are additionally supported these constants:
+.PP
+.nf
+.ft B
 	B2500000
 	B3000000
 	B3500000
 	B4000000
 .ft P
 .fi
 .PP
+Due to differences between architectures, portable applications should check
+if particular
+.BI B nnn
+constant is defined prior using it.
+.PP
 The zero baud rate, \fBB0\fP,
 is used to terminate the connection.
 If B0 is specified, the modem control lines shall no longer be asserted.
 Normally, this will disconnect the line.
-- 
2.20.1

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

[Alejandro Colomar (man-pages)]

Hi Pali!


On 7/31/21 4:55 PM, 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).
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>

Except for some wording issues (see below), looks good to me.

Thanks,

Alex

> ---
>   man3/termios.3 | 23 +++++++++++++++++++++++
>   1 file changed, 23 insertions(+)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 7b195c95912b..2ff8cc80e9eb 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -952,15 +952,38 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>   	B1000000
>   	B1152000
>   	B1500000
>   	B2000000
> +.ft P
> +.fi
> +.PP
> +On SPARC architecture are additionally supported these constants:

On the SPARC architecture,
or
On SPARC,

these constants are additionally supported


Or, if you want to avoid the comma:

These constants are additionally supported on SPARC (or: on the SPARC 
architecture):

> +.PP
> +.nf
> +.ft B
> +	B76800
> +	B153600
> +	B307200
> +	B614400
> +.ft P
> +.fi
> +.PP
> +On non-SPARC architectures are additionally supported these constants:

Here you don't need "the"; "on non-SPARC architectures" is correct.
But for the second part of the sentence, the same fix as above applies.

> +.PP
> +.nf
> +.ft B
>   	B2500000
>   	B3000000
>   	B3500000
>   	B4000000
>   .ft P
>   .fi
>   .PP
> +Due to differences between architectures, portable applications should check
> +if particular

if a particular

> +.BI B nnn
> +constant is defined prior using it.

s/prior/prior to/

> +.PP
>   The zero baud rate, \fBB0\fP,
>   is used to terminate the connection.
>   If B0 is specified, the modem control lines shall no longer be asserted.
>   Normally, this will disconnect the line.
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1776 bytes --]

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.

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

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Pali Rohár]

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

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man3/termios.3 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/man3/termios.3 b/man3/termios.3
index 7b195c95912b..500cf0713e4d 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -953,6 +953,24 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 	B1152000
 	B1500000
 	B2000000
+.ft P
+.fi
+.PP
+These constants are additionally supported on the SPARC architecture:
+.PP
+.nf
+.ft B
+	B76800
+	B153600
+	B307200
+	B614400
+.ft P
+.fi
+.PP
+These constants are additionally supported on non-SPARC architectures:
+.PP
+.nf
+.ft B
 	B2500000
 	B3000000
 	B3500000
@@ -960,6 +978,11 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
 .ft P
 .fi
 .PP
+Due to differences between architectures, portable applications should check
+if a particular
+.BI B nnn
+constant is defined prior to using it.
+.PP
 The zero baud rate, \fBB0\fP,
 is used to terminate the connection.
 If B0 is specified, the modem control lines shall no longer be asserted.
-- 
2.20.1

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

[Alejandro Colomar (man-pages)]

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/

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

[Alejandro Colomar (man-pages)]

Hi, Pali!

On 8/1/21 1:35 PM, 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).
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>

Patch applied!

Thanks,

Alex

> ---
>   man3/termios.3 | 23 +++++++++++++++++++++++
>   1 file changed, 23 insertions(+)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 7b195c95912b..500cf0713e4d 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -953,6 +953,24 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>   	B1152000
>   	B1500000
>   	B2000000
> +.ft P
> +.fi
> +.PP
> +These constants are additionally supported on the SPARC architecture:
> +.PP
> +.nf
> +.ft B
> +	B76800
> +	B153600
> +	B307200
> +	B614400
> +.ft P
> +.fi
> +.PP
> +These constants are additionally supported on non-SPARC architectures:
> +.PP
> +.nf
> +.ft B
>   	B2500000
>   	B3000000
>   	B3500000
> @@ -960,6 +978,11 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
>   .ft P
>   .fi
>   .PP
> +Due to differences between architectures, portable applications should check
> +if a particular
> +.BI B nnn
> +constant is defined prior to using it.
> +.PP
>   The zero baud rate, \fBB0\fP,
>   is used to terminate the connection.
>   If B0 is specified, the modem control lines shall no longer be asserted.
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3757 bytes --]

Hi, Alex!

At 2021-08-01T14:13:39+0200, Alejandro Colomar (man-pages) wrote:
> On 8/1/21 1:22 PM, G. Branden Robinson wrote:
> 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.

The 'ft' request changes the font (or style), and accepts exactly the
same parameter as the \f font (style) escape.

The 'fi' request enables filling; 'nf' disables it.

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

Sure, I'll mark 'em up like assembly.  I hope your mail reader uses a
monospaced/fixed-width font.

.fi			\" enable filling[1] of text
.PP			\" man(7) paragraphing macro; see groff_man(7)
On SPARC architecture	\" text line
.PP			\" man(7) paragraphing macro; see groff_man(7)
.nf			\" disable filling of text
.ft B			\" change font to style "B"
	B76800		\" text line using literal tab
	B153600		\" ditto
	B307200		\" ditto
	B614400		\" ditto
.ft P			\" change font to "previous" selection
.fi			\" enable filling[1] of text

Here's how I define filling in the groff Texinfo manual; many other
sources define it equivalently.

    GNU 'troff' reads its input character by character, collecting words
 as it goes, and fits as many words together on an output line as it
 can--this is known as "filling".  To GNU 'troff', a "word" is any
 sequence of one or more characters that aren't spaces, tabs, or
 newlines.  Words are separated by spaces, tabs, newlines, or file
 boundaries.(2)  (*note Filling-Footnote-2::) To disable filling, see
 *note Manipulating Filling and Adjustment::.

I try to avoid use of tab characters in man page sources, except to
separate columns in tbl(1) input.  I prefer to use the relative inset
feature (.RS/.RE) because the default size of a relative inset is a
configurable parameter.  (And if must be a certain value, it can be set
as the argument to the RS macro.)

.P			\" man(7) paragraphing macro; see groff_man(7)
On the SPARC[...]
the following[...]
.RS			\" begin relative inset
.TP			\" begin tagged paragraph
.B B76800		\" set argument in bold style
.TQ			\" declare additional paragraph tag
.B B153600		\" [repeat previous two lines]
.TQ			\"
.B B307200		\"
.TQ			\"
.B  B614400		\"
.RE			\" end relative inset.

.RS and .RE are used with timidity by man page authors; I think it is
because they are ill-understood.  It is certainly not because they are
new; like .B and .TP they date back to the original 1979 man(7)
implementation.  Even .P is "new", dating to Unix System III in 1980.
.TQ is the real newcomer, introduced to groff in January 2007.  Like
.TP, it's somewhat semantic.

> I'd like to be able to fix that.

Let me know if I can shed more light on things.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 8/4/21 8:14 AM, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2021-08-01T14:13:39+0200, Alejandro Colomar (man-pages) wrote:
>> On 8/1/21 1:22 PM, G. Branden Robinson wrote:
>> 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.
> 
> The 'ft' request changes the font (or style), and accepts exactly the
> same parameter as the \f font (style) escape.
> 
> The 'fi' request enables filling; 'nf' disables it.
> 
>>> 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)?
> 
> Sure, I'll mark 'em up like assembly.  I hope your mail reader uses a
> monospaced/fixed-width font.
> 
> .fi			\" enable filling[1] of text
> .PP			\" man(7) paragraphing macro; see groff_man(7)
> On SPARC architecture	\" text line
> .PP			\" man(7) paragraphing macro; see groff_man(7)
> .nf			\" disable filling of text
> .ft B			\" change font to style "B"
> 	B76800		\" text line using literal tab
> 	B153600		\" ditto
> 	B307200		\" ditto
> 	B614400		\" ditto
> .ft P			\" change font to "previous" selection
> .fi			\" enable filling[1] of text
> 
> Here's how I define filling in the groff Texinfo manual; many other
> sources define it equivalently.
> 
>      GNU 'troff' reads its input character by character, collecting words
>   as it goes, and fits as many words together on an output line as it
>   can--this is known as "filling".  To GNU 'troff', a "word" is any
>   sequence of one or more characters that aren't spaces, tabs, or
>   newlines.  Words are separated by spaces, tabs, newlines, or file
>   boundaries.(2)  (*note Filling-Footnote-2::) To disable filling, see
>   *note Manipulating Filling and Adjustment::.
> 
> I try to avoid use of tab characters in man page sources, except to
> separate columns in tbl(1) input.  I prefer to use the relative inset
> feature (.RS/.RE) because the default size of a relative inset is a
> configurable parameter.  (And if must be a certain value, it can be set
> as the argument to the RS macro.)
> 
> .P			\" man(7) paragraphing macro; see groff_man(7)
> On the SPARC[...]
> the following[...]
> .RS			\" begin relative inset
> .TP			\" begin tagged paragraph
> .B B76800		\" set argument in bold style
> .TQ			\" declare additional paragraph tag
> .B B153600		\" [repeat previous two lines]
> .TQ			\"
> .B B307200		\"
> .TQ			\"
> .B  B614400		\"
> .RE			\" end relative inset.

Yes, I prefer this way.

I'm sorry I forgot to answer to this email.  There may be others also...
If I forgot to address anything important, feel free to ping me :)

Cheers,

Alex

> 
> .RS and .RE are used with timidity by man page authors; I think it is
> because they are ill-understood.  It is certainly not because they are
> new; like .B and .TP they date back to the original 1979 man(7)
> implementation.  Even .P is "new", dating to Unix System III in 1980.
> .TQ is the real newcomer, introduced to groff in January 2007.  Like
> .TP, it's somewhat semantic.
> 
>> I'd like to be able to fix that.
> 
> Let me know if I can shed more light on things.
> 
> Regards,
> Branden
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/