Re: [Sbcl-devel] proposal: Yet Another Documentation Format Change

[William H. N. <wil...@ai...>]

On Wed, Mar 24, 2004 at 02:20:05PM +0100, Rudi Schlatte wrote:
> So, I was starting to port the debugger chapter of the cmucl manual to 
> sbcl, and became aware of a few things:
> 
> - With all of DocBook's kajillion tags, function definitions in the 
> sbcl manual are still wrapped in simple <synopsis></synopsis> tags, 
> with the explanation body as simple <para> elements afterwards.  And 
> some amount of browsing "DocBook: the Definitive Guide" didn't help me 
> find a better way to sanely mark up a function documentation.

I have also been surprised to find how clumsy the huge tagset can be
for plausible-sounding tasks. I suspect that to some extent this is a
fundamental consequence of how ontologies are harder to write and
maintain than almost anyone realizes until they try to do it, so
semantic markup is naturally clumsier than it seems it ought to be.
But maybe either a better design at the same level, or a design which
gave up on some of the ambitions about semantic markup, could be
easier to work with. (I don't know enough about texinfo to have an
opinion about the specific comparison to it.)
 
> - Editing DocBook is unfun; I got stuck halfway through the chapter.

Granted it's unfun, but for me it's not that much of an obstacle
compared to the unavoidable difficulties of writing useful text and
keeping it up to date. From what I've heard from other people on this
project and others, I'd guess that no one loves it but your reaction
to it is rather more intense than usual.

> This is contrary to my recent experiences with texinfo 
> (http://constantly.at/lisp/asdf/ and 
> http://constantly.at/lisp/asdf-install/): editing these was a pleasure; 
> the markup didn't get in the way, the results were half-decent looking 
> (both pdf and html, and I didn't even start playing with css), and the 
> tools were already installed and working.
> 
> Now, texinfo has its weak spots (no support for graphics, the tag set 
> is somewhat geared towards Emacs and the elisp manual), but the sbcl 
> manual doesn't have graphics anyway, and, well, documenting a Lisp 
> system is what we (I) want to do here anyway.  (Besides, makeinfo can 
> produce basic xml or docbook output, too.)
> 
> I'd like to volunteer translating the manual into texinfo.  Are there 
> any reasons not to?

Your volunteering offer does a lot to overcome any resistance that
would follow from sheer inertia, but I'm still pretty skeptical about
the idea. Besides my remarks above,
  -- I find it comforting that apparently DocBook is a usable format for
     writing complete books. My impression is that it would be awkward
     to do that in texinfo.
  -- My impression is that DocBook is more widely used. (This isn't
     actually much of an argument against texinfo, since it's also
     sufficiently widely used that it should be reasonably convenient.
     It's more an argument against some hypothetical third choice
     which might come up.)

On the other hand, there's one argument against DocBook which you
didn't mention except in passing ("tools were already installed and
working"). My biggest frustration with DocBook is that the tools
required to translate it are so elaborate and fiddly that it seems to
be hard to make it completely routine to build it. It seemed to take a
long time before it became mostly routine to be able to build DocBook
on major distributions, and even now de facto portability requires a
lot of knowledge of OS-dependent file locations. I don't think the
SBCL manual requires anything but the plainest, most vanilla DocBook,
so I would've hoped that building it could be as simple (from the
end-user point of view, after the OS maintainers finish setting up all
the file locations) as the analogous LaTeX "latex manual.tex".
Instead, DocBook "hello world" seems to involve our doc/Makefile and
doc/catalogs/*.xml, >100 lines of stuff to hack on (which at the
moment happens to need some kind of hack to autodetect and handle the
OS=debian-old case which exists on my laptop).

I'm pretty sure that I could work with either system; I don't see
killer advantages one way or another. Your strong negative reaction to
DocBook could be considered a killer advantage, of course, and if
other developers have had similar reactions before but just didn't
speak up, they'd probably convince me to switch if they start speaking
up now. But just from what I've seen and heard so far -- and guessing
that the other developers mostly don't find the DocBook they know to
be much more frustrating than the texinfo they know not of -- my
inclination is to remain with DocBook despite your offer to convert to
texinfo.

(Two more arguments to try if you're sufficiently frustrated: (1) find
a multideveloper project or two which switched to texinfo and has
written up a summary of why in retrospect it was a good decision,
and/or (2) convert 200 lines or so of text more or less cribbed from
the existing manual from DocBook to texinfo, with
foo-in-texinfo.texinfo, foo-in-docbook.xml,
foo.html-as-converted-by-texinfo, foo.html-as-converted-by-docbook,
and possibly some other output format you think would be convincing;
then send the resulting wouldnt-you-rather-work-with-texinfo.tar file
to the list.)

-- 
William Harold Newman <wil...@ai...>
to make it simpler, he cut out lots of ono-essential stuff
  -- dan_b explaining SBCL on #lisp
PGP key fingerprint 85 CE 1C BA 79 8D 51 8C  B9 25 FB EE E0 C3 E5 7C