documentation formats

[Graham Percival]

On Wed, Nov 11, 2009 at 05:47:28PM -0500, Kieren MacMillan wrote:
> Werner,
>
>> What's the problem here?
>
> The problem is that I come to Lilypond with a skill set — specifically, 
> many years of Java+Javascript+(X)HTML+XSL(T)+CSS+(La)TeX experience — 
> which should be more than adequate for any modern documentation project 
> involving a WWW component.

If we did stuff in plain html, we'd lose the pdf docs.  If we did
stuff in plain latex, we'd lose the html docs (without a lot of
tweaking).  Both would lose the info docs, which IMO wouldn't be
terrible, but some people seem to like.

I asked for alternate ideas almost a year ago (I think it was
Jan), but after looking at various suggestions, we decided that
texinfo was still the best way to go.

*shrug*

> Oh, wait... I've got to learn yet another markup language (one which I am 
> unlikely to use in any other job/situation in my maoing lifetime), and 
> install a bunch of apps (still in progress, over an hour later?!) before 
> I can even start the [alleged] 2-5 hours of content 
> development/improvement.
>
> I guess what I'm really saying is, if we think the barrier-to-entry for 
> USERS is high, we've got another thing coming re: DEVELOPERS...  =\

As you can see on -devel, I've been trying to make the build
system easier (including only requiring texi2html (perl) and
lilypond-book to make the docs).  But that's *another* highly
non-trivial problem.

> p.s. Hopefully I'm more resilient than others who have come before me — 
> and subsequently dropped off the face of the interwebs, if Graham's "0 
> documentation developers" is accurate —

It's worse, since all of those documentation developers learned
enough texinfo to write docs.  They learned things, and then all
either "graduated" to being developers (which, in the long run, is
not a bad thing at all!), or drifted away, or are unable to work
for various perfectly valid reasons.


But really, if you find yourself wanting to do anything that isn't
already in the same place of that file... we should talk.  For the
benefit of unified presentation /and/ saving your sanity, I
strongly recommend that all you do is copy&paste and change text.
I don't mean @text; only change text that doesn't appear as a
@command.

Cheers,
- Graham