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