* [PATCH libnetfilter_queue v3 2/3] build: doc: can choose what to build and install
2021-08-21 5:38 [PATCH libnetfilter_queue v3 1/3] build: doc: Fix NAME entry in man pages Duncan Roe
@ 2021-08-21 5:38 ` Duncan Roe
2021-08-21 5:38 ` [PATCH libnetfilter_queue v3 3/3] build: doc: VPATH builds work again Duncan Roe
2021-08-21 9:55 ` [PATCH libnetfilter_queue v3 1/3] build: doc: Fix NAME entry in man pages Jeremy Sowden
2 siblings, 0 replies; 7+ messages in thread
From: Duncan Roe @ 2021-08-21 5:38 UTC (permalink / raw)
To: pablo; +Cc: netfilter-devel
Update doxygen/Makefile.am to build and install man pages and html documentation
conditionally. Involves configure.ac and doxygen.cfg.in, see below.
CONFIGURE.AC
Update `configure --help` to list non-default documentation options, as do most
packages (i.e. list non-defaults). 3 listed options:
1. --enable-html-doc
2. --disable-man-pages
3. --without-doxygen
Option 3 overrides 1 & 2: e.g. if you have --without-doxygen but not
--disable-man-pages you get:
WARNING: Doxygen disabled - man pages will not be built
doxygen is not run if no documentation is requested.
Configure command Installed package size (KB)
========= ======= ========= ======= ==== ====
./configure --without-doxygen 176
./configure --disable-man-pages 176
./configure 300
./configure --enable-html-doc 1460
./configure --enable-html-doc\
--disable-man-pages 1340
Do some extra re-ordering for clarity. Also for clarity, since this is
linux-only, re-work test commands to look mode modern.
DOXYGEN.CFG.IN
HTML and man page generation are both conditional.
Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
configure.ac | 76 +++++++++++++++++++++++++++++++--------------
doxygen.cfg.in | 3 +-
doxygen/Makefile.am | 11 ++++++-
3 files changed, 64 insertions(+), 26 deletions(-)
diff --git a/configure.ac b/configure.ac
index 0fe754c..376d4ff 100644
--- a/configure.ac
+++ b/configure.ac
@@ -10,9 +10,42 @@ AM_INIT_AUTOMAKE([-Wall foreign subdir-objects
tar-pax no-dist-gzip dist-bzip2 1.6])
m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
+case "$host" in
+*-*-linux* | *-*-uclinux*) ;;
+*) AC_MSG_ERROR([Linux only, dude!]);;
+esac
+
dnl kernel style compile messages
m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
+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
@@ -20,44 +53,39 @@ AM_PROG_LIBTOOL
AC_PROG_INSTALL
CHECK_GCC_FVISIBILITY
-case "$host" in
-*-*-linux* | *-*-uclinux*) ;;
-*) AC_MSG_ERROR([Linux only, dude!]);;
-esac
-
dnl Dependencies
PKG_CHECK_MODULES([LIBNFNETLINK], [libnfnetlink >= 0.0.41])
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
- include/Makefile include/libnetfilter_queue/Makefile
- doxygen/Makefile
- 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], [
+AS_IF([test "$with_doxygen" = yes], [
AC_CHECK_PROGS([DOXYGEN], [doxygen])
AC_CHECK_PROGS([DOT], [dot], [""])
- AS_IF([test "x$DOT" != "x"],
+ AS_IF([test -n "$DOT"],
[AC_SUBST(HAVE_DOT, YES)],
[AC_SUBST(HAVE_DOT, NO)])
])
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])
- with_doxygen=no
- ])
+AS_IF([test -z "$DOXYGEN" -a "$with_doxygen" = yes], [
+ dnl Only run doxygen Makefile if doxygen installed
+ AC_MSG_WARN([Doxygen not found - no documentation will be built])
+ with_doxygen=no
+ enable_html_doc=no
+ enable_man_pages=no
])
+
+dnl Output the makefiles
+AC_CONFIG_FILES([Makefile src/Makefile utils/Makefile examples/Makefile
+ libnetfilter_queue.pc doxygen.cfg
+ include/Makefile include/libnetfilter_queue/Makefile
+ doxygen/Makefile
+ include/linux/Makefile include/linux/netfilter/Makefile])
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.cfg.in b/doxygen.cfg.in
index 266782e..757d72e 100644
--- a/doxygen.cfg.in
+++ b/doxygen.cfg.in
@@ -22,7 +22,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
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 5bcef61..37ed7aa 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -24,6 +24,7 @@ doxyfile.stamp: $(doc_srcs) Makefile.am
# automake (run by autogen.sh) allows comments starting ## after continuations
# but not blank lines
+if BUILD_MAN
/bin/bash -p -c 'declare -A renamed_page;\
##
main(){ set -e; cd man/man3; rm -f _*;\
@@ -219,6 +220,7 @@ remove_temp_files(){ for i in $$temps;\
};\
##
main'
+endif
touch doxyfile.stamp
@@ -228,11 +230,18 @@ all-local: doxyfile.stamp
clean-local:
rm -rf $(top_srcdir)/doxygen/man $(top_srcdir)/doxygen/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)$(htmldir) $(DESTDIR)$(mandir) man html doxyfile.stamp
endif
--
2.17.5
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH libnetfilter_queue v3 1/3] build: doc: Fix NAME entry in man pages
2021-08-21 5:38 [PATCH libnetfilter_queue v3 1/3] build: doc: Fix NAME entry in man pages Duncan Roe
2021-08-21 5:38 ` [PATCH libnetfilter_queue v3 2/3] build: doc: can choose what to build and install Duncan Roe
2021-08-21 5:38 ` [PATCH libnetfilter_queue v3 3/3] build: doc: VPATH builds work again Duncan Roe
@ 2021-08-21 9:55 ` Jeremy Sowden
2021-08-22 3:33 ` Duncan Roe
2 siblings, 1 reply; 7+ messages in thread
From: Jeremy Sowden @ 2021-08-21 9:55 UTC (permalink / raw)
To: Duncan Roe; +Cc: pablo, netfilter-devel
[-- Attachment #1.1: Type: text/plain, Size: 7920 bytes --]
On 2021-08-21, at 15:38:03 +1000, Duncan Roe wrote:
> Add a post_process() function to the big shell script inside doxygen/Makefile.am
> to make the NAME line in a man page list the functions defined, like other man
> pages do.
> This function does a number of other things:
> - 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
> - Delete lines that make older versions of man o/p an unwanted blank line
>
> Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> ---
> v2: Delete lines that make older versions of man o/p an unwanted blank line
> v3: same as v2 but there are now 2 more patches
> doxygen/Makefile.am | 172 ++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 172 insertions(+)
>
> diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
> index 29078de..5bcef61 100644
> --- a/doxygen/Makefile.am
> +++ b/doxygen/Makefile.am
> @@ -21,19 +21,32 @@ doxyfile.stamp: $(doc_srcs) Makefile.am
> # 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).
> +# automake (run by autogen.sh) allows comments starting ## after continuations
> +# but not blank lines
> +
Would it not make life easier to move all this shell-script into a
build_man.sh and just call that from the make-file? Patch attached.
J.
> /bin/bash -p -c 'declare -A renamed_page;\
> +##
> 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" 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);\
> do for j in $$(ls -S | tail -n+$$first_link);\
> do grep -E -q $$i$$ $$j && break;\
> @@ -42,10 +55,169 @@ 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);\
> 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'
>
> touch doxyfile.stamp
[-- Attachment #1.2: 0001-build-use-a-separate-shell-script-to-build-man-pages.patch --]
[-- Type: text/x-diff, Size: 12507 bytes --]
From 562e9dcfd27faa3edf3464c67e15aabf8a14f2ba Mon Sep 17 00:00:00 2001
From: Jeremy Sowden <jeremy@azazel.net>
Date: Sat, 21 Aug 2021 10:45:36 +0100
Subject: [PATCH] build: use a separate shell-script to build man-pages.
---
doxygen/Makefile.am | 198 +--------------------------------------
doxygen/build_man.sh | 215 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 218 insertions(+), 195 deletions(-)
create mode 100755 doxygen/build_man.sh
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index e788843002de..52dca075f37d 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -25,201 +25,7 @@ doxyfile.stamp: $(doc_srcs) Makefile.am
# but not blank lines
if BUILD_MAN
- /bin/bash -p -c 'declare -A renamed_page;\
-##
-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" 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);\
- 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;\
-};\
-##
-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'
+ ./build_man.sh
endif
touch doxyfile.stamp
@@ -245,3 +51,5 @@ endif
uninstall-local:
rm -rf $(DESTDIR)$(htmldir) $(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 000000000000..da8c84e81c42
--- /dev/null
+++ b/doxygen/build_man.sh
@@ -0,0 +1,215 @@
+#!/bin/bash -p
+
+declare -A renamed_page
+
+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" 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)
+ 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
+}
+
+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.32.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply related [flat|nested] 7+ messages in thread