Re: working on the new website

[Graham Percival]

On Sun, Aug 02, 2009 at 07:55:14PM +0200, John Mandereau wrote:
> Le samedi 01 août 2009 à 20:22 -0700, Graham Percival a écrit : 
> > On Sat, Aug 01, 2009 at 07:32:21PM -0600, Andrew Hawryluk wrote:
> > > OK, sounds good. New questions then:
> > > - do I need to run 'make doc' to build the essay in the new location?
> > 
> > Mao, I forgot about that.  That'd take ages.
> 
> It depends much on your machine... it may take from 26 min to more than
> 2 hours on a 1,4 GHz Celeron GNU/Linux box with 512 MB RAM.

Lucky.  :)
address@hidden:~/svn/lilypond$ make doc-clean &> /dev/null
address@hidden:~/svn/lilypond$ time make doc &> /dev/null

real    226m57.986s
user    193m0.560s
sys     18m35.950s


Granted, that builds all the input/ files as well, but I'm pretty
certain that those take about 1 hour, leaving 3 hours for the
actual docs.  And no, I wasn't using my laptop at the time; I
started the build just before I went out for the evening.

> > You're on osx, right?  Or linux?  I've attached a shell script
> > that just builds the essay.
> 
> Please don't write, use and spread such scripts, or make sure I won't
> notice them nor their consequences: they will likely break next time
> makefiles are changed, and there are already so many issues and
> questions with the official build system that we don't want to be
> bothered by halping contributors that use such alternative building
> methods.

Oops, I meant to warn Andrew that it was fragile.  Andrew: if it
stops working at some point, let me know and I'll whip up another
script.

Other than that, I don't regret it in the least.  It's my job to
make sure that other people can do their jobs.  That was the
fastest+easiest way to let Andrew get started.  In the long term,
I'd definitely recommend that he use the normal build system, but
since that's in flux right now, the custom shell script lets him
concentrate on his job (the essay), without getting distracted by
other issues.


> >   Eventually I hope to have individual
> > targets in the makefile, but I couldn't get that to work.
> 
> Cross-references maps from all other manuals may be necessary to build
> one manual in HTML.  It might be possible to detect dependencies far
> enough to determine which other manuals one manual refers to, but
> frankly there are much more essential goals to reach first.

Well, the point of individual-manual building would be to test one
specific manual.  For those cases, we could just make the ref
point to null or whatever.

> >   The doc
> > build process is in the middle of a severe revamping,
> 
> Docs makefiles dependencies are currently a mess, which I won't attempt
> at polishing before many other things are sorted out: web site
> integration, Texinfo parser, translation infrastructure...

That makes sense.

> > Rendered output (from the shell script) is in
> > Documentation/out/essay.html
> 
> Documentation/out-www/essay.html.

The shell script dumps it in out/.  I used an $OUTDIR, though, so
if Andrew wanted, he could make it out-www/ or out-stupid-script/
or whatever.

Cheers,
- Graham