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 8:09 PM
Subject: Re: Quick way to recreate docs


> On Tue, Aug 02, 2011 at 07:48:14PM +0100, Phil Holmes wrote:
> > ----- Original Message ----- From: "Graham Percival"
> > <address@hidden>
> > >On Tue, Aug 02, 2011 at 05:01:00PM +0100, Phil Holmes wrote:
> > >Off the top of my head, I suspect that this can be done with
> > > make out=www Documentation/out-www/learning.pdf
> >
> > 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'
>
> Ok, what about
>  touch Documentation/notation.tely
>  make out=www Documentation/out-www/notation.pdf

Surprisingly, I get:

address@hidden:~/lilypond-git/build$ touch Documentation/notation.tely
address@hidden:~/lilypond-git/build$ make out=www 
Documentation/out-www/notation.pdf
make: Nothing to be done for `Documentation/out-www/notation.pdf'.

I'll have a look at make out=www at some point.

> The problem with the docs failing to rebuild when you edit one of
> the included is well-known, and is almost certainly another of
> these one-line fixes to the build system that requires 3 hours to
> write.  :(

And the rest.  I took about 2.5 days sorting out the missing pictures.

> > >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.
>
> Yes, it builds html instead.
>
> *shrug*
>
> I personally prefer to view docs in html, but I have no problem
> with people wanting pdf instead.  I'm still a bit hesitant about
> adding a script that duplicates existing functionality in the
> build system, but OTOH it's not like we're short of disk space or
> anything.


OK.  To me, the ability to have the whole document compiled and viewable 
quickly would improve my (very poor) ability to write docs quite a bit.

I've now knocked up a script.  It's run like:

./MakeDocScript.sh essay

to create essay.pdf.  It works for all the docs, including contributor and 
web.  Most pdfs take, in total, 10 seconds or so to create fresh.  Notation 
took 70 seconds on my system.

If I was writing docs, I'd want to use this - anyone want to test it?

--
Phil Holmes