Re: Quick way to recreate docs

[Graham Percival]

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?

> 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

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

Cheers,
- Graham