Hi Job,

Job Snijders wrote on Mon, Jun 17, 2024 at 02:45:06PM +0000:

> It seems -susv1, -susv3, and -susv4 are not used in man pages in base
> at all (other than mdoc).

Luckily we have a good apropos(1):

   $ man -M/usr/share/man -kw St=sus 
  /usr/share/man/man1/col.1   # <<< note this one <<<
  /usr/share/man/man3/pthread_getconcurrency.3
  /usr/share/man/man3/pthread_mutexattr.3
  /usr/share/man/man3/pthread_rwlock_destroy.3
  /usr/share/man/man3/pthread_rwlock_init.3
  /usr/share/man/man3/pthread_rwlock_rdlock.3
  /usr/share/man/man3/pthread_rwlock_unlock.3
  /usr/share/man/man3/pthread_rwlock_wrlock.3
  /usr/share/man/man3/pthread_rwlockattr_destroy.3
  /usr/share/man/man3/pthread_rwlockattr_getpshared.3
  /usr/share/man/man3/pthread_rwlockattr_init.3
  /usr/share/man/man3/pthread_rwlockattr_setpshared.3
  /usr/share/man/man3/pthread_schedparam.3
  /usr/share/man/man7/mdoc.7

> The handful of references to -susv2 in
> lib/libpthread could be replaced with references to ISO 1003.1?

I agree that replacing -susvX references with POSIX references makes
sense where that can be done in such a way that the resulting
statement is correct.

When considering the replacement, keep in mind that so far, our policy
has been to usually list the *latest* officially published POSIX standard
that our implementation conforms to.  That is most relevant for the
primary audience of our manual pages, software developers: It is good
practice to adhere to the latest stable POSIX standard when developing.

Some might object that developers should also consider when a feature
first became available because that might impact portability, too.
But we tend to cover that aspect in the HISTORY rather than in the
STANDARDS section.  Admittedly, HISTORY does not and cannot possibly
cover when something became available on other systems, so also listing
initial standardization might occasionally provide some limited value,
too - but even that wouldn't guarantee portability.

Anyway, i don't think we have the manpower to list initial standardization
in addition to conformance to the current standard.  In addition to that,
attempting it might result in excessive amounts of text.

Besides, i worry how to approach the upcoming -p1003.1-2008
to -p1003.1-2024 updates.  That certainly cannot be automated
with sed(1) or anything like that.  Doing it properly essentially
requires reading our entire manuals, the entire 2024 POSIX standard,
and comparing both.  Not exactly what i'd call a small task...

Yours,
  Ingo