[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Quick way to recreate docs

From: Jean-Charles Malahieude
Subject: Re: Quick way to recreate docs
Date: Tue, 02 Aug 2011 20:59:38 +0200
User-agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv: Gecko/20110621 Fedora/3.1.11-1.fc14 Thunderbird/3.1.11

Le 02/08/2011 20:48, Phil Holmes disait :
----- 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
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:

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

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.

This would as well "speed up" translation work, where you have to
touch notation.tely when you correct a typo in winds.itely


reply via email to

[Prev in Thread] Current Thread [Next in Thread]