Re: Directory structure for docs and web site

[Graham Percival]

On Tue, Jul 21, 2009 at 07:45:28PM +0200, John Mandereau wrote:
> I have a naive question with not so naive implications about the current
> shape of docs reorganization: what is the planned directory structure
> for the new web site?
> 
> Do we want to make a clear distinction between the site and the docs in
> the URL, i.e. do we keep web/ and doc/v2.*/?

I would personally remove the web/, and have things like
  lilypond.org/introduction.html
  lilypond.org/doc/v2.x/
  lilypond.org/download/
  lilypond.org/tiny_examples.html
along with whatever redirects are desirable.



I'm a bit confused by the below discussion; it makes no mention of
the "lilypond-general texinfo in master, lilypond-general imported
into web repo, web built separately" proposal.  Does this fall
under #1 or #2, or would you rather discuss it as a #3?


> 1) Keep the full web site away from Lily main source tree, i.e. on web
> branch.

Are you using "full web site" as in "the complete web site,
including google analytics numbers", or "full web site" as in
"anything to do with the web site"?
I still think the texinfo files should be in master, but perhaps
not the generated images, and not some really web-specific stuff
like the htaccess.

I'm honestly not certain if this fits into #1 or not.

> This implies that nothing of the web site requires compilation
> of ly snippets, e.g. Examples should be reintegrated into Documentation
> as a Texinfo document. 

No; Examples can stay exactly the way it is.  It uses @image to
include png files.  This involves no compilation of ly snippets.
I have *never* proposed, nor supported, the use of @lilypond for
the website (or lilypond-general).

> Pros: clear separation of the web site (which is for all Lily versions)
> and the docs (which is version-specific).

And as long as the texinfo files are in master, this still allows
the building of an offline lilypond-general document for the doc
tarball.


> 2) Merging the web site into LilyPond sources, with all problems of
> directory strucutre in mind that wouldn't happen without this merge.
> 
> Pros: simple cross-references, easier use of ly snippets in the web
> site.
> Cons: merging the web site of the branch that actually hosts the web
> site into the other one, at least every time the latter branch is
> released (in order to distribute an up-to-date web site), potentially
> unclear distinction of what is precisely built on lilypond.org, more
> cluttering of Git history.

... now it looks like the "import texinfo files from another repo"
fits better into #2.

If the editing of texinfo is in main, then the git history is no
more cluttered than any other manual.  Due to our tight linkage of
documentation and source (which, given the pace of development, is
unavoidable), the git history is *already* cluttered up with "Doc:
a few minor edits" or "Doc: CG: clarify git instructions on
windows".  Not to mention all the translation updates!

I can't imagine that adding a few "Web: beautify contemporary
rhythms example" or "Web: announce new version" (especially if
that was included in a "bump VERSION" update!) would complicate
matters more.


The precise building of what's on lilypond.org should be fairly
clear: it is built from the web repo, with the exception of
/doc/2.x/, which is built from the relevant branch of main.  This
wouldn't change at all from the current web-building process.


Cheers,
- Graham