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


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.

The glibc community has recently undergone some significant changes
that probably make it easier for our projects to work more closely
together.

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?

Cheers,
Carlos.


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