From: "Drew Adams" <drew.adams@oracle.com>
To: "'Jeff Clough'" <jeff@chaosphere.com>
Cc: 'David Kastrup' <dak@gnu.org>, emacs-devel@gnu.org
Subject: RE: Guile in Emacs
Date: Thu, 15 Apr 2010 09:11:48 -0700 [thread overview]
Message-ID: <7FD4F9AC1DDE4490898CB06959609E96@us.oracle.com> (raw)
In-Reply-To: <m3k4s9udsd.fsf@logrus.localdomain>
> > 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.
next prev parent reply other threads:[~2010-04-15 16:11 UTC|newest]
Thread overview: 127+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <4B8147A9.7030504@gmail.com>
[not found] ` <87ljemdzxo.fsf@stupidchicken.com>
2010-02-23 5:31 ` Next pretest, and branching plans Jason Rumney
2010-02-23 18:29 ` Eli Zaretskii
2010-02-23 21:12 ` Jason Rumney
2010-02-24 6:04 ` Richard Stallman
2010-02-24 13:34 ` Sean Sieger
2010-02-24 15:05 ` Davis Herring
2010-02-24 15:18 ` Sean Sieger
2010-02-24 14:05 ` Chong Yidong
2010-02-25 14:26 ` Richard Stallman
2010-02-26 18:03 ` manuals [was Re: Next pretest, and branching plans] Glenn Morris
2010-02-27 2:32 ` Richard Stallman
2010-02-27 16:52 ` Next pretest, and branching plans Johan Bockgård
2010-03-03 3:52 ` Glenn Morris
2010-03-05 0:31 ` Johan Bockgård
2010-03-05 19:50 ` integer overflow [was Re: Next pretest, and branching plans] Glenn Morris
2010-03-05 22:35 ` integer overflow Stefan Monnier
2010-03-06 2:55 ` Glenn Morris
2010-03-06 3:11 ` Chong Yidong
2010-03-06 7:03 ` Helmut Eller
2010-03-06 15:45 ` Stefan Monnier
2010-03-06 16:23 ` Davis Herring
2010-03-06 16:33 ` Drew Adams
2010-03-07 7:52 ` Richard Stallman
2010-03-07 16:06 ` David Kastrup
2010-03-07 17:18 ` Stephen J. Turnbull
2010-03-07 17:42 ` David Kastrup
2010-03-08 4:49 ` Jay Belanger
2010-03-08 8:04 ` Richard Stallman
2010-03-08 14:41 ` Guile in Emacs (was: integer overflow) Ted Zlatanov
2010-03-08 17:32 ` Guile in Emacs Ted Zlatanov
2010-03-08 18:42 ` Guile in Emacs (was: integer overflow) Chad Brown
2010-03-09 7:07 ` Ken Raeburn
2010-03-09 16:22 ` Guile in Emacs Ted Zlatanov
2010-03-10 8:07 ` Ken Raeburn
2010-03-10 13:58 ` David Kastrup
2010-03-09 3:19 ` Guile in Emacs (was: integer overflow) Richard Stallman
2010-04-11 23:33 ` Thomas Lord
2010-04-12 12:30 ` Richard Stallman
2010-04-12 20:05 ` Thomas Lord
2010-04-13 12:44 ` Guile in Emacs Bruce Stephens
2010-04-13 15:51 ` Thomas Lord
2010-04-13 16:07 ` Stefan Monnier
2010-04-13 18:56 ` Thomas Lord
2010-04-13 19:22 ` Christian Lynbech
2010-04-14 10:14 ` Bruce Stephens
2010-04-14 14:10 ` joakim
2010-04-13 19:13 ` Christian Lynbech
2010-04-14 1:47 ` Thomas Lord
2010-04-14 3:33 ` Christian Lynbech
2010-04-14 23:33 ` Richard Stallman
2010-04-14 5:02 ` Richard Stallman
2010-04-14 6:45 ` christian.lynbech
2010-04-14 19:07 ` Thomas Lord
2010-04-14 19:34 ` Bruce Stephens
2010-04-14 20:09 ` Jose A. Ortega Ruiz
2010-04-15 7:34 ` christian.lynbech
2010-04-14 23:33 ` Richard Stallman
2010-04-15 3:52 ` Drew Adams
2010-04-15 6:01 ` David Kastrup
2010-04-15 6:54 ` Drew Adams
2010-04-15 11:59 ` Jeff Clough
2010-04-15 12:49 ` christian.lynbech
2010-04-15 13:54 ` Jeff Clough
2010-04-15 14:03 ` Lennart Borgman
2010-04-15 16:13 ` Drew Adams
2010-04-16 13:48 ` Jeff Clough
2010-04-16 14:03 ` christian.lynbech
2010-04-16 14:25 ` Jeff Clough
2010-04-16 14:25 ` Drew Adams
2010-04-16 14:39 ` David Kastrup
2010-04-16 14:40 ` Jeff Clough
2010-04-16 8:27 ` christian.lynbech
2010-04-17 4:41 ` Richard Stallman
2010-04-19 7:52 ` christian.lynbech
2010-04-16 22:29 ` Emacs Info manuals (was: Guile in Emacs) Juri Linkov
2010-04-15 16:11 ` Drew Adams [this message]
2010-04-15 7:21 ` Guile in Emacs christian.lynbech
2010-04-15 7:36 ` David Kastrup
2010-04-15 8:34 ` christian.lynbech
2010-04-15 9:06 ` David Kastrup
2010-04-15 9:45 ` Helmut Eller
2010-04-15 10:39 ` christian.lynbech
2010-04-15 18:47 ` Richard Stallman
2010-04-15 22:42 ` Harald Hanche-Olsen
2010-04-15 22:50 ` Harald Hanche-Olsen
2010-04-17 4:40 ` Richard Stallman
2010-04-15 23:02 ` Helmut Eller
2010-04-17 4:40 ` Richard Stallman
2010-04-17 6:46 ` Helmut Eller
2010-04-17 19:55 ` Richard Stallman
2010-04-14 13:30 ` John Wiegley
2010-04-14 14:18 ` Helmut Eller
2010-04-14 15:40 ` Tom Tromey
2010-04-14 7:51 ` David Kastrup
2010-04-14 8:42 ` christian.lynbech
2010-04-14 9:55 ` immanuel litzroth
2010-04-14 10:28 ` christian.lynbech
2010-04-14 11:25 ` Stephen J. Turnbull
2010-04-14 12:26 ` christian.lynbech
2010-04-14 16:49 ` Ken Raeburn
2010-04-14 18:29 ` Tom Tromey
2010-04-14 20:02 ` Ken Raeburn
2010-04-14 11:23 ` Jeff Clough
2010-04-14 13:11 ` Stephen J. Turnbull
2010-04-14 13:11 ` Stephen Eilert
2010-04-14 13:49 ` Helmut Eller
2010-04-14 15:47 ` Tom Tromey
2010-04-14 16:41 ` Drew Adams
2010-04-14 20:10 ` David De La Harpe Golden
2010-04-15 10:38 ` Leo
2010-03-06 19:04 ` integer overflow Helmut Eller
2010-03-06 21:26 ` Stefan Monnier
2010-03-07 7:51 ` Richard Stallman
2010-03-07 19:05 ` Johan Bockgård
2010-03-06 20:35 ` Chong Yidong
2010-03-13 3:10 ` Next pretest, and branching plans Christoph
2010-03-13 7:42 ` Eli Zaretskii
2010-03-13 14:54 ` Christoph
2010-03-13 18:30 ` Stefan Monnier
2010-03-13 19:06 ` Eli Zaretskii
2010-03-14 2:38 ` Jason Rumney
2010-03-14 2:50 ` Christoph
2010-03-14 3:07 ` Jason Rumney
2010-03-14 17:55 ` Eli Zaretskii
2010-03-17 0:29 ` Christoph
2010-03-17 4:14 ` Eli Zaretskii
2010-03-17 12:44 ` Jason Rumney
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7FD4F9AC1DDE4490898CB06959609E96@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=dak@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=jeff@chaosphere.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.