[PATCH XTS 3/7] Double-use the README as man-page.

[Dan Nicholson]

On Tue, Jun 29, 2010 at 4:10 PM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> If asciidoc and xmlto is available at install time, convert the README to a
> man page. The autotool hack for this is a bit complicated, but does the job.
> It's essentially copied from libXi that uses asciidoc + xmlto for man page
> generation as well.
>
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  Makefile.am  |   24 ++++++++++++++++++++++++
>  README       |   23 +++++++++++++++++------
>  configure.ac |   19 +++++++++++++++++++
>  3 files changed, 60 insertions(+), 6 deletions(-)
>
> diff --git a/Makefile.am b/Makefile.am
> index 7bd345e..3d53694 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -18,3 +18,27 @@ check-local: check.sh
>  # Helper target for testing subsets (test-Xopen, etc.)
>  test-%:
>        @$(MAKE) $(AM_MAKEFLAGS) check scenario='$*'
> +
> +if HAVE_DOCTOOLS
> +miscmandir = $(MISC_MAN_DIR)
> +xtsman_txt = XTS.txt
> +xtsman_xml = $(xtsman_txt:.txt=.xml)
> +xtsman_pre = $(xtsman_txt:.txt=.man)
> +miscman_DATA = $(xtsman_pre:.man=.$(MISC_MAN_SUFFIX))
> +
> +SUFFIXES = .man .$(MISC_MAN_SUFFIX) .txt .xml
> +
> +XTS.txt: README
> +       cp $(srcdir)/README XTS.txt
> +
> +.man.$(MISC_MAN_SUFFIX):
> +       sed -e 's|miscmansuffix|$(MISC_MAN_SUFFIX)|' < $< > $@
> +.txt.xml:
> +       $(ASCIIDOC) -b docbook -d manpage -o $@ $<
> +.xml.man:
> +       $(XMLTO) man $<
> +       mv -f $(@:.man=.miscmansuffix) $@
> +
> +MAINTAINERCLEANFILES = *.xml $(xtsman_pre) $(xtsman_txt)
> +endif
> +
> diff --git a/README b/README
> index af18b04..41f86ee 100644
> --- a/README
> +++ b/README
> @@ -1,8 +1,18 @@
> +XTS(miscmansuffix)
> +==================
> +
> +Name
> +----
> +    XTS - The X Test Suite
> +
> +Description
> +-----------
> +
>  This is a revamped version of X Test Suite (XTS) which removes some of
>  the ugliness of building and running the tests.
>
>  Downloading
> -===========
> +-----------
>  Currently xts it is only available from a git repository.
>
>        $ git clone git://people.freedesktop.org/~dbn/xtest.git
> @@ -10,8 +20,9 @@ Currently xts it is only available from a git repository.
>  Eventually there will be a tarball release when it is stabilized.
>
>  Requirements
> -============
> +------------
>  Required libraries: libX11, libXext, libXi, libXtst
> +
>  Required utilities: xdpyinfo, xset, perl, bdftopcf, mkfontdir
>
>  If you are using packages outside of the standard system directories,
> @@ -19,7 +30,7 @@ make sure to set PATH and PKG_CONFIG_PATH appropriately. See
>  pkg-config(1) for details on the latter.
>
>  Build and Install
> -=================
> +-----------------
>  The build and install are now straightforward:
>
>        $ ./autogen.sh  # using a git checkout
> @@ -28,7 +39,7 @@ The build and install are now straightforward:
>        $ make install
>
>  Running the Tests
> -=================
> +-----------------
>  The tests can be run from the build directory or from the installed
>  package. The check.sh script sets up the environment to run tests from
>  the build tree.
> @@ -56,7 +67,7 @@ the xts-report tool (formerly vswrpt):
>        $ xts-report -f /xts/output/dir/journal
>
>  Running a Single Test
> -=====================
> +---------------------
>  The pt script can be used to run a single set of tests or a single test case
>  only. For example, to run only the XGrabButton tests, run
>         $ pt ./XGrabButton
> @@ -75,7 +86,7 @@ To run only a single test-case inside one test set, use the -i flag.
>  This command only runs test case 10 (t010() in the source).
>
>  Bugs
> -====
> +----
>  Some tests provide different results when run as a set versus run
>  one-by-one with the pt script. This has been observed with
>  Xlib13/XGrabButton where the modifier state is not reset correctly.
> diff --git a/configure.ac b/configure.ac
> index 158b72a..6f51fc0 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -109,6 +109,25 @@ fi
>  m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])],
>     [AC_SUBST([AM_DEFAULT_VERBOSITY], [1])])
>
> +# Generate man page if asciidoc and xmlto are available.
> +AC_ARG_VAR([XMLTO], [Path to xmlto command])
> +AC_PATH_PROG([XMLTO], [xmlto])
> +AC_ARG_VAR([ASCIIDOC], [Path to asciidoc command])
> +AC_PATH_PROG([ASCIIDOC], [asciidoc])
> +
> +AM_CONDITIONAL([HAVE_DOCTOOLS], [test "x$XMLTO" != "x" && test "x$ASCIIDOC" != "x"])
> +if test "x$XMLTO" = "x" || test "x$ASCIIDOC" = "x"; then
> +    AC_MSG_WARN([xmlto or asciidoc not found - cannot create man pages without it])
> +else
> +    if test x$MISC_MAN_SUFFIX = x    ; then
> +        case $host_os in
> +            solaris*)       MISC_MAN_SUFFIX=5  ;;
> +            *)              MISC_MAN_SUFFIX=7  ;;
> +        esac
> +    fi
> +    AC_SUBST(MISC_MAN_SUFFIX)
> +fi
> +
>  AC_CONFIG_FILES([
>  Makefile
>  check.sh

All the autoconf magic seems fine, but is there any reason not to pull
in the macros from xorg-macros at some point?

--
Dan