Re: Quick way to recreate docs

[Phil Holmes]

----- Original Message ----- 
From: "Graham Percival" <address@hidden>
To: "Phil Holmes" <address@hidden>
Cc: <address@hidden>
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 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)


My suggestion would be to make it into a script, and if doc writers like it, 
add it to the make system.

--
Phil Holmes