Re: [clisp-list] Docbook again

[Sam S. <sd...@gn...>]

> * In message <159...@da...>
> * On the subject of "[clisp-list] Docbook again"
> * Sent on Wed, 12 Mar 2003 17:12:29 +0100
> * Honorable Aurelio Bignoli <a.b...@co...> writes:
>
> An interesting reply from Norman Walsh:
> > 
> > I think CL documentation fits squarely in DocBook's problem
> > domain. If DocBook's not rich enough to document CLOS (or CLisp, or
> > maybe I misunderstand something),

DocBook is good enough for CLISP.

> > please tell us how and why.

My only problems with docbook are:

1. BNF is not standard.  IIUC, one needs to go through special hoops to
   get EBNF to work, and DSSSL does not support it (XSL, apparently,
   does).  There are quite a few places in impnotes were we use tables
   instead of BNF.  It would be nice if someone volunteered to convert
   those tables to EBNF and DSSSL to XSL.

2. It is non-trivial to convert it to plain text (like texinfo).

3. One cannot define "local entities" (i.e., abbreviation for locally
   frequent forms).  E.g.:

Function EXT:RE-EXPORT

The function (EXT:RE-EXPORT FROM-PACK TO-PACK) re-exports all external
symbols from FROM-PACK also from TO-PACK, provided it already uses
FROM-PACK; and SIGNALs an ERROR otherwise.

   DocBook source:

<section id="re-export"><title>Function &re-export;</title>

<para>The function <literal role="sexp"
 >(&re-export; <replaceable>FROM-PACK</replaceable>
               <replaceable>TO-PACK</replaceable>)</literal>
 re-exports all external symbols from
 <replaceable>FROM-PACK</replaceable> also from
 <replaceable>TO-PACK</replaceable>, provided it already uses
 <replaceable>FROM-PACK</replaceable>; and &signal;s an &error-t; otherwise.
</para></section>

   this would look much better if I could just write

<section id="re-export"><title>Function &re-export;</title>
(let ((from-pack "<replaceable>FROM-PACK</replaceable>")
      (to-pack "<replaceable>TO-PACK</replaceable>"))
<para>The function <literal role="sexp"
 >(&re-export; &from-pack; &to-pack;)</literal>
 re-exports all external symbols from &from-pack; also from
 &to-pack;, provided it already uses &from-pack;;
 and &signal;s an &error-t; otherwise.
</para>)</section>

   the frequently used idioms, like <replaceable>number</replaceable>,
   are already global entities defined in impent.xml.
   what about idioms that are frequently used in an isolated part of
   the document?

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat8 GNU/Linux
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.palestine-central.com/links.html>
Computers are like air conditioners: they don't work with open windows!