[Plplot-devel] Re: api.xml patch + DocBook building rant

[Rafael L. <ra...@de...>]

* Alan W. Irwin <ir...@be...> [2003-03-08 08:46]:

> Done.  It solves the problem, but also highlights some dependency issues
> that need to be fixed, see below.

Thanks, Alan.  I am still without network access to my email machine and I
am replying essentially from the SF web interface.  This problem should be
fixed by Monday.

This is for Joao: the next time you break one of the XML files, there is no
problem at all, we can fix the bugs that you introduce.  However, stop
pestering about scripts that are not working anymore or about the DocBook
system as a whole :-)

> > I am just realizing that when Octave bindings building is enable, we must
> > check in configure.ac for the presence of some of the Perl modules.  This is
> > done currently only for the DocBook documentation.
> 
> I agree, but keep the list of modules to the absolute minimum required.  At
> the moment, there is no problem with generating the octave documentation on
> RedHat with their standard perl modules, but if you ask for anything more
> that is not needed to generate the octave documentation, you probably won't
> be able to build octave on RH since their perl module support is so minimal.

I have been thinking about another idea: why do not include those .txt file
in the tarbal, in a similar way we do for the swig and DocBook files?  I can
easily change the rules in bindings/octave/Makefile.am to achieve this, such
that make dist will build this files previous to inclusion in the tarball.
The neat implication is that, at the user's side, no perl module will be
needed to build the Octave bindings.

> Now to the dependency issue.  I applied the patch and re-ran make, but the
> perl script in question was not executed again unless I ran make clean first.
> Here is the bad stanza from Makefile.am:
> 
> [makefile rule removed]
>
> There are substantial dependency problems with this stanza.  First, the
> prerequisite list should include ../../../doc/docbook/bin/api2text.pl \
> ../../../doc/docbook/src/plplotdoc.xml.in \
> ../../../doc/docbook/src/api.xml. That is easy enough to put in and solves
> the current dependency issue.

Yes, this must be done.

> However, I also notice the target list needs
> an additional entry since api2text.pl generates a very large number of *.txt
> files.  I don't think we want to put those in the target list since it would
> be a maintenance headache.  However, could you make some sort of timestamp
> file to be put in the target list that was updated *only if* api2text.pl was
> a success?  Without this time stamp, if you simply rerun make after a syntax
> problem in api.xml, the make would go through without any apparent problems.
> The only symptom would be the plplot_octave_txt/*.txt files were not there
> or incomplete.

Interesting: I just started some hours ago to make the changes in the
Makefile.am in order to address exactly the two issues that you mention
above.  In general lines, it will work like this:

    if enable_octave  
    # Yes the next addition to EXTRA_DIST must be inside the AM conditional
    EXTRA_DIST += doc-stamp
    # [...]
    doc-stamp: etc/plplot.doc \
               ${top_builddir}/doc/docbook/src/plplotdoc.xml.in \  
               ${top_builddir}/doc/docbook/src/api.xml
            mkdir -p plplot_octave_txt
            cp etc/plplot.doc plplot_octave_txt/plplot.doc
            ( cd plplot_octave_txt; \
              ${top_builddir}/doc/docbook/bin/api2text.pl \
    	      ${top_builddir}/doc/docbook/src/plplotdoc.xml.in \  
    	      ${top_builddir}/doc/docbook/src/api.xml ) \
    	    && touch doc-stamp

(Notice that the doc-stamp file is created only if the api2txt.pl script
suceeds.)

I will commit this change when I will have access to my production machine
again.

-- 
Rafael