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@xxxxxxxxxxxxxxx> > > > --- > > > 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. Cheers ... Duncan.
