Re: the "separate, but integrated" website proposal

[Graham Percival]

On Sun, Aug 02, 2009 at 09:16:15PM +0200, John Mandereau wrote:
> Le lundi 27 juillet 2009 à 18:13 -0700, Graham Percival a écrit :
> > - nobody edits texinfo files in this repo.  They are imported
> >   via scripts/update-imported.sh from the
> 
> I have one first concern with update-imported.sh: downloading latest
> changes from master branch by requesting a tarball from Git web
> interface is wasting bandwidth and Savannah servers ressources, it's

I think that's a minor issue at this stage, but if we went with
this idea (which we don't appear to be doing), I'd certainly
implement your solution to this problem.

> > - the website can be built without lilypond, or even texinfo
> >   installed.  All it needs it texi2html (perl).
> 
> You hide other requirements by making them generated manually -- music
> examples for instance --

"generated manually" meaning "run make generate-examlpes once a
year or so".

> > - normal users cannot screw up the official, uploaded, web page.
> >   (a dedicated developer needs to import the latest changes from
> >   master and review them, before pushing them to the lilypond-web
> >   repo)
> 
> Have you already found any developer to do this?

Since it's roughly half the work of updating LSR, I don't think
this would be a problem.  I can handle this stuff, no problem.

> And it would be bad to
> distribute an outdated offline version of the web site in either master
> or stable/*, so there should be a dedicated developer to cherry-pick
> website changes from one branch into the other one.

Mao, I hadn't thought of that.  I mean, master/ would have the
latest changes anyway (since any changes are made there), but we'd
definitely want to backport those anyway.

Not that this backporting would be a big job -- once you verified
that the changes were good for the web.repo, you'd just run the
"copy Documentation/web/* from master/ to stable/" script.

> This and and the
> requirement to regenerated examples by hand are too much overhead for
> our development resources, I can't support this plan in its current
> infrastructure shape.

Again, the plan is that we *wouldn't* regenerate examples on a
regular basis.  And certainly not by hand!

> My proposal to upload most of the web site from generated documentation
> of stable branch solves this problem: regular contributors can edit the
> web site on master, then the dedicated developer you mention cherry-pick
> changes into stable branch.  We'd have cron job on lilypond.org take a
> almost built output tree of stable docs and only (re)build the web site
> and a bit of stuff we don't want in distributed docs (e.g. home page
> news).  I won't precise it any further, but will start hacking instead
> and propose patches.

Ok.

Ultimately, this is your show.  I'm not convinced that a separate
web repo with imported files isn't the best way, but since you're
doing this work and not me, it's up to you.

A few things to consider:
- under the "website from stable" proposal, updating the examples
  will require me to rsync them.  (they can't depend on the latest
  stable release, since we might want to update the examples on
  a different schedule)
  This isn't necessarily a problem, since I'll be around a lot for
  the next few years... but it's worth considering.
- actually, let's *not* automatically take the examples from the
  latest stable.  We need a distinct way of updating them anyway,
  so all this would do would be to add another layer of
  "paperwork" for making a release.
- I can't see any parts of the website that particularly don't
  belong as distributed docs.  Sure, we could probably identify a
  few sections here and there that don't *need* to be in a doc
  tarball, but I don't think it's worth it to identify those
  sections and creating build scripts to omit them.
- Ideally, we'd have a script that copies everything from
  master/Documentation/web/* to stable/2.12/Documentation/web/.
- the scripts on lilypond.org will need to easily be changeable
  from stable/2.12 to stable/2.14.
- we'll need to add a few extra files to master like
  lilypond.org.htaccess and favicon, but this isn't a big deal.



> > My only uncertainty with this proposal is that I'm not certain how
> > this affects the cross-references.  I'm hopeful that since the
> 
> Err, cross-references to other manuals need more information (see
> below). Unless you import all manuals into web repo and build from there
> (which would make no sense), you need at least the xref-map files of
> other manuals.

That makes sense.  If we were doing the separate repo thing, then
we'd just import the xref-map as well.



> BTW what about creating a directory Documentation/graphics, which would
> host non-Lily-generated graphics for all manuals?

Well, a few days ago I asked about a Documentation/pictures.  I'm
not troubled about whether we call it pictures or graphics.  I
still have a slight preference for moving images into their
respective dirs (say, notation/images/, essay/images/, etc) but I
know that would create more work.

I was tempted to investigate this makefile change myself in a few
days, but if you'd rather just dump everything into a graphics,
I'm fine with that.

Cheers,
- Graham