[RFC:util/macros] Add XORG_CHECK_GROFF for building specs

[Alan Coopersmith]

Thanks, I like this idea, and wish it had been done before I moved
all those troff docs from xorg-docs to the individual modules (though
there's still more to move out of xorg-docs).

Why not make the flags to check for an argument to the macro, so that
modules can check for whichever of -ms, -mm, -t, -e they need?

Also, for a generic macro, the flag should probably be something like
--with-groff instead of --enable-specs.

On the other hand, the "MAKE_{TEXT,HTML,etc.}" result variable names
are a bit generic, since we may have multiple formats of documentation
available - maybe GROFF_TO_TEXT or something like that?

(I'm wondering if we'll want to someday have this done in most modules,
 with rules to run groff -man -Thtml to convert man pages to html as
 we used to do in the monolith, or if that was only really useful for
 the website maintainer publishing the docs.)

	-Alan Coopersmith-           alan.coopersmith at sun.com
	 Sun Microsystems, Inc. - X Window System Engineering

Yaakov (Cygwin/X) wrote:
> From: Yaakov Selkowitz <yselkowitz at users.sourceforge.net>
> 
> With the spec docs being moved out of xorg-docs into the related library
> or proto package, this macro handles the configure code necessary to
> check for and build the specs from groff macros.
> ---
> This was named and written in a style similar to the docbook and linuxdoc
> checks.  Several things to note:
> 
> 1) util/macros configure.ac would need a version bump to 1.4.0
> 
> 2) While most macros are ms, xtrans uses mm and xtst (still in xorg-docs)
> has some of both.  Since the ms macros are the majority, and that's where
> we've had some problems recently, I left the check for -ms.
> 
> 3) Because of that, and other differences in the various GROFF_FLAGS (e.g.
> libX11 specs require -e, others do not), I did not add move any more flags
> into the MAKE_* variables.
> 
> An example of usage is to follow from libSM.  Comments welcome.
> 
>  xorg-macros.m4.in |   71 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 71 insertions(+), 0 deletions(-)
> 
> diff --git a/xorg-macros.m4.in b/xorg-macros.m4.in
> index 8875193..2c5658c 100644
> --- a/xorg-macros.m4.in
> +++ b/xorg-macros.m4.in
> @@ -310,6 +310,77 @@ AC_SUBST(MAKE_PDF)
>  AC_SUBST(MAKE_HTML)
>  ]) # XORG_CHECK_DOCBOOK
>  
> +# XORG_CHECK_GROFF
> +# -------------------
> +# Minimum version: 1.4.0
> +#
> +# Defines the variable MAKE_SPECS if the necessary tools and
> +# files are found. $(MAKE_TEXT) blah.ms will then produce blah.txt.
> +# Whether or not the necessary tools and files are found can be checked
> +# with the AM_CONDITIONAL "BUILD_SPECS"
> +AC_DEFUN([XORG_CHECK_GROFF],[
> +AC_ARG_VAR([GROFF], [Path to a groff executable that supports -ms])
> +AC_ARG_VAR([PS2PDF], [Path to a ps2pdf executable])
> +
> +AC_PATH_PROGS([GROFF], [groff], [none], [$PATH:/usr/gnu/bin])
> +AC_PATH_PROGS([PS2PDF], [ps2pdf], [none], [$PATH:/usr/gnu/bin])
> +
> +if test x$GROFF != xnone ; then
> +    AC_MSG_CHECKING([whether $GROFF -ms works])
> +    if $GROFF -ms -I. /dev/null >/dev/null 2>&1 ; then
> +        groff_works=yes
> +    else
> +        groff_works=no
> +        GROFF=none
> +    fi
> +    AC_MSG_RESULT([$groff_works])
> +fi
> +
> +AC_MSG_CHECKING([Whether to build specification docs])
> +
> +AC_ARG_ENABLE(specs, AC_HELP_STRING([--enable-specs],
> +                                   [Enable building of specification docs]),
> +              [BUILDSPECS="${enableval}"], [BUILDSPECS="auto"])
> +
> +if test x$BUILDSPECS = xauto; then
> +    if test x$GROFF = xnone ; then
> +        BUILDSPECS=no
> +    else
> +        BUILDSPECS=yes
> +    fi
> +fi
> +
> +AC_MSG_RESULT([$BUILDSPECS])
> +
> +if test x$BUILDSPECS = xyes && test x$GROFF = xnone ; then
> +    AC_MSG_ERROR([can't build specification docs without groff])
> +fi
> +
> +AM_CONDITIONAL(BUILD_SPECS, [test x$BUILDSPECS = xyes])
> +
> +AC_MSG_CHECKING([Whether to build PDF specification docs])
> +
> +if test x$PS2PDF != x && test x$BUILD_PDFDOC != xno; then
> +   BUILDPDFDOC=yes
> +else
> +   BUILDPDFDOC=no
> +fi
> +
> +AM_CONDITIONAL(BUILD_PDFDOC, [test x$BUILDPDFDOC = xyes])
> +
> +AC_MSG_RESULT([$BUILDPDFDOC])
> +
> +MAKE_TEXT="env GROFF_NO_SGR=TRUE $GROFF -Tutf8 -I\$(srcdir)"
> +MAKE_PS="$GROFF -Tps -I\$(srcdir)"
> +MAKE_PDF="$PS2PDF"
> +MAKE_HTML="$GROFF -Thtml -I\$(srcdir)"
> +
> +AC_SUBST(MAKE_TEXT)
> +AC_SUBST(MAKE_PS)
> +AC_SUBST(MAKE_PDF)
> +AC_SUBST(MAKE_HTML)
> +]) # XORG_CHECK_GROFF
> +
>  # XORG_CHECK_MALLOC_ZERO
>  # ----------------------
>  # Minimum version: 1.0.0