Re: proposal for doc+web sources

[Graham Percival]

On Sat, Jul 18, 2009 at 12:03:04PM +0200, John Mandereau wrote:
> I'd like to start working on the plan below real soon now

I'd also like you to start working on it real soon now.  :)
Especially the creation on essay; that way, I can start doing the
doc rearrangement and tackle the content of the AU.


> Le samedi 11 juillet 2009 à 03:21 -0700, Graham Percival a écrit : 
> > docs/topdocs/
> > docs/topdocs/changes.texi
> > docs/topdocs/compile.texi
> 
> I don't see the points of keeping a subdirectory topdocs: if the
> documents in this directory play a so different role from other,

Good point.  I had a vague notion that having them there might
make it easier to produce the top-level *.txt files, but I
honestly would rather have them moved.  If you're happy with that,
then by all means let's move them.

compile.itexi would go in devel.  (note the itexi)
I guess we'd need an "install.texi" somewhere, just to produce the
INSTALL.txt document.  Since compile.itexi is mainly intended as
part of the CG, it wouldn't have a @top node.


I propose that we make Changes a standalone document:
  Documentation/changes.tely
we don't need a subdir for this, since it should only just be the
single file.


> Putting this issue aside, what I propose is
> 
> Documentation
> |
> |- web.tely -> lilypond
> |
> |- learning.tely -> lilypond-learning
> |- notation.tely -> lilypond-notation 
> \- ...idem for glossary, essay, application, snippet, devel, changes, authors

Yes, with the proviso that "snippet" might require extra trickery.
(i.e. Documentation/snippet/lsr, Documentation/snippet/new/, etc)

Oh wait: authors doesn't get its own manual.  That will move into
web.tely, as part of community.itexi.

And we /might/ want to rename "devel" to "contributors", just to
keep it close to the CG name.  The original devel/ dir was just to
oppose user/.

> > regression/   new location of input/regressions/
> > input/        completely deleted
> 
> Unlike the overhaul of documention structure, I don't see what we gain
> in renaming/removing input/regression in terms of building (makefiles)
> simplification or maintenance, so I'm not keen on doing this without
> stronger arguments.

Ok, that's fine.  It's a bit weird to have input/regression/ with
nothing else in input/, but (just like the Documentation/ => docs/
change), this isn't delaying any other work.

I'll also tackle this in Sep, in a separate branch, with patches,
etc.

> About the switch to SCons we have mentioned, I think the simplification
> to be brought to the Documentation makefiles makes me feel this switch
> not so useful as I used to think, i.e. I consider dropping this for more
> than one year.

Up to you.  I mean, the simplification would also make it *easier*
to switch, so maybe you want to do it sooner, just for fun. :)

> Unless there are objections, I'll start applying this plan by moving the
> three manuals and snippets very soon.

I think we have more than three manuals, but other than that, agreed.

Cheers,
- Graham