Method: make a temporary .c file with a \defgroup instad of \mainpage and run
doxygen on that, with a specially cut-down doxygen config.
Most of the change is to doxygen/build_man.sh. build_man.sh remains generic,
so should be able to make man7 pages for other projects e.g. libnetfilter_log.
build_man.sh must be invoked with arguments to activate man7 generation, so will
continue to work in other projects as before.
The HTML display stays as it was: \section is not available inside a
\defgroup and so is changed to <h1> ... </h1>. This looks the same as \defgroup
but doesn't come with an implicit \anchor as \defgroup does: we can always add
an anchor if we need one.
The man3 pages reference libnetfilter_queue.7.
Signed-off-by: Duncan Roe <duncan_roe@xxxxxxxxxxxxxxx>
---
doxygen/Makefile.am | 6 +--
doxygen/build_man.sh | 101 +++++++++++++++++++++++++++++++++++++--
doxygen/man7.extra.txt | 1 +
doxygen/old_doxy_fix.txt | 5 ++
src/libnetfilter_queue.c | 14 +++---
5 files changed, 113 insertions(+), 14 deletions(-)
create mode 100644 doxygen/man7.extra.txt
create mode 100644 doxygen/old_doxy_fix.txt
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index c6eeed7..e98368b 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -10,12 +10,12 @@ doc_srcs = $(top_srcdir)/src/libnetfilter_queue.c\
$(top_srcdir)/src/extra/udp.c\
$(top_srcdir)/src/extra/icmp.c
-doxyfile.stamp: $(doc_srcs) Makefile
+doxyfile.stamp: $(doc_srcs) Makefile build_man.sh man7.extra.txt old_doxy_fix.txt
rm -rf html man
doxygen doxygen.cfg >/dev/null
if BUILD_MAN
- $(abs_top_srcdir)/doxygen/build_man.sh
+ $(abs_top_srcdir)/doxygen/build_man.sh libnetfilter_queue libnetfilter_queue.c
endif
touch doxyfile.stamp
@@ -42,4 +42,4 @@ uninstall-local:
rm -rf $(DESTDIR)$(mandir) man html doxyfile.stamp $(DESTDIR)$(htmldir)
endif
-EXTRA_DIST = build_man.sh
+EXTRA_DIST = build_man.sh man7.extra.txt old_doxy_fix.txt
diff --git a/doxygen/build_man.sh b/doxygen/build_man.sh
index 0d3be4c..38a6b3f 100755
--- a/doxygen/build_man.sh
+++ b/doxygen/build_man.sh
@@ -1,19 +1,20 @@
#!/bin/sh
-[ -n "$BASH" ] || exec bash -p $0
+[ -n "$BASH" ] || exec bash -p $0 $@
# Script to process man pages output by doxygen.
# We need to use bash for its associative array facility.
# (`bash -p` prevents import of functions from the environment).
+# Args: none or 2 being man7 page name & relative path of source with \mainpage
declare -A renamed_page
main(){
set -e
- cd man/man3; rm -f _*
+ pushd man/man3 >/dev/null; rm -f _*
count_real_pages
rename_real_pages
make_symlinks
- post_process
+ post_process $@
}
count_real_pages(){
@@ -76,9 +77,101 @@ post_process(){
done
+ [ $# -ne 2 ] || make_man7 $@
+
remove_temp_files
}
+make_man7(){
+ popd >/dev/null
+ target=$(grep -Ew INPUT doxygen.cfg | rev | cut -f1 -d' ' | rev)/$2
+ mypath=$(dirname $0)
+
+ # Build up temporary source in temp.c
+ # (doxygen only makes man pages from .c files).
+ mygrep \\\\mainpage $target
+ tail -n+$((linnum-1)) $target | head -n1 >temp.c
+ echo " * \\defgroup $1 $1 overview" >>temp.c
+ tail -n+$((linnum+1)) $target >$fileA
+ linnum=$(grep -En '\*/' $fileA | head -n1 | cut -d: -f1)
+ head -n$((linnum - 1)) $fileA >> temp.c
+
+ # Add any lines specific to this project
+ # (E.g. to satisfy an off-page link)
+ [ ! -r $mypath/man7.extra.txt ] || cat $mypath/man7.extra.txt >> temp.c
+
+ echo ' */' >> temp.c
+ cat >> temp.c <<////
+
+ /**
+ * @{
+ *
+ * $1 - DELETE_ME
+ */
+int $1(void)
+{
+ return 0;
+}
+/**
+ * @}
+ */
+////
+
+ # Create temporary doxygen config in fileC
+ cat /dev/null >$fileC
+ for i in \
+ PROJECT_NAME \
+ PROJECT_NUMBER \
+ ABBREVIATE_BRIEF \
+ FULL_PATH_NAMES \
+ TAB_SIZE \
+ OPTIMIZE_OUTPUT_FOR_C \
+ EXAMPLE_PATTERNS \
+ ALPHABETICAL_INDEX \
+ SEARCHENGINE \
+ GENERATE_LATEX \
+ ; do grep -Ew $i doxygen.cfg >>$fileC; done
+ cat >>$fileC <<////
+INPUT = temp.c
+GENERATE_HTML = NO
+GENERATE_MAN = YES
+MAN_EXTENSION = .7
+////
+
+ doxygen $fileC >/dev/null
+
+ # Remove SYNOPSIS line if there is one
+ target=man/man7/$1.7
+ mygrep "SH SYNOPSIS" $target
+ [ $linnum -eq 0 ] || delete_lines $linnum $((linnum+1))
+
+ # doxygen 1.8.9.1 and possibly newer run the first para into NAME
+ # (i.e. in this unusual group). There won't be a SYNOPSIS when this happens
+ if grep -Eq "overview$1" $target; then
+ head -n2 temp.c >$fileA
+ cat $mypath/old_doxy_fix.txt >>$fileA
+ tail -n+3 temp.c >>$fileA
+ cat $fileA >temp.c
+ doxygen $fileC >/dev/null
+ fi
+
+ # Insert top-level "See also" of man7 page in all real man3 pages
+ for target in $(find man/man3 -type f)
+ do mygrep "Detailed Description" $target
+ [ $linnum -ne 0 ] || mygrep "Function Documentation" $target
+ [ $linnum -ne 0 ] || { echo "NO HEADER IN $target" >&2; continue; }
+ head -n$((linnum-1)) $target >$fileA
+ cat >>$fileA <<////
+.SH "See also"
+\\fB${1}\\fP(7)
+////
+ tail -n+$linnum $target >>$fileA
+ cp $fileA $target
+ done
+
+ rm temp.c
+}
+
fix_double_blanks(){
linnum=1
#
@@ -225,4 +318,4 @@ remove_temp_files(){
done
}
-main
+main $@
diff --git a/doxygen/man7.extra.txt b/doxygen/man7.extra.txt
new file mode 100644
index 0000000..62c8698
--- /dev/null
+++ b/doxygen/man7.extra.txt
@@ -0,0 +1 @@
+ * \anchor LibrarySetup
diff --git a/doxygen/old_doxy_fix.txt b/doxygen/old_doxy_fix.txt
new file mode 100644
index 0000000..46eeff8
--- /dev/null
+++ b/doxygen/old_doxy_fix.txt
@@ -0,0 +1,5 @@
+ * \manonly
+.PP
+.SH "Detailed Description"
+.PP
+\endmanonly
diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c
index a170143..1269181 100644
--- a/src/libnetfilter_queue.c
+++ b/src/libnetfilter_queue.c
@@ -45,11 +45,11 @@
* libnetfilter_queue homepage is:
* https://netfilter.org/projects/libnetfilter_queue/
*
- * \section deps Dependencies
+ <h1>Dependencies</h1>
* libnetfilter_queue requires libmnl, libnfnetlink and a kernel that includes
* the Netfilter NFQUEUE over NFNETLINK interface (i.e. 2.6.14 or later).
*
- * \section features Main Features
+ * <h1>Main Features</h1>
* - receiving queued packets from the kernel nfnetlink_queue subsystem
* - issuing verdicts and possibly reinjecting altered packets to the kernel
* nfnetlink_queue subsystem
@@ -71,15 +71,15 @@
* When a queue is full, packets that should have been enqueued are dropped by
* kernel instead of being enqueued.
*
- * \section git Git Tree
+ * <h1>Git Tree</h1>
* The current development version of libnetfilter_queue can be accessed at
* https://git.netfilter.org/libnetfilter_queue.
*
- * \section privs Privileges
+ * <h1>Privileges</h1>
* You need the CAP_NET_ADMIN capability in order to allow your application
* to receive from and to send packets to kernel-space.
*
- * \section using Using libnetfilter_queue
+ * <h1>Using libnetfilter_queue</h1>
*
* To write your own program using libnetfilter_queue, you should start by
* reading (or, if feasible, compiling and stepping through with *gdb*)
@@ -97,7 +97,7 @@ gcc -g3 -ggdb -Wall -lmnl -lnetfilter_queue -o nf-queue nf-queue.c
* article:
* https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/
*
- * \section errors ENOBUFS errors in recv()
+ * <h1>ENOBUFS errors in recv()</h1>
*
* recv() may return -1 and errno is set to ENOBUFS in case that your
* application is not fast enough to retrieve the packets from the kernel.
@@ -106,7 +106,7 @@ gcc -g3 -ggdb -Wall -lmnl -lnetfilter_queue -o nf-queue nf-queue.c
* you may hit it again sooner or later. The next section provides some hints
* on how to obtain the best performance for your application.
*
- * \section perf Performance
+ * <h1>Performance</h1>
* To improve your libnetfilter_queue application in terms of performance,
* you may consider the following tweaks:
*
--
2.35.8
