Re: [PATCH libmnl 1/1] build: doc: "make" builds & installs a full set of man pages

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

On Sun, Jun 27, 2021 at 02:30:55PM +1000, Duncan Roe wrote:
> On Wed, Jun 23, 2021 at 07:26:21PM +0200, Pablo Neira Ayuso wrote:
> 
> [...]
> >
> > Applied, thanks.
> >
> > One thing that needs a fix (both libnetfilter_queue and libmnl).
> >
> > If doxygen is not installed...
> >
> > configure: WARNING: Doxygen not found - continuing without Doxygen support
> >
> > it warns that it is missing...
> >
> > checking that generated files are newer than configure... done
> > configure: creating ./config.status
> > config.status: creating Makefile
> > config.status: creating src/Makefile
> > config.status: creating include/Makefile
> > config.status: creating include/libmnl/Makefile
> > config.status: creating include/linux/Makefile
> > config.status: creating include/linux/netfilter/Makefile
> > config.status: creating examples/Makefile
> > config.status: creating examples/genl/Makefile
> > config.status: creating examples/kobject/Makefile
> > config.status: creating examples/netfilter/Makefile
> > config.status: creating examples/rtnl/Makefile
> > config.status: creating libmnl.pc
> > config.status: creating doxygen.cfg
> > config.status: creating doxygen/Makefile
> > config.status: creating config.h
> > config.status: config.h is unchanged
> > config.status: executing depfiles commands
> > config.status: executing libtool commands
> >
> > libmnl configuration:
> >   doxygen:          yes
> >
> > but it says yes here.
> >
> >
> > I'd prefer if documentation is not enabled by default, ie. users have
> > to explicitly specify --with-doxygen=yes to build documentation, so
> > users explicitly picks what they needs.
> 
> I'm fine with *html* being optional:
> 
>   --enable-html      build HTML documentation [default=no]
> 
> ATM `make install` doesn't do anything with the html dir. With --enable-html, I
> guess it should install html/ where --htmldir points [DOCDIR].
> 
> But I think not having man pages in the past was a serious deficiency which we
> can now address.
> 
> Think of it from a (Linux) Distributor's point of view. Man pages take up very
> little space in the distribution medium: symlinks are removed and the remaining
> pages compressed. Man pages stay compressed on installation and the symlinks are
> re-created by the postinstall script (and now as .gz or whatever files).

We are not Linux distributors, it's up to them to decide what they are
shipping in their packages, this debate is out of our scope. Assuming
that enabling this by default will not make them include this.

Most users rely on libmnl because they use some utility that pulls in
this dependency, most of them are not developers.

> Typical end-users of the distribution won't have source, so the *need*
> documentation.
> 
> Personally I'm happy if the build depends on doxygen and fails if it's not
> installed.

That's probably fine for you, but embedded developer will not be happy
with this dependency.

> If you inmsist on only printing a warning when doxygen is not installed then in
> that event .configure could output:
> 
> > libmnl configuration:
> >   doxygen:          no
> > man pages:          no
> 
> with no "man pages" line when doxygen is installed.

I'd really prefer to retain the existing default that has been in
place for many years.

> What do you think?

It's also possible to provide up to date snapshots in the Netfilter
website to give it more visibility.

BTW, the autogenerated manpage differs quite a bit from standard
manpages in other existing packages? Do you know of any other software
following this approach of converting doxygen to manpage?

Thanks.