Doxygen2man (#388)

* doxygen2man: Add utility to generate man pages from doxygen

This is in here from kronosnet so it cna be used by other parts
of the cluster stack.

* [man] drop trailing white spaces

Signed-off-by: Fabio M. Di Nitto <[email protected]>

* [build] cleanup variable names

Signed-off-by: Fabio M. Di Nitto <[email protected]>

* [build] add conditionals to use internal or external doxygen2man

Signed-off-by: Fabio M. Di Nitto <[email protected]>

* Update .gitignore

Signed-off-by: Fabio M. Di Nitto <[email protected]>

Co-authored-by: Christine Caulfield <[email protected]>

.gitignore

@@ -44,6 +44,7 @@ conftest.*
 libtool
 libqb.spec
 libqb-*
+/doxygen2man/doxygen2man
 cov
 compat_reports
 abi_dumps
@@ -53,6 +54,7 @@ test-driver
 
 /tests/**/*.real
 /tests/**/*.trs
+/tests/ipc-test-name
 /tests/functional/log_callsite_bench.c
 /tests/functional/**/log_callsite_bench_section*.c
 /tests/functional/**/log_client

Makefile.am

@@ -39,7 +39,7 @@ ACLOCAL_AMFLAGS		= -I m4
 
 dist_doc_DATA		= COPYING INSTALL README.markdown
 
-SUBDIRS			= include lib docs tools tests examples
+SUBDIRS			= include lib docs tools tests examples doxygen2man
 
 doxygen:
 	$(MAKE) -C docs doxygen

configure.ac

@@ -167,6 +167,24 @@ if test x"$have_glib" = xyes; then
 AC_DEFINE_UNQUOTED([HAVE_GLIB], [1], [We have glib])
 fi
 
+# For building doxygen2man and man pages
+PKG_CHECK_MODULES([libxml], [libxml-2.0])
+
+# if we are not cross-compiling, we can use the locally built
+# version of doxygen2man, otherwise we can look for
+# a locally installed version. If neither are usable, then
+# don´t build the man pages
+if test "x$cross_compiling" = "xno"; then
+  AM_CONDITIONAL([BUILD_MAN], 1)
+  DOXYGEN2MAN="\$(abs_builddir)/doxygen2man/doxygen2man"
+else
+  AC_CHECK_PROGS([DOXYGEN2MAN], [doxygen2man])
+  if test "x$DOXYGEN2MAN" = "x"; then
+    AM_CONDITIONAL([BUILD_MAN], 0)
+  fi
+fi
+AC_SUBST(DOXYGEN2MAN)
+
 # Checks for header files.
 AC_HEADER_STDC
 AC_HEADER_SYS_WAIT
@@ -792,6 +810,7 @@ AC_CONFIG_FILES([Makefile
 		 tests/Makefile
 		 tests/test.conf
 		 examples/Makefile
+		 doxygen2man/Makefile
 		 docs/Makefile
 		 docs/common.dox
 		 docs/html.dox

doxygen2man/Doxyfile.example

@@ -0,0 +1,19 @@
+#
+# Copyright (C) 2017-2020 Red Hat, Inc.  All rights reserved.
+#
+# Author: Fabio M. Di Nitto <[email protected]>
+#         Christine Caulfield <[email protected]>
+#
+# This software licensed under GPL-2.0+
+#
+# Example file for doxygen when using doxygen2man
+#
+PROJECT_NAME	       = libqb
+PROJECT_NUMBER         = 2.0
+INPUT                  = ../include/qb/
+XML_OUTPUT             = ./xml
+GENERATE_XML           = YES
+XML_PROGRAMLISTING     = NO
+AUTOLINK_SUPPORT       = NO
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO

doxygen2man/Makefile.am

@@ -0,0 +1,24 @@
+#
+# Copyright (C) 2017-2019 Red Hat, Inc.  All rights reserved.
+#
+# Authors: Fabio M. Di Nitto <[email protected]>
+#          Federico Simoncelli <[email protected]>
+#
+# This software licensed under GPL-2.0+
+#
+
+MAINTAINERCLEANFILES	= Makefile.in
+
+EXTRA_DIST             = doxygen2man.1
+
+bin_PROGRAMS	= doxygen2man
+
+all: $(PROGRAMS) $(MANS)
+
+doxygen2man_SOURCES = doxygen2man.c
+doxygen2man_CPPFLAGS = -I$(top_srcdir)/include/
+doxygen2man_CFLAGS = $(AM_CFLAGS) $(libxml_CFLAGS)
+doxygen2man_LDADD = $(top_builddir)/lib/libqb.la $(libxml_LIBS)
+
+man1_MANS = doxygen2man.1
+

doxygen2man/doxygen2man.1

@@ -0,0 +1,67 @@
+.\"
+.\" * Copyright (C) 2010-2020 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Christine Caulfield <[email protected]>
+.\" *
+
+.TH "DOXYGEN2MAN" "8" "2020-03-09" "" ""
+.SH "NAME"
+doxygen2man \- A tool to generate man pages from Doxygen XML files
+.SH "SYNOPSIS"
+.B doxygen2man [OPTIONS] <XML file>
+.SH "DESCRIPTION"
+.P
+This is a tool to generate API manpages from a doxygen-annotated header file
+First run doxygen on the file and then run this program against the main XML file
+it created and the directory containing the ancilliary files. It will then
+output a lot of *.3 man page files which you can then ship with your library.
+.P
+You will need to invoke this program once for each .h file in your library,
+using the name of the generated .xml file. This file will usually be called
+something like <include-file>_8h.xml, eg qbipcs_8h.xml
+.P
+If you want HTML output then simpy use nroff on the generated files as you
+would do with any other man page.
+
+.SH "OPTIONS"
+.TP
+.B -a
+Print ASCII dump of man pages to stdout
+.TP
+.B -m
+Write man page files to <output dir>
+.TP
+.B -P
+Print PARAMS section
+.TP
+.B -s <s>
+Write man pages into section <s> <default 3)
+.TP
+.B -p <package>
+Use <package> name. default <Package>
+.TP
+.B -H <header>
+Set header (default \"Programmer's Manual\")
+.TP
+.B -D <date>
+Date to print at top of man pages (format not checked, default: today)
+.TP
+.B -Y <year>
+Year to print at end of copyright line (default: today's year)
+.TP
+.B -o <dir>
+Write all man pages to <dir> (default .)
+.TP
+.B -d <dir>
+Directory for XML files (./xml/)
+.TP
+.B -h
+Print usage text
+
+.SH "SEE ALSO"
+.BR doxygen (1)
+.SH "AUTHOR"
+Christine Caulfield
+.PP