RE: Guile in Emacs

[Drew Adams]

> >> Common Lisp has sooo much to document.  The Emacs Lisp Manual would
> >> get a lot bigger if it had to include the specs of so many 
> >> functions.
> >
> > The Elisp manual would not need to document things that are vanilla
> > Common Lisp (i.e. respect the CL standard). It could simply
> > cross-reference the relevant CL doc. The Elisp manual would need to
> > document only extensions or departures from the standard. 
> > It does not need to reproduce all of the existing CL documentation.
> 
> The manuals of an editor with a user-accessible extension 
> language (with Emacs, this is the case for Elisp but not
> for C) need to document this extension language.

Emacs needs to document its extension language, yes of course. That means that
it needs to enable users to obtain complete documentation about the language.
That does not mean that the Emacs manuals (e.g. Elisp manual) themselves need to
specify everything about CL functions Emacs might support. It simply means that
Emacs needs to provide users access to that information.

A cross reference can be focused directly to an appropriate section of existing
Common-Lisp documentation. We need not just dump a user into the TOC of a large
manual.

It is a choice whether we want clicking a cross-reference in an Emacs manual to
take you (a) to a section of the same manual or another manual available locally
or (b) to a section of a manual that might be on the Web. A cross reference
might well be to a non-local or a non-GNU manual or specification. What is
important is that we give users access to the specific info they need.

> Otherwise, only programmers can be expected to be able to use it.  One
> reason for that is that non-Emacs specific Lisp manuals will not focus
> about how to get things done with Emacs.  Applying a manual utterly
> without editing focus to editing tasks is quite a large intellectual
> feat.

The Emacs manual(s) will of course focus on how to get things done with Emacs.
If there is something Emacs-specific to be said about a function such as `some',
then yes, the Emacs manuals are an appropriate place to say that. That does not
imply that everything possible to be said about every Common-Lisp construct
needs to be covered in the Emacs manual. That would be an absurd approach.