Re: [PATCH libmnl v2] build: do not build documentation automatically

[Pablo Neira Ayuso <pablo@netfilter.org>]

On Wed, Oct 16, 2024 at 12:17:44PM +1100, Duncan Roe wrote:
> On Mon, Oct 14, 2024 at 01:20:27PM +0200, Pablo Neira Ayuso wrote:
> > On Mon, Oct 14, 2024 at 01:12:02PM +0200, Jan Engelhardt wrote:
> > [...]
> > > Having worked extensively with wxWidgets (also doxygenated) in the past
> > > however, I found that when the API is large, needs frequent lookup,
> > > documentation has many pages, and online retrieval latency becomes a
> > > factor, I prefer a local copy as a quality-of-live improvement.
> >
> > For reference, there is one online available at:
> >
> > https://www.netfilter.org/projects/libmnl/doxygen/html/
> >
> > for the current release.
>           ^^^^^^^
>           (since I prompted you to update it last month)

Indeed, I appreciate your reminder.

> > [...]
> > > Removals are a powerful action that is seldomly undone at the distro
> > > levels, so it can be regarded as the final say (well, in "95% of
> > > cases").
> > [...]
> > > Hiding stuff behind a configure knob is not a removal though,
> > > so it is not too big a deal.
> >
> > Exactly.
> >
> > > >Moreover, documentation is specifically designed for developers who
> > > >are engaged in the technical aspects. Most users of this software are
> > > >building it because it is a dependency for their software.
> > >                                             ^^^^^^^^^^^^^^
> > >
> > > The way it's phrased makes those users users of the libmnl API (i.e.
> > > developers), and documentation is warranted.
> > >
> > > (The following statement would be more accurate:
> > >
> > > >Most users of this software are
> > > >building it because it is a dependency for someone else's software
>     ^^^^^^^^^
> > > >they want to utilize.
> 
> WRONG. These users get the built package from their distributor. Many would not
> have the know-how to do anything else.

... And it seems distros don't include already built doxygen
documentation in their packages.

> Our direct end-users are developers and distributors.
>  - developers typically work at the tip of the master branch so will want
> current documentation
>  - Distributors can easily strip ot what they don't want, as Jan mentioned. But
> I don't agree with him that "Hiding stuff behind a configure knob ... is not too
> big a deal". It's not immediately obvious what --with-doxygen does.
> >
> > That sounds more precise, yes.
> >
> A precise description of users we don't have :)
> 
> Pablo, could you perhaps share with us what triggered you to think of doing this
> at all?

I believe we have provide a good number of reasons already.

Thanks.