[PATCH libnetfilter_queue v3 1/6] build: doc: Fix man pages

[PATCH libnetfilter_queue v3 1/6] build: doc: Fix man pages

[Duncan Roe]

Split off shell script from within doxygen/Makefile.am into
doxygen/build_man.sh.

This patch by itself doesn't fix anything.
The patch is only for traceability, because diff patch format is not very good
at catching code updates and moving code together.
Therefore the script is exactly as it was; it still looks a bit different
because of having to un-double doubled-up $ signs, remove trailing ";/" and so
on.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/Makefile.am  | 34 +++-------------------------------
 doxygen/build_man.sh | 29 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 31 deletions(-)
 create mode 100755 doxygen/build_man.sh

diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 29078de..5068544 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -16,37 +16,7 @@ doxyfile.stamp: $(doc_srcs) Makefile.am
 	[ ! -d ../src.distcheck ] || \
 { set -x; cd ..; rm src; mv src.distcheck src; }
 
-# We need to use bash for its associative array facility
-# (`bash -p` prevents import of functions from the environment).
-# The command has to be a single line so the functions work
-# and so `make` gives all lines to `bash -c`
-# (hence ";\" at the end of every line but the last).
-	/bin/bash -p -c 'declare -A renamed_page;\
-main(){ set -e; cd man/man3; rm -f _*;\
-  count_real_pages;\
-  rename_real_pages;\
-  make_symlinks;\
-};\
-count_real_pages(){ page_count=0;\
-  for i in $$(ls -S);\
-  do head -n1 $$i | grep -E -q '^\.so' && break;\
-    page_count=$$(($$page_count + 1));\
-  done;\
-  first_link=$$(($$page_count + 1));\
-};\
-rename_real_pages(){ for i in $$(ls -S | head -n$$page_count);\
-  do for j in $$(ls -S | tail -n+$$first_link);\
-    do grep -E -q $$i$$ $$j && break;\
-    done;\
-    mv -f $$i $$j;\
-    renamed_page[$$i]=$$j;\
-  done;\
-};\
-make_symlinks(){ for j in $$(ls -S | tail -n+$$first_link);\
-  do ln -sf $${renamed_page[$$(cat $$j | cut -f2 -d/)]} $$j;\
-  done;\
-};\
-main'
+	$(abs_top_srcdir)/doxygen/build_man.sh
 
 	touch doxyfile.stamp
 
@@ -64,3 +34,5 @@ install-data-local:
 uninstall-local:
 	rm -r $(DESTDIR)$(mandir) man html doxyfile.stamp
 endif
+
+EXTRA_DIST = build_man.sh
diff --git a/doxygen/build_man.sh b/doxygen/build_man.sh
new file mode 100755
index 0000000..304a305
--- /dev/null
+++ b/doxygen/build_man.sh
@@ -0,0 +1,29 @@
+#!/bin/bash -p
+# We need to use bash for its associative array facility
+# (`bash -p` prevents import of functions from the environment).
+declare -A renamed_page
+main(){ set -e; cd man/man3; rm -f _*
+  count_real_pages
+  rename_real_pages
+  make_symlinks
+}
+count_real_pages(){ page_count=0
+  for i in $(ls -S)
+  do head -n1 $i | grep -E -q '^\.so' && break
+    page_count=$(($page_count + 1))
+  done
+  first_link=$(($page_count + 1))
+}
+rename_real_pages(){ for i in $(ls -S | head -n$page_count)
+  do for j in $(ls -S | tail -n+$first_link)
+    do grep -E -q $i$ $j && break
+    done
+    mv -f $i $j
+    renamed_page[$i]=$j
+  done
+}
+make_symlinks(){ for j in $(ls -S | tail -n+$first_link)
+  do ln -sf ${renamed_page[$(cat $j | cut -f2 -d/)]} $j
+  done
+}
+main
-- 
2.17.5

[PATCH libnetfilter_queue v3 2/6] build: doc: Add a man page post-processor to build_man.sh

[Duncan Roe]

