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

Thu Sep 11 06:20:08 UTC 2008

On Thu, Sep 11, 2008 at 3:45 AM, David Lutterkort <lutter at redhat.com> wrote:

> 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.
>

Yes, I had tried that before, and for some reason I seemed to need the
-I$(NDDIR)/Modules. I'll investigate on this since it shouldn't be required
indeed.

>
> > 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)

I tried this, but automake doesn't use ifdef. Instead, it uses "if" but then
you have to declare your variable in configure.in, and I didn't want to
create configure.in just for this. If I tried to use "ifdef" in the standard
Make way, automake complains that it found "endif" without any "if".
Did I miss something?

>
>
> > 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 ;)
>

Yes, as I said on the IRC chan ;)

>
> > 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
>

OK, I'll fix that

>
> > +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.

Yes indeed, this is the only reason why I kept it.

>
>
> 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.
>

Yes, that's right. I went for that option at first because Debian has a
wrapper in /usr/bin/naturaldocs and I thought I would just copy and modify
it. But there is not much of a need eventually, and since I test the
presence of NaturalDocs in configure.ac, the test in the wrapper is not
necessary either.

>
> 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)

Yes, Menu.txt and created/modified by ND. However, ND renames the old
Menu.txt into Menu_Backup.txt before doing so, so you can always restore the
Menu.txt that you had before. I'm not sure about a Menu.in, because I think
it's ND that has to create/modify the Menu.txt anyway. So the normal way of
using it should be to run "make", modify/fix Menu.txt, run make again, check
that the result is fine, commit the new Menu.txt and run make clean.

Raphael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080911/99a30bbb/attachment.htm>