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]
