Re: the "separate, but integrated" website proposal

[John Mandereau]

Le lundi 27 juillet 2009 à 18:13 -0700, Graham Percival a écrit :
> Details are in the ADD-TO-CG.txt file, but as a brief summary:
> - nobody edits texinfo files in this repo.  They are imported
>   via scripts/update-imported.sh from the
>   unstable/current/head/master lilypond branch.
>   (currently the URL points to web-gop because the texinfo files
>   aren't in master yet)

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
better to set a variable in a untracked file that tells the script about
the location of a local Git clone of master branch that can be pulled by
the script.


> - 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 -- whereas a stable doc build (which is necessary
for bringing cross-references anyway, see below) can bring such examples
by just uploading (by ssh and/or rsync or whatever) a docs snapshot.


> I believe this satisfies a number of requirements:
> - we have a set of integrated docs for tarballs (i.e.
>   lilypond-general.texi -> lilypond.texi in the main branch)
> - normal contributors can easily work on website text
>   (i.e. Jonathan could add another famous lilypond performance
>   to our Introductions->Productions page (on master) without
>   changing branches/repos)
> - 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?  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.  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.

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.  MY plan would be a bit of work to set up on
lilypond.org (not significantly more than your proposal), and this
avoids copying and updating Texinfo files and pictures and whatnot from
one Git branch to another by operations more complex than simple
merging.


> My only uncertainty with this proposal is that I'm not certain how
> this affects the cross-references.  I'm hopeful that since the
> texinfo files are the same in master/ and the web repo, it won't
> be hard to make the links on the uploaded website point to the doc
> links.

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.  One easy way to make them available is to upload them to
lilypond.org, which could e.g. be done by including the xref-maps in
uploaded (stable) docs.


> (if there's no better way of doing it, I could even make a python
> script to replace links like @ref{Learning manual} with
> @uref{docs/2.12/learning-manual/index.html, Learning manual}.)

Have you realized that this process is more complex because of our
custom file splitting?  .xref-map files provide necessary information
for texi2html so it correctly does this, you needn't rewrite makeinfo in
Python :-)

Anyway, it looks necessary to move the Texinfo doc from web-gop to
master regardless of the amount of amending I'm tempted to bring, so I
really plan to do it tomorrow.

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

Best,
John

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