Re: Directory structure for docs and web site

[John Mandereau]

Le mercredi 22 juillet 2009 à 21:46 -0700, Graham Percival a écrit :
> 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!

I think putting more responsability for releases, which is not such a
bad thing IMHO. Hey, this would probably mean the web site should be
build in stable branch, which fits the need to make links from the web
site to *stable* docs by default.


> - requires lilypond (could be problems for a distinct web repo)

But this won't be in a distinct repo, and you designed lilypond-general
Texinfo document so it would be difficult to do anything else :-)


> - we DO NOT want to show the input code.

Why not?


> - we want to show an expanded image upon click (possibly via
>   javascript).

This feature needn't 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?

This will make 704 Kb evey time the examples are updated.  If you
compare this with current master branch history weight (a bit less than
60 Mb), that can potentially bloat up the history.  I prefer to hack
lilypond-book.


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

I'm still questioning this. I don't and I can't put my veto on this, but
I might refuse to do it myself without stronger justifications.


> Hmm... ok.  I'm slightly concerned about the downloadable tarball
> (it might be nice to offer downloadable HTML and pdf tarballs).

Unlike the web site, this will work out of the box.


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

Oh, I'm almost sure that it will be ugly, whoever does it: this will
likely be a hack in postprocess_html.py:hack_urls() or the like :-P



I hope we're done for now with brain surgery on docs, so as far as I'm
concerned I declare the docs in a releasable state again, modulo a few
buglets that may remain (broken HTML links, missing manuals in splitted
HTML :-).

The next things I plan for the docs infrastructure : translating node
names directly in docs, split out the essay and add lilypond-general,
make docs maintenance scripts use a real Texinfo parser and optimize
makefiles -- in this order, maybe the two last items in parallel.

Speaking of lilypond-general (it will be the info document name), are
you OK with naming it general.texi?  This will avoid adding yet another
ad-hoc makefile hack. This will produce general/index.html and
general-big-page.html in the docball, and this name won't appear for the
online web site of course.

Until it's ready to replace the old web site (this means in particular:
at least translated in the languages which have active translators by
the end of August), I propose not to add links to lilypond-general from
Documentation/index.html nor from anywhere, so people who are aware of
its existence will be able to see the output on kainhofer.com or in the
released docball without having to build it themselves.

Best,
John

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