[dropping libc-alpha due to scope of my comments]
Hi Alex,
At 2023-01-01T17:26:28+0100, Alejandro Colomar wrote:
[...]
> +.ad l
> +.nh
> +.TS
[...]
> +T{
> +.BR arc4random (),
> +.BR arc4random_uniform (),
> +.BR arc4random_buf ()
> +T} Thread safety MT-Safe
> +.TE
> +.hy
> +.ad
I would counsel against putting these *roff requests outside the table
definition. I think that having them where you do (1) misleads the
reader/maintainer into thinking that they influence how table entries in
general are typeset, and (2) they risk being retained in the event the
man page is refactored to stop using a table definition to present the
material.
--begin snip--
Ordinarily, a table entry is typeset rigidly. It is not filled,
broken, hyphenated, adjusted, or populated with additional inter‐
sentence space. [...] In contrast to conventional roff input
(within a paragraph, say), changes to text formatting, such as font
selection or vertical spacing, do not persist between entries.
[...]
Text blocks are formatted as was the text prior to the table,
modified by applicable column descriptors. Specifically, the
classifiers A, C, L, N, R, and S determine a text block’s alignment
within its cell, but not its adjustment. Add na or ad requests to
the beginning of a text block to alter its adjustment distinctly
from other text in the document. As with other table entries, when
a text block ends, any alterations to formatting parameters are
discarded. They do not affect subsequent table entries, not even
other text blocks.[1]
--end snip--
Admittedly, if you had a single table region with a bunch of text blocks
in it, it is more economical to change (and later restore) the
formatting of "the text prior to the table", so you don't have to whack
each text block with ".ad l" and ".nh" individually.
But in this case you can move 2 lines and drop two, since the changed
alignment and automatic hyphenation disablement will be "discarded".
> +.sp 1
When you throw the groff 1.23.0 switch and start using the `MR` macro,
you can get rid of this too. https://savannah.gnu.org/bugs/?49390
> +.SH STANDARDS
> +These nonstandard functions are present in several Unix systems.
>
> I'm not a native speaker, but I think it should be s/in/on/.
[a native English speaker has entered the chat]
Neither will sound wrong to most ears. I think "on" is a little more
idiomatic, as we tend to speak of operating systems as some kind of
platform or foundation upon which other activities are conducted or
interfaces are constructed. But we also speak of an OS as an
environment in which we carry out tasks. ("I tried doing development in
Windows--it was hell!") When speaking of an entry point to "the system"
(not to say "the kernel"), I think the argument for "on" is stronger,
since we are speaking of it in that platform/foundational sense. I see
this usage in man-pages(7) itself.[2]
More important, I think, would be to pick one phrasing for the Linux
man-pages and use it consistently.
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man
[2] I also see both "The conventions described on this page" and
"The first command in a man page", revealing that slippage between
these prepositions is common in other contexts as well. I never
noticed this until I looked for it.
Attachment:
signature.asc
Description: PGP signature
