Here's my proposal for the source/makefile view of documentation. (this is the big argument one)
My understanding is that linking between texinfo manuals is easier if the main files are in the same directory. With that in mind, I propose: docs/ docs/learning.tely docs/learning/*.itely docs/notation.tely docs/notation/*.itely + glossary, essay, application docs/snippets.tely (moved from input/lsr/ and input/new/) docs/snippets/*.ly docs/contributors.texi docs/contributors/*.texi docs/web.texi docs/web/*.itexi docs/topdocs/ docs/topdocs/changes.texi docs/topdocs/compile.texi regression/ new location of input/regressions/ input/ completely deleted - yes, I propose putting web in with the other documentation. As I said, my understanding is that this makes linking between documents easier. Yes, that could be fixed with some @rManualName{} trickery. I'm not in a position to judge how tricky this would be, because whatever gets decided, I'm not making the build scripts for this. How much cross-referencing do we want? Probably not a huge amount, but enough that is could be a pain. Web->Manuals links to every manual, of course. The FAQ -- which might live as part of manuals.itexi in manuals, or as a separate manual in docs/ -- wants to link to the LM, website, and AU. Quite possibly other items, too. The AU will probably want to link to certain pages on the website. LM probably also wants to link to parts of the website (Community->Contact ->Tiny examples, and maybe ->Bug reports). There are other considerations: I'd like to include the authors and THANKS file in Community->Authors. I suppose we could move all the author bios into a separate branch... but what about the THANKS file? I _guess_ we could hack up a git checkout, so whenever you built the docs in a separate web/ repository, it would get the latest THANKS from the separate lilypond.git repository... but this sounds ridiculous to me. Ditto for the Changes manual (the renamed NEWS) and FAQ. The master copy of this obviously needs to be in the source, but that means that we either distribute these as fully distinct manuals (a one-page lilypond-faq.pdf ?), or do some weird hackery to include it in the build process of a separate website repository. I know that there's some concerns about people accidently screwing up the website and having it show up in an hour. I've never been quite certain why we have an automatic hourly rebuild -- we don't update the website all that often. We could disable that for a few months, see how often people screw up the website and go with a script to upload the generated website, then re-evaluate the situation. Or we could have a separate repo and some weird build process hackery. To be honest, I'm completely sick of this particular debate. As long as the user's view (proposed in separate email) makes sense and I don't need to do the build stuff, I don't care whether the web ends up in a separate repo or merged into master. Hmm, I just identified one problem in my glorious vision of mutual co-operation after a merge: which set of manuals would current HEAD point to? I mean, we'd want the Manuals page to point to 2.12.3, and the Community->Development manuals to point to 2.13.4... but having them in the same source tree doesn't really help that problem. I guess we could have a different makefile target to specify building the web/ as the main website, versus building web/ as a local info, pdf, or html file. In "local" mode, the links in Manuals would point to whatever the rest of the docs were, whereas in "web" mode, they'd point to the appropriate stable/devel versions. Whatever. I think the documentation/usage goal of more integration between the docs and website is sound. I'm now less certain about the best technical implementation of that idea, but as long as the usage goal is met, I won't complain any more. - Graham PS if I wasn't going to be writing content, organizing volunteers, and making releases, I *would* be offering to do the build system and/or scripts. I wrote all the CMake[1] build stuff for Marsyas (an audio analysis + synthesis program, not as complicated as lilypond due to no translations, but trivial either). I'm not a complete jerk. :) [1] last summer, I decided on CMake because it had the most readable / easiest-to-use build system. I went back and glanced at it again, and I still think the readability is good. However, I don't recommend it for lilypond; their lack of documentation (they sell a hard-copy book) was _very_ annoying. That was my first bad experience with "open-source the software, sell support". - Graham _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel