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 04/20/2012 01:30 AM, David Miller wrote:
From: "Joseph S. Myers"<joseph@codesourcery.com>
Date: Thu, 19 Apr 2012 23:18:53 +0000 (UTC)

In accordance with the GNU Coding Standards, man pages are secondary
to the Texinfo documentation for GNU software.  They should be read
as independent observations about the library rather than a contract
with applications.

Unfortunately this line of thinking ignores reality. I really am getting frustrated with these repeated divisive statements about the manual pages vs glibc.

If the glibc documentation were complete and widely used, you could
say that the man-pages are secondary.

But the glibc documentation is far from complete and is not widely
used, and therefore the man-pages are not secondary.

The man pages are the de-facto documentation for the application
programming interfaces provided by glibc.  They are the primary and
only complete source.  No coding standards document, GNU or otherwise,
can change this fact.

I would like to see a deeper acceptance and acknowledgment of this
reality, rather than the continued usage of scarecrows such as the GNU
Conding Standards to pretend that the actual situation is different or
should not be acknowledged.

I agree with Dave here. The man pages are indeed the de-facto documentation.


How can we actually better work together?

I propose the following things as a starting point:

* Michael is now on the default CC list of bugs for the glibc manual and thus will see requests for documentation - many of them are for man pages instead of the texinfo documentation.

* If glibc introduces or changes an interface, the author will work with the man pages project on updating the man pages (and also on updating the glibc manual). The man pages team is welcome to approach the glibc team with questions and reviews on man pages.

* The glibc wiki contains a reference to the man pages project.

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


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