- 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
For better readability, shell function definitions are separated by blank
lines, and there is a bit of annotation.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/build_man.sh | 200 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 195 insertions(+), 5 deletions(-)

diff --git a/doxygen/build_man.sh b/doxygen/build_man.sh
index 304a305..e0cda71 100755
--- a/doxygen/build_man.sh
+++ b/doxygen/build_man.sh
@@ -1,20 +1,37 @@
 #!/bin/bash -p
-# We need to use bash for its associative array facility
+
+# 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).
+
 declare -A renamed_page
-main(){ set -e; cd man/man3; rm -f _*
+
+main(){
+  set -e
+  cd man/man3; rm -f _*
   count_real_pages
   rename_real_pages
   make_symlinks
+  post_process
 }
-count_real_pages(){ page_count=0
+
+count_real_pages(){
+  page_count=0
+  #
+  # Count "real" man pages (i.e. not generated by MAN_LINKS)
+  # MAN_LINKS pages are 1-liners starting .so
+  # Method: list files in descending order of size,
+  # looking for the first 1-liner
+  #
   for i in $(ls -S)
   do head -n1 $i | grep -E -q '^\.so' && break
     page_count=$(($page_count + 1))
   done
   first_link=$(($page_count + 1))
 }
-rename_real_pages(){ for i in $(ls -S | head -n$page_count)
+
+rename_real_pages(){
+  for i in $(ls -S | head -n$page_count)
   do for j in $(ls -S | tail -n+$first_link)
     do grep -E -q $i$ $j && break
     done
@@ -22,8 +39,181 @@ rename_real_pages(){ for i in $(ls -S | head -n$page_count)
     renamed_page[$i]=$j
   done
 }
-make_symlinks(){ for j in $(ls -S | tail -n+$first_link)
+
+make_symlinks(){
+  for j in $(ls -S | tail -n+$first_link)
   do ln -sf ${renamed_page[$(cat $j | cut -f2 -d/)]} $j
   done
 }
+
+post_process(){
+  make_temp_files
+  #
+  # DIAGNOSTIC / DEVELOPMENT CODE
+  # set -x and restrict processing to keep_me: un-comment to activate
+  # Change keep_me as required
+  #
+  #keep_me=nfq_icmp_get_hdr.3;\
+  #do_diagnostics;\
+  #
+  # Work through the "real" man pages
+  for target in $(ls -S | head -n$page_count)
+  do mygrep "^\\.SH \"Function Documentation" $target
+    # Next file if this isn't a function page
+    [ $linnum -ne 0 ] || continue
+
+    del_modules
+    del_bogus_synopsis
+    fix_name_line
+    move_synopsis
+    del_empty_det_desc
+    del_def_at_lines
+    fix_double_blanks
+  done
+
+  remove_temp_files
+}
+
+fix_double_blanks(){
+  linnum=1
+  #
+  # Older versions of man display a blank line on encountering "\fB\fP";
+  # newer versions of man do not.
+  # doxygen emits "\fB\fP" on seeing "\par" on a line by itself.
+  # "\par" gives us double-spacing in the web doc, which we want, but double-
+  # spacing looks odd in a man page so remove "\fB\fP".
+  #
+  while [ $linnum -ne 0 ]
+  do mygrep \\\\fB\\\\fP $target
+    [ $linnum -eq 0 ] || delete_lines $linnum $linnum
+  done
+}
+
+del_def_at_lines(){
+  linnum=1
+  while [ $linnum -ne 0 ]
+  do mygrep "^Definition at line [[:digit:]]* of file" $target
+    [ $linnum -eq 0 ] || delete_lines $(($linnum - 1)) $linnum
+  done
+}
+
+# Only invoked if you un-comment the 2 diagnostic / development lines above
+do_diagnostics(){
+  mv $keep_me xxx
+  rm *.3
+  mv xxx $keep_me
+  page_count=1
+  set -x
+}
+
+del_empty_det_desc(){
+  mygrep "^\\.SH \"Function Documentation" $target
+  i=$linnum
+  mygrep "^\\.SH \"Detailed Description" $target
+  [ $linnum -ne 0  ] || return 0
+  [ $(($i - $linnum)) -eq 3 ] || return 0
+  delete_lines $linnum $(($i -1))
+}
+
+move_synopsis(){
+  mygrep "SH SYNOPSIS" $target
+  [ $linnum -ne 0  ] || return 0
+  i=$linnum
+  # If this is a doxygen-created synopsis, leave it.
+  # (We haven't inserted our own one in the source yet)
+  mygrep "^\\.SS \"Functions" $target
+  [ $i -gt $linnum ] || return 0
+
+  mygrep "^\\.SH \"Function Documentation" $target
+  j=$(($linnum - 1))
+  head -n$(($j - 1)) $target | tail -n$(($linnum - $i - 1)) >$fileC
+  delete_lines $i $j
+  mygrep "^\\.SS \"Functions" $target
+  head -n$(($linnum - 1)) $target >$fileA
+  tail -n+$(($linnum + 1)) $target >$fileB
+  cat $fileA $fileC $fileB >$target
+}
+
+fix_name_line(){
+  all_funcs=""
+
+  # Search a shortened version of the page in case there are .RI lines later
+  mygrep "^\\.SH \"Function Documentation" $target
+  head -n$linnum $target >$fileC
+
+  while :
+  do mygrep ^\\.RI $fileC
+    [ $linnum -ne 0 ] || break
+    # Discard this entry
+    tail -n+$(($linnum + 1)) $fileC >$fileB
+    cp $fileB $fileC
+
+    func=$(cat $fileG | cut -f2 -d\\ | cut -c3-)
+    [ -z "$all_funcs" ] && all_funcs=$func ||\
+      all_funcs="$all_funcs, $func"
+  done
+  # For now, assume name is at line 5
+  head -n4 $target >$fileA
+  desc=$(head -n5 $target | tail -n1 | cut -f3- -d" ")
+  tail -n+6 $target >$fileB
+  cat $fileA >$target
+  echo "$all_funcs \\- $desc" >>$target
+  cat $fileB >>$target
+}
+
+del_modules(){
+  mygrep "^\.SS \"Modules" $target
+  [ $linnum -ne 0  ] || return 0
+  i=$linnum
+  mygrep "^\\.SS \"Functions" $target
+  delete_lines $i $(($linnum - 1))
+}
+
+del_bogus_synopsis(){
+  mygrep "SH SYNOPSIS" $target
+  #
+  # doxygen 1.8.20 inserts its own SYNOPSIS line but there is no mention
+  # in the documentation or git log what to do with it.
+  # So get rid of it
+  #
+  [ $linnum -ne 0  ] || return 0
+  i=$linnum
+  # Look for the next one
+  tail -n+$(($i + 1)) $target >$fileC;\
+  mygrep "SH SYNOPSIS" $fileC
+  [ $linnum -ne 0  ] || return 0
+
+  mygrep "^\\.SS \"Functions" $target
+  delete_lines $i $(($linnum - 1))
+}
+
+# Delete lines $1 through $2 from $target
+delete_lines(){
+  head -n$(($1 - 1)) $target >$fileA
+  tail -n+$(($2 +1)) $target >$fileB
+  cat $fileA $fileB >$target
+}
+
+mygrep(){
+  set +e
+  grep -En "$1" $2 2>/dev/null >$fileH
+  [ $? -ne 0 ] && linnum=0 ||\
+    { head -n1 $fileH >$fileG; linnum=$(cat $fileG | cut -f1 -d:); }
+  set -e
+}
+
+make_temp_files(){
+  temps="A B C G H"
+  for i in $temps
+  do declare -g file$i=$(mktemp)
+  done
+}
+
+remove_temp_files(){
+  for i in $temps
+  do j=file$i
+    rm ${!j}
+  done
+}
+
 main
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 2/6] build: doc: Add a man page post-processor to build_man.sh

[Pablo Neira Ayuso]

On Sat, Aug 28, 2021 at 01:35:04PM +1000, Duncan Roe wrote:
> - 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
> For better readability, shell function definitions are separated by blank
> lines, and there is a bit of annotation.

Also applied, thanks.

Please, in the future, let's try to avoid this multi-item patches, one
thing at a time the best for traceability.

Thanks.

[PATCH libnetfilter_queue v3 3/6] build: doc: Avoid having to special-case `make distcheck`

[Duncan Roe]

- Move doxygen.cfg.in to doxygen/
- Tell doxygen.cfg.in where the sources are
- Let doxygen.cfg.in default its output to CWD
- In Makefile, `doxygen doxygen.cfg` "just works"

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 configure.ac                             |  4 ++--
 doxygen/Makefile.am                      | 12 +-----------
 doxygen.cfg.in => doxygen/doxygen.cfg.in |  3 +--
 3 files changed, 4 insertions(+), 15 deletions(-)
 rename doxygen.cfg.in => doxygen/doxygen.cfg.in (93%)

diff --git a/configure.ac b/configure.ac
index 0fe754c..4721eeb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -31,9 +31,9 @@ PKG_CHECK_MODULES([LIBMNL], [libmnl >= 1.0.3])
 
 dnl Output the makefiles
 AC_CONFIG_FILES([Makefile src/Makefile utils/Makefile examples/Makefile
-        libnetfilter_queue.pc doxygen.cfg
+	libnetfilter_queue.pc
 	include/Makefile include/libnetfilter_queue/Makefile
-	doxygen/Makefile
+	doxygen/Makefile doxygen/doxygen.cfg
 	include/linux/Makefile include/linux/netfilter/Makefile])
 
 AC_ARG_WITH([doxygen], [AS_HELP_STRING([--with-doxygen],
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 5068544..f38009b 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -4,17 +4,7 @@ doc_srcs = $(shell find $(top_srcdir)/src -name '*.c')
 
 doxyfile.stamp: $(doc_srcs) Makefile.am
 	rm -rf html man
-
-# Test for running under make distcheck.
-# If so, sibling src directory will be empty:
-# move it out of the way and symlink the real one while we run doxygen.
-	[ -f ../src/Makefile.in ] || \
-{ set -x; cd ..; mv src src.distcheck; ln -s $(top_srcdir)/src; }
-
-	cd ..; doxygen doxygen.cfg >/dev/null
-
-	[ ! -d ../src.distcheck ] || \
-{ set -x; cd ..; rm src; mv src.distcheck src; }
+	doxygen doxygen.cfg >/dev/null
 
 	$(abs_top_srcdir)/doxygen/build_man.sh
 
diff --git a/doxygen.cfg.in b/doxygen/doxygen.cfg.in
similarity index 93%
rename from doxygen.cfg.in
rename to doxygen/doxygen.cfg.in
index 266782e..99b5c90 100644
--- a/doxygen.cfg.in
+++ b/doxygen/doxygen.cfg.in
@@ -1,12 +1,11 @@
 # Difference with default Doxyfile 1.8.20
 PROJECT_NAME           = @PACKAGE@
 PROJECT_NUMBER         = @VERSION@
-OUTPUT_DIRECTORY       = doxygen
 ABBREVIATE_BRIEF       =
 FULL_PATH_NAMES        = NO
 TAB_SIZE               = 8
 OPTIMIZE_OUTPUT_FOR_C  = YES
-INPUT                  = .
+INPUT                  = @abs_top_srcdir@/src
 FILE_PATTERNS          = *.c
 RECURSIVE              = YES
 EXCLUDE_SYMBOLS        = EXPORT_SYMBOL \
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 3/6] build: doc: Avoid having to special-case `make distcheck`

[Pablo Neira Ayuso]

On Sat, Aug 28, 2021 at 01:35:05PM +1000, Duncan Roe wrote:
> - Move doxygen.cfg.in to doxygen/
> - Tell doxygen.cfg.in where the sources are
> - Let doxygen.cfg.in default its output to CWD
> - In Makefile, `doxygen doxygen.cfg` "just works"

Applied, thanks.

[PATCH libnetfilter_queue v3 4/6] build: doc: fix `make distcleancheck`

[Duncan Roe]

`make distcleancheck` was not passing before this patchset. Now fixed.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/Makefile.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index f38009b..bab34bf 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -14,7 +14,7 @@ CLEANFILES = doxyfile.stamp
 
 all-local: doxyfile.stamp
 clean-local:
-	rm -rf $(top_srcdir)/doxygen/man $(top_srcdir)/doxygen/html
+	rm -rf man html
 install-data-local:
 	mkdir -p $(DESTDIR)$(mandir)/man3
 	cp --no-dereference --preserve=links,mode,timestamps man/man3/*.3\
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 4/6] build: doc: fix `make distcleancheck`

[Pablo Neira Ayuso]

On Sat, Aug 28, 2021 at 01:35:06PM +1000, Duncan Roe wrote:
> `make distcleancheck` was not passing before this patchset. Now fixed.

Applied, thanks.

5/6 and 6/6 in this series, I'll catch up to review them later.

[PATCH libnetfilter_queue v3 5/6] build: doc: Allow to specify whether to produce man pages, html, neither or both

[Duncan Roe]

- configure --help lists non-default documentation options.
  Looking around the web, this seemed to me to be what most projects do.
  Listed options are --without-doxygen, --enable-html-doc &
  --disable-man-pages.
- configure warns on inconsistent options e.g. --without-doxygen by itself
  warns man pages will not be built.
- configure.ac re-ordered so --without-doxygen overrides --enable-any-doc.
If html is requested, `make install` installs it in htmldir.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 configure.ac           | 41 ++++++++++++++++++++++++++++++++++++-----
 doxygen/Makefile.am    | 11 ++++++++++-
 doxygen/doxygen.cfg.in |  3 ++-
 3 files changed, 48 insertions(+), 7 deletions(-)

diff --git a/configure.ac b/configure.ac
index 4721eeb..a4fb629 100644
--- a/configure.ac
+++ b/configure.ac
@@ -13,6 +13,35 @@ m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
 dnl kernel style compile messages
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
 
+dnl Must check for --without-doxygen before  checking --enable-*
+AC_ARG_WITH([doxygen], [AS_HELP_STRING([--without-doxygen],
+	    [Don't run doxygen (to create documentation)])],
+	    [with_doxygen="$withval"], [with_doxygen=yes])
+
+AC_ARG_ENABLE([html-doc],
+	      AS_HELP_STRING([--enable-html-doc], [Enable html documentation]),
+	      [], [enable_html_doc=no])
+AS_IF([test "$with_doxygen" = no -a "$enable_html_doc" = yes], [
+	AC_MSG_WARN([Doxygen disabled - html documentation will not be built])
+	enable_html_doc=no
+])
+AM_CONDITIONAL([BUILD_HTML], [test "$enable_html_doc" = yes])
+AS_IF([test "$enable_html_doc" = yes],
+	[AC_SUBST(GEN_HTML, YES)],
+	[AC_SUBST(GEN_HTML, NO)])
+
+AC_ARG_ENABLE([man-pages],
+	      AS_HELP_STRING([--disable-man-pages], [Disable man page documentation]),
+	      [], [enable_man_pages=yes])
+AS_IF([test "$with_doxygen" = no -a "$enable_man_pages" = yes], [
+	AC_MSG_WARN([Doxygen disabled - man pages will not be built])
+	enable_man_pages=no
+])
+AM_CONDITIONAL([BUILD_MAN], [test "$enable_man_pages" = yes])
+AS_IF([test "$enable_man_pages" = yes],
+	[AC_SUBST(GEN_MAN, YES)],
+	[AC_SUBST(GEN_MAN, NO)])
+
 AC_PROG_CC
 AM_PROG_CC_C_O
 AC_DISABLE_STATIC
@@ -36,9 +65,7 @@ AC_CONFIG_FILES([Makefile src/Makefile utils/Makefile examples/Makefile
 	doxygen/Makefile doxygen/doxygen.cfg
 	include/linux/Makefile include/linux/netfilter/Makefile])
 
-AC_ARG_WITH([doxygen], [AS_HELP_STRING([--with-doxygen],
-	    [create doxygen documentation])],
-	    [with_doxygen="$withval"], [with_doxygen=yes])
+AS_IF([test "$enable_man_pages" = no -a "$enable_html_doc" = no], [with_doxygen=no])
 
 AS_IF([test "x$with_doxygen" != xno], [
 	AC_CHECK_PROGS([DOXYGEN], [doxygen])
@@ -52,12 +79,16 @@ AM_CONDITIONAL([HAVE_DOXYGEN], [test -n "$DOXYGEN"])
 AS_IF([test "x$DOXYGEN" = x], [
 	AS_IF([test "x$with_doxygen" != xno], [
 		dnl Only run doxygen Makefile if doxygen installed
-		AC_MSG_WARN([Doxygen not found - continuing without Doxygen support])
+		AC_MSG_WARN([Doxygen not found - no documentation will be built])
 		with_doxygen=no
+		enable_html_doc=no
+		enable_man_pages=no
 	])
 ])
 AC_OUTPUT
 
 echo "
 libnetfilter_queue configuration:
-  doxygen:                      ${with_doxygen}"
+  doxygen:                      ${with_doxygen}
+man pages:                      ${enable_man_pages}
+html docs:                      ${enable_html_doc}"
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index bab34bf..5235f78 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -6,7 +6,9 @@ doxyfile.stamp: $(doc_srcs) Makefile.am
 	rm -rf html man
 	doxygen doxygen.cfg >/dev/null
 
+if BUILD_MAN
 	$(abs_top_srcdir)/doxygen/build_man.sh
+endif
 
 	touch doxyfile.stamp
 
@@ -16,13 +18,20 @@ all-local: doxyfile.stamp
 clean-local:
 	rm -rf man html
 install-data-local:
+if BUILD_MAN
 	mkdir -p $(DESTDIR)$(mandir)/man3
 	cp --no-dereference --preserve=links,mode,timestamps man/man3/*.3\
 	  $(DESTDIR)$(mandir)/man3/
+endif
+if BUILD_HTML
+	mkdir  -p $(DESTDIR)$(htmldir)
+	cp  --no-dereference --preserve=links,mode,timestamps html/*\
+		$(DESTDIR)$(htmldir)
+endif
 
 # make distcheck needs uninstall-local
 uninstall-local:
-	rm -r $(DESTDIR)$(mandir) man html doxyfile.stamp
+	rm -rf $(DESTDIR)$(mandir) man html doxyfile.stamp $(DESTDIR)$(htmldir)
 endif
 
 EXTRA_DIST = build_man.sh
diff --git a/doxygen/doxygen.cfg.in b/doxygen/doxygen.cfg.in
index 99b5c90..14bd0cf 100644
--- a/doxygen/doxygen.cfg.in
+++ b/doxygen/doxygen.cfg.in
@@ -21,7 +21,8 @@ ALPHABETICAL_INDEX     = NO
 SEARCHENGINE           = NO
 GENERATE_LATEX         = NO
 LATEX_CMD_NAME         = latex
-GENERATE_MAN           = YES
+GENERATE_MAN           = @GEN_MAN@
+GENERATE_HTML          = @GEN_HTML@
 MAN_LINKS              = YES
 HAVE_DOT               = @HAVE_DOT@
 DOT_TRANSPARENT        = YES
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 5/6] build: doc: Allow to specify whether to produce man pages, html, neither or both

[Duncan Roe]

Hi Pablo,

On Sat, Aug 28, 2021 at 01:35:07PM +1000, Duncan Roe wrote:
> - configure --help lists non-default documentation options.
>   Looking around the web, this seemed to me to be what most projects do.
>   Listed options are --without-doxygen, --enable-html-doc &
>   --disable-man-pages.
> - configure warns on inconsistent options e.g. --without-doxygen by itself
>   warns man pages will not be built.
> - configure.ac re-ordered so --without-doxygen overrides --enable-any-doc.
> If html is requested, `make install` installs it in htmldir.
>
> Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> ---
>  configure.ac           | 41 ++++++++++++++++++++++++++++++++++++-----
>  doxygen/Makefile.am    | 11 ++++++++++-
>  doxygen/doxygen.cfg.in |  3 ++-
>  3 files changed, 48 insertions(+), 7 deletions(-)
>
[...]

Just in case you missed it, this one is still to do.

Regarding warnings - I did try all the option combinations and again w/out
doxygen installed, so maybe you can satisfy yourself with a few random choices.

Cheers ... Duncan.

[PATCH libnetfilter_queue v3 6/6] build: doc: Eliminate warning from ./autogen.sh

[Duncan Roe]

Running autogen.sh gives the following output when it gets to
doxygen/Makefile.am:
  doxygen/Makefile.am:3: warning: shell find $(top_srcdir: non-POSIX variable name
  doxygen/Makefile.am:3: (probably a GNU make extension)

Since we are targetting GNU make, disable such warnings.

suggested_by: Jeremy Sowden <jeremy@azazel.net>

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 configure.ac | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/configure.ac b/configure.ac
index a4fb629..cdd333a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -6,7 +6,7 @@ AC_CANONICAL_HOST
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_HEADERS([config.h])
 
-AM_INIT_AUTOMAKE([-Wall foreign subdir-objects
+AM_INIT_AUTOMAKE([-Wall -Wno-portability foreign subdir-objects
 	tar-pax no-dist-gzip dist-bzip2 1.6])
 m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
 
-- 
2.17.5

[PATCH libnetfilter_queue v2] build: doc: Eliminate warning from ./autogen.sh

[Duncan Roe]

Replace shell function call with a list of sources

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 doxygen/Makefile.am | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 5235f78..738ebce 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -1,6 +1,14 @@
 if HAVE_DOXYGEN
 
-doc_srcs = $(shell find $(top_srcdir)/src -name '*.c')
+doc_srcs = $(top_srcdir)/src/libnetfilter_queue.c\
+           $(top_srcdir)/src/nlmsg.c\
+           $(top_srcdir)/src/extra/checksum.c\
+           $(top_srcdir)/src/extra/ipv4.c\
+           $(top_srcdir)/src/extra/pktbuff.c\
+           $(top_srcdir)/src/extra/ipv6.c\
+           $(top_srcdir)/src/extra/tcp.c\
+           $(top_srcdir)/src/extra/udp.c\
+           $(top_srcdir)/src/extra/icmp.c
 
 doxyfile.stamp: $(doc_srcs) Makefile.am
 	rm -rf html man
-- 
2.17.5

Re: [PATCH libnetfilter_queue v2] build: doc: Eliminate warning from ./autogen.sh

[Pablo Neira Ayuso]

On Sun, Aug 29, 2021 at 01:45:51PM +1000, Duncan Roe wrote:
> Replace shell function call with a list of sources

Applied, thanks.

Verion info

[Duncan Roe]

On Sat, Aug 28, 2021 at 01:35:03PM +1000, Duncan Roe wrote:
> Split off shell script from within doxygen/Makefile.am into
> doxygen/build_man.sh.
>
> This patch by itself doesn't fix anything.
> The patch is only for traceability, because diff patch format is not very good
> at catching code updates and moving code together.
> Therefore the script is exactly as it was; it still looks a bit different
> because of having to un-double doubled-up $ signs, remove trailing ";/" and so
> on.
>
> Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> ---
v2: Split original into 5 steps
v3: Add extra patch to avoid ./autogen.sh warning (1st 5 patches unchanged)

Re: [PATCH libnetfilter_queue v3 1/6] build: doc: Fix man pages

[Pablo Neira Ayuso]

On Sat, Aug 28, 2021 at 01:35:03PM +1000, Duncan Roe wrote:
> Split off shell script from within doxygen/Makefile.am into
> doxygen/build_man.sh.
> 
> This patch by itself doesn't fix anything.
> The patch is only for traceability, because diff patch format is not very good
> at catching code updates and moving code together.
> Therefore the script is exactly as it was; it still looks a bit different
> because of having to un-double doubled-up $ signs, remove trailing ";/" and so
> on.

Applied.