Directory structure for docs and web site

[John Mandereau]

Hi guys,

I expect comments (and even maybe votes from developers) about the
directory structure, which will very soon drive an important part of the
docs and web site reorganization (especially the makefiles and
buildscripts :-P).

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'm not comfortable with putting everything at the same level on the web
site as a direct upload of the compiled docs would product, assuming we
actually merge the web site into docs:

lilypond.org
  web/  -- main web site
  learning-big-page  -- Learning Manual (big page)
  learning/          -- Learning Manual (splitted)
  notation-big-page -- Notation Reference (big page)
  notation/
etc.

I can't imagine putting the docs for development branch at toplevel:
this would make them default docs, which is not acceptable. If we ever
want to have docs at toplevel, it should be docs for stable branch, so
the web site should be rather edited on stable/2.x Git branch.


That said, if we decide to keep the current directory structure, there
must be some HTML links hacking in some Python and/or Texi2html init
file. I see two possible plans in this case, which have already been
mentioned, but I try to explain more implications, pros and cons below.

1) Keep the full web site away from Lily main source tree, i.e. on web
branch. 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. 

Pros: clear separation of the web site (which is for all Lily versions)
and the docs (which is version-specific).
Cons: more work to make possible building a site for offline browsing
(although this is easily achieved by importing some Python code from
master branch), the web site building process must retrieve compiled
xref-maps from docs, HTML links hacking in Python scripts or Texi2HTML
init file (a bit of a hassle, but I've already done this with
Snippets<->Documentation/user).


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.


Note that although this issue is not completely orthogonal to putting
all Texinfo manuals in Documentation/, the latter should be done first
anyway, because it will simplify cross-referencing inside documentation
and between docs and the web site regardless of the web sources
location.

Best,
John

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