bug#12233: 24.1.50; Please index "sexp" in Elisp manual

bug#12233: 24.1.50; Please index "sexp" in Elisp manual

[Drew Adams]

1. The concept "sexp" is not indexed as such in the Elisp manual.
Please add an index entry for "sexp", which targets node `Intro Eval'.
 
2. I find it misleading that that node, in introducing the terms
"S-expression" and "sexp", also says: "but we generally do not use this
terminology in this manual."
 
The term "sexp" is used throughout Emacs Lisp, including in the names
and doc strings of multiple functions.
 
If you really choose to de-emphasize its use in explanations in the
manual, fine.  But don't point that out, at least using such language,
because it can easily give the impression that Emacs Lisp does not use
the term "sexp", which is plain wrong.
 
It is also not even true that "we generally do not use this terminology
in this manual."  Just search for "sexp" and you will see.  There are
two occurrences of "sexp" in the main menu alone!  There are 89
occurrences of "sexp" in the manual (as well there should be).
 

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-08-13 on MARVIN
Bzr revision: 109584 monnier@iro.umontreal.ca-20120813141247-76irjqslrfncn30u
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'
 

bug#12233: 24.1.50; Please index "sexp" in Elisp manual

[Drew Adams]

> 1. The concept "sexp" is not indexed as such in the Elisp manual.
> Please add an index entry for "sexp", which targets node `Intro
> Eval'.

Actually, perhaps node `Simple Types' is more appropriate.  Or perhaps both
nodes should be targeted.

In `Simple Types' we see that a sexp is not just a syntactic expression (e.g.
buffer/program text), but it is "any _Lisp object_ that can be printed and read
back."  This is important and not necessarily generally understood, particularly
by those new to Lisp.

"Sexp" _is_ sometimes, as in `backward-sexp', used also to refer to a textual
expression in a program (e.g. buffer text).  This is a terminological shortcut,
as is `up-list' etc. - such functions move point over program text that
_represents_ a sexp, a list, etc.

Even Wikipedia is a bit confusing on this point, saying that "Lisp uses
S-expressions as an external representation for data and code.  S-expressions
can be read with the primitive Lisp function READ."  As opposed to sexps _being_
Lisp objects.  [http://en.wikipedia.org/wiki/Homoiconicity]

And it says that "sexps... are a _notation_ for nested list (tree-structured)
data...".  http://en.wikipedia.org/wiki/S-expressions  As opposed to _being_
such data/programs.

But Wikipedia does also point out that sexps can be both: it speaks of "data
s-expressions" and "source code s-expressions".  It says that Lisp, unlike some
other languages, "uses [sexps] for source code as well as data".

And Wikipedia is clearer wrt "symbol" - it makes clear that a symbol is a sexp,
and it says, "When Lisp reads data that contains textual represented symbols,
existing symbols are referenced."  Which distinguishes symbols as textual
representation of symbols as Lisp objects.

Because of this double usage, it is important to make it clear that `sexp' does
have the main meaning as being a Lisp object, just like a number, list, or
string. It is all the more important because its name calls out "expression",
which is sometimes understood as program text.

Another place where it should be made clear that "sexp" refers to a Lisp object
and not program source text is for a function such as `sexp-at-point'.  The doc
string says only this:

 "Return the sexp at point, or nil if none is found."

But that just begs the question.  The doc string should explicitly point out
that the buffer text at point is _read_, producing a Lisp object, which is what
is returned.  E.g. if the sexp at point is (foo bar), then the return value
satisfies `listp', not `stringp'.


[Note, Common Lisp avoids the terms "sexp" and "S-expression".  "Sexp" and
"symbolic expression" do not appear at all in "Common Lisp The Language 2".
"S-expression" appears there only in two places (two pages out of ~1100): (1)
when describing ~S for function `format', (2) when discussing the implementation
of macro `backquote', where the term is used to refer to expressions as Lisp
objects.  And it uses the term "expression" in both senses (textual expression
to be parsed/read and Lisp object), but perhaps more often in the sense of Lisp
object.

CTTL2 also uses "form", which it defines as "a data object meant to be evaluated
as a program to produce one or more values (which are also data objects). One
may request evaluation of any data object, but only certain ones are meaningful.
For instance, symbols and lists are meaningful forms, while arrays normally are
not...  Meaningful forms may be divided into three categories: self-evaluating
forms, such as numbers; symbols, which stand for variables; and lists."]

bug#12233: 24.1.50; Please index "sexp" in Elisp manual

[Chong Yidong]

Done in trunk, thanks.