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

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

On Mon, Oct 14, 2024 at 06:55:45PM +1100, Duncan Roe wrote:
> Hi Pablo,
> 
> On Sat, Oct 12, 2024 at 07:15:21PM +0200, Pablo Neira Ayuso wrote:
> > Make it option, after this update it is still possible to build the
> > documentation on demand via:
> >
> >  cd doxygen
> >  make
> >
> > if ./configure found doxygen. Otherwise, no need to build documentation
> > when building from source.
> >
> > Update README to include this information.
> >
> > Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
> > ---
> >  Makefile.am |  2 +-
> >  README      | 10 ++++++++++
> >  2 files changed, 11 insertions(+), 1 deletion(-)
> >
> > diff --git a/Makefile.am b/Makefile.am
> > index 94e6935d6138..6ec1a7b98827 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -2,7 +2,7 @@ include $(top_srcdir)/Make_global.am
> >
> >  ACLOCAL_AMFLAGS = -I m4
> >
> > -SUBDIRS = src include examples doxygen
> > +SUBDIRS = src include examples
> >  DIST_SUBDIRS = src include examples doxygen
> >
> >  pkgconfigdir = $(libdir)/pkgconfig
> > diff --git a/README b/README
> > index 317a2c6ad1d6..c82dedd2266a 100644
> > --- a/README
> > +++ b/README
> > @@ -23,6 +23,16 @@ forced to use them.
> >  You can find several example files under examples/ that you can compile by
> >  invoking `make check'.
> >
> > += Documentation =
> > +
> > +If ./configure reports that doxygen has been found, then you can build
> > +documentation through:
> > +
> > +	cd doxygen
> > +	make
> > +
> > +then, open doxygen/html/index.html in your browser.
> > +
> >  = Contributing =
> >
> >  Please submit any patches to <netfilter-devel@vger.kernel.org>.
> > --
> > 2.30.2
> >
> >
> Why are you doing this?
> 
> I don't like this patch because:-
> 
> Distributors typically use the default config to make a package. That would mean
> libmnl would go out without any documentation, hardly an encouragement to use
> it.

We do not have control over the specific items that distributors
choose to include in their packages. Each distributor operates
independently and curates their packages based on their own
preferences. Therefore, the final decisions regarding package contents
rest solely with the distributors.

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. Therefore,
for non-developers, this step in the building process is not relevant.

Please, note that users can still opt-in to compile documentation as
it is documented in the README file.

Thanks.