Re: the "separate, but integrated" website proposal

[Graham Percival]

On Mon, Aug 03, 2009 at 02:12:54PM +0200, John Mandereau wrote:
> Le lundi 03 août 2009 à 04:19 -0700, Graham Percival a écrit :
> > "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.

Well, it depends how you define "tweak".  In the LM, we lean
pretty heavily on "tweak = \override and \set" (plus others).
Some of those examples definitely *do* use tweaks!

I'd rather keep the wiggle room and just say "look at these
examples".  Nobody will think that we loaded the images in gimp
and changed things!

I'd also rather keep the safety of *not* generating them for every
stable release.

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

Ok.  I'm willing to try it.  I mean, in the worst case, we could
just switch lilypond.org to automatically download images from
  http://lilynet.net/example_upload/
and give write permission for that dir to whoever you want.

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

- for X months, where X is as large as possible, the "stable"
  branch *is* the "main" branch, so there's more changes.
- the examples will deliberately do fancy stuff; a small change to
  a spacing algorithm or improved slur shape might result in a
  manually-placed fingering causing a collision.

If this wasn't our "pride and joy showcase for non-users", I'd be
perfectly content letting the images be built however they are.  I
mean, I don't care (much) if a headword ends up looking silly.
But on the website, I *really* want to be certain that nothing
changes unless we explicitly want it to change.

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

I don't see any harm in distributing the news.  Granted, most of
it is really boring ("released 2.7.4.  Fixed some beam issues"),
but it only adds a few pages to the pdf.  For the HTML, users can
simply avoid following the link to "Old news".

It's true that we *could* remove the Download pages.  But again:
they don't really cause any problems.  The install instructions
are in there, so theoretically somebody might get lilypond and the
docs on a CD, but might not figure out how to double-click on the
lilypond.exe file.

Hey, there must be *some* reason why the windows users wanted an
enumerated list of 6 items!  On a more serious note, the info in
Unix or MacOS X could well be useful.

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

Sorry.  Of course you're right here; the above was a thinko/typo.
I just meant that in general, it should be easy to change from
stable/2.x to stable/2.y (or even stable/3.x).  i.e. please add a
        IMPORT_FROM=stable/2.14
to the top of the makefile (or python script).  One of my
complaints about GUB was that they *didn't* do this, so I had to
hunt around through script to find "rsync ... address@hidden".

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

I thought the website was going to be built from the stable
branch?  If we're doing that, then let's delete the web branches.

> > Well, a few days ago I asked about a Documentation/pictures.
> 
> This directory already serves another purpose, list it and/or see
> ROADMAP.

Why should the 3 logos -- one of which is depecated, and one of
which I've never seen before in my life -- have their own dir?
I'm not totally against this, but I can't see a good reason for
it.  Especially with a generic name like "pictures".  Now, if it
was "logos", or possibly "old-and-unused-and-current-logos", then
I'd agree.


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

Hmm, I hadn't realized that we had shared images.  Ok, we can dump
everything into pictures... oops, I mean graphics.

> Finally, do you mind if I import files from web-gop by just copying
> them, i.e. without the whole history?

Fine with me.  In the comment for the import, please write
something like
----
Web: import files from web-gop branch.

Overall structure by Graham, with many comments and suggestions
from -user.  Patrick McCarty worked extensively on the css and its
integration with texinfo.  Jonathan worked on the Introduction.
Patrick Schmidt did further work on the CSS and the Old news page.
----


> I'll hack lilypond-book to produce snippets with preview images
> and "click to enlarge/click to see the complete score" links.

... I'm still really iffy about this.  Both Jonathan and I spent a
few hours trying to force lilypond to create images with a
specific pixel width (600 pixels, IIRC -- see
texinfo/examples/GNUmakefile).  We both failed.

> For attribution and copyright issues, we may preserve web-gop
> branch.

No; we want to remove both web branches.  Or at very least, move
them into an archive repo.  I think the above text is sufficient
to cover attribution.

Cheers,
- Graham