Bug#759186: debian-policy: please consider adding "nodoc" as a possible value for DEB_BUILD_OPTIONS to policy

[Johannes Schauer <j.schauer@email.de>]

Hi,

Quoting Russ Allbery (2014-08-26 23:51:08)
> > I think that it is a good idea.  Here is a draft patch.
> 
> > When writing this patch, I became unsure if “*-doc” packages are the best
> > description for the binary packages that will not be built.

probably in many cases but while it would not make sense to restrict to
packages named in a certain way, *-doc packages could serve as an example of
what is not built.

> > Should it be any package in the “documentation” section instead ?

Having a package centric view on it would forbid to not build the documentation
which is shipped as part of a main package without a special *-doc package.

> > Or should it be kept vague to give flexibility to the maintainer to do the
> > right thing ?  I opted for this choice and wrote “packages containing the
> > generated documentation”.

I would agree to the latter.

> This is somewhat ambiguous about things like copyright and changelog, which
> might be considered part of the documentation (since they're in
> /usr/share/doc).  How about this:
> 
> > --- a/policy.sgml
> > +++ b/policy.sgml
> > @@ -2256,6 +2256,11 @@ zope.
> >                 This tag says to not run any build-time test suite
> >                 provided by the package.
> >             </item>
> > +           <tag>nodoc</tag>
> > +           <item>
> > +               Do not build the documentation and do not build the binary
> > +               packages containing the generated documentation.
> > +           </item>
> >             <tag>noopt</tag>
> >             <item>
> >                 The presence of this tag means that the package should
> 
>     This tag says not to build any separate binary packages that contain
>     only documentation, and ideally to skip any time- or
>     resource-consuming build steps that only generate documentation.
>     Examples include Doxygen-generated documentation, generation of info
>     pages from Texinfo source, or generation of PDF files from TeX
>     documents.

A question is, whether the "nodoc" option should result in some binary package
not being built. The mechanics of conditionally not building certain binary
packages is already specified for build profiles. I do not think that the
DEB_BUILD_OPTIONS mechanic is the right place for this.

In my view, DEB_BUILD_OPTIONS should just enable or disable certain code paths
of the upstream build itself but not influence anything else. So if "nodoc" is
set, the build should just not run the steps that create documentation. If
there are any *-doc binary packages, then they will probably come out empty but
that should be expected. If documentation was part of a main binary package,
then that package will now ship less files.

I would thus propose the following paragraph:

    This tag says to skip any build steps that only generate documentation.
    Examples include running help2man, Doxygen-generated documentation,
    generation of info pages from Texinfo source, or generation of PDF files
    from TeX documents.

I don't think it's important to limit the use on "time- or resource-consuming
build steps".

cheers, josch