RE: Guile in Emacs

["Drew Adams" <drew.adams@oracle.com>]

> > 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.
> 
> It is also important for that information to be available in 
> one place. When the information you need is split between two
> (or more) manuals, a wiki, a HOW-TO and Wonder Tommy's blog,
> it sucks, no matter how well cross-referenced or searchable it is.
> There's a better way and Emacs has it (for the most part).

It is a classic documentation dilemma that you cannot have everything you want
to know about something in a single place. What you want to know about something
is different from what person X wants/needs to know. And what you need to know
today is different from what you need tomorrow.

This is still a problem even if you are dealing with only a single, local manual
that is self-contained as a whole (contains all of the info on its subject). You
might want to see one organization into manual sections and person X might want
to see a different organization. And for you alone, the optimal organization
might be different today (looking for info on some topic) from tomorrow (looking
with a different eye).

IOW, there are *trade-offs*. People dealing with documentation professsionally
deal with such trade-offs everyday - it's a significant part of what they do.

Of course, there are trade-offs that many users might agree are reasonably good
ones, and there are trade-offs that many would agree are poor ones. Picking an
extremely poor documention organization as your example does not invalidate the
fact that trade-offs are always required.

> I've never subscribed to the theory that just because a feature is
> described on some web page out there, and not in the official manual,
> that it's "documented".  Why people want to see this as the success of
> the internet rather than as a failure of the documentation is 
> beyond me.

No one mentioned "some web page out there". You are simply arguing about a straw
man. The point is that Common Lisp has a standard definition (at least one!),
and the language is documented.

To the extent that Emacs supports some or all of that standard to various
degrees, the Emacs documentation needs to:

1. Be clear about that support, specifying which CL standard is supported and
specifying exactly any divergences from that standard.

2. Give clear guidance about any Emacs-specific uses of particular features from
that standard.

That does not imply that the *Emacs* doc needs to reproduce, in addition, a
complete documentation of the standard language that it (more or less) supports.
That's the point of having a standard that can be referenced.

Nothing prevents the Emacs doc from giving examples and explanation of how to
use particular Common Lisp constructs in an Emacs environment. Quite the
contrary.

> Keep the information itself in one place

It's a wonderfully naive idea. Get involved with documenting something
(non-trivial) and you will soon discover the trade-offs. Keeping X "in one
place" begs the question of what X is, how much X encompasses, and what point of
view X is regarded from (audience background, audience quest/need).

> that I can put on a tablet as a PDF, or print out and take with
> me on an overnight.  Not everyone reads their docs from within
> Emacs all of the time.
> 
> For what it's worth.