Re: documentation formats

[David Kastrup]

Graham Percival <address@hidden> writes:

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

Emacs as an editor is enough of a suggestion for developers that the
question "how do I indent code?" is answered "as lilypond-mode does".
Navigating through info is much faster and more direct than through HTML
which is one of the main reasons Emacs (and GNU) never switched to
something else.

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

git uses Asciidoc which outwardly looks less intimidating and more
directly readable (and can produce man pages as well).  But both the
resulting XML/Docbook layer as well as the Asciidoc translator are
lousily documented.  I've had quite a bit a problem with those.

HTML directly misses too much structure and information which is nice to
have in some hypertext readers.

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

Really, Texinfo is a better choice than some other popular options
because it is reasonably well maintained and documented.  It means
people can come along and have a chance of learning things without
external help.  Or with.  And it's clear enough to mostly
fly-by-example.

-- 
David Kastrup