Include libiio0-doc in non-minimal packagelist files

[lionel]

There are some unsettled questions regarding whether and how much documentation to include in non-minimal packagelist files. Prior to distro-seed, the TS-7100 and TS-7180 didn't shy away from including documentation packages when development library packages were being included on these boards. This documentation is "cheap" space-wise compared to the other packages, relatively in-sync with whatever is on the board, and maintenance-free. It has been nice to find it there.

The counter-view is that documentation packages should never be included without a compelling reason, even though some man pages and HTML documentation already exist (albeit inadvertently) in distro-seed builds.

[ts-kris]

Using two products that are still technically in engineering sampling as a basis for what has been included in the history of images to determine what goes in future images is not really a fair starting point when it affects more than just the two platforms.

Historically, we include man and packages install their man pages alongside it. Packages that have a man page in Debian basically have to include them in the package by Debian policy. There is no way to disable them easily without installing and then removing just the man pages, breaking installed packages. Any external package documentation is not normally included.

While it may not take up much space, more often than not it will go unused as modern documentation is HTML and there is no way to view that on-device without setting up an HTTP server on the device. e.g. unless you are using a TPC platform with a display, or a command-line web browser, you can't easily view rendered HTML.

The goal of our distributions is to create a minimum viable booting system, with common creature comforts that make using a system more functional out of the box without including the kitchen sink. That is unfortunately a nebulous definition, but development documentation for a package that not every application is going to use, when its easier to look online at the documentation as it wants to be rendered HTML, definitely falls in to kitchen sink territory.

[lionel]

It helps to know or be reminded that HTML documentation (already installed "involuntarily" by packages in the rootfs) is easy to view via the built-in web server, which can be run from a documentation directory with:

python3 -m http.server

So for example, on any Debian 12 distro-seed image today you can do this:

python3 -m http.server -d /usr/share/doc/base-passwd

or this:

python3 -m http.server -d /usr/share/doc

and then point any web browser that can reach your board at port 8000. This prints the URLs for all interfaces that the board has up:

ip addr show up | sed -En 's/.*inet ([0-9.]+).*/http:\/\/\1:8000/p'

This demonstrates the fact that documentation is in HTML isn't a huge impediment to a developer working directly on a board, and in some cases is better than man pages alone (as was the case with libiio-dev). And a more direct path to version-specific information than the web.

Which leads to another aspect of the "kitchen-sink" concern. If one is already putting toolchains and *-dev packages on a board – especially one where it should be made as seamless as reasonably possible to bring over applications using the packages provided – having the correct documentation for said packages/versions close at hand doesn't sound like a problem.

Requiring any *-doc package available for a *-dev package to be included in any packagelist that includes the *-dev package may well be a "kitchen sink" problem. But should that be taken to mean that -doc packages are excluded in all cases?

[ts-kris]

It helps to know or be reminded that HTML documentation (already installed "involuntarily" by packages in the rootfs) is easy to view via the built-in web server, which can be run from a documentation directory with:

python3 -m http.server

So for example, on any Debian 12 distro-seed image today you can do this:

python3 -m http.server -d /usr/share/doc/base-passwd

or this:

python3 -m http.server -d /usr/share/doc

and then point any web browser that can reach your board at port 8000. This prints the URLs for all interfaces that the board has up:

ip addr show up | sed -En 's/.*inet ([0-9.]+).*/http:\/\/\1:8000/p'

This demonstrates the fact that documentation is in HTML isn't a huge impediment to a developer working directly on a board, and in some cases is better than man pages alone (as was the case with libiio-dev). And a more direct path to version-specific information than the web.

Yes but this assumes one of two things: 1) That people have this in their workflow (not something we can predict, and from personal experience both myself and others in similar industries usually refer to the correct version in web documentation because it is quick and easy to have multiple sources of documentation open simultaneously. Including not only documentation but code as well much more easily than just on-unit). 2) We document this heavily so people know about it and how to use it. Which we do not, and documenting how to view HTML documentation on-unit is out of the scope of our documentation and would muddy existing manuals or require additional maintenance of other pages.

Which leads to another aspect of the "kitchen-sink" concern. If one is already putting toolchains and *-dev packages on a board – especially one where it should be made as seamless as reasonably possible to bring over applications using the packages provided – having the correct documentation for said packages/versions close at hand doesn't sound like a problem.

Requiring any *-doc package available for a *-dev package to be included in any packagelist that includes the *-dev package may well be a "kitchen sink" problem. But should that be taken to mean that -doc packages are excluded in all cases?

This brings up a good point. We shouldn't have -dev packages in our images. We need a few of them for building our utils packages for example, but, those are requirements on the host environment and not the target. However, we cannot predict library needs for end users and even including "obvious" dev packages could easily go completely unused. Trying to predict that is a slippery slope that will lead to immense effort on our side to debate, maintain, document, ensure what is shipped, etc.; while end users will simply just install what they need anyway.

Our images are designed to showcase the features of the hardware and to let the customer hit the ground running. No need to download a huge BSP, no licenses to walk through, here is a console, here is a compiler, connect your preferred workflow to this and go. I would actually like to argue that tools like gdb don't belong in our image, however I can see it being extremely useful to just already have in some situations.

libiio-dev is the only dev package in our images, and should actually be removed. If needed for end application development, it, and the -doc package, can be installed by the end developer.