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

[Russ Allbery <rra@debian.org>]

Johannes Schauer <j.schauer@email.de> writes:
> Quoting Russ Allbery (2014-08-26 23:51:08)

>>     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.

Ah, yes, that's a good point.  It's going to be tricky to suppress the
actual package construction without modifying debian/control, which we
don't want to do.

> 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.

This is back to the problem of ambiguity with changelog, copyright, etc.
Hm.  How about:

    This tag says to skip any build steps that only generate package
    documentation.  Required files such as copyright and changelog files
    must still be generated and put in the package, but other generated
    documentation such as help2man-generated pages, Doxygen-generated API
    documentation, or info pages generated from Texinfo sources should be
    skipped if possible.  This option does not change the set of binary
    packages generated by the source package, but documentation-only
    binary packages may be nearly empty when built with this option.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>