[DRE-maint] When to separate into separate binary -doc package (WAS Re: github-markup_0.7.5~git.20130607.8154dca-1_amd64.changes REJECTED)

[Per Andersson]

On Wed, Apr 16, 2014 at 11:24 PM, Cédric Boutillier <boutil at debian.org> wrote:
> Dear Gergely,
>
> On Mon, Jul 22, 2013 at 05:00:06PM +0000, Gergely Nagy wrote:
>
>> I would also recommend merging the -doc package into the main binary
>> package, because frankly, that extra 156k uncompressed is not going to
>> matter.

(...)

> I am about to upload a new version for this package, as a result of a
> collective effort. All the points you have mentioned have been
> addressed:
(...)
> - a unique binary package containing the library and the documentation.

When is it worth to separate the documentation from the main package?

I did a quick search for -doc packages and it looks like most of them are
larger than a megabyte or so.

The Debian Ruby Policy draft states that documentation should be
packaged in a separate package, if it's not really small.

    http://anonscm.debian.org/gitweb/?p=pkg-ruby-extras/ruby-policy.git;a=blob;f=ruby-policy.mdw;h=b73fc81565f386ff9730cfdfbc8ed168fffbb409;hb=HEAD#l170

Adding an actual size there would be helpful.


The Java policy states that the API *must* be placed in a separate -doc package
and then be recommended by the library package. It does not seem to be followed
though, after having a quick glance in the archive.


I have started working on automatically building the documentation with gem2deb.
(Volunteered for this at DebConf13...)


--
Per