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

[Joao C. <jc...@fe...>]

On Saturday 08 March 2003 19:37, Rafael Laboissiere wrote:
> * 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 sent the report *before* I made the modifications to api.xml.

And, as a matter of fact, after I cvs update, configure, etc:

[jcard@feup] cvs -f -z3 update -R -d -P .

[jcard@feup] cvs status doc/docbook/src/api.xml
===================================================================
File: api.xml           Status: Up-to-date

   Working revision:    1.47
   Repository revision: 1.47    
/cvsroot/plplot/plplot/doc/docbook/src/api.xml,v

[jcard@feup] ./bootstrap.sh && ./myconfig && make clean && make
...

mkdir -p plplot_octave_txt
cp etc/plplot.doc plplot_octave_txt/plplot.doc
cd plplot_octave_txt; \
../../../doc/docbook/bin/api2text.pl \
../../../doc/docbook/src/plplotdoc.xml.in \
../../../doc/docbook/src/api.xml

undefined entity at line 2915, column 62, byte 85921 at 
/usr/lib/perl5/site_perl/5.8.0/i586-linux-thread-multi/XML/Parser.pm line 185
make[4]: *** [plplot_octave_txt/plplot.doc] Error 255

The fact that Alan can make it is (I think) only because he can also make the 
documentation. I changed nothing in my system.

Joao

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