Code

doc: Use asciidoc instead of a2x and added asciidoc.conf.
authorSebastian Harl <sh@tokkee.org>
Fri, 23 May 2014 17:46:37 +0000 (19:46 +0200)
committerSebastian Harl <sh@tokkee.org>
Fri, 23 May 2014 17:46:37 +0000 (19:46 +0200)
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.

15 files changed:
.gitignore
README
configure.ac
doc/Makefile.am
doc/asciidoc.conf [new file with mode: 0644]
doc/sysdb.1.txt
doc/sysdb.7.txt
doc/sysdbd-cname-dns.5.txt
doc/sysdbd-collectd-unixsock.5.txt
doc/sysdbd-mk-livestatus.5.txt
doc/sysdbd-puppet-store-configs.5.txt
doc/sysdbd-syslog.5.txt
doc/sysdbd.1.txt
doc/sysdbd.conf.5.txt
doc/sysdbql.7.txt

index 74921b8..dbdf2bb 100644 (file)
@@ -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 (file)
--- a/README
+++ b/README
@@ -66,11 +66,10 @@ Prerequisites
 
     <http://pubs.opengroup.org/onlinepubs/9699919799/>
 
-  * asciidoc, xsltproc, xmlto:
+  * asciidoc, xmlto:
     The AsciiDoc text document format is used to write the manpages.
 
     <http://www.methods.co.nz/asciidoc/>
-    <http://xmlsoft.org/XSLT/>
     <https://fedorahosted.org/xmlto/>
 
   * libedit or libreadline:
index 2e55bc7..849223c 100644 (file)
@@ -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])
index 8c280e4..a50754d 100644 (file)
@@ -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 (file)
index 0000000..f07a9cc
--- /dev/null
@@ -0,0 +1,34 @@
+[macros]
+(?u)(?P<name>manpage):(?P<target>\S+?)\[(?P<section>\d+\w*)\]=
+
+ifdef::backend-docbook[]
+[manpage-inlinemacro]
+<citerefentry>
+<refentrytitle>{target}</refentrytitle><manvolnum>{section}</manvolnum>
+</citerefentry>
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[manpage-inlinemacro]
+<a href="{target}.{section}.html">{target}({section})</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">SysDB</refmiscinfo>
+<refmiscinfo class="version">{package_version}</refmiscinfo>
+<refmiscinfo class="manual">SysDB Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>{manname}</refname>
+<refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
index 4746cc9..ccb2e96 100644 (file)
@@ -1,7 +1,5 @@
 sysdb(1)
 ========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index 325cbca..9f217b3 100644 (file)
@@ -1,7 +1,5 @@
 sysdb(7)
 ========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index a41bc3b..21e375f 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd-cname-dns(5)
 ===================
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index 67c9574..6add73f 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd-collectd-unixsock(5)
 ===========================
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index b84e0f4..ab11b7e 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd-mk-livestatus(5)
 =======================
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index 82b5ecf..537cb98 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd-puppet-store-configs(5)
 ==============================
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index a3aee5a..054e1c8 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd-syslog(5)
 ================
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index 53e936b..51c329c 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd(1)
 =========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-version {package_version}, {build_date}
 :doctype: manpage
 
 NAME
@@ -70,7 +68,7 @@ None known.
 
 SEE ALSO
 --------
-*sysdbd.conf*(5)
+manpage:sysdbd.conf[5]
 
 AUTHOR
 ------
index 25be073..e6c387d 100644 (file)
@@ -1,7 +1,5 @@
 sysdbd.conf(5)
 ==============
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------
index a6d7314..5f967c6 100644 (file)
@@ -1,7 +1,5 @@
 sysdbql(7)
 ==========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-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
 ------