Re: Directory structure for docs and web site

[John Mandereau]

Le mardi 04 août 2009 à 05:06 -0700, Graham Percival a écrit :
> 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.

You could do it, but it's a bit more of effort.  I could facilitate this
effort by documenting the makefiles inline and the overall
infrastructure in the CG, but the time I have for this is currently
completely absorbed by dicsussions about the building process.  If you
think it's worth documeting the makefiles, please either add everything
I recently told you and will tell you about the building process as
makefiles comments or into the CG, or leave it up to me and stop
thinking out loud on the list on how the building infrastructure works
(and I don't want to snob you by ignoring such questions).


> 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?"

I guess, by documenting it properly?  With all the repsect I have for
Kernighan, I don't agree with writing less clever code just to make it
easier to debug.  There are well-known coding standards and rules
(including proper code commenting) that still allow cleverness.


> 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.

I've already got one half by deciding not to merge makefiles for docs in
English and translated docs, which would add another layer of
complexity.  Are you satisfied? :-)


> 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.

Agreed.


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

This is a bit too deep, we only need a separate to have specific
makefile bits and not clutter Documentation/ nor general/.

John

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