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 74921b82349d1474e1b4d3333f42755977e1dbb8..dbdf2bb49d8398a41277e73926272957c75ac291 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 06c639f0dba11620f2220c4dd1261c4eed310a14..97dc2fe6194995d651d2e6dbfd3c866dff81b32a 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 2e55bc70d687a162cdb61a5969f90c2a299e80c8..849223c82e4e4622b2dccf727d6c86038c7a27d6 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 8c280e40de53a529ada92aac93c7bb191a7c1a80..a50754d924d969625d51812a9deb9eea40c064c9 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 4746cc9e68dfc4bae98de4eac907ff78f9911d1c..ccb2e96b7de55bac1eef85cbaf000c2f173be7b9 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 325cbca17bc5f0aa6ad1787f3427be94d9188a2a..9f217b314d127bc5271b8bba2d4bf3ca3d8756e1 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 a41bc3b02ac7ef8af00297ed3a8cbe30b406da1d..21e375fd9caa83e1eadab1af2ff4f1bea4573631 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 67c9574eb84bded8babd71d31636cb770bd92ab4..6add73fe8c5549ce62b56f22ad7bee03b8dc5c59 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 b84e0f406a5b836545e201e553345941e3cdf700..ab11b7e22ede4e8b2c38f971afe0147b7cad2ea3 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 82b5ecf2bbedcbed7cee8755372861d6a547caf4..537cb9842aae06044ac9a63b091eca31c7a2d46c 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 a3aee5a4374e96c4fc2508665e55373ed19be46a..054e1c82d481d6bd4f49cf0f435618e84d8cbc4c 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 53e936b6fc421251957f85688292c5938b48398a..51c329c2eb86a1d875c819e541ff9e64608e13c6 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 25be073198ae598e2de501258f063d839384a70e..e6c387d5c866219d94f4b79a73fc67f5d81b87de 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 a6d7314b41844108c4368b10a1e8c584b1a4ae7e..5f967c63f492ff19aa179857528c04597d1047dc 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
 ------