Re: proposal for doc+web sources

[Graham Percival]

On Sat, Jul 11, 2009 at 03:02:33PM -0600, Carl Sorensen wrote:
> 
> On 7/11/09 4:21 AM, "Graham Percival" <address@hidden> wrote:
> 
> > Here's my proposal for the source/makefile view of documentation.
> > (this is the big argument one)
> 
> In general, I think these proposals are reasonable.

Actually, giving it some more thought, there *is* some tension
between the release cycles of the main source tree and the
website.

That said, I still think we should distribute some of the website
info along with the release-specific docs.


What about having the texinfo in *both* places, but don't edit
them in the web/ branch?  Basically, it would work vaguely like
LSR.  The main website texinfo files would be in main/, but a
dedicated website person would import those files into a web/
branch (or repo) from time to time?

This way,
- we can include a "snapshot" of the website in the doc build from
  main/.  Texinfo cross-references and the like work easily, so
  the docs ("user information") will be more coherent.
- doc writers and translators only work on main/ (or
  translations)
- we retain a "house of sober second thought" (sorry, Canadian
  political joke there... although AFAIK it would work in any
  country with a distinct second layer of representative, such
  as the US Senate or the UK House of Lords)

... let me try this again:

  The online website won't get screwed up if somebody makes a
  mistake in the main/ branch.  The dedicated website person
  will check the website before importing altered texinfo files
  from main/ to the web/ repo.

- really website-specific material, such as the google analytics
  stuff, would only be stored in the web/ repo.
- if desired, we could even alter the texi2html tweaking, css
  file, or even alter the "main" texinfo file, depending on
  whether it was the online website or a local "snapshot" for
  distribution with the release.

  I'm not certain if we'd want to change the CSS at all (a
  different color scheme for the local copy?), but it could
  well be a good idea to change the Download page.  I mean,
  if somebody's downloaded a lilypond-doc package in debian
  or whatever, they probably already have lilypond package.
  So maybe we'd omit those pages... also, the Search box
  won't do much good.  etc.

Cheers,
- Graham