[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: library packaging doc...

On Fri, Jan 28, 2005 at 12:20:25PM +0900, Junichi Uekawa wrote:

 > >  I haven't read the document in question in a rather long time, so
 > >  I can't actually object (on some sort of serious basis, I mean),
 > >  but I would nevertheless request that the document be handed to
 > >  the -english mailing list for proofreading *before* it's uploaded
 > >  as a package and that a big "THIS IS A *GUIDE*" banner be stamped
 > >  on it.  The last thing I want is people complaining that libfoo
 > >  doesn't follow some chapter and verse of said guide under the
 > >  impression that it is somehow "correct", "standard" or
 > >  "mandatory".
 > I think this proofreading has happened some time ago; but will
 > definitely benefit from being proof-read again.

 Most definitely.  Proofreading != spellchecking, you know?  The
 (current!) document has a very, what should I call it? Bumpy style?
 Maybe even jolty.  Your use of punctuation is... let's say unusual.

 What I'm saying is that it's hard to read.

 You provide little rationale at places where rationale is really needed
 and make some assertions at places where they are really not needed.
 Off the top of my head, the SONAME section could use some rewriting.
 The parts concerning to static libraries need some serious rewording.
 The part about version numbers really needs clear examples.

 In fact, the whole thing needs "do [this] and watch it break like
 [this]" examples.

 > This document has been around for more than 2 years now.

 I know.  I didn't like it at the beginning either.

 It *does* contain some rather useful information, but again, it falls
 short at places where it shouldn't.

 > As for your objection of "correct", "standard" or "mandatory", I
 > would say that this document is a recommendation, and should be
 > followed when there is not a good argument against it. If there is a
 > good reason not to follow this document, in which case I would
 > recommend providing a patch against the libpkg-guide.

 What I'm saying is that -- in the same way that some people insist on
 Debian Policy to be followed blindly -- there are already some people
 insisting that this document be followed blindly.  "Raising" the status
 of it to something more "official" would make things only worse.

 > After all, what this document tried to be is to document current
 > practice, backed with some bugreports resulting from mis-packaging;

 Yes, I still remember the discussion and I'm still burned out by it.  I
 recall vividly how I had to waste much time to convince you that there
 was a problem with libpng in the first place and then even more time to
 get you to understand what the proper solution was.  I really have no
 intention of rehashing that chapter.


Reply to: