proposal for doc+web sources

[Graham Percival]

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