Re: proposal for doc+web sources

[Graham Percival]

On Thu, Jul 16, 2009 at 04:45:35PM +0200, John Mandereau wrote:
> Le jeudi 16 juillet 2009 à 04:46 -0700, Graham Percival a écrit :
> > It's impossible to miss, as is
> > INSTALL.txt in the tarball, so the masocists that want to compile
> > from source can still find their instructions.
> 
> Do you mean that all packagers are masocists? :-)

Package managers are an anomoly.  There's no reason for normal
users to compile from source.

inb4 "oh, but I want to run lilypond on my netbsd-powered arm
toaster".  Those aren't normal users.

> > I think this is met by my later proposal to keep a separate web/
> > repo, but to not edit the texinfo sources on that branch.  That
> > way, no lilypond snippet compiling will be necessary to build the
> > website, so the hourly build will be fine.
> 
> If no Texinfo/ly compilation is done on web branch, then there should be
> no Texinfo/ly source on web. I assume you mean this.

No, I mean:
  master/Documentation/web.texi
  master/Documentation/web/*.itexi
(used in GUB release "web" versions)

  web.repo/texinfo/*.itexi
(exact copy of the files in master/.  Nobody edits these, apart
from the web person who imports the versions from master/ after
verifying that they still work)
  web.repo/texinfo/cross-references-trickery
(exact copy of whatever is done in master/Documentation)


Hourly build of the website can run just fine from web/ with no ly
compiling.  lilypond.org doesn't even need to have texinfo
installed; texi2html can run by itself.  This way, building web is
a lightweight, self-contained process.

I don't think that having an exact copy of files in master/ in
web.repo/ is a horrible idea.  If you think it is, then we could
go back to the idea of requring master/ to build the website.  I
think that's too much of a requirement.


Basically, we want a bunch of texinfo files to be used in the
documentation tarball compiling, and in the website.  However we
do things, we either need to build everything from master/  (you
and Han-Wen have convinced me that's not the best idea), or
require both repos in order to build the website, or keep copies
of those files in both repos.


> > I'm not certain we want to require an active internet connection.
> 
> I'm against recording HTML ouptut

I'm against this too.

> and/or a bunch of generated
> PNG/SVG/EPS images of music in web repository: this will clutter history
> a lot.

I think we should have this, though.  Why not?  The current
website does this.  I think site/images/ has about 20 images of
lilypond output. 

The thing is, we definitely *don't* want the images to be built
automatically.  Once in a while -- perhaps once a year -- a
website person should try generating the examples/ and examine the
output carefully.  Are there any flaws?  If so, don't update the
images in Examples.  If there's no flaws, then go ahead an 


In case there's any doubt, we're only talking about the 8-10
images in Introduction->Examples.  No wait; we're doing the "zoom
in" thing.  16-20 png images.
There's no other lilypond output on the website.  I suppose we
might add some lilypond output for a background image or logo or
something, but that's even more of a "don't update this without
lots of careful thought" thing.

Cheers,
- Graham