Re: [PATCH] Fix up LD_* vars behaviour

["Carlos O'Donell" <carlos at systemhalted dot org>]

On Fri, Apr 13, 2012 at 6:23 PM, Michael Kerrisk <mtk.manpages@gmail.com> wrote:
>> The glibc community has recently undergone some significant changes
>> that probably make it easier for our projects to work more closely
>> together.
>
> Yup. You folk seem to running a whole spirit-of-glasnost thing at the
> moment. ;-)

Eek! ;-)

>> I would like to work more closely with the man-pages project in the
>> following three concrete ways:
>>
>> (a) Link to the man-pages project from the glibc documentation page:
>> http://www.gnu.org/software/libc/documentation.html, and consider the
>> man-pages as an alternative source of information for the interfaces
>> defined in glibc.
>>
>> (b) Work closely with the project to keep key man pages updated e.g.
>> ld.so. For example we've just added a new --inhibit-cache that will be
>> out with 2.16.
>>
>> (b) Make it part of our contribution checklist to update the
>> associated linux man-page e.g. "Where is your linux man-pages update?"
>> (http://sourceware.org/glibc/wiki/Contribution%20checklist).
>>
>> (c) Work out a commit after review process for interested developers
>> that will be checking in patches to the linux man-pages.
>>
>> Whether we like it or not there are three sources of information for
>> the Linux kernel and glibc APIs:
>>
>> (1) Official standards like http://pubs.opengroup.org/onlinepubs/009695399/
>> - Information about portability is very good.
>> - Unfortunately they do not document glibc specific information.
>>
>> (2) The GNU C Library manual http://www.gnu.org/software/libc/manual/
>> - Traditional manual available in many formats.
>>
>> (3) The man-pages project
>> http://man7.org/linux/man-pages/dir_all_alphabetic.html
>> - Detailed information per interface in man format.
>>
>> Each of (1), (2) and (3) offers our users choice in how they want to
>> view the APIs.
>>
>> For example at Mentor Graphics we ship the (2) as HTML and serve it
>> through Eclipse help along with all the other GNU tools project
>> manuals to provide a comprehensive cross-indexed searchable set of
>> manuals. This is relatively easy to do with texinfo manuals.
>>
>> It is my opinion that (1), (2) and (3) will exist forever and that we
>> should be creating a community that ensures all are updated and
>> reflect reality.
>>
>> Comments?
>
> All of the above sounds great to me. But (stepping out on a limb
> here...), here's a proposed extension to the above: embrace man pages
> fully as the repository of detailed glibc interface documentation.
> Here's where I'm coming from:
>
> 0. It seems pointless to duplicate effort maintaining detailed API
> documentation in both man-pages and the glibc manual.

I don't think anyone wants to waste time duplicating the effort done
by the man-pages project. I certainly don't.

> 1. For most of the glibc interfaces, man-pages already does a rather
> better job of documenting interface details than does the glibc
> manual. I can't see much benefit in replicating that level of quality
> in the glibc manual (and I doubt anyone will step forward to try to do
> that).

Agreed.

> 2. Notwithstanding the previous, the glibc manual does do some things
> that man-pages doesn't do. Here, I'm meaning that the glibc manual is
> more "book like" than the man pages; in some areas it provides quite
> good coverage of "how and why" to do things. Going forward, make that
> the focus of the manual, rather than trying to detail all of the APIs
> (where, anyway, the manual falls far short).

I like that idea.

> 3. The corollary to the previous... Invest effort in man-pages to
> ensure that it does accurately reflect the details of the glibc
> implementation, and can be treated as the authoritative source for
> those details.

Agreed.

> Just to be clear, Carlos, I'd happily live with your proposal, since
> it would be a great improvement on the current situation. But, there
> could be benefits for both projects if we went a little further as I
> propose above.

I agree.

I would still like to see terse function descriptions in glibc just to
provide a "What's this function signature?" type information, then the
"How and why?" in book-ish form, and if you need anything else go to
(1) or (3).

Personally I like the proposal.

Which reminds me that sys/platform/ppc.h should get documented in man-pages.

Comments?

Cheers,
Carlos.