Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4274 bytes --]

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

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

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]