termios.3: SPARC architecture has 4 different Bnnn constants
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
@@ -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
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).Signed-off-by Pali Rohár <[email protected]>
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
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/
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
-0B1500000 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
+.PPman3/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
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 PI 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
+.PPman3/termios.3 +10
-0+On SPARC architecture are additionally supported these constants: +.PP +.nf +.ft B + B76800 + B153600 + B307200 + B614400 +.ft P +.fiHere'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/
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
.REQuoted 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
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
.REQuoted 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; seegroff_man(7)
On SPARC architecture \" text line
.PP \" man(7) paragraphing macro; seegroff_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 textHere'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/
PATCH v2 1/1 termios.3: SPARC architecture has 4 different Bnnn constants
In reply to Pali RohárSPARC 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
@@ -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
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).Signed-off-by Pali Rohár <[email protected]>
Patch applied!
Thanks,
Alex
Quoted 46 lines
--- man3/termios.3 | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)man3/termios.3 +23
-0@@ -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/