[Xen-devel] [PATCH 2 of 2 v3] docs: use elinks to format markdown-generated html to text

[Matt Wilson <msw@xxxxxxxxxx>]

Markdown, while easy to read and write, isn't the most consumable
format for users reading documentation on a terminal. This patch uses
elinks (by default) to format markdown produced HTML into text files.

Signed-off-by: Matt Wilson <msw@xxxxxxxxxx>

---
Changes since v3:
 * check for html to text dump tool in ./configure
 * switch to using elinks
 * allow command line flags to dump tool to be specified

Changes since v4:
 * none, just adjusted the commit message

diff -r 3b3582f4dc42 -r 6a1ee7eacd9c config/Tools.mk.in
--- a/config/Tools.mk.in        Thu Sep 06 21:31:51 2012 -0700
+++ b/config/Tools.mk.in        Thu Sep 06 21:33:05 2012 -0700
@@ -34,6 +34,8 @@
 DOT                 := @DOT@
 NEATO               := @NEATO@
 MARKDOWN            := @MARKDOWN@
+HTMLDUMP            := @HTMLDUMP@
+HTMLDUMPFLAGS       := @HTMLDUMPFLAGS@
 
 # Extra folder for libs/includes
 PREPEND_INCLUDES    := @PREPEND_INCLUDES@
diff -r 3b3582f4dc42 -r 6a1ee7eacd9c docs/Makefile
--- a/docs/Makefile     Thu Sep 06 21:31:51 2012 -0700
+++ b/docs/Makefile     Thu Sep 06 21:33:05 2012 -0700
@@ -146,9 +146,20 @@
        $(call move-if-changed,$@.tmp,$@)
 
 txt/%.txt: %.markdown
-       $(INSTALL_DIR) $(@D)
-       cp $< $@.tmp
+       @$(INSTALL_DIR) $(@D)
+ifdef MARKDOWN
+ifdef HTMLDUMP
+       @echo "Running markdown to generate $*.txt ... "; \
+       $(MARKDOWN) $< | $(HTMLDUMP) $(HTMLDUMPFLAGS) > $@.tmp
        $(call move-if-changed,$@.tmp,$@)
+else
+       @echo "html dump tool (like elinks) not installed; just copying $<." \;
+       cp $< $@;
+endif
+else
+       @echo "markdown not installed; just copying $<." \;
+       cp $< $@;
+endif
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
        $(INSTALL_DIR) $(@D)
diff -r 3b3582f4dc42 -r 6a1ee7eacd9c tools/configure.ac
--- a/tools/configure.ac        Thu Sep 06 21:31:51 2012 -0700
+++ b/tools/configure.ac        Thu Sep 06 21:33:05 2012 -0700
@@ -93,6 +93,15 @@
 AX_DOCS_TOOL_PROGS([DOT], [dot])
 AX_DOCS_TOOL_PROGS([NEATO], [neato])
 AX_DOCS_TOOL_PROGS([MARKDOWN], [markdown markdown_py])
+AC_ARG_VAR([HTMLDUMP],
+           [Path to html-to-text generation tool (default: elinks)])
+AC_PATH_PROG([HTMLDUMP], [elinks])
+AS_IF([! test -x "$ac_cv_path_HTMLDUMP"], [
+    AC_MSG_WARN([$ac_cv_path_HTMLDUMP is not available so text documentation 
will be unformatted markdown])
+])
+AC_SUBST([HTMLDUMPFLAGS], ["-dump"])
+AC_ARG_VAR([HTMLDUMPFLAGS], [Flags passed to html to text translation tool])
+
 AS_IF([test "x$xapi" = "xy"], [
     AX_PATH_PROG_OR_FAIL([CURL], [curl-config])
     AX_PATH_PROG_OR_FAIL([XML], [xml2-config])

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel