I recently introduced support for nodoc for libgdamm5.0 in its
packaging branch (not uploaded to unstable yet) [1]. Since there is
only one arch-indep package, the -doc package, there are no packages
built when an arch-indep build is attempted with the nodoc build
profile.

This is technically a violation of Debian Policy 4.9.1 which has this wording
"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." [2]

I don't think there is any benefit to anyone from empty -doc packages.
Therefore, I propose that that sentence be removed. (Maybe with a
statement specifically saying that it's ok not to build certain binary
packages that only contain documentation. Or we could be more
aggressive and make it a recommendation to *not* create empty
documentation packages.)

History
=====
The nodoc section of Debian Policy was requested in
https://bugs.debian.org/759186

The original proposed wording did not have the sentence I disagree
with. This wasn't added until comment 40 (but see also comment 35).
See the concern expressed in comment 50 which in my opinion foresees
the issue I present here.

Other Info
========
Specifically, it is these lines in debian/control that lead to this
-doc package not being built. Perhaps that possibility was not as
clearly seen when the Debian Policy wording was added.

Package: libgdamm5.0-doc
Build-Profiles: <!nodoc>

The wiki also would need to be updated. [3]

[1] https://anonscm.debian.org/git/pkg-gnome/libgdamm5.0.git
[2] https://www.debian.org/doc/debian-policy/#debian-rules-and-deb-build-options
[3] https://wiki.debian.org/BuildProfileSpec#Registered_profile_names

Thanks,
Jeremy Bicha

What about packages that depend on -doc packages ?
They might become uninstallable.

Cheers,

build profile with the nodoc build option. This is a very easy mistake to
make; I'm not sure what the point of the nodoc build option is any more,
other than compatibility with packages and tools that might already have
used it.

My interpretation is that the nodoc build profile requires/implies the
nodoc build option (building with the nodoc profile but not the nodoc
option is undefined behaviour, and is allowed to fail), but the nodoc
option does not imply the nodoc profile. A build with both the profile
and the option is allowed to be more aggressive in its
documentation-removal than a build with just the option, and for example
delete entire packages.

(You have to use the profile anyway if you want your build-dependencies
to be reduced, so in practice I think the only useful combinations are
neither or both.)

Indeed, for it to be useful, I think this has to happen, because build
profiles are not meant to make functional changes to a built binary
package, but for gtk-doc packages (and probably others) losing the
documentation is a functional change: it means the .devhelp file is
no longer there, so other packages can't use it to rewrite/adjust
cross-references at build time.

I already did that. The page was recently edited to specify nodoc as "may
make non-functional changes to content, *must not* change set of packages"
(my emphasis) based on the same misunderstanding you had. I discussed
that change with the author of that edit on IRC, and he agreed that it
had been a misunderstanding; so I reverted the change, taking it back to
"may make non-functional changes to content, *may* change set of packages".

    smcv

Thanks.

Specifically, this is what I used in my test case where no packages are built.
sbuild -d unstable -A --no-arch-any --profiles nodoc

Do you have a reason why we should not remove that sentence from Debian Policy?

Jeremy Bicha

for a valid reason? They might be installable-but-broken, which seems
worse than being uninstallable.

If I can install (for example) the gnome-api-docs metapackage, it doesn't
seem very useful or in keeping with the relevant maintainers' intentions
for the documentation that it is intended to pull in to be missing?

One of the design principles for build profiles (which are unfortunately
not in Policy yet, #757760) was that if a package has functionally
significant content, "profiled" builds that omit some or all of
its functionality should not build it, instead of building it with
different/missing functionality and misleadingly satisfying dependencies
with a version of the package that might be considered broken.

In the case of gtk-doc documentation (popular in GNOME but also used
elsewhere), documentation can be functionally significant. Documentation
built by gtk-doc has a mechanism for adjusting cross-references at
build-time to point to a local copy of a dependency's documentation. For
example, ostree depends on GLib; it has a Build-Depends-Indep on the
GLib documentation, so that gtk-doc can read GLib's .devhelp file and
rewrite external web links in libostree's documentation to be relative
links into a local copy of GLib's documentation. If ostree's (arch-indep,
non-nodoc-profile) build was allowed to go ahead with an empty version
of libglib2.0-doc installed, its result would be different (admittedly
only slightly, but reproducible builds are something we want, so that
should be considered a bug).

I suspect gtk-doc is not the only documentation system with similar
properties.

    smcv

As far as I understand it, this is considered to have undefined behaviour
(the package is not guaranteed to build, either correctly or at all) unless
you also specify DEB_BUILD_OPTIONS=nodoc.

I have no particular objection to your proposal, I just don't think what
you implemented in this package was a Policy violation (I did the same
in ostree, and in the unreleased version of flatpak in collab-maint git).

    smcv