Re: Documentation/essay/

[John Mandereau]

2009/7/9 Graham Percival <address@hidden>:
> Is anybody familiar with the monstrosity that is the
> makefiles/stepmake build system in LilyPond?
>
> I've split the essay away from LM 1, because it never belonged
> there, and the website redesing had a nice place for it on its
> own.  I hacked up the GNUmakefile until it compiled, but I'm not
> certain I did it right.

Didn't you plan that the final place of the essay be on the main web site?
Oh well, it's all right for me if it's in the documentation.



> 1)  Could you check Documentation/GNUmakefile,
> Documentation/user/GNUmakefile, and
> Documentation/essay/GNUmakefile?

macros.itexi and fdl.itexi must not be copied, appropriate -I flag for
lilypond-book and texinfo processors should be used instead.

essay/GNUmakefile is dirty with lots of commented out stuff; source
files should generally not be committed to Git like this, next time please
send a patch (even a simple one made with "git diff" is fine) before
committing.

Documentation/user/GNUmakefile has not been cleaned up.

IMO, an .itely file that contains all the actual contents is superfluous,
it should be merged

Finally, although I agree with splitting the essay out from the Learning
Manual, I don't see the point of creating a new directory for it, it
could go to Documentation/topdocs instead.



> 2)  Once that's done, I'll split off the other manuals, so that we
> only have one manual per directory.

WTM do you want to have one manual per directory? I agree it
would make clearer which master .tely file each .itely files belongs
to, but I see no other reason, so this would be much work for little
gain. Could you motivate this change, so that I consider accepting
to take over the implied work on makefiles?

I'm so sick and tired of hacking makefiles that I seriously consider
trying scons to build the website, which would make a first try before
possibly switch to it for LilyPond too (if it is allowed by GNU); so
unless there is any urgent need to massively split directories, I'm
not keen on supporting this right now.



> 3)  How would separate files affect cross-linking?  And do we want
> to put any shared files (macros?) in Documentation/, instead of
> copying them around all the time?

Cross-linking would be just a little hairier. And how would you name
subdirectories for splitted HTML manuals? Would we end up with
Documentation/notation/notation? :-P



> 4)  How does this affect the translation infrastructure?

All the work of splitting directories would have to be redone for the
translations makefiles.

Best,
John