From 125e7cfb1cfb48c9d6654766abfae3dfea1030fe Mon Sep 17 00:00:00 2001 From: Sebastian Harl Date: Fri, 23 May 2014 19:46:37 +0200 Subject: [PATCH] doc: Use asciidoc instead of a2x and added asciidoc.conf. This allows to specify custom macros, which is currently used to turn references to other manpages into links in the HTML output. In general, it will make it easier to apply customizations. --- .gitignore | 3 + README | 3 +- configure.ac | 24 +++--- doc/Makefile.am | 105 +++++++++++++++++--------- doc/asciidoc.conf | 34 +++++++++ doc/sysdb.1.txt | 4 +- doc/sysdb.7.txt | 10 +-- doc/sysdbd-cname-dns.5.txt | 4 +- doc/sysdbd-collectd-unixsock.5.txt | 4 +- doc/sysdbd-mk-livestatus.5.txt | 4 +- doc/sysdbd-puppet-store-configs.5.txt | 4 +- doc/sysdbd-syslog.5.txt | 4 +- doc/sysdbd.1.txt | 4 +- doc/sysdbd.conf.5.txt | 4 +- doc/sysdbql.7.txt | 4 +- 15 files changed, 130 insertions(+), 85 deletions(-) create mode 100644 doc/asciidoc.conf diff --git a/.gitignore b/.gitignore index 74921b8..dbdf2bb 100644 --- a/.gitignore +++ b/.gitignore @@ -31,10 +31,13 @@ ltmain.sh # build output doc/*.1 doc/*.1.html +doc/*.1.xml doc/*.5 doc/*.5.html +doc/*.5.xml doc/*.7 doc/*.7.html +doc/*.7.xml doc/docbook-xsl.css src/frontend/grammar.c src/frontend/grammar.h diff --git a/README b/README index 06c639f..97dc2fe 100644 --- a/README +++ b/README @@ -66,11 +66,10 @@ Prerequisites - * asciidoc, xsltproc, xmlto: + * asciidoc, xmlto: The AsciiDoc text document format is used to write the manpages. - * libedit or libreadline: diff --git a/configure.ac b/configure.ac index 2e55bc7..849223c 100644 --- a/configure.ac +++ b/configure.ac @@ -380,21 +380,15 @@ if test "x$XMLTO" = "x"; then have_xmlto="no" build_documentation="no (missing xmlto)" fi +AC_SUBST([XMLTO]) -have_xsltproc="yes" -AC_PATH_PROG([XSLTPROC], [xsltproc]) -if test "x$XSLTPROC" = "x"; then - have_xsltproc="no" - build_documentation="no (missing xsltproc)" +have_asciidoc="yes" +AC_PATH_PROG([ASCIIDOC], [asciidoc]) +if test "x$ASCIIDOC" = "x"; then + have_asciidoc="no" + build_documentation="no (missing asciidoc)" fi - -have_a2x="yes" -AC_PATH_PROG([A2X], [a2x]) -if test "x$A2X" = "x"; then - have_a2x="no" - build_documentation="no (missing a2x)" -fi -AC_SUBST([A2X]) +AC_SUBST([ASCIIDOC]) integration_tests="yes" AC_PATH_PROG([VALGRIND], [valgrind]) @@ -449,8 +443,8 @@ AC_MSG_RESULT([ package version: $PACKAGE_VERSION]) AC_MSG_RESULT([ build date: $BUILD_DATE]) AC_MSG_RESULT() AC_MSG_RESULT([ Tools:]) -AC_MSG_RESULT([ AsciiDoc (a2x): . . . . . . $have_a2x]) -AC_MSG_RESULT([ xmlto / xsltproc: . . . . . $have_xmlto / $have_xsltproc]) +AC_MSG_RESULT([ AsciiDoc: . . . . . . . . . $have_asciidoc]) +AC_MSG_RESULT([ xmlto: . . . . . . . . . . $have_xmlto]) AC_MSG_RESULT() AC_MSG_RESULT([ Features:]) AC_MSG_RESULT([ documentation: . . . . . . $build_documentation]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 8c280e4..a50754d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,8 @@ -SUFFIXES = .1 .5 .7 .1.html .5.html .7.html .1.txt .5.txt .7.txt +SUFFIXES = \ + .1 .5 .7 \ + .1.html .5.html .7.html \ + .1.txt .5.txt .7.txt \ + .1.xml .5.xml .7.xml EXTRA_DIST = \ sysdb.1.txt \ @@ -31,7 +35,17 @@ CLEANFILES = \ sysdbd-puppet-store-configs.5.html \ sysdbd-syslog.5.html \ sysdb.7.html \ - sysdbql.7.html + sysdbql.7.html \ + sysdb.1.xml \ + sysdbd.1.xml \ + sysdbd.conf.5.xml \ + sysdbd-cname-dns.5.xml \ + sysdbd-collectd-unixsock.5.xml \ + sysdbd-mk-livestatus.5.xml \ + sysdbd-puppet-store-configs.5.xml \ + sysdbd-syslog.5.xml \ + sysdb.7.xml \ + sysdbql.7.xml man_MANS = \ sysdb.1 \ @@ -57,45 +71,66 @@ html_DATA = \ sysdb.7.html \ sysdbql.7.html -ADOC_ATTRS = -apackage_version=$(PACKAGE_VERSION) \ - -abuild_date="$$( date --utc '+%F' )" \ +ADOC_FLAGS = \ + -f$(srcdir)/asciidoc.conf \ + -apackage_version=$(PACKAGE_VERSION) \ -alocalstatedir=$(localstatedir) +# XXX: Make asciidoc use this stylesheet HTML_ATTRS = --stylesheet=$(srcdir)/sysdb-man.css -sysdb.1: sysdb.1.txt ../version -sysdbd.1: sysdbd.1.txt ../version -sysdbd.conf.5: sysdbd.conf.5.txt ../version -sysdbd-cname-dns.5: sysdbd-cname-dns.5.txt ../version -sysdbd-collectd-unixsock.5: sysdbd-collectd-unixsock.5.txt ../version -sysdbd-mk-livestatus.5: sysdbd-mk-livestatus.5.txt ../version -sysdbd-puppet-store-configs.5: sysdbd-puppet-store-configs.5.txt ../version -sysdbd-syslog.5: sysdbd-syslog.5.txt ../version -sysdb.7: sysdb.7.txt sysdb-description.txt ../version -sysdbql.7: sysdbql.7.txt sysdb-description.txt ../version +MAN_DEPS = asciidoc.conf ../version -sysdb.1.html: sysdb.1.txt ../version -sysdbd.1.html: sysdbd.1.txt ../version -sysdbd.conf.5.html: sysdbd.conf.5.txt ../version -sysdbd-cname-dns.5.html: sysdbd-cname-dns.5.txt ../version -sysdbd-collectd-unixsock.5.html: sysdbd-collectd-unixsock.5.txt ../version -sysdbd-mk-livestatus.5.html: sysdbd-mk-livestatus.5.txt ../version -sysdbd-puppet-store-configs.5.html: sysdbd-puppet-store-configs.5.txt ../version -sysdbd-syslog.5.html: sysdbd-syslog.5.txt ../version -sysdb.7.html: sysdb.7.txt sysdb-description.txt ../version -sysdbql.7.html: sysdbql.7.txt sysdb-description.txt ../version +sysdb.1.xml: sysdb.1.txt $(MAN_DEPS) +sysdbd.1.xml: sysdbd.1.txt $(MAN_DEPS) +sysdbd.conf.5.xml: sysdbd.conf.5.txt $(MAN_DEPS) +sysdbd-cname-dns.5.xml: sysdbd-cname-dns.5.txt $(MAN_DEPS) +sysdbd-collectd-unixsock.5.xml: sysdbd-collectd-unixsock.5.txt $(MAN_DEPS) +sysdbd-mk-livestatus.5.xml: sysdbd-mk-livestatus.5.txt $(MAN_DEPS) +sysdbd-puppet-store-configs.5.xml: sysdbd-puppet-store-configs.5.txt $(MAN_DEPS) +sysdbd-syslog.5.xml: sysdbd-syslog.5.txt $(MAN_DEPS) +sysdb.7.xml: sysdb.7.txt sysdb-description.txt $(MAN_DEPS) +sysdbql.7.xml: sysdbql.7.txt sysdb-description.txt $(MAN_DEPS) -.1.txt.1: - @A2X@ -d manpage -f manpage $(ADOC_ATTRS) $< -.1.txt.1.html: - @A2X@ -d manpage -f xhtml $(HTML_ATTRS) $(ADOC_ATTRS) $< +sysdb.1: sysdb.1.xml +sysdbd.1: sysdbd.1.xml +sysdbd.conf.5: sysdbd.conf.5.xml +sysdbd-cname-dns.5: sysdbd-cname-dns.5.xml +sysdbd-collectd-unixsock.5: sysdbd-collectd-unixsock.5.xml +sysdbd-mk-livestatus.5: sysdbd-mk-livestatus.5.xml +sysdbd-puppet-store-configs.5: sysdbd-puppet-store-configs.5.xml +sysdbd-syslog.5: sysdbd-syslog.5.xml +sysdb.7: sysdb.7.xml +sysdbql.7: sysdbql.7.xml -.5.txt.5: - @A2X@ -d manpage -f manpage $(ADOC_ATTRS) $< -.5.txt.5.html: - @A2X@ -d manpage -f xhtml $(HTML_ATTRS) $(ADOC_ATTRS) $< +sysdb.1.html: sysdb.1.txt $(MAN_DEPS) +sysdbd.1.html: sysdbd.1.txt $(MAN_DEPS) +sysdbd.conf.5.html: sysdbd.conf.5.txt $(MAN_DEPS) +sysdbd-cname-dns.5.html: sysdbd-cname-dns.5.txt $(MAN_DEPS) +sysdbd-collectd-unixsock.5.html: sysdbd-collectd-unixsock.5.txt $(MAN_DEPS) +sysdbd-mk-livestatus.5.html: sysdbd-mk-livestatus.5.txt $(MAN_DEPS) +sysdbd-puppet-store-configs.5.html: sysdbd-puppet-store-configs.5.txt $(MAN_DEPS) +sysdbd-syslog.5.html: sysdbd-syslog.5.txt $(MAN_DEPS) +sysdb.7.html: sysdb.7.txt sysdb-description.txt $(MAN_DEPS) +sysdbql.7.html: sysdbql.7.txt sysdb-description.txt $(MAN_DEPS) + +.1.txt.1.xml: + @ASCIIDOC@ $(ADOC_FLAGS) -b docbook -d manpage $< +.5.txt.5.xml: + @ASCIIDOC@ $(ADOC_FLAGS) -b docbook -d manpage $< +.7.txt.7.xml: + @ASCIIDOC@ $(ADOC_FLAGS) -b docbook -d manpage $< -.7.txt.7: - @A2X@ -d manpage -f manpage $(ADOC_ATTRS) $< +.1.xml.1: + @XMLTO@ man $< +.5.xml.5: + @XMLTO@ man $< +.7.xml.7: + @XMLTO@ man $< + +.1.txt.1.html: + @ASCIIDOC@ $(ADOC_FLAGS) -b xhtml11 -d manpage $< +.5.txt.5.html: + @ASCIIDOC@ $(ADOC_FLAGS) -b xhtml11 -d manpage $< .7.txt.7.html: - @A2X@ -d manpage -f xhtml $(HTML_ATTRS) $(ADOC_ATTRS) $< + @ASCIIDOC@ $(ADOC_FLAGS) -b xhtml11 -d manpage $< diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 0000000..f07a9cc --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,34 @@ +[macros] +(?u)(?Pmanpage):(?P\S+?)\[(?P
\d+\w*)\]= + +ifdef::backend-docbook[] +[manpage-inlinemacro] + +{target}{section} + +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[manpage-inlinemacro] +{target}({section}) +endif::backend-xhtml11[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +SysDB +{package_version} +SysDB Manual + + +{manname} +{manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + diff --git a/doc/sysdb.1.txt b/doc/sysdb.1.txt index 4746cc9..ccb2e96 100644 --- a/doc/sysdb.1.txt +++ b/doc/sysdb.1.txt @@ -1,7 +1,5 @@ sysdb(1) ======== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -59,7 +57,7 @@ None known. SEE ALSO -------- -*sysdbd*(1), *sysdbql*(7) +manpage:sysdbd[1], manpage:sysdbql[7] AUTHOR ------ diff --git a/doc/sysdb.7.txt b/doc/sysdb.7.txt index 325cbca..9f217b3 100644 --- a/doc/sysdb.7.txt +++ b/doc/sysdb.7.txt @@ -1,7 +1,5 @@ sysdb(7) ======== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -28,7 +26,7 @@ collects system and inventory information from the backends and aggregates objects retrieved from different backends based on their attributes. This way, it creates a uniform hierarchy of the entire infrastructure. -For details about the SysDB daemon, see its manual page *sysdbd*(1). +For details about the SysDB daemon, see its manual page manpage:sysdbd[1]. sysdb ~~~~~ @@ -36,13 +34,13 @@ The SysDB client is a terminal-based, interactive shell which may be used to query the SysDB daemon. It connects to a running daemon and then accepts commands from the user, sends them to the server, and displays the results. -For details about the SysDB client, see its manual page *sysdb*(1). For +For details about the SysDB client, see its manual page manpage:sysdb[1]. For details about how to query the database, see the specification of the SysDB -query language in *sysdbql*(7). +query language in manpage:sysdbql[7]. SEE ALSO -------- -*sysdb*(1), *sysdbd*(1), *sysdbql*(7) +manpage:sysdb[1], manpage:sysdbd[1], manpage:sysdbql[7] AUTHOR ------ diff --git a/doc/sysdbd-cname-dns.5.txt b/doc/sysdbd-cname-dns.5.txt index a41bc3b..21e375f 100644 --- a/doc/sysdbd-cname-dns.5.txt +++ b/doc/sysdbd-cname-dns.5.txt @@ -1,7 +1,5 @@ sysdbd-cname-dns(5) =================== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -26,7 +24,7 @@ CONFIGURATION SEE ALSO -------- -*sysdbd*(1), *sysdbd.conf*(5) +manpage:sysdbd[1], manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd-collectd-unixsock.5.txt b/doc/sysdbd-collectd-unixsock.5.txt index 67c9574..6add73f 100644 --- a/doc/sysdbd-collectd-unixsock.5.txt +++ b/doc/sysdbd-collectd-unixsock.5.txt @@ -1,7 +1,5 @@ sysdbd-collectd-unixsock(5) =========================== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -44,7 +42,7 @@ CONFIGURATION SEE ALSO -------- -*sysdbd*(1), *sysdbd.conf*(5) +manpage:sysdbd[1], manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd-mk-livestatus.5.txt b/doc/sysdbd-mk-livestatus.5.txt index b84e0f4..ab11b7e 100644 --- a/doc/sysdbd-mk-livestatus.5.txt +++ b/doc/sysdbd-mk-livestatus.5.txt @@ -1,7 +1,5 @@ sysdbd-mk-livestatus(5) ======================= -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -44,7 +42,7 @@ CONFIGURATION SEE ALSO -------- -*sysdbd*(1), *sysdbd.conf*(5) +manpage:sysdbd[1], manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd-puppet-store-configs.5.txt b/doc/sysdbd-puppet-store-configs.5.txt index 82b5ecf..537cb98 100644 --- a/doc/sysdbd-puppet-store-configs.5.txt +++ b/doc/sysdbd-puppet-store-configs.5.txt @@ -1,7 +1,5 @@ sysdbd-puppet-store-configs(5) ============================== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -57,7 +55,7 @@ CONFIGURATION SEE ALSO -------- -*sysdbd*(1), *sysdbd.conf*(5) +manpage:sysdbd[1], manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd-syslog.5.txt b/doc/sysdbd-syslog.5.txt index a3aee5a..054e1c8 100644 --- a/doc/sysdbd-syslog.5.txt +++ b/doc/sysdbd-syslog.5.txt @@ -1,7 +1,5 @@ sysdbd-syslog(5) ================ -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -23,7 +21,7 @@ CONFIGURATION SEE ALSO -------- -*sysdbd*(1), *sysdbd.conf*(5) +manpage:sysdbd[1], manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd.1.txt b/doc/sysdbd.1.txt index 53e936b..51c329c 100644 --- a/doc/sysdbd.1.txt +++ b/doc/sysdbd.1.txt @@ -1,7 +1,5 @@ sysdbd(1) ========= -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -70,7 +68,7 @@ None known. SEE ALSO -------- -*sysdbd.conf*(5) +manpage:sysdbd.conf[5] AUTHOR ------ diff --git a/doc/sysdbd.conf.5.txt b/doc/sysdbd.conf.5.txt index 25be073..e6c387d 100644 --- a/doc/sysdbd.conf.5.txt +++ b/doc/sysdbd.conf.5.txt @@ -1,7 +1,5 @@ sysdbd.conf(5) ============== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -137,7 +135,7 @@ system's syslog service. SEE ALSO -------- -*sysdbd*(1) +manpage:sysdbd[1], manpage:sysdb[7] AUTHOR ------ diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt index a6d7314..5f967c6 100644 --- a/doc/sysdbql.7.txt +++ b/doc/sysdbql.7.txt @@ -1,7 +1,5 @@ sysdbql(7) ========== -Sebastian "tokkee" Harl -version {package_version}, {build_date} :doctype: manpage NAME @@ -166,7 +164,7 @@ replies look like. The replies are pretty-printed to more easily follow them. SEE ALSO -------- -*sysdb*(1) +manpage:sysdb[1] AUTHOR ------ -- 2.30.2