[PATCH RFC libnetfilter_queue 0/1] Make usable man pages

[PATCH RFC libnetfilter_queue 0/1] Make usable man pages

[Duncan Roe]

fixmanpages.sh generates a top-level man page file tree such that man/man3
contains an entry for every documented nfq function. This is what users expect.

See main commit for how fixmanpages.sh works.

Itwould be nice to have "make" run "doxygen doxygen.cfg; ./fixmanpages.sh" and
"make install" install the man pages but I'm not yet that good with autotools.

There could be a similar script for libmnl.

Duncan Roe (1):
  doc: setup: Add shell script fixmanpages.sh to make usable man pages

 fixmanpages.sh | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100755 fixmanpages.sh

-- 
2.14.5

[PATCH RFC libnetfilter_queue 1/1] doc: setup: Add shell script fixmanpages.sh to make usable man pages

[Duncan Roe]

fixmanpages.sh generates a top-level man page file tree such that man/man3
contains an entry for every documented nfq function.

How it works: Doxygen generates a man page for every module. For each module,
fixmanpages.sh copies the man age to a file with the name of the first defined
function in the module: e.g. it copies tcp.3 to nfq_tcp_get_hdr.3. Then it
symlinks all the other functions defined in the module to that file, e.g.
ln -s nfq_tcp_get_hdr.3 nfq_tcp_get_payload.3.

The end result is that when a user types "man some_nfq_function", a man page
will always display.

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 fixmanpages.sh | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100755 fixmanpages.sh

diff --git a/fixmanpages.sh b/fixmanpages.sh
new file mode 100755
index 0000000..32b2420
--- /dev/null
+++ b/fixmanpages.sh
@@ -0,0 +1,60 @@
+#!/bin/bash -p
+#set -x
+function main
+{
+  set -e
+  rm -rf man
+  mkdir -p man/man3
+  cd doxygen/man/man3
+  setgroup LibrarySetup nfq_open
+  add2group nfq_close nfq_bind_pf nfq_unbind_pf
+  setgroup Parsing nfq_get_msg_packet_hdr
+  add2group nfq_get_nfmark nfq_get_timestamp nfq_get_indev nfq_get_physindev\
+    nfq_get_outdev nfq_get_physoutdev nfq_get_indev_name nfq_get_physindev_name\
+    nfq_get_outdev_name nfq_get_physoutdev_name nfq_get_packet_hw nfq_get_uid\
+    nfq_get_gid nfq_get_secctx nfq_get_payload
+  setgroup Queue nfq_fd
+  add2group nfq_create_queue nfq_destroy_queue nfq_handle_packet nfq_set_mode\
+    nfq_set_queue_flags nfq_set_queue_maxlen nfq_set_verdict nfq_set_verdict2\
+    nfq_set_verdict_batch nfq_set_verdict_batch2 nfq_set_verdict_mark
+  setgroup ipv4 nfq_ip_get_hdr
+  add2group nfq_ip_set_transport_header nfq_ip_mangle nfq_ip_snprintf\
+    nfq_ip_set_checksum
+  setgroup ipv6 nfq_ip6_get_hdr
+  add2group nfq_ip6_set_transport_header nfq_ip6_mangle nfq_ip6_snprintf
+  setgroup nfq_cfg nfq_nlmsg_cfg_put_cmd
+  add2group nfq_nlmsg_cfg_put_params nfq_nlmsg_cfg_put_qmaxlen
+  setgroup nfq_verd nfq_nlmsg_verdict_put
+  add2group nfq_nlmsg_verdict_put_mark nfq_nlmsg_verdict_put_pkt
+  setgroup nlmsg nfq_nlmsg_parse
+  setgroup otherfns pktb_tailroom
+  add2group pktb_mac_header pktb_network_header pktb_transport_header
+  setgroup pktbuff pktb_alloc
+  add2group pktb_usebuf pktb_data pktb_len pktb_free pktb_mangle pktb_mangled
+  setgroup tcp nfq_tcp_get_hdr
+  add2group nfq_tcp_get_payload nfq_tcp_get_payload_len\
+    nfq_tcp_compute_checksum_ipv4 nfq_tcp_compute_checksum_ipv6\
+    nfq_tcp_snprintf nfq_tcp_mangle_ipv4 nfq_tcp_mangle_ipv6
+  setgroup udp
+  add2group nfq_udp_get_hdr nfq_udp_get_payload nfq_udp_get_payload_len\
+    nfq_udp_mangle_ipv4 nfq_udp_mangle_ipv6 nfq_udp_snprintf
+  setgroup internals nfq_udp_compute_checksum_ipv4
+  add2group nfq_udp_compute_checksum_ipv6
+  setgroup uselessfns pktb_push
+  add2group pktb_pull pktb_put pktb_trim
+}
+function setgroup
+{
+  cp $1.3 ../../../man/man3/$2.3
+  BASE=$2
+}
+function add2group
+{
+  cd ../../../man/man3
+  for i in $@
+  do
+    ln -sf $BASE.3 $i.3
+  done
+  cd - >/dev/null
+}
+main
-- 
2.14.5

Re: [PATCH RFC libnetfilter_queue 0/1] Make usable man pages

[Duncan Roe]

Hi Pablo,

On Mon, Jan 06, 2020 at 06:09:14PM +1100, Duncan Roe wrote:
> fixmanpages.sh generates a top-level man page file tree such that man/man3
> contains an entry for every documented nfq function. This is what users expect.
>
> See main commit for how fixmanpages.sh works.
>
> Itwould be nice to have "make" run "doxygen doxygen.cfg; ./fixmanpages.sh" and
> "make install" install the man pages but I'm not yet that good with autotools.
>
> There could be a similar script for libmnl.
>
> Duncan Roe (1):
>   doc: setup: Add shell script fixmanpages.sh to make usable man pages
>
>  fixmanpages.sh | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 60 insertions(+)
>  create mode 100755 fixmanpages.sh
>
> --
> 2.14.5
>
Don't worry about applying this, it's is just a Proof Of Concept. Personally
I've found it useful because I can now easily review generated man format doco.

I've found some instructions for integrating doxygen into autotools at
http://chris-miceli.blogspot.com/2011/01/integrating-doxygen-with-autotools.html
so will be giving that a go.

Cheers ... Duncan.