Hi Scott, thanks for repeatedly working on time-related library documentation. :-)
Unless noted otherwise, i agree with Todd's comments. Todd C. Miller wrote on Wed, Nov 09, 2022 at 10:31:15AM -0700: > On Wed, 09 Nov 2022 16:47:22 +0000, Scott Cheloha wrote: >> RETURN VALUES >> >> - Pull ERRORS into this section. No need to put the one error in a >> .Bl/.El, we can just mention it inline. > OK I somewhat strongly object to this change. If there is content for a standard section, that section ought to be present, even if it is very short. The point is that a manual page should not only contain the expected information, but all that information should also be in the expected places, such that by merely looking at the section headers, you can already tell whether a given standard section has content, without reading any of the text. For example, the RETURN VALUES section ought to be absent if and only if all functions documented in the page are void. For example, the ERRORS section ought to be absent if and only if none of the functions ever touch the errno. Admittedly, our pages may not be perfect in that respect, some libc pages may be missing an ERRORS section even though the functions in questions sometimes set errno, but that's a (mild) defect. We certainly should not delete an existing ERRORS section for a function that definitely does set the errno. Also, in sections with a strongly conventional syntax (like ERRORS), it is preferable to use the standard syntax even in corner cases. In this case, yes, i do recommend a list with a single element. Similarly, a utility program that can take exactly one option still gets the standard DESCRIPTION sentence "The options are as follows:" and then a one-element list. The advantage for readers is having the familiar layout, and for developers the update becomes easier when the second option is added; not that anything will ever be added to pause(3), but consistency in style is still a good thing. Similarly, in code, using getopt(3) is recommended even in a program that only takes a single option. >> SEE ALSO >> >> - Nix select(2) and setitimer(2), they aren't directly relevant. > OK. The reason select(2) is there is probably because you can > emulate pause() using select(). I don't feel strongly about this. Removing select(2) is probably OK because the reason explained by Todd is mostly historical. In Perl, you still use select() to sleep for less than one second, but that's irrelevant to C programming. I'm less convinced about removing setitimer(2). To me, setitimer(2) feels just as relevant as kill(2). Both cause signals to be delivered (asap or later), which is quite relevant because that causes pause(3) to return. >> HISTORY >> >> - We still have sigpause(3) and sigblock(3) in userspace. Should >> we .Xr them? They aren't systems calls anymore, but they were >> at that time. Unsure what to do here. Polishing the HISTORY section should in no case hold up your other work. > I think it is better to use .Fn for sigpause(3) and sigblock(3) > rather than .Xr here. In this very special case, where sigpause(3) and sigblock(3) are strongly deprecated, i agree. Pointing out their continued existence - even below HISTORY - risks accidentally encouraging their use. > Note that in 4.3-Reno pause(3) was still implemented in terms of > sigpause(3) and sigblock(3), it is just that those functions were > themselves wrappers instead of system calls. Personally, I would > drop the bit about 4.3-Reno since it is not really correct in my > opinion. It could be argued either way: IMHO, a wrapper around a wrapper around foo is still a wrapper around foo, so at least my version that's currently in the tree can be argued to be correct. Admittedly, Scott's version less so; pause(3) certainly wasn't reimplemented for Reno. Then again, replacing the last phase (starting at "and around") with the following would avoid the semantic disagreement: It has been using sigsuspend(2) and sigprocmask(2) since 4.3-BSD Reno. Yours, Ingo
