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,

So I preface my comments here with some background and some
observations, some straightforward, some perhaps contentious.

1. I came to man pages around 2000 as a steadily increasing
contributor, and became maintainer in late 2004. By that time,
obviously, both glibc and man-pages were long-established projects.
And, unfortunately, the relationships between the two projects does
not seem to have been terribly friendly. I do not know the details of
why, but the lead maintainer on one project was rather too laconic,
and the lead on the other was often unfriendly, and probably neither
of these things helped.

2. There's a significant amount of duplicated effort between the glibc
manual and the man pages. That's unfortunate. Partly it's about
philosophical differences (man vs info format). I don't know what the
best (or most agreeable) way is of minimizing that duplication of
effort, but I would be interested to have a discussion about how we
could improve things by better cooperation.

3. The glibc manual has some nice overview and background
documentation that can't be found in man-pages, but I think one does
not have to look too far to conclude that the documentation of glibc
*interfaces* in man-pages is generally rather better than the
corresponding documentation in the glibc manual (although a few glibc
interfaces are not yet documented in man-pages but are in the glibc
manual).  Aside from (usually) having a greater level of detail, there
are significant general areas covered in man-pages that are barely (or
not at all) covered in the glibc manual. Here, I'm thinking of things
such as the VERSIONS sections which let users know when an interface
became available, documentation of feature test macro requirements,
statements about relevant standards in CONFORMING TO, and a general
philosophy of documenting historical changes in details of the
interfaces.

4. I think it's worth considering why man-pages has better
documentation. These are my theories:

* There's been an active maintainer that cared explicitly about
documentation. man-pages was started in 1993 by Rik Faith, and, a
little surprisingly, I am only the third maintainer. Andries Brouwer
did a huge amount of work over 9+ years, with the releases from 1.6
through to 1.70. (One limitation of Andries's work though was that he
was not good at involving others: there was no dedicated mailing list,
no changelog, and no version control; all of which I rectified when I
took over.) And I did a huge amount of work after that (although time
pressures have seriously limited my input in the last 2 or 3 years).

* The project has been welcoming of participation. Since 2004 (when
man-pages got version control, so that these things can be tracked),
man-pages has incorporated contributions and input from around 500
different individuals in around 7500 commits. I suspect the
corresponding numbers are markedly different for the glibc manual.
(And as an aside, I must add that I was one of many who got burned
when making first attempts to contribute (code) to glibc a decade ago,
and gave up, instead limiting myself to making bug reports.)

* Without wanting to start a flame war, there's the format problem. I
have yet to meet a programmer who had a kind word to say about
info(1). Programmers strongly prefer "man page" format. And,
preferring man pages, they contribute to the man-pages project.

On Fri, Apr 13, 2012 at 6:19 AM, Roland McGrath <roland@hack.frob.com> wrote:
>> > If we made a mistake on an implementation and it's been out in the
>> > wild for some time, and people do depend upon it, we're essentially
>> > stuck supporting it forever whether we like it or not.
>>
>> Agreed.
>
> There are two categories here.
>
> If something was always explicitly unspecified or undefined and we didn't
> make an explicit choice to make it more predictable in the glibc API, then
> people depending on whatever behavior they observed were wrong to do so.
> We can change it when it's worthwhile for other reasons. ?Of course,
> practical considerations of common usage may influence our choices. ?An
> excellent example is the recent memcpy change. ?Developers who thought
> memcpy was memmove were wrong, even though it happened to be the case that
> glibc's memcpy reliably behaved as memmove for years. ?We changed it and it
> was entirely fine that we did. ?But there were practical problems affecting
> many users, so we found a middle ground: those developers were still wrong,
> but glibc users using existing binaries from those developers deserved that
> we help them work around the problem, so we did.
>
> What Dave mentioned is the second category, for which I don't know of an
> example off hand. ?That is, we always had consistent behavior and there was
> no particular reason to think that there was an accepted range of variation
> in the behavior a future library might exhibit, but we were violating a
> specification to which we otherwise attempt to conform. ?If such a case
> arises, we'll have to figure out how to handle it. ?Standards do matter,
> but users also matter, and it's our responsibility to bridge the gap
> appropriately in each case.
>
>> - If we release it, and users use it, and can be reasonably expected
>> to have it keep working either by ambiguity in the standard or
>> documentation, then we must support it.
>
> That is too broad. ?There is plenty of ambiguity in documentation,
> especially in absent documentation. ?Every case is a balancing test
> and there is no simple rule that relieves us from applying our judgment.
>
>> Roland, unfortunately I feel that your position with respect to the
>> linux man pages project is not correct. As a project we have failed to
>> document our own interfaces and over the years the linux man pages has
>> become *the* canonical documentation for the GNU Libc interfaces like
>> LD_* vars passed to ld.so.1. Whether we agree with them or not is
>> irrelevant at this point, we need to think about our users, and our
>> users for lack of our own documentation, rely on the linux man pages.
>
> I disagree utterly. ?We cannot be held hostage to what some uncoordinated
> other people out in the world have done.

Roland, I don't disagree with your general point here (though I'd
paint some of the details you mention below a little differently), but
see below for a general counter point.

> There is a long history of Linux
> man pages being thoroughly wrong. ?Unfortunately, there is also a long
> history of some glibc features lacking documentation in the manual, and of
> the manual not always being right.

I do feel the picture you paint here ("man pages being thoroughly
wrong... the manual not always being right") is a little skewed. Yes,
there are errors in the man pages, and some stood for a long time, but
by now, they're of generally high quality (and yes, you will still
find exceptions to that statement). There are also longstanding errors
in the glibc manual, but I think they're less likely to be reported,
for the reasons given above.

> When the manual does not comport with
> the reality or intent of the code, then we change the manual. ?When the
> manual doesn't say anything at all, then the appropriate level of
> compatibility and the reasonableness of a given user's expectations must be
> subject to our careful judgment. ?There are no easy rules.
>
> What users mostly do in fact is just experiment and observe, and then
> expect the behavior they observed to be preserved in the future.
> Sometimes those expectations are reasonable and sometimes they are not.
> We are responsible to all the users, past, present, and future--not just
> particular vociferous past users who rail against some change. ?We are
> the experts and it's our responsibility to judge what's best overall,
> not that of some subset of users and not that of some man-page writer.
> Sometimes slavish compatibility with the past bad assumptions of
> application developers or outside documentation writers does a
> disservice to the users at large. ?That's one reason we have major
> releases and minor releases. ?Certainly controversial cases don't change
> in minor releases.

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?

Cheers,

Michael


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