all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* tutorial or guidebook text for some complex topics
@ 2006-10-23 18:35 Drew Adams
  2006-10-23 19:59 ` Stefan Monnier
                   ` (2 more replies)
  0 siblings, 3 replies; 25+ messages in thread
From: Drew Adams @ 2006-10-23 18:35 UTC (permalink / raw)


Suggestion for after the release -

There are a few fundamental data structures that Emacs uses that are quite
complex and variable in form. I'm thinking of things like keymaps (including
menus), font-lock-keywords, and faces/text properties.

These complex structures are generally specified accurately in the Elisp
manual. However, it is not always easy to learn about them by simply reading
such a rigorous specification.

My own experience, at least, bears that out. I've spent quite a bit of time
trying to grasp what these things are and the various forms they can take,
and most of my (still incomplete) understanding of them has come from coding
and examining code that manipulates them.

These structures are complex, with multiple possible cases to consider. They
are not abstract data types with defined accessor functions, so code that
manipulates them must explicitly "parse" them as cons trees, being careful
at each access step.

Personally, I'd prefer to see them treated as ADTs with accessor functions,
but I expect that others will disagree, so I'm not suggesting that change.

What I would suggest is that the documentation be beefed up a little, to
help users understand these critters better. I'd like to suggest that these
topics be dealt with in a tutorial or user-guide manner, with examples to
help people learn what these critters can look like and how to use them.

Adding pedagogical doc for each of these (and there may be some others)
would help, but that doc probably doesn't belong in the Elisp manual, which
is essentially a reference manual. A separate document or documents would
likely be appropriate. An analogy is the Emacs-Lisp Intro book, which leads
you by the hand to learn some Emacs-Lisp. I don't know if that book would
itself be a good target for these topics, or if, instead, a separate
document would be better.

WDOT? Anyone else think that we could use some more explanation for these
topics?

^ permalink raw reply	[flat|nested] 25+ messages in thread

end of thread, other threads:[~2006-10-26  8:52 UTC | newest]

Thread overview: 25+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2006-10-23 18:35 tutorial or guidebook text for some complex topics Drew Adams
2006-10-23 19:59 ` Stefan Monnier
2006-10-23 21:14   ` Drew Adams
2006-10-23 21:46     ` Nick Roberts
2006-10-23 21:58       ` Drew Adams
2006-10-23 22:54         ` Nick Roberts
2006-10-23 23:24           ` Drew Adams
2006-10-24  0:13             ` Nick Roberts
2006-10-24  7:06               ` David Kastrup
2006-10-24  7:44                 ` David Kastrup
2006-10-24 20:46                   ` Drew Adams
2006-10-24 20:45               ` Drew Adams
2006-10-23 23:33         ` Robert J. Chassell
2006-10-24 17:42         ` Richard Stallman
2006-10-24 20:51           ` Drew Adams
2006-10-23 22:08       ` David Kastrup
2006-10-24 17:42       ` Richard Stallman
2006-10-24 23:49     ` Stefan Monnier
2006-10-23 20:01 ` Eli Zaretskii
2006-10-23 21:19   ` Drew Adams
2006-10-24 17:42 ` Richard Stallman
2006-10-24 19:31   ` Drew Adams
2006-10-25 18:03     ` Richard Stallman
2006-10-25 18:21       ` Drew Adams
2006-10-26  8:52         ` Richard Stallman

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.