Re: translation of :documentation to loom

James Rice <>
Date: Mon, 4 Jul 1994 12:27:57 PDT
From: James Rice <>
Subject: Re: translation of :documentation to loom 
In-reply-to: Your message of Mon, 4 Jul 94 12:36:01 +0200 
Message-id: <CMM.0.88.773350077.rice@hpp.Stanford.EDU>
> Hi,
>   I'm wondering why the translation of :documentation has moved into
> the :annotation part of the respective loom construct. Any reason?
> I'd prefer to translate it to the normal documentation string of Loom.
> Bye
> Gerd

Well, ... There is a good reason for it, but you may not
agree.  The problem is that LOOM doesn't store the doc
strings in a manner that is regular wrt the rest of the
knowledge base and simply uses the VARIABLE (or maybe
FUNCTION, I can't remember) documentation type to store the
doc string within the Lisp image.  This assumes that every
LOOM concept/relation that has documentation will be named
by a symbol and that that symbol will be unique, i.e. no
distinct concepts/relations in different KBs/contexts with
the same name.  This is particularly losing for Ontolingua
because Ontolingua says such a lot of things and has such
verbose docstrings about already extant symbols in the Lisp
package.  It's totally rude to overwrite the doc string for
(say) the LISP function LIST with the ontolingua doc string.

There is a clear tension here between doing the right thing
and ending up being well integrated with the underlying
lisp.  In right thing to do would be to store the doc
strings somewhere in a manner that would make them
constistent with the representation and then define a
documentation method that extracts the doc string
appropriately given an object in that representation scheme.
Obviously this is trivial if you call (documentation
|R|foo), but in LOOM you want to be able to use the
emacs doc command to get the doc string when all you have is
the symbol that names the concept/relation.  You can always
define a method that is eql specialized on (say)
'loom-relation, but this won't work in general because CL
has not done the right thing.  There is no portable way to
interrogate a Lisp about the different doc types, and the
documentation commands provided in the emacs interfaces
usually use a fixed quoted doc type to look up (typically
FUNCTION and/or VARIABLE).  The Loom implementors have taken
the path of least resistence.  They want doc strings to
work, but they understandably don't want to have a major
portability nightmare.  Ontolingua also wants doc strings to
work, but it's important to ontolingua not to do anything
that will damage other things that are resident in the
system.  It is after all a tool that's supposed to be able to
translate into different (presumably memory-resident)
implementations.  Thus, we have decided to be very careful
about trying not to break other things.

There's nothing technically difficult about emitting
docstrings in the normal LOOM manner for the LOOM back end,
but it's not clear to me that it's a good thing to do.

I guess we could put in a switch.  Sigh.