[augeas-devel] [PATCH] Add naturaldocs to doc/

[David Lutterkort]

On Wed, 2008-09-10 at 16:12 +0200, Raphael Pinson wrote:
> # HG changeset patch
> # User Raphael Pinson <raphink at gmail.com>
> # Date 1221055915 -7200
> # Node ID a2e54bd5c9fd56b804dc94f5690aa66e9f4ce046
> # Parent  f4e2629f1b5176c22341c0d84fb57cff4f2bf791
> Add naturaldocs to doc/
> Add Makefile.am to doc/ and doc/naturaldocs/
> Adapt Makefile.am and configure.ac to build docs:
>   - add --with-naturaldocs=DIR
>   - add --with-pdfdocs

First off, very nice work; I tried it and it works.

> diff -r f4e2629f1b51 -r a2e54bd5c9fd Makefile.am
> --- a/Makefile.am	Tue Sep 09 11:50:01 2008 +0200
> +++ b/Makefile.am	Wed Sep 10 16:11:55 2008 +0200
> @@ -1,4 +1,4 @@ SUBDIRS=gnulib/lib src gnulib/tests test
> -SUBDIRS=gnulib/lib src gnulib/tests tests man
> +SUBDIRS=gnulib/lib src gnulib/tests tests man doc
>  
>  ACLOCAL_AMFLAGS = -I gnulib/m4
>  
> diff -r f4e2629f1b51 -r a2e54bd5c9fd configure.ac
> --- a/configure.ac	Tue Sep 09 11:50:01 2008 +0200
> +++ b/configure.ac	Wed Sep 10 16:11:55 2008 +0200
> @@ -3,6 +3,35 @@ AC_CONFIG_AUX_DIR([build/aux])
>  AC_CONFIG_AUX_DIR([build/aux])
>  AM_CONFIG_HEADER([config.h])
>  AM_INIT_AUTOMAKE([-Wno-portability])
> +
> +
> +dnl Check for NaturalDocs
> +AC_ARG_WITH([naturaldocs],
> +  [AS_HELP_STRING([--with-naturaldocs=DIR],
> +    [path to NaturalDocs install dir to generate documentation])], 
> +  [AC_CHECK_FILE($withval/NaturalDocs,
> +      NATURALDOCSDIR=$withval
> +      HAS_NATURALDOCS=naturaldocs,
> +      [ AC_MSG_ERROR(You asked to use NaturalDocs but it could not be found)])
> +  ])
> +AC_SUBST(HAS_NATURALDOCS)
> +AC_SUBST(NATURALDOCSDIR)

I'd prefer it if we could pass the path to the naturaldocs binary/script
instead of the dir to the NaturalDocs install - that way, it would also
work with a NaturalDocs install from a package (rpm/deb), where you
don't really have an install dir.

> diff -r f4e2629f1b51 -r a2e54bd5c9fd doc/Makefile.am
> --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
> +++ b/doc/Makefile.am	Wed Sep 10 16:11:55 2008 +0200
> @@ -0,0 +1,15 @@
> +
> +SUBDIRS = $(HAS_NATURALDOCS)

I'd prefer it if this was something like

        ifdef HAS_NATURALDOCS
          SUBDIRS += naturaldocs
        endif

(or even 'ifdef NATURALDOCSDIR' - we don't need two variables for this)

> diff -r f4e2629f1b51 -r a2e54bd5c9fd doc/naturaldocs/Makefile
> --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
> +++ b/doc/naturaldocs/Makefile	Wed Sep 10 16:11:55 2008 +0200

Ooops .. shouldn't be checked in ;)

> diff -r f4e2629f1b51 -r a2e54bd5c9fd doc/naturaldocs/Makefile.am
> --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
> +++ b/doc/naturaldocs/Makefile.am	Wed Sep 10 16:11:55 2008 +0200
> @@ -0,0 +1,24 @@
> +
> +# Default install dir for NaturalDocs
> +NDPROJECT=conf
> +NDSRC=$(top_builddir)/src
> +NDLENSES=$(top_builddir)/lenses
> +NDFORMAT=HTML
> +NDOUTPUT=output

I think I confused you yesterday: the source files need to be relative
to srcdir, i.e. something like

        NDPROJECT=$(srcdir)/conf
        NDSRC=$(top_srcdir)/src
        NDLENSES=$(top_srcdir)/lenses
        NDFORMAT=HTML
        NDOUTPUT=output
        NDSTYLE=Augeas
        
The easiest way to check that that is all setup right, is to do
something like
        mkdir /tmp/build
        cd /tmp/build
        $AUGEAS_CHECKOUT/configure ... your favorite configure
        options ...
        cd doc && make

> +NaturalDocs:
> +	mkdir -p $(NDOUTPUT) && \
> +	NDDIR=$(NATURALDOCSDIR) \
> +	   ./naturaldocs \
> +	      -p $(NDPROJECT) \
> +	      -i $(NDSRC)   \
> +	      -i $(NDLENSES) \
> +	      -o $(NDFORMAT) $(NDOUTPUT) \
> +	      -s $(NDSTYLE)

The 'naturaldocs' invocation must also be '$(srcdir)/naturaldocs'

> diff -r f4e2629f1b51 -r a2e54bd5c9fd doc/naturaldocs/naturaldocs
> --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
> +++ b/doc/naturaldocs/naturaldocs	Wed Sep 10 16:11:55 2008 +0200
> @@ -0,0 +1,24 @@
> +#!/bin/sh
> +
> +
> +usage() {
> + echo "Wrapper for NaturalDocs in Augeas"
> + echo -e "Usage: [NDDIR=/path/to/naturaldocs/dir] ./naturaldocs [ND options]\n"
> +}
> +
> +
> +if [ ! -f "$NDDIR/NaturalDocs" ]; then
> +   echo "Error: Could not find NaturalDocs in $NDDIR"
> +   echo "Please specify the path to NaturalDocs with NDDIR=/path/to/naturaldocs/dir"
> +   echo ""
> +   usage
> +   exit 1
> +fi
> +
> +
> +[ "x$1" = "x--help" ] && usage
> +
> +exec /usr/bin/perl -M"NaturalDocs::Languages::Augeas" \
> +                   -I"$NDDIR/Modules" -I"Modules" \
> +		   $NDDIR/NaturalDocs $@

It seems that the '-I"$NDDIR/Modules"' is not needed, which is the only
place where NDDIR is used besides to invoke the ND script - if I didn't
fat finger that, that means we can simply have users tell us where their
ND script is instead of the whole dir.

Also, can we get rid of the wrapper script and just stick the whole
naturaldocs invocation into the Makefile.am ? I don't think there's much
of a need for the wrapper - in addition, the '-I"Modules"' needs to be
relative to $(srcdir) again, which will be simpler to do when everything
is in the Makefile.

Anyway, very nice work; if we can get these few wrinkles ironed out, I'd
love to commit this.

Also, after doing a make in doc/, 'hg st -mard' says that
naturaldocs/conf/Menu.txt was modified - that has to be avoided; maybe
copy the original Menu.txt to somewhere else before letting ND lose on
it (could be as simple as checking in a Menu.txt.in and copying in the
make rule)
        
David