On Thursday, 12 August 1999, Werner LEMBERG writes:
> to become more intimate with LilyPond, I've revised
> reference-manual.yo completely -- well, I haven't added more info to
> it, but I tried to improve its appearance -- it now looks quite nice
> in both DVI and HTML format.
Thanks, I'll have a look. Btw, you should make a unified diff and
send that, rather than the new file, ie, do something like:
diff -u refman.yo-1.2 refman.yo > refman.diff
Changes are always examined carefully before they're applied.
> Nevertheless, a lot of examples still look bad, and I don't know how
> to improve them (or rather not interested in reading source code).
> Most notably, the spacing in some code snippets is extremely bad. So
> please fix this.
Which ones? (Add a comment or TODO list in refman.yo)
> PS: Why don't you use texinfo to document lilypond. What was the
> reason for choosing yodl?
To be frank, we've found the Yodl documentation to be a pain in the neck.
It's cost us (esp me) a lot of development time that should have gone
into Lily. We're looking for a better solution, and plan to drop Yodl
from Lily real soon now.
Producing documentation (for Lilypond) has been too much of an issue,
mainly because
* We need to include (LilyPond-)generated examples.
* We want to support quite some doc formats, and generate them
from one source language:
- latex for high quality hard copy; include .ps images
- html for www, and to provide searchable doc; include .png images
- plain text for README, INSTALL etc.
- texinfo for structured, well searchable doc; no images
- unix man format; for executables only, no images
At the time (we'll have to check again)
* Latex2html was no option for producing fine html output from latex.
* Producing plain text from latex source seems near to impossible too
(if you can't use lynx).
* Texinfo2html was not available (how good is it now?).
* We had Perl's pod2* scripts for producing man pages/html/text but:
- we decided to drop Perl in favour of Python (Python is not a read
only language, imho)
- perl 5.x's pod2* tools were broken
So, Yodl seemed to be the perfect solution. A converter for new output
formats can be added quite easily (yodl2texinfo).
Problems with Yodl
* Not standard. Yodl is not in major distributions/it is not being
used by (many) developers. This is bad, because it makes Lily
dependent on an obscure tool (Lily may not be in RedHat because of
this), and we've got to do virtually all maintenance ourselves.
* Badly implemented:
- Buggy. Far less robust than expected when we evaluated it at first.
Lots and lots of bugs have been fixed already, but we expect new bugs
to crop up.
- Slow. There are ideas, and there have been attempts to fix this,
but we won't put any major development time into yodl anymore.
- It's all macros, and Macro Languages Suck (TM).
- It's still hairy to get all output formats to look good. In
particular, producing high quality latex source is difficult.
* Although the Yodl language itself has some nice ideas, it has awkward
things too. Maintaining/developing a good documentation package
is a lot of work. Lots of features are still missing.
* Mudela support in the Yodl language now seems to be a bad solution.
The mudela-book script is a much faster and cleaner solution to
produce latex with lilypond examples. It should be easy to learn
mudela-book about html.
Alternatives and issues
Whatever source documentation language(s?) we'll choose, we'll probably
have to do some mudela-book preprocessing to handle embedded mudela.
* Preprocess to texinfo
- how good is texinfo2html
- where is texinfo2tex
- is texinfo2dvi an option for producing high-quality hard copy doco
(ie, is it better than yodl2latex?)
- awkward typing?
- manual node structure maintenance or be forced to use emacs?
- node names cannot contain , : . ? ! \ ' ` { } -- ---
- how to generate unix manual pages?
* Preprocess to latex
- quality/availability of latex2html
- how to generate texinfo docs?
- how to generate unix manual pages?
* Preprocess to sgml
- use of favourite text editor / docbook / need to type <bla>text</bla>?
- speed?
- problems with sgmltools-2.0:
- sgml2texinfo and sgml2man were dropped. To quote Cees de Groot
(sgmltools maintainer):
Well, err, there is this new format, HTML, that makes info a tad
obsolete. There's this even newer format, XML, that will make
info very obsolete this year...
[..]
Info is dead.
duh.
- sgmltools is about to be abandoned by Cees de Groot, what will the
quality of maintence be in the future?
- development of an independent sgml2texinfo converter was started,
but:
- not standard
- quality/maintenance?
- it uses perl: we'd reintroduce the perl dependency
- not included in major distributions, probably because of these
problems
Ideas?
Jan.
Jan Nieuwenhuizen <[EMAIL PROTECTED]> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien/ | http://www.lilypond.org/
