Hi Branden! On 1/1/23 21:48, G. Branden Robinson wrote:
[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 +.adI 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.
To be honest, tbl(1) is still something I can't write without looking at the manual, so what I end up doing normally is just copy an existing one and trust that it was written correctly.
It seems I was assuming too much :)
--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 1When 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]
Thanks for the detailed explanation!
More important, I think, would be to pick one phrasing for the Linux man-pages and use it consistently.
I should do that. If I only remembered this every time I write... I'll try to.
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.
When we have some time, we could do some global language consistency fixes like these. I'll need help for that.
Cheers, Alex -- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
