Re: proposal for doc+web sources

[Graham Percival]

On Thu, Jul 16, 2009 at 01:30:56AM +0200, John Mandereau wrote:
> Le samedi 11 juillet 2009 à 03:21 -0700, Graham Percival a écrit :
> > docs/
> 
> I assume you mean Documentation.

No; I really want to rename that dir.  I've wanted to rename it
since I first got involved in lilypond.  Typing shift-d has been
bugging me for the past 6 years, and I want it gone.  :)

I'm assuming that this is easy in git, and that a "git mv" will
keep the history, not produce conflicts, etc.

> > docs/learning.tely
> > docs/learning/*.itely
> > docs/notation.tely
> > docs/notation/*.itely
> > + glossary, essay, application
> 
> Fine, but Info file names must be named lilypond (for the main Info
> documentation, probably some kind of part of the web site)

Definitely; "info lilypond" should give you the website (or
whatever parts thereof are present in the main repo)

> or lilypond-*. IIRC source file names don't have to have the
> same file name prefix as the Info file, I'll have to check this.

Every manual contains a line like this:
  @setfilename lilypond.info
so I assume it's easy to change.

> > docs/web.texi
> > docs/web/*.itexi
> 
> Why not, but this can only be almost permanent contents IMHO (I'll try
> to explain at the end of this message).

IMO, "changes.tely" (oops) definitely should be present for every
build from source.


> > docs/topdocs/compile.texi
> 
> Do you mean this would be a standalone document?

No; this would only be present in the CG and as INSTALL.txt in
tarballs.  Yes, there's a direct link from Download->Source to the
relevant chapter of the CG.  It's impossible to miss, as is
INSTALL.txt in the tarball, so the masocists that want to compile
from source can still find their instructions.

> > regression/   new location of input/regressions/
> > input/        completely deleted
> 
> Can somebody already starts checking where could go stuff that remains
> in input/{tutorial,manual}?

input/manual/ -> docs/notation/
  (and/or docs/learning/, as appropriate)
input/tutorial/ -> docs/application
  (unless we rename that manual... in any case, this is AU stuff)
input/lsr, new, texidocs -> docs/snippets/ lsr, new, texidocs
  (my earlier email was unclear about this, sorry)
input/mutopia -> /dev/null
  (I honestly don't know if these have been visible at all for
  the past 8 years; it's certainly not obvious, if they are!)
input/*.ly -> /dev/null
  (examples are done in web-gop now)


> > There are other considerations: I'd like to include the authors
> > and THANKS file in Community->Authors.  I suppose we could move
> 
> In all that reasoning, you missed the essential fact that as long as
> we'll have two branches, building the web site will require at least two
> branches (or by-products of two branches), one for the development
> branch, the other for the stable branch; (BTW you pointed this out later
> in your message). So some "weird hackery" is needed to get (download or
> cd into another local Git branch and generate) generated Texinfo xref
> maps from the other branch to generate correct HTML links, or
> alternatively we are bound to have the same node names and output
> directories in both branches.
> 
> This also raises the web site build host issue: a hourly cron job on
> lilypond.org for building is currently incompatible with having ly
> snippets compiled during the build; even if we can get Lily to run
> safely, I doubt that lilypond.org host will provide efficiently the
> needed CPU and memory ressources while keeping its server role.

I think this is met by my later proposal to keep a separate web/
repo, but to not edit the texinfo sources on that branch.  That
way, no lilypond snippet compiling will be necessary to build the
website, so the hourly build will be fine.

Of course, the split-repo thing brings back a bunch of trickery to
get references working. :(

> The temporal part would be contents that changes often and/or that
> requires information from several branches: the news and the download
> pages.

And Changes.

> Building it would require an active Internet connection, a read
> access to Lily git repo and a build of the website including some
> by-products (e.g. xref-map files to get cross-references right).

I'm not certain we want to require an active internet connection.
If we have an "imported read-only" directory in the web repo (just
like our current input/lsr/ is an "imported read-only"
directory... read-only by policy, not technically read-only) then
we can still build it offline.  As long as somebody updates the
imported read-only dir from time to time.
(just like the LSR editor updates input/lsr/ from time to time)

> The atemporal part would be all the rest, which would be compiled from
> master branch sources in Documentation/web and would follow the usual
> release cycle, allowing verification, validation, translation updating
> between releases.
> 
> The offline version of the web site would be available in the docball,
> temporal pages would be replaced by atemporal flavors of these ones.
> 
> I'm not sure about where the temporal part should live; the simplest
> would be keeping it in web branch, so we are sure not to mix technical
> differences between them.

I agree with a split between temporal and atemporal, altough could
we call it "variable and permenant" or something like that?  It's
confusing when I try to skim emails about {'','a'}temporal at
4:46am.  :)

Cheers,
- Graham