Skip to contentSkip to conversation

termios.3: SPARC architecture has 4 different Bnnn constants

PATCH Superseded Pali Rohár 3 participants 8 messages Jul 31, 2021 – Sep 10, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 termios.3: SPARC architecture has 4 different Bnnn constants

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

---
 man3/termios.3 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
man3/termios.3 +23 -0
index 7b195c95912b..2ff8cc80e9eb 100644
@@ -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.
Signature · 1 line
2.20.1
#1 lore raw

Hi Pali!

Quoted 7 lines · 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).

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

Thanks,

Alex

Quoted 9 lines
---
  man3/termios.3 | 23 +++++++++++++++++++++++
  1 file changed, 23 insertions(+)
man3/termios.3 +0 -0
index 7b195c95912b..2ff8cc80e9eb 100644

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 959

Quoted 8 lines
man3/termios.3 +4 -0
@@ -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):

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 970

Quoted 11 lines
man3/termios.3 +11 -0
+.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.

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 982

Quoted 12 lines
man3/termios.3 +5 -0
+.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

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 984

Quoted 2 lines
man3/termios.3 +2 -0
+.BI B nnn
+constant is defined prior using it.

s/prior/prior to/

Quoted 6 lines
man3/termios.3 +1 -0
+.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.
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#2 lore raw
In reply to Pali Rohár

Hi, Pali!

Quoted 6 lines · 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).

[...]

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 956

Quoted 3 lines
man3/termios.3 +1 -0
 	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.

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 968

Quoted 12 lines

+.fi
+.PP

man3/termios.3 +10 -0
+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

#3 lore raw

Hi, Branden, Pali,

Quoted 18 lines · G. Branden Robinson

Hi, Pali!

Quoted 6 lines · 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).

[...]

Quoted 3 lines

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.

Quoted 8 lines

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.

Quoted 30 lines

man3/termios.3 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: · line 968

Quoted 13 lines

+.fi
+.PP

man3/termios.3 +10 -0
+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

Quoted 7 lines

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#4 lore raw

Hi, Alex!

Quoted 4 lines · Alejandro Colomar (man-pages)

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.

Quoted 25 lines
Quoted 16 lines

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

Quoted 8 lines

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

Quoted 3 lines

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.

Quoted 1 line

I'd like to be able to fix that.

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

Regards,
Branden

#5 lore raw

Hi, Branden!

Quoted 75 lines · G. Branden Robinson

Hi, Alex!

Quoted 4 lines · Alejandro Colomar (man-pages)

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.

Quoted 25 lines
Quoted 16 lines

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

Quoted 8 lines

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

Quoted 3 lines

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

Quoted 13 lines

.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

Quoted 15 lines

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

Quoted 1 line

I'd like to be able to fix that.

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

Regards,
Branden

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#6 lore raw

PATCH v2 1/1 termios.3: SPARC architecture has 4 different Bnnn constants

In reply to 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).

---
 man3/termios.3 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
man3/termios.3 +23 -0
index 7b195c95912b..500cf0713e4d 100644
@@ -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.
Signature · 1 line
2.20.1
#7 lore raw

Hi, Pali!

Quoted 7 lines · 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).

Patch applied!

Thanks,

Alex

Quoted 46 lines
---
  man3/termios.3 | 23 +++++++++++++++++++++++
  1 file changed, 23 insertions(+)
man3/termios.3 +23 -0
index 7b195c95912b..500cf0713e4d 100644
@@ -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.
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/