[Xen-devel] [PATCH 2 of 3] 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
lynx to format markdown produced HTML into text files.

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

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

diff -r 674b694814c8 -r 9a308e4fdc19 config/Tools.mk.in
--- a/config/Tools.mk.in        Wed Aug 29 11:07:52 2012 -0700
+++ b/config/Tools.mk.in        Wed Aug 29 11:50:44 2012 -0700
@@ -33,6 +33,8 @@
 DOT                 := @DOT@
 NEATO               := @NEATO@
 MARKDOWN            := @MARKDOWN@
+HTMLDUMP            := @HTMLDUMP@
+HTMLDUMPFLAGS       := @HTMLDUMPFLAGS@
 
 # Extra folder for libs/includes
 PREPEND_INCLUDES    := @PREPEND_INCLUDES@
diff -r 674b694814c8 -r 9a308e4fdc19 docs/Docs.mk
--- a/docs/Docs.mk      Wed Aug 29 11:07:52 2012 -0700
+++ b/docs/Docs.mk      Wed Aug 29 11:50:44 2012 -0700
@@ -10,3 +10,5 @@
 DOT            := dot
 NEATO          := neato
 MARKDOWN       := markdown
+HTMLDUMP        := elinks
+HTMLDUMPFLAGS   := -dump
diff -r 674b694814c8 -r 9a308e4fdc19 docs/Makefile
--- a/docs/Makefile     Wed Aug 29 11:07:52 2012 -0700
+++ b/docs/Makefile     Wed Aug 29 11:50:44 2012 -0700
@@ -136,9 +136,17 @@
        $(call move-if-changed,$@.tmp,$@)
 
 txt/%.txt: %.markdown
-       $(INSTALL_DIR) $(@D)
-       cp $< $@.tmp
-       $(call move-if-changed,$@.tmp,$@)
+       @$(INSTALL_DIR) $(@D)
+       set -e ; \
+       if which $(MARKDOWN) >/dev/null 2>&1 && \
+               which $(HTMLDUMP) >/dev/null 2>&1 ; then \
+               echo "Running markdown to generate $*.txt ... "; \
+               $(MARKDOWN) $< | $(HTMLDUMP) $(HTMLDUMPFLAGS) > $@.tmp ; \
+               $(call move-if-changed,$@.tmp,$@) ; \
+       else \
+               echo "markdown or html dump tool (like links) not installed; 
just copying $<."; \
+               cp $< $@; \
+       fi
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
        $(INSTALL_DIR) $(@D)
diff -r 674b694814c8 -r 9a308e4fdc19 tools/configure.ac
--- a/tools/configure.ac        Wed Aug 29 11:07:52 2012 -0700
+++ b/tools/configure.ac        Wed Aug 29 11:50:44 2012 -0700
@@ -92,6 +92,16 @@
 AX_DOCS_TOOL_PROG([DOT], [dot])
 AX_DOCS_TOOL_PROG([NEATO], [neato])
 AX_DOCS_TOOL_PROG([MARKDOWN], [markdown])
+
+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