Re: the "separate, but integrated" website proposal

[John Mandereau]

Le lundi 03 août 2009 à 04:19 -0700, Graham Percival a écrit :
> 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".

OTOH we could be a bit prouder and say on the examples pages something
like "These examples are generated with latest stable version without
any further tweak to the source files, which are available through a
link at the side of each image" just like the old examples.


> 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.

As you proposed to move the main web site sources to the main source
tree, I think we should take as many advantages as possible of the build
system, including generating examples from ly source, sharing the
translation infrastructure and the HTML postprocessing.


> 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.

This is the only significant disavantage of what I propose: every
contributor that has permission to push can update a branch from
another, but only Han-Wen, Jan and you can upload compiled docs.  I
think it's not a big deal as long as there are at least two of you
available to react within a day or two if necessary.


> - 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 don't see the issue here: stable branch should only carry
documentation improvements and bug fixes that introduce no regression.
I can't remember any adventurous changes to Lily binary or lilypond-book
have been committed that would break generated music examples (some
early 2.10 releases had broken docs, but because of the build system).


> - 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.

On the contrary, before you explain a precise plan I understood that web
repo would contain the two only things that surely don't make sense in
the "distributed web site" (i.e. general information): the news entries
and the download pages, which would be generated only in HTML in Web
repo. Those two pages would still be generated automatically from a cron
job, so that e.g. uploading a release will trigger a build of download
pages.


> - Ideally, we'd have a script that copies everything from
>   master/Documentation/web/* to stable/2.12/Documentation/web/.

Sure, even if some manual adjustments may be sometimes necessary after
having run the script.


> - the scripts on lilypond.org will need to easily be changeable
>   from stable/2.12 to stable/2.14.

It will be much easier to release 2.14 and the new web site at the same
time; if we don't, somebody (me?) will have to move docs in stable/2.12
(OK, the makefiles would mostly need to be copied without further
hacking, but even with this this would be much of a pain too).  You have
the final say on this, but now you know that it costs to release the
website before 2.14 (releasing it after would be a lesser pain).


> - we'll need to add a few extra files to master like
>   lilypond.org.htaccess and favicon, but this isn't a big deal.

Can't they remain on web branch along with the news and download pages?


> Well, a few days ago I asked about a Documentation/pictures.

This directory already serves another purpose, list it and/or see
ROADMAP.


> 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 wouldn't create significantly more work, but having pictures in
respective manual directories would create more Git history noise and
more ad-hoc include path specifications for images shared between
several manuals.


> 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.

I took me at least a year during hobby time to understand Lily build
system, so I can do this within one hour, building and testing included.
You probably agree with me that's not such an exciting job, so let's
attribute it to the available contributor that can do it quickest.


Finally, do you mind if I import files from web-gop by just copying
them, i.e. without the whole history?  E.g. I don't want to import
generated lys, as you probably know. I'll hack lilypond-book to produce
snippets with preview images and "click to enlarge/click to see the
complete score" links.  For attribution and copyright issues, we may
preserve web-gop branch.

Best,
John

signature.asc
Description: Ceci est une partie de message numériquement signée