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

[Peter Hutterer]

On Tue, Jun 29, 2010 at 04:59:15PM -0700, Dan Nicholson wrote:
> 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?

The macros are moving a bit too fast for my liking for XTS. Since we haven't
audited the tests yet and there's bound to be quite a few that need
fixing, I'd rather be able to pull in latest XTS on an older box (e.g. RHEL)
without having to rely on whatever the latest macros version is.

If the duplication gets out of proportion, then maybe but for now I think
this hunk above should pretty much be it, right?

Cheers,
  Peter