Standards References

[Rical Jasan <ricaljasan at pacific dot net>]

I'm working on updating things in the manual, mostly in the Sockets
chapter right now (have also been chipping away at the empty POSIX
Threads chapter, which is possibly lower-hanging fruit, but more of it,
and less familiar), and I'm keeping in mind the eventual project of
annotating relevant standards with some kind of (presumably) macro
framework [1].  To that end, I have some questions.

Doing a rough survey [2] of the standards @comments to get an idea of
what's present, I see a variety of levels of certainty and specificity
(not the actual output of [2]):

 BSD
 BSD/SVID
 GNU
 IPv6 Basic API
 ISO
 ISO/Amend1
 LFS
 Linux
 Obsolete
 POSIX
 POSIX.1
 POSIX.1b
 POSIX.1c
 POSIX.1g
 POSIX.2
 Sun
 SunOS
 SUNRPC
 SVID
 Unix
 Unix98
 X/Open
 XOPEN
 XPG
 XPG2
 XPG4
 XPG4.2
 ???

and my favorite:

 I doubt this really exists

Those are merely representative; they occur in various combinations,
cases, alternate spellings, etc.  There are others I know I've seen but
aren't present above either, like RFCs and some IEEEs.  Even more fun,
and ironically unstandardized, some seem to go by multiple names.
Sometimes more detailed information is present within the function
description itself, for example.

Point being, that list is by no means complete, but should work for the
following question:

 * Where can I find the references for these standards?

Based on elements of the description of the framework in [1], it seems
that in an ideal manual, we'd have definitive annotations for all the
standards a given item fell under; e.g., different feature nest macros
may independently yield a particular function's declaration.

It would also seem that standards' versions would be relevant here, as I
believe some header tests check for them (and who knows, maybe some
should, but don't).  I would think we would want the earliest version of
the standard in which something was present, but I can see doing that
exhaustively getting messy, and mind-numbing, quick.

This is obviously work for a historian, and unfortunately I haven't
lived this particular history, so it's an actual study.  Recognizing
that, I think it'd be more practical to ignore the encyclopaedic utopia
of 20 years from now [3] and focus on the necessary legwork that needs
to be done.  So my next question:

 * How do the following first steps sound?

 1) Refactor all the source-level standards @comments into
  a) a consistent ordering wrt. line placement (@comment before @def)
  b) a consistent nomenclature (no more XOPEN and X/Open)

which should put us in a good place to:

 2) Implement a basic macro framework by
  a) converting @comments to macros and
  b) removing the free-form comments already in descriptions

Getting through Step 2 seems achievable (for me) in the reasonably short
term, and gets the manual to a point where we have a consistent
framework for annotating standards in the manual.  At that point,
further work could be done to:

 3) Fill in missing standards and
 4) Vet standards references for
  a) correctness,
  b) completeness, and even
  c) versions

I imagine those steps would apply to both the manual and the headers.

The proposal in [1] envisions perhaps a greater level of interoperation
than I could provide in the short term, but I would like to see the
standards references cleaned up, period.  As described in [4] (looking
now at the notes mentioned there, they are from March 2015), I think a
simple macro framework would be nice, and would provide much-needed
consistency, at least within the manual itself.  I also don't think it
conflicts with the extended vision in [1] (e.g., automated checking of
all macros and headers with their documented standards, etc.) because
that could come after Step 2 or supplant it entirely, and Steps 3 & 4
are really just the long-term historian's work that will plug in to
whatever framework exists (including the current one, if Steps 1 and/or
2 never happen).  I've tried to pick steps that do something useful
regardless of how many or which are taken, always improving something,
keeping our options open, and easing any future work.


Well, that's enough for now.  Thank you for your time.

Rical

----
[1] https://sourceware.org/ml/libc-alpha/2016-06/msg00039.html
[2] sed -rn '/^@c(omment)? /{:loop;h;n;/^@c(omment)?
/{bloop};/^@(def|item)/{g;p}}' manual/*.texi | sort -u
[3] https://sourceware.org/ml/libc-alpha/2016-10/msg00095.html
[4] https://sourceware.org/ml/libc-alpha/2016-06/msg00064.html