On Fri, 17 Jan 2025 at 10:56:39 +0900, Simon Richter wrote:
> basically we'd have to give every -dev package containing
> manual pages a -doc package
In many cases I think this is best-practice anyway, because it takes
the documentation generation toolchain out of the critical path for
bootstrapping, cross-compiling, and slow architectures. Many libraries
have their API reference as HTML or even PDF, generated via something
like Doxygen, gtk-doc or Pandoc, and kicking out that documentation into
a separate package significantly reduces what needs to be built to get
a minimal version of the library that is enough to continue to build
dependent packages. For existing libraries that have not done this,
I can see the argument for not introducing a -doc package to avoid NEW,
but when packaging a new library or doing a SONAME bump I would nearly
always split out the API reference into a -doc package.
The nodoc build option and build profile go some way towards resolving
this, but need to be invoked explicitly every time and alter the
contents of built binary packages (not reproducible), whereas a separate
Architecture: all documentation package "just works" and is easy to
acceptance-test (if it builds successfully on the official buildds and
has the desired contents, then you have succeeded).
I can see that if the library of interest only has man pages (no HTML)
and they're hand-written *roff (not generated from a more author-friendly
source format with some tool) this might be considered unnecessary,
because in that case there is no documentation toolchain, but that's
uncommon in the ecosystems I usually work with.
Similarly if a library has manual or automated as-installed tests, I've
taken to always splitting them into an -examples or -tests package to
avoid multiarch issues (and if it doesn't have even a manual smoke-test,
I've started considering that to be an upstream bug that should be resolved
before packaging, because that's how we get packages that nobody wants to
NMU or team-upload because we don't know how to test them).
smcv
