This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] Fix up LD_* vars behaviour


Hello Carlos,

On Fri, Apr 13, 2012 at 1:39 PM, Carlos O'Donell
<carlos@systemhalted.org> wrote:
> On Thu, Apr 12, 2012 at 7:57 PM, Michael Kerrisk <mtk.manpages@gmail.com> wrote:
>> The problem with the above view, when it comes to the many (many)
>> interfaces (or details of interfaces) that are undocumented in the
>> glibc manual, is that the users of glibc have no predictable contract
>> about behavior. That's a grave disservice to glibc users. There was no
>> documentation, so the users poked around to discover the details, and
>> then wrote applications based on assumptions that what existed would
>> always be so. But, given the lack of documentation, what else were
>> those users otherwise supposed to do?
>
> Michael,
>
> I would like to say that in the one or two times I've interacted with
> the man-pages project you've been nothing but perfectly professional
> and helpful and that reflects enourmously on my opinion of the
> man-pages project. Please keep up the good work.

Thank you.

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

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

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

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

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.

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.

Cheers,

Michael


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]