----- Original Message ----- From: "Graham Percival"
To: "Phil Holmes"
Sent: Tuesday, August 02, 2011 6:31 PM
Subject: Re: Quick way to recreate docs
On Tue, Aug 02, 2011 at 05:01:00PM +0100, Phil Holmes wrote:
As many will know, I've been looking at the make process, and in
particular make doc. I've found that there is a very quick way to
remake docs into a PDF when any of the source text has changed. For
notation, this takes about 2 minutes on my machine, compared with 2
hours 20 minutes for a full fresh doc make (I've just cited that for
comparison of the speed of my Ubuntu VM).
Off the top of my head, I suspect that this can be done with
make out=www Documentation/out-www/learning.pdf
or something like it?
I didn't know this command, but if I edit notation.itely (one of the
includes in notation) I then get:
address@hidden:~/lilypond-git/build$ make out=www
Documentation/out-www/notation.pdf
make: Nothing to be done for `Documentation/out-www/notation.pdf'
It requires that make doc
has already been performed to set up many of the source files.
Someone who knows Unix better than me could make it into a script.
Is this mechanism worth publicising? I don't want to get a problem
where it's seen to be skirting the correct make mechanism, but if I
was writing docs, this is the way I'd test the result.
Well, we already have a "skirting" mechanism for doc stuff:
scripts/auxiliar/doc-section.sh
Yeah - I've used that, but found it awkward to set up and doesn't (IIRC)
give you the full PDF output to check.
Due to the First Law of Build Systems ("a build system is
fundamentally a way of creating command-line commands"), any
script could be turned into a make mechanism, and any make
mechanism could be turned into a script. And the speed of doc
builds are 95% dependent on the speed of lilypond itself (for
creating graphical output), 5% on the speed of
latex+dvips+ghostscript+texi2html+makeinfo, and 0% (rounded) on
the speed of the actual build system.
So the only real consideration IMO is how easy the script-vs-make
would be to maintain. More people understand shell scripts than
make, but if we actively use two separate ways of creating docs
(i.e. make and shell scripts) then that seems to be asking for
trouble.
At the moment, I would lean towards including it as part of the
make build system itself, but only if you think it would take you
less than twice as long as it would to make a shell script.
(oh, but all this is assuming that the functionality isn't already
in the build script with the above "make out=www ... " command)
My suggestion would be to make it into a script, and if doc writers like
it, add it to the make system.