Re: Directory structure for docs and web site

[Graham Percival]

On Wed, Jul 22, 2009 at 10:29:37AM +0200, John Mandereau wrote:
> Le mardi 21 juillet 2009 à 23:57 -0700, Graham Percival a écrit :
> > I still think the texinfo files should be in master, but perhaps
> > not the generated images, and not some really web-specific stuff
> > like the htaccess.
> 
> If lilypond-general (which includes examples) contains LilyPond music
> examples, generated images can (and probably should IMHO) be lilypond
> files or @lilypond blocks that are built along with the docs.

I disagree; @lilypond blocks have a few problems for this case:
- this is a really "courageous" regression test.  Ok, ideally we'd
  never merge any patches that break any regtests, but it happens
  from time to time -- especially since IMO nobody is actually
  checking the regtest comparisons.
     (yes, getting this started again is a priority in GOP)
  It's one thing to have some bugs show up in the manual; it's
  another thing to have a bug resulting in ugly examples on the
  Introduction page!
- requires lilypond (could be problems for a distinct web repo)
- we DO NOT want to show the input code.
- we want to show an expanded image upon click (possibly via
  javascript).

All in all, we'd need to check the output all the time, write a
special rule for @lilypond when running texi2html on the website
(actually, I guess this would need to be a special-case option for
lilypond-book), etc etc.  And for what benefit?  So that we can
avoid adding 704 Kb to the git tracker?

I agree that generated files shouldn't be added to source
repositories as a general rule, but I really think that this is a
special case that merits an exemption.  We'd (and by "we", I mean
"you" ;P)  need to add little quirks to so many portions of the
build system, not to mention the ongoing risk or ongoing "check
the output on Examples" task.


> > The precise building of what's on lilypond.org should be fairly
> > clear: it is built from the web repo, with the exception of
> > /doc/2.x/, which is built from the relevant branch of main.  This
> > wouldn't change at all from the current web-building process.
> 
> Except that HTML pages from lilypond-general are moved from /doc/2.x
> to /. As the Texinfo docs structure will be greatly simplified, this is
> an acceptable amount of hacking :-)

Hmm... ok.  I'm slightly concerned about the downloadable tarball
(it might be nice to offer downloadable HTML and pdf tarballs).
For those tarballs, we'd want to generate HTML files that point to
HTML files within the tarball, whereas in the for-upload html
files, we'd want to point lilypond-general links at ../../

I have no suggestions about how to do this in a nice way, but as
long as you're aware of the issue, I'm sure that you can find a
nicer solution than mine, anyway.  :)

> Now it's more clear which direction we follow, I can comfortably get
> back to hacking makefiles and moving files.

Thanks!

Cheers,
- Graham