Re: Standards References

[Carlos O'Donell <carlos at redhat dot com>]

On 10/14/2016 01:22 AM, Rical Jasan wrote:
> 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?

That is a fairly broad and difficult to answer question.

Many of the older standards are very difficult to get today.

Michael Kerrisk is probably the best keeper of the flame, and if you
find any more information I would submit patches to the linux man
pages project to update this page:

http://man7.org/linux/man-pages/man7/standards.7.html

The Open Group has the largest collection that I am aware of and several
of them are free to access (you may need an account):
http://www.opengroup.org/standards/unix
http://pubs.opengroup.org/onlinepubs/007908799/
http://www.unix.org/version2/

The ISO standards are accessible also directly from WG14:
http://www.open-std.org/jtc1/sc22/wg14/www/standards

The three most important standards for glibc are:
* POSIX Issue 7:
http://pubs.opengroup.org/onlinepubs/9699919799/
* ISO C11 (N1570)
* IEEE 754-2008 (only for sale from the IEEE)
  https://standards.ieee.org/findstds/standard/754-2008.html
 
> 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.

Yes.

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

Right.

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

Agreed.

>  * 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)

That makes sense.

> 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

Agreed.

> 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

And enforce that all functions need a standard reference.

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

Yes.

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

Agreed, that sounds great.

It reminds me a bit of the MT/AS/AC annotations work that we did, but
extending the manual again into the realm of annotated standards
compliance.

One thing to note is that there is a difference between 'the name of
the function comes from standard X' and 'the function implements what
standard X says it does', and these two don't always match. Like the
POSIX scheduling functions do not do what POSIX says they do, instead
they match more closely what Linux does. So it's not entirely clear
if those functions are buggy, should get fixed to comply, or should
not be defined if you're goal is to use only functions from a given
standard.
 
> Well, that's enough for now.  Thank you for your time.

A final note about copyright and licensing. The manual is GFDL and the
source code is GPLv2, so you cannot copy any legally significant text
from one to the other without relicensing permission by the FSF.

I believe that Joseph Myers has such an authority in GCC to do just that,
but we don't in glibc. It would be required if we had some closer source
to manual integration. We would need someone who was blessed to legally
run a script to update the manual from the source or vice-versa.

Technically I think we violate this with the errno list generation scripts
we have that integrate with the manual, but perhaps we can call that
"not legally significant."

-- 
Cheers,
Carlos.