Re: Directory structure for docs and web site

[Graham Percival]

On Tue, Aug 04, 2009 at 12:22:02PM +0200, John Mandereau wrote:
> Le lundi 03 août 2009 à 05:57 -0700, Graham Percival a écrit :
> >   They complicate the build process
> > even more.
> 
> I'm not sure what this means, but it's hard to scare me with the build
> process.

That's the biggest thing that scares me.

Look, I was sole maintainer of the docs for 4 years.  A few times,
I took a look at the build process because I wanted something or
other changed.  Each time, I abandoned the idea after a few hours,
because I was getting nowhere.

Yes, you and Jan and Han-Wen -- although I'm not positive about
the last two -- know how the doc build and translation stuff
works.  But that doesn't fill me with glee.  Next year, you're
going to be doing less lilypond work, and the other two are
already doing less than they did a few years ago.  Are we going to
end up with another case where none of the actively-working doc
people are too scared to touch the doc build system for another 4
years?

There's a great quote, I think by somebody Kernighan: "Debugging
is twice as hard as writing the program in the first place.  So if
you write your code as cleverly as possible, how will you ever
debug it?"

Now, it's safe to assume that reading somebody else's code is
twice as hard as reading your own code.  And I think it's also
safe to assume that the next person to touch the build process
won't want to spend as long on it as you're willing to spend in
Aug.  So the entire build process should be written 1/4 as
intelligently as you want to write it.

> > Wow, you're right.  Some files in input/ are included, others
> > aren't.  Some dirs in input/mutopia/ are included, others aren't.
> > What a maoing mess!
> 
> Let's not bury input/ and input/mutopia too quickly,

I said I'd think about it.  If we need any long pieces -- and I'm
not convinced we do -- then we might as well put them in LSR.  But
I don't think we need to make any decisions about this yet, so
let's get other matters settled first.

> or please tell me a
> new directory name for the examples .ly sources...
> Documentation/examples?

I'd suggest Documentation/general/examples/  ?  Assuming the
manual is called general.texi, right?

Cheers,
- Graham