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