[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: documentation formats
From: |
David Kastrup |
Subject: |
Re: documentation formats |
Date: |
Thu, 12 Nov 2009 07:03:06 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/23.1.50 (gnu/linux) |
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
- Re: Quit [now definitely O/T], (continued)
- Re: Quit [now definitely O/T], Graham Percival, 2009/11/11
- Re: Quit [now definitely O/T], Kieren MacMillan, 2009/11/11
- Re: Quit [now definitely O/T], Graham Percival, 2009/11/11
- Re: Quit [now definitely O/T], Werner LEMBERG, 2009/11/11
- Re: Quit [now definitely O/T], Kieren MacMillan, 2009/11/11
- documentation formats, Graham Percival, 2009/11/11
- Re: documentation formats, Kieren MacMillan, 2009/11/11
- Re: documentation formats, Graham Percival, 2009/11/11
- Re: documentation formats, Jan Nieuwenhuizen, 2009/11/12
- Re: documentation formats, David Kastrup, 2009/11/12
- Re: documentation formats,
David Kastrup <=
- Re: Quit [now definitely O/T], Jan Nieuwenhuizen, 2009/11/12
- Re: Quit [now definitely O/T], David Kastrup, 2009/11/12
- Re: Quit [now definitely O/T], Jesús Guillermo Andrade, 2009/11/12
- Re: Quit [now definitely O/T], David Kastrup, 2009/11/12
- Re: Quit [now definitely O/T], Jesús Guillermo Andrade, 2009/11/12
- Re: Quit [now definitely O/T], David Kastrup, 2009/11/13
- Re: Quit [now definitely O/T], Kieren MacMillan, 2009/11/12
- Re: Quit [now definitely O/T], Jan Nieuwenhuizen, 2009/11/12
- Re: Quit [now definitely O/T], Kieren MacMillan, 2009/11/12
- Re: Quit [now definitely O/T], Jan Nieuwenhuizen, 2009/11/12