William Harold Newman wrote:
> Where did the Makefile come from? It looks as though it might have
> been autogenerated by some tool, or at least copied from some more
> general system. If so I'd prefer to write something like
It's a makefile I originally wrote for UFFI and then generalized for
CLSQL. Mentioning the origin of the "standard docfile processing"
would clear up any begged question of "whose standard".
> sbcl-html.dsl is unneeded now, right? "grep dsl *" doesn't show
> anything referring to it, and I doubt it magically affects the
> operation of xsltproc even when nothing refers to it.
Correct, DSSSL is no longer used and that file can be deleted.
> The html-stamp approach seems at least a little bit surprising. One
> might expect -- and at least I expected -- that I could verify that
> things worked by blowing away *.html, rerunning make.sh, and verifying
> that the .html files were recreated, but they're not. I realize that
> the foo-stamp approach is used in other Makefiles for similar
> problems, so possibly what I'm observing here is that the
> "make-doc.sh" file has become a distracting/confusing relic now that
> there's a doc/Makefile which controls everything.
The goal of html-stamp is, of course, to avoid unnecessary building of
the html/* files. Similarly functionality could be achieved by using
html/index.html as a timestamp and assuming if html/index.html is
present that xsltproc ran to completion.
I had considered converting my Makefile to a shell script, since SBCL
typically uses shell scripts to invoke build and clean
operations. However, I decided against that initially since the
Makefile allows multiple targets (html, pdf, ps, txt) and also handles
building targets only when sources have newer timestamps. At this
point, getting rid of make-doc.sh and clean.sh would not be losing
> On the theme of relics, is there a realistic possibility that
> different people will have plug-compatible versions of xsltproc with
> different names? The find-jade machinery in make-doc.sh was intended
> to cope with the jade-vs.-openjade split. Unless there such a split in
> the xsltproc world, perhaps we could just get rid of the machinery in
> make-doc.sh now.
There are other XSL transformers that could be used (Saxon, Xalan, XT,
MSXML), but xsltproc seems widely available and works very well. The
web page http://www.sagehill.net/docbookxsl/XSLprocessors.html has a
good overview of the available XSLT engines. I doubt very much that
any of them are "plug-compatible" in terms of the syntax of their
command lines. With appropriate commands lines, they should all work
similarly except that some transformers might not support the XInclude
module which I employ so that each chapter is a valid XML file.
An installation of the xsltproc program is unlikey to be in non-PATH
directory, so getting rid of the machinery in make-doc.sh would be
fine. An alternative would be to extend the machinery to find other
XSLT engines and help gmake use those other engines. However, I'm not
in favor of this unless people report that installing xsltproc is
difficult and they would prefer a different XSLT program.
One other advantage of xsltproc is that it includes xmllint which can
be invoked by "make check". The docbook file is verified by xsltproc
in the other targets, but one can use the "check" target to verify
without creating output files.