Subject: [clisp-list] Docbook again

From: Aurelio Bignoli <[email-masked]>
Date: Wed Mar 12 14:01:15 2003

An interesting reply from Norman Walsh:

> From: Norman Walsh <[email-masked]>
> To: Henrik Motakef <[email-masked]>
> Cc: james anderson <[email-masked]>, [email-masked]
> Subject: DOCBOOK: Re: using docbook for CLOS
> Date: Wed, 12 Mar 2003 07:32:23 -0500
> 
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> / Henrik Motakef <[email-masked]> was heard to say:
> | why. Incidentally, I recently started to think about extending docbook
> | to be a better fit for CL documentation, but a) I don't know if it's a
> 
> 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), please tell us how and why.
> 
>                                         Be seeing you,
>                                           norm
> 
> - -- 
> Norman Walsh <[email-masked]>      | 'Heartless Cynics,' the young men
> http://www.oasis-open.org/docbook/ | shout, / Blind to the world of
> Chair, DocBook Technical Committee | Fact without; / 'Silly Dreamers,'
>                                    | the old men grin / Deaf to the
>                                    | world of Purpose within.--W. H.
>                                    | Auden
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.0.6 (GNU/Linux)
> Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>
> 
> iD8DBQE+byjXOyltUcwYWjsRAki4AJ42V07zYOlrbdL43gXuNjC9Wj3wzgCfRWLq
> HnqKnE78RAw15Zio7ZkwB7E=
> =ODjZ
> -----END PGP SIGNATURE-----

---

From: Sam Steingold <[email-masked]>
Date: Wed Mar 12 18:45:12 2003

> * In message <[email-masked]>
> * On the subject of "[clisp-list] Docbook again"
> * Sent on Wed, 12 Mar 2003 17:12:29 +0100
> * Honorable Aurelio Bignoli <[email-masked]> writes:
>
> > 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!

---

From: Paolo Amoroso <[email-masked]>
Date: Thu Mar 13 08:47:14 2003

> > From: Norman Walsh <[email-masked]>
[...]
> > Date: Wed, 12 Mar 2003 07:32:23 -0500
[...]
> > misunderstand something), please tell us how and why.

I seem to remember that Pierre Mai tweaked DocBook to better fit the
documentation needs of the MaiSQL manual. He may--no pun intended--have
some suggestions.

Paolo
-- 
Paolo Amoroso <[email-masked]>