Re: Standards References

[Rical Jasan <ricaljasan at pacific dot net>]

On 10/26/2016 01:58 AM, Michael Kerrisk (man-pages) wrote:
> On 26 October 2016 at 10:23, Rical Jasan <ricaljasan@pacific.net> wrote:
>> > On 10/25/2016 04:48 AM, Michael Kerrisk wrote:
>>> >> On Tue, Oct 25, 2016 at 3:50 AM, Carlos O'Donell <carlos@redhat.com> wrote:
>>>> >>> On 10/14/2016 05:33 AM, Rical Jasan wrote:
>>>>> >>>> To start fleshing out 1b below, would you want to use those names, or
>>>>> >>>> names from feature_test_macros(7), or both?  I think I would lean
>>>>> >>>> towards correlating the two, so rendered names might be more friendly
>>>>> >>>> like standards(7), but were connected to the names in
>>>>> >>>> feature_test_macros(7), allowing us to eventually say things like, "foo
>>>>> >>>> is standardized by Nicely Formatted Standard Name, and made available
>>>>> >>>> whenever _NFSN is defined.", or however we agree on the rendering.
>>>> >>>
>>>> >>> I would also lean towards correlating the two.
>>> >>
>>> >> Yes, if we could have some consistency between the two projects, that
>>> >> would be great.
>> >
>> > So how would you envision the two (projects) integrating?  Perhaps
>> > naïvely, I would have gone for some kind of auxiliary data file in
>> > manual/, or worse, some data structure like an associative array/hash
>> > tucked away in a script there to provide the translation, at least to
>> > get it off the ground.  Maybe even a bunch of macros in macros.texi, if
>> > that seemed most maintainable.  I'm not familiar with how the man pages
>> > project is maintained, so I have a hard time imagining what sort of
>> > solution would best serve the two.
>> >
>> > Maybe a new database?  /etc/stdftm  :)  I'm reading Carlos' response as
>> > desiring a correlation between standards names and feature test macros
>> > (in the glibc manual), and Michael's use of "projects" to mean something
>> > common between the manual and manpages.  Maybe that's a little out of
>> > scope, or maybe that's a worthwhile -- and achievable -- ideal.
>> >
>> > Doing this from scratch in the glibc leaves the doors wide open for us,
>> > but, Michael, what would work for you?
> 
> In the first instance, I was thinking that it's desirable to have
> consistency in the names and terminology (perhaps based around the
> terms in standards(7), since that what the man pages use already,
> though there may be room for improvement / fine-tuning). This probably
> also implies a correlation between standards names and feature test
> macros in the glibc manual.

There is definitely more colour in standards(7) than there is in the
glibc manual, but it sounds like I should be wary of referencing it too
much until we decide we want 1:1 correlation with the names.  I will
say, if I wasn't working on the manual here, that would be a place I'd
assume was authoritative, in the sense you at least wrote the name of a
standard correctly.  I'll keep in mind that if I ever find a standard
formats their name differently from what you've written, to let you know.

By "colour", I mean the glibc manual is rather devoid of any granularity
in its presentation of standards names, on the whole (referring mostly
to the @comments, but also the free-form text).  For example, "System V
release 2" or "SVr2" isn't ever mentioned---"SVID" is the norm.  There
are notable exceptions; e.g., arith.texi, where the @comment might say
"ISO", but the text says "IEEE 754-2008".  I'm not yet close to a
framework that accommodates that, but it's definitely a goal I keep in
mind.  The issue I see is, there isn't an "ISO" standard or feature test
macro equivalent to "IEEE 754-2008" (though versioned FTMs might
include/exclude it; I haven't looked in-depth yet).

"SVID" is probably a bad example that needs special attention too, as I
believe it falls under the "MISC" FTM.  The historian in me wants to say
at least "SVr2", but that may wind up being a part of the textual
component, and not the automated ftm<->std bit.

> Creating a "database" of this information that could be shared is an
> interesting idea, and beyond what I was thinking of when I replied
> earlier.

I was being a little facetious with /etc there, :), but..

> The way that I'd probably use it is as a consistency check
> for what's in the CONFORMING TO section in the man pages, but I'm not
> sure how well such checks could be automated.

that makes me think of the auxiliary data file idea.  If licensing
between the projects allowed, were we to maintain a file that correlated
the feature test macros found throughout the headers (well, features.h)
with specific (versions of) standards(7), we could work something out
that was easy to use for everyone.

On the topic of conformance, Carlos mentioned that the glibc provides
things mandated by standards, but which had deviant implementations.
That opens a can of worms for both CONFORMING TO and the manual (i.e.,
how to say, "This function is mandated by POSIX.1g, present, but
implemented in a non-conforming way by GNU/Linux.").  I'm sure the
solution can be fancy enough to accommodate both, though.  :)

Rical