From: Pierre Habouzit <madcoder@debian.org>
Date: Sun, 11 Jan 2009 18:33:00 +0000 (+0100)
Subject: Add some rules to deal with documentation generation.
X-Git-Url: http://git.madism.org/?a=commitdiff_plain;ds=sidebyside;h=063d8a2ddca1e35efde7a3dec5eb04387dfb0922;p=apps%2Fpfixtools.git

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
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
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
--- 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)