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


Hi Carlos,

On Tue, Apr 17, 2012 at 12:32 PM, Carlos O'Donell
<carlos@systemhalted.org> wrote:
> 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

(Yes, sure.)

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

Thanks for the enthusiasm Carlos. I'd certainly be interested to hear
opinions from more of the maintainers on whether this is an idea they
could buy into.

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/


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