Re: Directory structure for docs and web site

[John Mandereau]

Le lundi 27 juillet 2009 à 01:17 -0700, Graham Percival a écrit :
> I thought we were keeping the uploaded-website on a separate
> branch?

The uploaded website is the generated website; as it's generated, it
doesn't need nor deserve to be stored in a version control system, it
should just be uploaded to lilypond.org.  My point was, as we agree not
to take too much risk by building the main web site examples from master
branch, and as links from the main web site to the documentation will
mostly point to stable branch docs, let's build the web site from stable
branch; this quite clear, isn't it?  I'm open to other proposals, but at
this point I expect clearly defined proposals which aim at a complete
solution.



>   Yes, it's the opposite of what I originally suggested,
> but you and Han-Wen convinced me otherwise.

I'm lost. Han-Wen was sceptical about merging the web site into the main
source tree, wasn't he?



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

And what about curious people that want to easily look at the sources?
OK, the source shouldn't be shown by cliking on the PNG image on web
page, but I think it should be reachable from the page by a link e.g.
with a small font size.


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

As I understand it, the web repo won't contain stuff that is necessary
to build lilypond.tely, so it won't contain generated images, right?
What is this web repo you keep talking about?  Please draw a picture or
whatever, as this is completely unclear to me. Current web branch will
be trimmed to keep the minimal stuff that still needs to be built on
lilypond.org, and the rest of the web site will come from an upload of
compiled docs, or have you another plan in mind?


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

There is no LilyPond binary that runs on lilypond.org, so that's fair;
most of the future web site will be generated on a machine that has to
run lily binary anyway, so let's benefit from this.  Don't tell me we're
going to add generated PNGs of all examples in input/ and input/mutopia
that are on current Examples page.



> I think we misunderstood each other somewhere (with regards to
> website building),

... and we still do. If you want to propose something else that what I
do, please specify with enough details, not saying "I thought that..."
"I believe but haven't verified that...".


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

They are necessary mixed and interleaved, just like syntax and semantics
are often mixed in a language -<:-)


> - could the css be moved to a separate dir?

Unless we have more than 8 CSS files, I think it's not necessary. BTW
what about junking texinfo.css?


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

This won't make the build any simpler, and I see no benefit for the
editors. As we're going to add some more pictures from web-gop, there
will be enough pictures for moving them to a Documentation/pictures/,
copying/converting them into Documentation/out-www/, so they end up in
Documentation/ in the docball and thus will work without extra hacking
in postprocess_html.py.


> - bibliography/ will be moving to essay/ once it exists.

I'll create a stub for the essay (after having handled Patrcik's
reports), just like I did for LM and AU ;-)


> 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

"lilypond" is fine, unless there is any objection let's adopt it.


> I admit that having a lilypond.texi and lilypond/ directory might
> be slightly confusing for doc editors and makefile editors...

We already have notation.tely and notation/ etc.


> OTOH, any confusion over this would only happen at the very
> beginning of somebody's doc editing.

Sure, so that's not a big deal.

Best,
John

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