[PATCH libmnl] build: do not build documentation automatically

[PATCH libmnl] build: do not build documentation automatically

[Pablo Neira Ayuso]

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

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

[Phil Sutter]

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

This is rather unelegant in an autotools-project. You probably did
consider setting 'with_doxygen=no' in configure.ac line 48, why did you
choose this way?

Cheers, Phil

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

[Pablo Neira Ayuso]

On Sat, Oct 12, 2024 at 09:54:04PM +0200, Phil Sutter 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
> 
> This is rather unelegant in an autotools-project. You probably did
> consider setting 'with_doxygen=no' in configure.ac line 48, why did you
> choose this way?

--with-doxygen=no would do try trick, yes.

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

[Phil Sutter]

On Sat, Oct 12, 2024 at 11:26:32PM +0200, Pablo Neira Ayuso wrote:
> On Sat, Oct 12, 2024 at 09:54:04PM +0200, Phil Sutter 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
> > 
> > This is rather unelegant in an autotools-project. You probably did
> > consider setting 'with_doxygen=no' in configure.ac line 48, why did you
> > choose this way?
> 
> --with-doxygen=no would do try trick, yes.

Not sure if it was clear, but I meant to change the default in
configure.ac, so users will have to pass --with-doxygen=yes if they
want to build these docs. I guess that's the most intuitive way for
users.

Cheers, Phil

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

[Pablo Neira Ayuso]

On Sun, Oct 13, 2024 at 01:03:17AM +0200, Phil Sutter wrote:
> On Sat, Oct 12, 2024 at 11:26:32PM +0200, Pablo Neira Ayuso wrote:
> > On Sat, Oct 12, 2024 at 09:54:04PM +0200, Phil Sutter 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
> > > 
> > > This is rather unelegant in an autotools-project. You probably did
> > > consider setting 'with_doxygen=no' in configure.ac line 48, why did you
> > > choose this way?
> > 
> > --with-doxygen=no would do try trick, yes.
> 
> Not sure if it was clear, but I meant to change the default in
> configure.ac, so users will have to pass --with-doxygen=yes if they
> want to build these docs. I guess that's the most intuitive way for
> users.

Thanks, I will submit a patch to change default.

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

[Duncan Roe]

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.

It has been on my todo list to bring libmnl documentation up to the standard of
libnetfilter_queue and libnetfilter_log (use build_man.sh to produce acceptable
man pages; make more use of \returns, \note and so on; add required #includes to
synopsis; fix grammar etc). Default would then be generate man pages. You would
have ./configure options --disable-man-pages & --enable-html-doc.

Cheers ... Duncan

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

[Pablo Neira Ayuso]

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.

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

[Jan Engelhardt]

>Duncan Roe wrote:
>> 
>> 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.

It is true that distros commonly go with upstream default. When the 
upstream default is on "auto" however, it becomes a distro default,
which, due to a blank recipe, quickly becomes "no-documentation".
(Because of this, openSUSE was embarassingly not building libmnl-doc.)

As to whether that is an impediment to creating libmnl-exercising 
software, I cannot say.

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.


On Monday 2024-10-14 10:09, Pablo Neira Ayuso wrote:
>
>We do not have control over the specific items that distributors
>choose to include in their packages.
>[...] the final decisions regarding package contents
>rest solely with the distributors.

Well, not quite.

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"). Think of:

* deprecated C APIs (distros would rather patch consumer programs to
  work with the new ones)

* GNOME desktop, which is infamous for removing stuff due to
  confusion ([1])
[1] https://medium.com/@fulalas/gnome-linux-a-complete-disaster-feb27b13a5c2

Hiding stuff behind a configure knob is not a removal though,
so it is not too big a deal.


>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.


Anyway, looking at what distros _are_ doing is an indicator what
"users" (intermediate consumers, or users at the end of the build
chain) desire and what is worth doing upstream somehow.

* ICU manages documentation separately; in a sense you could see
  this as --enable-doc=no. The ICU APIs are however apparently
  complicated enough that documentation is desirable to have
  available, and so you do find libicu-doc/icu-doc in distros.

* the closer a software is to the bootstrap core, and the more
  outrageous the build requirements for some (sub)component(s) are,
  there more likely it is for those (sub)component(s) to be built in
  a two-phase build or be completely omitted due to complexity.

	* texlive
	* pandoc
	* ant/maven
	* rust/ghc/go

docbook/asciidoc seems right on the edge (because of its potential
to depend on a latex backend), but doxygen seems easy.

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

[Pablo Neira Ayuso]

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.

[...]
> 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.

That sounds more precise, yes.

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

[Pablo Neira Ayuso]

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.

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

[Duncan Roe]

Hi Pablo,

On Wed, Oct 16, 2024 at 09:26:10AM +0200, Pablo Neira Ayuso wrote:
> ... And it seems distros don't include already built doxygen
> documentation in their packages.
>
With the libmnl man pages the way they are, I can't say I blame them ;)

However it *is* normal userland practice to offer a set of man pages with a
library.

libnetfilter_log and libnetfilter_queue both have acceptable man pages. I'm
happy to cut over libmnl to use build_man.sh much as I did for
libnetfilter_log. Default would then be: run doxygen to produce man pages.

I could make that my next netfilter project.

What do you think?

Cheers ... Duncan.