Add some rules to deal with documentation generation.

Signed-off-by: Pierre Habouzit <madcoder@debian.org>

diff --git a/mk/asciidoc.conf b/mk/asciidoc.conf
new file mode 100644 (file)
index 0000000..138604f
--- /dev/null
+++ b/mk/asciidoc.conf
@@ -0,0 +1,51 @@
+## linkgit: macro
+#
+# Usage: linkgit:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show GIT link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[attributes]
+asterisk=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+ifdef::backend-docbook[]
+[linkgit-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Postfix Tools</refmiscinfo>
+<refmiscinfo class="version">{pft_version}</refmiscinfo>
+<refmiscinfo class="manual">Postfix Tools Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[linkgit-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]

diff --git a/mk/callouts.xsl b/mk/callouts.xsl
new file mode 100644 (file)
index 0000000..6a361a2
--- /dev/null
+++ b/mk/callouts.xsl
@@ -0,0 +1,30 @@
+<!-- callout.xsl: converts asciidoc callouts to man page format -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:template match="co">
+       <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+       <xsl:text>.sp&#10;</xsl:text>
+       <xsl:apply-templates/>
+       <xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+       <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
+       <xsl:apply-templates/>
+       <xsl:text>.br&#10;</xsl:text>
+</xsl:template>
+
+<!-- sorry, this is not about callouts, but attempts to work around
+ spurious .sp at the tail of the line docbook stylesheets seem to add -->
+<xsl:template match="simpara">
+  <xsl:variable name="content">
+    <xsl:apply-templates/>
+  </xsl:variable>
+  <xsl:value-of select="normalize-space($content)"/>
+  <xsl:if test="not(ancestor::authorblurb) and
+                not(ancestor::personblurb)">
+    <xsl:text>&#10;&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>

diff --git a/mk/common.mk b/mk/common.mk
index a1b1412..058d21d 100644 (file)
--- a/mk/common.mk
+++ b/mk/common.mk
@@ -32,23 +32,45 @@
 #   see AUTHORS and source files for details                                 #
 ##############################################################################
 
+__DIR__:=$(realpath $(dir $(lastword $(MAKEFILE_LIST))))
+
 include ../mk/cflags.mk
 
 prefix ?= /usr/local
 LDFLAGSBASE += $(if $(DARWIN),-L/opt/local/lib,-Wl,-warn-common)
 CFLAGSBASE  += --std=gnu99 -I../ -I../common $(if $(DARWIN),-I/opt/local/include,)
+ASCIIDOC     = asciidoc -f $(__DIR__)/asciidoc.conf -d manpage \
+              -apft_version=$(shell git-describe)
+XMLTO        = xmlto -m $(__DIR__)/callouts.xsl
+MAN_SECTIONS = 1 2 3 4 5 6 7 8 9
 
 INSTALL_PROGS = $(addprefix install-,$(PROGRAMS))
 
-all: $(GENERATED) $(LIBS) $(PROGRAMS) | $(GENERATED)
+all: $(GENERATED) $(LIBS) $(PROGRAMS)
+
+DOCS_SRC  = $(foreach s,$(MAN_SECTIONS),$(patsubst %.$(s),%.txt,$(filter %.$(s),$(DOCS))))
+DOCS_HTML = $(DOCS_SRC:.txt=.html)
+DOCS_XML  = $(DOCS_SRC:.txt=.xml)
+doc: $(DOCS) $(DOCS_HTML)
 
-install: all $(INSTALL_PROGS)
+install: all $(INSTALL_PROGS) install-doc
+
+install-doc: doc
+       $(if $(DOCS),\
+           set -e\
+           $(foreach s,$(MAN_SECTIONS),\
+               $(foreach m,$(filter %.$(s),$(DOCS)),\
+                   ; install -d $(DESTDIR)$(prefix)/share/man/man$(s)/ \
+                   ; install $(m) $(DESTDIR)$(prefix)/share/man/man$(s)/ \
+       )))
+       $(if $(DOCS_HTML),install $(DOCS_HTML) $(DESTDIR)$(prefix)/share/doc/pfixtools)
 
 $(INSTALL_PROGS): install-%:
        install $* $(DESTDIR)$(prefix)/sbin
 
 clean:
        $(RM) $(LIBS:=.a) $(PROGRAMS) $(TESTS) .*.o .*.dep
+       $(RM) $(DOCS) $(DOCS_XML) $(DOCS_HTML)
 
 distclean: clean
        $(RM) $(GENERATED)
@@ -77,6 +99,15 @@ headers:
 
 $(LIBS): %: %.a
 
+$(DOCS_HTML): %.html: %.txt
+       $(ASCIIDOC) -b xhtml11 -o $@ $<
+
+$(DOCS_XML): %.xml: %.txt
+       $(ASCIIDOC) -b docbook -o $@ $<
+
+%.1 %.2 %.3 %.4 %.5 %.6 %.7 %.8 %.9: %.xml
+       $(XMLTO) man $<
+
 .SECONDEXPANSION:
 
 $(LIBS:=.a): $$(patsubst %.c,.%.o,$$($$(patsubst %.a,%,$$@)_SOURCES)) Makefile
@@ -86,6 +117,8 @@ $(LIBS:=.a): $$(patsubst %.c,.%.o,$$($$(patsubst %.a,%,$$@)_SOURCES)) Makefile
 $(PROGRAMS) $(TESTS): $$(patsubst %.c,.%.o,$$($$@_SOURCES)) Makefile
        $(CC) -o $@ $(filter %.o,$^) $(LDFLAGS) $($@_LIBADD) $(filter %.a,$^)
 
+$(DOCS):
+
 -include $(foreach p,$(PROGRAMS) $(TESTS),$(patsubst %.c,.%.dep,$(filter %.c,$($p_SOURCES))))
 
-.PHONY: install-dir $(INSTALL_PROGS)
+.PHONY: install-doc install-dir $(INSTALL_PROGS)