Re: Mandatory -dbg packages for libraries? (and API docs too)
On Sat, Apr 28, 2007 at 02:37:46PM -0700, Steve Langasek wrote: write documentation or don't understand the API. Wrong API docs are surely worse than not having no docs, aren't they? snip If I thought putting it in policy would significantly improve the availability of API docs in Debian, I would support doing so. But I don't think this will happen, and anyway if people want to campaign for improving our API documentation they can do that in any number of ways without asking for it to be put in policy first. On Sat, Apr 28, 2007 at 02:48:23PM -0700, Russ Allbery wrote: In my case, because of: binary-without-manpage (1283 packages, 3616 tags) I think we should demonstrate our ability to deliver on tasks we've already promised to do before promising to do even more in the same vein. That's all true, but it fails to convince me that is better not to state this in the policy than to state it (only Steve's point about wrong API docs, but I'm convinced it will be quantitatively small). My approach to this is first to decide whether API docs in the policy is something we want in debian or not. Then, if it is the case, to state it in the policy. Then see how this will be received by DDs and maybe start filing bug with patches for fixing the issues. I don't like thinking nh, it won't work, so please don't try to enforce it. Cheers. -- Stefano Zacchiroli -*- PhD in Computer Science ... now what? [EMAIL PROTECTED],debian.org,bononia.it} -%- http://www.bononia.it/zack/ (15:56:48) Zack: e la demo dema ?/\All one has to do is hit the (15:57:15) Bac: no, la demo scema\/right keys at the right time signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
[Neil Williams] I chose Debian as a development platform for my own reasons and my decision was not deemed to be wise in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to upgrade to Fedora or SuSE. Are you saying Fedora and SuSE have API documentation for all the libraries they ship? I must say, that surprises me. My own experience with upstream's opinion of Debian is that they think we should have fixed #291641 a long, long time ago. And I can't disagree. (The problem is that since libtool apparently exposes a shortcoming in binutils, nobody seems willing to add a workaround to libtool, waiting instead for a fix from binutils.) signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Sun, Apr 29, 2007 at 09:23:03AM +0200, Stefano Zacchiroli wrote: docs, but I'm convinced it will be quantitatively small). My approach to this is first to decide whether API docs in the policy is something we want in debian or not. Then, if it is the case, to state it in the policy. Then see how this will be received by DDs and maybe start filing bug with patches for fixing the issues. I don't like thinking nh, it won't work, so please don't try to enforce it. Why do you feel that putting this into policy is a useful first step? To me the approach that you're suggesting seems to be the wrong way round - it really shouldn't require a policy amendment to ask for the inclusion of documentation. It's not something that requires a great deal of coordination between packages. -- You grabbed my hand and we fell into it, like a daydream - or a fever. signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
On 29-Apr-07, 03:10 (CDT), Peter Samuelson [EMAIL PROTECTED] wrote: [Neil Williams] I chose Debian as a development platform for my own reasons and my decision was not deemed to be wise in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to upgrade to Fedora or SuSE. Are you saying Fedora and SuSE have API documentation for all the libraries they ship? I must say, that surprises me. And if so, why haven't they submitted them upstream? :-) Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Mandatory -dbg packages for libraries? (and API docs too)
Stefano Zacchiroli [EMAIL PROTECTED] writes: That's all true, but it fails to convince me that is better not to state this in the policy than to state it (only Steve's point about wrong API docs, but I'm convinced it will be quantitatively small). My approach to this is first to decide whether API docs in the policy is something we want in debian or not. Then, if it is the case, to state it in the policy. Then see how this will be received by DDs and maybe start filing bug with patches for fixing the issues. I don't like thinking nh, it won't work, so please don't try to enforce it. This is generally not how Policy works. Policy modifications that render large numbers of packages buggy are only accepted in very unusual circumstances. Normally, the onus is on the folks wanting to make the change to get widespread adoption first, and then the Policy modification happens afterwards. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Wed, Apr 25, 2007 at 04:23:38PM +0200, Stefano Zacchiroli wrote: On Tue, Apr 24, 2007 at 08:12:46AM -0700, Steve Langasek wrote: If we are talking about hand-written documentation you're of course right. However if you're talking about documentation which can be generated automatically from sources (and not that it was the ideal point of Neil) than you're not. There are ways to generate manpages from --help output of programs. We still have a lot of programs in Debian with no manpages. According to my experience with html2man doesn't work that properly every time, but I see your point. But still I don't get the objection: is the laziness of people a good reason not to state the right path? Is this right path going to describe best practices for providing *good* API documentation? Some maintainers will do anything policy (or lintian) tells them to. If you say libraries must include API documentation in policy, they'll write API documentation -- even if they don't know how to write documentation or don't understand the API. Wrong API docs are surely worse than not having no docs, aren't they? It happened to me many times to find library -dev packages with upstream sources commented with some literate programming stuff but nevertheless missing the corresponding automatically generated API docs in the package. That's a pity. And that's something the policy should address. Hmm, I don't agree that it needs to be addressed in policy, FWIW. Fair enough, but note that having man pages is actually addressed by the policy. Why do you think API doc shouldn't? After all man pages are docs for users and API doc are too, with the only difference that in the latter case the users are programmers. If I thought putting it in policy would significantly improve the availability of API docs in Debian, I would support doing so. But I don't think this will happen, and anyway if people want to campaign for improving our API documentation they can do that in any number of ways without asking for it to be put in policy first. Cheers, -- 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]
Re: Mandatory -dbg packages for libraries? (and API docs too)
Stefano Zacchiroli [EMAIL PROTECTED] writes: Fair enough, but note that having man pages is actually addressed by the policy. Why do you think API doc shouldn't? After all man pages are docs for users and API doc are too, with the only difference that in the latter case the users are programmers. In my case, because of: binary-without-manpage (1283 packages, 3616 tags) I think we should demonstrate our ability to deliver on tasks we've already promised to do before promising to do even more in the same vein. Good library API documentation is in many cases much harder to write than a man page for a binary. Many of those already diagnosed missing man pages are a matter of a few minutes to write a brief man page for a wrapper script or simple utility. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Tue, Apr 24, 2007 at 08:12:46AM -0700, Steve Langasek wrote: If we are talking about hand-written documentation you're of course right. However if you're talking about documentation which can be generated automatically from sources (and not that it was the ideal point of Neil) than you're not. There are ways to generate manpages from --help output of programs. We still have a lot of programs in Debian with no manpages. According to my experience with html2man doesn't work that properly every time, but I see your point. But still I don't get the objection: is the laziness of people a good reason not to state the right path? It happened to me many times to find library -dev packages with upstream sources commented with some literate programming stuff but nevertheless missing the corresponding automatically generated API docs in the package. That's a pity. And that's something the policy should address. Hmm, I don't agree that it needs to be addressed in policy, FWIW. Fair enough, but note that having man pages is actually addressed by the policy. Why do you think API doc shouldn't? After all man pages are docs for users and API doc are too, with the only difference that in the latter case the users are programmers. Cheers. -- Stefano Zacchiroli -*- PhD in Computer Science ... now what? [EMAIL PROTECTED],debian.org,bononia.it} -%- http://www.bononia.it/zack/ (15:56:48) Zack: e la demo dema ?/\All one has to do is hit the (15:57:15) Bac: no, la demo scema\/right keys at the right time signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Mon, Apr 23, 2007 at 04:27:34PM -0700, Steve Langasek 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 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? If we are talking about hand-written documentation you're of course right. However if you're talking about documentation which can be generated automatically from sources (and not that it was the ideal point of Neil) than you're not. It happened to me many times to find library -dev packages with upstream sources commented with some literate programming stuff but nevertheless missing the corresponding automatically generated API docs in the package. That's a pity. And that's something the policy should address. Often, even when comments are not properly formatted, doc generation tools can generate useful documents which complements .h files or similar stuff in other languages. Cheers. -- Stefano Zacchiroli -*- PhD in Computer Science ... now what? [EMAIL PROTECTED],debian.org,bononia.it} -%- http://www.bononia.it/zack/ (15:56:48) Zack: e la demo dema ?/\All one has to do is hit the (15:57:15) Bac: no, la demo scema\/right keys at the right time signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Mon, 23 Apr 2007 19:32:46 -0400 Joey Hess [EMAIL PROTECTED] wrote: Neil Williams wrote: I chose Debian as a development platform for my own reasons and my decision was not deemed to be wise in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to upgrade to Fedora or SuSE. Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Debian is respected as a distribution for users because of the multiple architecture support and the patches and bug reports that are forwarded upstream - what is missing (IMHO) is respect for Debian as the distribution of choice for upstream development itself. Are you generalising from your one poor personal experience with a non-Debian-friendly upstream, or do you have a significant body of data that I don't about masses of upsteams who are not Debian friendly? Generalising - which probably isn't giving me the best overview, you're right. My impression has always been that a significant proportion of upstreams use Debian, or are at least familiar with it. I base this on, amoung other things, interacting with hundreds of different upstreams whose packages I have maintained in Debian, as well as working in linux companies and personally knowing a lot of upstream developers. Do you then think that Debian should not require basic API docs if upstream don't provide them - even if the information is available (and properly distributable) from outside the .orig ? The only significant documentation that is missing in Debian that I know of is GFDL licensed docs which have been removed from main. Aside from that, if a library is missing documentation, it's missing it because it's not available upsteam either. The 'big' libraries are very well documented, it's the smaller ones. Individually these may not be significant but collectively, I think there is an appreciable gap in the API docs. Recently, I've been working with libarchive (deb-gview) and libgtkhtml (gtk2 port of quicklist). libarchive has nicely commented headers which could be turned into HTML but aren't, libgtkhtml has only a test program. (I've missed one -doc package myself - just noticed that libgpewidget can build a -doc package so that's just gone on the ToDO list along with a few wishlist bugs for the above packages.) Maybe instead of seeking API docs as a requirement it would be better to seek a section under Best Practise that outlines how man (3) can be used to provide at least an introduction to the API when the .orig does not contain docs itself? -- Neil Williams = http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/ pgpNFcyopAoRV.pgp Description: PGP signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Tue, Apr 24, 2007 at 09:13:18AM +0200, Stefano Zacchiroli wrote: On Mon, Apr 23, 2007 at 04:27:34PM -0700, Steve Langasek 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 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? If we are talking about hand-written documentation you're of course right. However if you're talking about documentation which can be generated automatically from sources (and not that it was the ideal point of Neil) than you're not. There are ways to generate manpages from --help output of programs. We still have a lot of programs in Debian with no manpages. It happened to me many times to find library -dev packages with upstream sources commented with some literate programming stuff but nevertheless missing the corresponding automatically generated API docs in the package. That's a pity. And that's something the policy should address. Hmm, I don't agree that it needs to be addressed in policy, FWIW. -- 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]
Re: Mandatory -dbg packages for libraries? (and API docs too)
On Sun, 22 Apr 2007 20:39:26 +0100 Neil Williams [EMAIL PROTECTED] wrote: After reading the responses so far, the -doc element of my original idea needs modification. I'd like to see all library source packages having a minimum of 4 binary packages required by Policy: the SONAME, the -dev, the -dbg and a -doc package. (Libraries for perl or other non-compiled languages would be exempt from -dbg packages but not -doc.) The -doc is overkill for all packages but I still feel it is important for upstream development that all libraries have at least basic API documentation within Debian, not just somewhere in the Google cache. I think a -dbg package should be mandatory for all libraries that can support it, albeit with an introductory period where it is advisable, recommended then required. 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. Where such documentation makes a -doc package worthwhile, that should be done but a man (3) page in the -dev would be sufficient in some cases. I would like to see -doc packages - or at least substantive and reliable API documentation - being the norm for all libraries in Debian. As with the -dbg, the 'must' could be introduced as a recommendation prior to being mandatory. The tools exist for all these changes - only the incentive to use the tools is needed. Things like that make Debian a nicer environment to be upstream, not just a nice environment to be a DD or user. I'm upstream for many of my Debian packages and I'd like to think that Debian unstable would be the distribution of choice for upstream development. I was using Debian for upstream development long before I even considered being a DD. I chose Debian as a development platform for my own reasons and my decision was not deemed to be wise in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to upgrade to Fedora or SuSE. Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Debian is respected as a distribution for users because of the multiple architecture support and the patches and bug reports that are forwarded upstream - what is missing (IMHO) is respect for Debian as the distribution of choice for upstream development itself. Possible policy amendment: Any library source package capable of building with debug information (i.e. with -g) must do so. Any such library source package must strip the debug symbols into separate objects, provide a binary package librarynamesoversion-dbg containing these separate objects as /usr/lib/debug/path/to/ELF/object for each /path/to/ELF/object in the main library package, and reference these separate objects in a .gnu_debuglink section in the corresponding unstripped object. (Thanks to Josh Triplett) I'd like to add something on -doc to that proposition but haven't decided how just yet. All library packages must include at least basic API documentation either in the -dev package or in a dedicated -doc package where sufficient documentation exists. Wherever possible, documentation should cover the entire library API, be generated from the source code of the library and be registered with helper programs like dwww and/or devhelp etc. (subject to being introduced as a recommendation prior to being made mandatory.) What happens now? Would these changes need a GR? Would it be sufficient to generate a bug report against Policy? Or submit these ideas to -policy and take from there? -- Neil Williams = http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/ pgpRNdsh1sZHy.pgp Description: PGP signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
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. Is there any case where existing valid distributable documentation is *not* in the appropriate Debian package? (Not including issues like the GDL). Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Huh? Why do upstreams think that they need to be DDs to use Debian? Because we discourage non-DD upstreams from distributing crappy non-conforming .debs alongside their crappy non-conforming .rpms? (Not that I blame upstreams for having crappy .debs; there's a lot of policy and a lot of technology to understand - better to let a specialist take care of it.) All library packages must include at least basic API documentation either in the -dev package or in a dedicated -doc package where sufficient documentation exists. Wherever possible, documentation should cover the entire library API, be generated from the source code of the library and be registered with helper programs like dwww and/or devhelp etc. I'd remove the generated from the source code clause. Yes, many projects choose to do their docs that way. Some don't. Would these changes need a GR? No. Or submit these ideas to -policy and take from there? Yes. Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Mandatory -dbg packages for libraries? (and API docs too)
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? A lack of application documentation makes a system hard for users - we know that so Policy mandates a man (1) for these people whether one exists in the .orig or not, even if it is almost empty. A lack of library documentation makes a system hard for upstream developers - these people are also Debian users and deserve support too. True, they may be more 'advanced' than the average user in terms of their knowledge of C or the autotools - doesn't mean that DD's can assume that they know how a DD would find out the information they need. Upstream generally tries to be as distro-neutral as possible - this can be very difficult with inadequate documentation. 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. The information isn't being made accessible and that results in people thinking you have to know what a DD knows in order to work out what is wrong with the upstream build on your system. These are development builds, not releases - not even snapshots. Things often break and if we want upstream releases that build nicely on Debian, it is good to encourage more upstream developers to use Debian. DD's win in the end - cleaner upstream development builds make for cleaner released .orig builds, meaning less patches! That has to be AGoodThing (tm)! Conversely, a lack of information can result in those upstream developers who choose to use Debian being flamed as a result of that choice because their commits break the build for other distros (another snippet from my pre-DD days!) I can assure you, claiming that your changes haven't broken the build on your Debian system cuts no ice when the change has broken everyone else's build!!! Without the docs, the Debian user is left without the information required to either defend their change or fix the build. Not good. If there is no documentation, file a bug upstream and ask. If the response is RTSL, this should at least be documented in Debian so that users of the -dev know who to blame for the lack of docs. Having a Debian man (3) also provides a focus for contribution of suitable content for the man (3) which in turn could be forwarded upstream. It's easier to add content to an existing man (3) than to create a patch to create a whole one from scratch - especially when the contributors are not necessarily familiar with Debian packaging beyond apt-get. Is there any case where existing valid distributable documentation is *not* in the appropriate Debian package? (Not including issues like the GDL). 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. Where possible though, a full -doc package is a far, far better option if Debian actually does want to support upstream development on Debian. That's why I stressed the registration of docs with dww and/or devhelp. Some libraries have very, very good docs - libglib2, libgtk2 - the problem comes with the smaller libraries, specialised tasks that are only used by a few applications. By definition, few people will know these API's yet these are often the very libraries that have the least documentation - hence mandatory -doc or man (3). Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Huh? Why do upstreams think that they need to be DDs to use Debian? I can only speak from my own experience upstream on this - I wasn't new to Debian at the time but most questions that I asked (or problems that I experienced) came back with a response of must be something wrong with Debian because something everyone else did wasn't working for me. I didn't have the documentation available to find out what was wrong and it was very frustrating. In the end, I resorted to a laborious method involving rsync and simultaneous builds on Debian and Fedora prior to commits. That kind of hack can seriously drain
Re: Mandatory -dbg packages for libraries? (and API docs too)
Neil Williams wrote: Would these changes need a GR? Why would a policy change need a GR? How could a GR possibly be the best way to choose a sound technical policy? -- see shy jo signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
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]
Re: Mandatory -dbg packages for libraries? (and API docs too)
Neil Williams wrote: I chose Debian as a development platform for my own reasons and my decision was not deemed to be wise in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to upgrade to Fedora or SuSE. Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Debian is respected as a distribution for users because of the multiple architecture support and the patches and bug reports that are forwarded upstream - what is missing (IMHO) is respect for Debian as the distribution of choice for upstream development itself. Are you generalising from your one poor personal experience with a non-Debian-friendly upstream, or do you have a significant body of data that I don't about masses of upsteams who are not Debian friendly? My impression has always been that a significant proportion of upstreams use Debian, or are at least familiar with it. I base this on, amoung other things, interacting with hundreds of different upstreams whose packages I have maintained in Debian, as well as working in linux companies and personally knowing a lot of upstream developers. The only significant documentation that is missing in Debian that I know of is GFDL licensed docs which have been removed from main. Aside from that, if a library is missing documentation, it's missing it because it's not available upsteam either. -- see shy jo signature.asc Description: Digital signature
Re: Mandatory -dbg packages for libraries? (and API docs too)
Neil Williams wrote: snip 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. Is it unreasonable to expect libfoo's docs (independent of format or quality) to be located under /usr/share/doc/libfoo, and not somewhere else? snip Noting if the Debian library package differs significantly to the library upstream and why - not somewhere in NEWS.gz or README.gz, but in the one place application developers will look, the API docs. AFAIK, README.Debian is _the_ place where divergences from upstream should be noted. I can't find (yes, I only glanced through the documents, please correct me if I'm wrong) any reference to that neither in the Debian FAQ nor the Debian Reference, which I assume are the 2 most important user documents. Maybe a note should be added? -- Felipe Sateler -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
