Re: Directory structure for docs and web site

[Graham Percival]

On Sun, Jul 26, 2009 at 09:13:12PM +0200, John Mandereau wrote:
> 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.
> 
> 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.

...
I thought we were keeping the uploaded-website on a separate
branch?  Yes, it's the opposite of what I originally suggested,
but you and Han-Wen convinced me otherwise.

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

It would scare newbies.  The examples are complicated, involve
tweaks, etc.  The newbie-scaring goes in Text input, not Examples.

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

Which I'm expecting to be once a year?  These images also don't
need to be saved in the main repo; we only need them in the web
repo.  In this case, they won't clutter up the main history at
all, and would only be present in the distinct web repo.

Again, just like the 10-20 pieces of lilypond output in the
*current/old* web branch.


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

I think we misunderstood each other somewhere (with regards to
website building), but let's finish the purely doc-related stuff
first.  Or at least make it a separate email, so we don't have a
mixture of mundane doc maintance stuff with the website
discussion.

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

Ok.  A few other items:

- could the css be moved to a separate dir?
- could the png/eps files be moved to the relevant dirs (notation/
  and learning/ -- although the latter will be essay/ as soon as
  that exists) ?
- bibliography/ will be moving to essay/ once it exists.

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

I was hoping to just call it "lilypond".  Or rather, I was hoping
that the output filenames would be lilypond.info, lilypond.pdf,
and lilypond/index.html

I admit that having a lilypond.texi and lilypond/ directory might
be slightly confusing for doc editors and makefile editors...
OTOH, any confusion over this would only happen at the very
beginning of somebody's doc editing.

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

Ok.

Cheers,
- Graham