Re: Standards References

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hi Rical,

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.

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

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/