[PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[Pali Rohár]

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

diff --git a/man3/termios.3 b/man3/termios.3
index 01c20994424d..e603879e18d4 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -1068,8 +1068,9 @@ and
 are nonstandard, but available on the BSDs.
 .SH NOTES
 UNIX\ V7 and several later systems have a list of baud rates
-where after the fourteen values B0, ..., B9600 one finds the
-two constants EXTA, EXTB ("External A" and "External B").
+where after the fourteen values \fBB0\fP, ..., \fBB9600\fP
+one finds the two constants \fBEXTA\fP, \fBEXTB\fP
+("External A" and "External B").
 Many systems extend the list with much higher baud rates.
 .PP
 The effect of a nonzero \fIduration\fP with
-- 
2.20.1

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[Alejandro Colomar (man-pages)]

Hi Pali,

On 7/26/21 12:54 AM, Pali Rohár wrote:
> Signed-off-by: Pali Rohár <pali@kernel.org>
> ---
>   man3/termios.3 | 5 +++--
>   1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 01c20994424d..e603879e18d4 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -1068,8 +1068,9 @@ and
>   are nonstandard, but available on the BSDs.
>   .SH NOTES
>   UNIX\ V7 and several later systems have a list of baud rates
> -where after the fourteen values B0, ..., B9600 one finds the
> -two constants EXTA, EXTB ("External A" and "External B").
> +where after the fourteen values \fBB0\fP, ..., \fBB9600\fP

Could you please use .B and/or .BR instead of inline \fB...\fP?

See this extract from man-pages(7):

        Any  reference  to  the  subject of the current manual page
        should be written with the name in bold followed by a  pair
        of parentheses in Roman (normal) font.  For example, in the
        fcntl(2) man page, references to the subject  of  the  page
        would  be  written as: fcntl().  The preferred way to write
        this in the source file is:

            .BR fcntl ()

        (Using this format, rather than the  use  of  "\fB...\fP()"
        makes  it  easier to write tools that parse man page source
        files.)


Thanks,

Alex

> +one finds the two constants \fBEXTA\fP, \fBEXTB\fP
> +("External A" and "External B").
>   Many systems extend the list with much higher baud rates.
>   .PP
>   The effect of a nonzero \fIduration\fP with
> 


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

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[Pali Rohár]

On Thursday 29 July 2021 13:21:40 Alejandro Colomar (man-pages) wrote:
> Hi Pali,
> 
> On 7/26/21 12:54 AM, Pali Rohár wrote:
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> > ---
> >   man3/termios.3 | 5 +++--
> >   1 file changed, 3 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man3/termios.3 b/man3/termios.3
> > index 01c20994424d..e603879e18d4 100644
> > --- a/man3/termios.3
> > +++ b/man3/termios.3
> > @@ -1068,8 +1068,9 @@ and
> >   are nonstandard, but available on the BSDs.
> >   .SH NOTES
> >   UNIX\ V7 and several later systems have a list of baud rates
> > -where after the fourteen values B0, ..., B9600 one finds the
> > -two constants EXTA, EXTB ("External A" and "External B").
> > +where after the fourteen values \fBB0\fP, ..., \fBB9600\fP
> 
> Could you please use .B and/or .BR instead of inline \fB...\fP?

Ok, no problem. I used inline style because few lines below is already
used this \fIduration\fP inline style.

How do you prefer to format this part? \fBB0\fP, ..., \fBB9600\fP

> See this extract from man-pages(7):
> 
>        Any  reference  to  the  subject of the current manual page
>        should be written with the name in bold followed by a  pair
>        of parentheses in Roman (normal) font.  For example, in the
>        fcntl(2) man page, references to the subject  of  the  page
>        would  be  written as: fcntl().  The preferred way to write
>        this in the source file is:
> 
>            .BR fcntl ()
> 
>        (Using this format, rather than the  use  of  "\fB...\fP()"
>        makes  it  easier to write tools that parse man page source
>        files.)
> 
> 
> Thanks,
> 
> Alex
> 
> > +one finds the two constants \fBEXTA\fP, \fBEXTB\fP
> > +("External A" and "External B").
> >   Many systems extend the list with much higher baud rates.
> >   .PP
> >   The effect of a nonzero \fIduration\fP with
> > 
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[G. Branden Robinson]

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

At 2021-07-29T19:23:20+0200, Pali Rohár wrote:
> How do you prefer to format this part? \fBB0\fP, ..., \fBB9600\fP

I'd use the B or BR macro to set the literals, depending on whether they
are directly followed by something that should be in the roman style,
and I would definitely set the ellipsis in roman; when used as such,
it should never be set in bold or italics.  Use of the ellipsis in *roff
input requires some care, which is unfortunately often neglected.

.BR B0 ,
\&.\|.\|.\|,
.B 9600

(I dithered over inclusion of the thin space escape sequence \| between
the ellipsis and the comma.  I can see arguments either way, and a quick
Internet search does not suggest to me a strong wind in either
direction.  Since its presence or absence makes no difference for
terminal output, I expect most writers of man pages won't care.)

Regards,
Branden

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

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[Alejandro Colomar (man-pages)]

Hi Branden,

On 7/30/21 1:04 AM, G. Branden Robinson wrote:
> At 2021-07-29T19:23:20+0200, Pali Rohár wrote:
>> How do you prefer to format this part? \fBB0\fP, ..., \fBB9600\fP
> 
> I'd use the B or BR macro to set the literals, depending on whether they
> are directly followed by something that should be in the roman style,
> and I would definitely set the ellipsis in roman; when used as such,
> it should never be set in bold or italics.  Use of the ellipsis in *roff
> input requires some care, which is unfortunately often neglected.
> 
> .BR B0 ,
> \&.\|.\|.\|,
> .B 9600
> 
> (I dithered over inclusion of the thin space escape sequence \| between
> the ellipsis and the comma.  I can see arguments either way, and a quick
> Internet search does not suggest to me a strong wind in either
> direction.  Since its presence or absence makes no difference for
> terminal output, I expect most writers of man pages won't care.)


Thanks again for your input!
Good to know that.


Cheers,

Alex


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

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[Pali Rohár]

On Friday 30 July 2021 01:41:49 Alejandro Colomar (man-pages) wrote:
> Hi Branden,
> 
> On 7/30/21 1:04 AM, G. Branden Robinson wrote:
> > At 2021-07-29T19:23:20+0200, Pali Rohár wrote:
> > > How do you prefer to format this part? \fBB0\fP, ..., \fBB9600\fP
> > 
> > I'd use the B or BR macro to set the literals, depending on whether they
> > are directly followed by something that should be in the roman style,
> > and I would definitely set the ellipsis in roman; when used as such,
> > it should never be set in bold or italics.  Use of the ellipsis in *roff
> > input requires some care, which is unfortunately often neglected.
> > 
> > .BR B0 ,
> > \&.\|.\|.\|,
> > .B 9600
> > 
> > (I dithered over inclusion of the thin space escape sequence \| between
> > the ellipsis and the comma.  I can see arguments either way, and a quick
> > Internet search does not suggest to me a strong wind in either
> > direction.  Since its presence or absence makes no difference for
> > terminal output, I expect most writers of man pages won't care.)
> 
> 
> Thanks again for your input!
> Good to know that.

Perfect! I will change it in this way.

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

Re: [PATCH] termios.3: Use bold style for Bnn and EXTn macro constants

[G. Branden Robinson]

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

At 2021-07-30T02:21:33+0200, Pali Rohár wrote:
> > On 7/30/21 1:04 AM, G. Branden Robinson wrote:
> > > .BR B0 ,
> > > \&.\|.\|.\|,
> > > .B 9600
[..]
> Perfect! I will change it in this way.

Sadly I violated the Law of "B" Conservation in the above.

It should have been:

.BR B0 ,
\&.\|.\|.\|,
.B B9600

(I got hyper-focused on the ellipsis.)

Regards,
Branden

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

[PATCH v2] termios.3: Use bold style for Bnn and EXTn macro constants

[Pali Rohár]

Signed-off-by: Pali Rohár <pali@kernel.org>

---
Changes in v2:
* Do not use inline style
* Fix formatting ellipsis
---
 man3/termios.3 | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/man3/termios.3 b/man3/termios.3
index 01c20994424d..b7cdec507524 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -1068,8 +1068,14 @@ and
 are nonstandard, but available on the BSDs.
 .SH NOTES
 UNIX\ V7 and several later systems have a list of baud rates
-where after the fourteen values B0, ..., B9600 one finds the
-two constants EXTA, EXTB ("External A" and "External B").
+where after the fourteen values
+.BR B0 ,
+\&.\|.\|.\|,
+.B B9600
+one finds the two constants
+.BR EXTA ,
+.B EXTB
+("External A" and "External B").
 Many systems extend the list with much higher baud rates.
 .PP
 The effect of a nonzero \fIduration\fP with
-- 
2.20.1

Re: [PATCH v2] termios.3: Use bold style for Bnn and EXTn macro constants

[Alejandro Colomar (man-pages)]

Hi Pali,

On 7/30/21 12:32 PM, Pali Rohár wrote:
> Signed-off-by: Pali Rohár <pali@kernel.org>
> 

Patch applied.  Thanks,

Alex

> ---
> Changes in v2:
> * Do not use inline style
> * Fix formatting ellipsis
> ---
>   man3/termios.3 | 10 ++++++++--
>   1 file changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index 01c20994424d..b7cdec507524 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -1068,8 +1068,14 @@ and
>   are nonstandard, but available on the BSDs.
>   .SH NOTES
>   UNIX\ V7 and several later systems have a list of baud rates
> -where after the fourteen values B0, ..., B9600 one finds the
> -two constants EXTA, EXTB ("External A" and "External B").
> +where after the fourteen values
> +.BR B0 ,
> +\&.\|.\|.\|,
> +.B B9600
> +one finds the two constants
> +.BR EXTA ,
> +.B EXTB
> +("External A" and "External B").
>   Many systems extend the list with much higher baud rates.
>   .PP
>   The effect of a nonzero \fIduration\fP with
> 


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