Re: [PATCH libnetfilter_queue v2] build: doc: Fix NAME entry in man pages

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

On Sat, Aug 28, 2021 at 11:23:03AM +0200, Pablo Neira Ayuso wrote:
> On Sat, Aug 28, 2021 at 06:01:44AM +1000, Duncan Roe wrote:
> > On Tue, Aug 24, 2021 at 11:43:42AM +1000, Duncan Roe wrote:
> > > On Sun, Aug 15, 2021 at 02:15:09PM +0200, Pablo Neira Ayuso wrote:
> > > > On Tue, Aug 10, 2021 at 12:40:01PM +1000, Duncan Roe wrote:
> > > > > Make the NAME line list the functions defined, like other man pages do.
> > > > > Also:
> > > > > - If there is a "Modules" section, delete it
> > > > > - If "Detailed Description" is empty, delete "Detailed Description" line
> > > > > - Reposition SYNOPSIS (with headers that we inserted) to start of page,
> > > > >   integrating with defined functions to look like other man pages
> > > > > - Delete all "Definition at line nnn" lines
> > > > > - Delete lines that make older versions of man o/p an unwanted blank line
> > > > > - Insert spacers and comments so Makefile.am is more readable
> > > > >
> > > > > Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> > > > > ---
> > > > > v2: Delete lines that make older versions of man o/p an unwanted blank line
> > > > >  doxygen/Makefile.am | 172 ++++++++++++++++++++++++++++++++++++++++++++
> > > >
> > > > Time to add this to an independent fixup shell script for
> > > > doxygen-based manpages that Makefile.am could call instead?
> > >
> > > There is an independent fixup shell script at v4
> > > >
> > > > This script could be imported by other libraries too, so it only needs to
> > > > be downloaded from somewhere to be refreshed to keep it in sync with
> > > > latest.
> > >
> > > Please do not wait for this to happen. As I gain familiarity with autotools,
> > > there will be more and more incremental updates.
> > >
> > > So you can review them easily, I'll try to keep each patch doing just one thing.
> > > But that means more patches, so can you just apply one of the patch series so we
> > > don't get too far behind?
> > > >
> > > > The git tree could cache a copy of this script.
> > >
> > > Here's a possible mechanism, but it needs there to be a new netfilter git
> > > project: how would you be with that?
> > >
> > >  - autogen.sh does `git clone libnetfilter_doc`
> > >  - autogen.sh distributes the files(*) in libnetfilter_doc to wherever they go
> > >    in the current source tree
> > >  - autogen.sh deletes libnetfilter_doc/
> > >
> > > This approach has the advantage that `make distcheck` tarballs are complete,
> > > i.e. don't require a working network to build.
> > >
> > > For best results, update doxygen comments in the source to contain SYNOPSIS
> > > sections.
> > >
> > > (*) as well as build_man.sh, most of configure.ac is boilerplate and could be
> > > encapsulated in 1 or more m4 macros to reside in libnetfilter_doc. Also most of
> > > doxygen.cfg.in could go there, with local variations in doxygen.cfg.local (at
> > > least EXCLUDE_SYMBOLS, maybe nothing else).
> > 
> > 
> > No need for a new git project. curl can fetch files from libnfq. E.g.
> > > curl https://git.netfilter.org/libnetfilter_queue/plain/doxygen/Makefile.am
> > fetches Makefile.am.
> > 
> > Same for doxygen/build_man.sh, once the patches are applied. autogen.sh would
> > run the curl commands.
> 
> autogen.sh to resync this script should be fine.
> 
> Did you consider to send some feedback to doxygen developers? Probably
> enhancing \manonly including sections (ie. \manonly{synopsis}) would
> be the way to go? I guess that would be more work upstream, but
> everyone would benefit from this.
> 
> Anyway, your build_man.sh script is starting to look nicer, thanks.

I mean: the output of the man pages is looking better than the ones
that doxygen is autogenerating, is it that doxygen manpage support is
"basic" as it look without your script?