On Tue, Apr 24, 2007 at 12:00:59AM +0100, Neil Williams wrote: > On Mon, 23 Apr 2007 16:15:02 -0500 > Steve Greenland <[EMAIL PROTECTED]> wrote:
> > On 23-Apr-07, 15:51 (CDT), Neil Williams <[EMAIL PROTECTED]> wrote: > > > I think that all libraries - without exception - must come with some > > > API documentation and the docs should be as complete and as accurate > > > as possible - ideally generated from the source itself. > > That's not a Debian issue. All we can do is include the documentation > > provided by upstream. Sure, a DD *can* write docs when they are > > missing, but we don't (and shouldn't) require it. > Why not? What is wrong with writing a basic man (3) for a library when > we already have a requirement for a man (1) for the application? That the existing requirement is already too much for us to keep up with, so adding new requirements, especially ones that require significant attention to detail to get right, dilutes our attention for little benefit? > A lack of library documentation makes a system hard for upstream > developers - these people are also Debian users and deserve support > too. Feel free to support them by writing any manpages you think are missing. > It is a Debian issue - it is precisely because the impression has got > about that Debian is unfriendly to upstream development that this kind > of change is absolutely necessary. Huh? > There is a distinct lack of man (3) and "coordinated" documentation for > libraries in Debian. True, some poorly documented packages include test > programs or examples somewhere under /usr/share/doc/ but it isn't > simple to track these down. At the very least, the Debian maintainer > should make it clear where these files are located in a man (3) for the > library. That sounds to me like an abuse of section 3 of the man hierarchy. > Where possible though, a full -doc package is a far, far > better option if Debian actually does want to support upstream > development on Debian. I think it's preposterous to assert that it's Debian's responsibility to provide upstream documentation for libraries in order to make Debian appealing as a platform to other upstreams. -- Steve Langasek Give me a lever long enough and a Free OS Debian Developer to set it on, and I can move the world. [EMAIL PROTECTED] http://www.debian.org/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
