Since one of the Release goals is proofing the manuals, I'm sending this here,
rather than the bug-lisp-manual. I've attached a patch to intro.texi and the
Changelog, but I'm going to inline the intro.texi part and make some comments,
so that a commiter can decide which parts to apply.
I tried to avoid simply stylistic issues. The only repeated change I made was adding
"notation, " index entries for each of the notation types, so that they will be listed
together in the index in the 'n' section.
! In Lisp, the symbol @code{nil} has three separate meanings: it
is a symbol with the name @samp{nil}; it is the logical truth value
@var{false}; and it is the empty list---the list of zero elements.
When used as a variable, @code{nil} always has the value @code{nil}.
--- 175,181 ----
@cindex boolean
@cindex false
! In Lisp, the symbol @address@hidden has three separate meanings: it
is a symbol with the name @samp{nil}; it is the logical truth value
@var{false}; and it is the empty list---the list of zero elements.
When used as a variable, @code{nil} always has the value @code{nil}.
==> nil is defined here, but there was no dfn.
***************
*** 197,203 ****
(not
nil)
; @r{Emphasize the truth value @var{false}}
@end example
! @cindex @code{t} and truth
@cindex true
In contexts where a truth value is expected, any address@hidden value
is considered to be @var{true}. However, @code{t} is the preferred way
--- 197,203 ----
(not
nil)
; @r{Emphasize the truth value @var{false}}
@end example
! @cindex @code{t}, uses of
@cindex true
In contexts where a truth value is expected, any address@hidden value
is considered to be @var{true}. However, @code{t} is the preferred way
==> Make this index entry consistent with nil entry
***************
*** 209,222 ****
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
to use them as constants in a program. An attempt to change their
! values results in a @code{setting-constant} error. The same is true of
! any symbol whose name starts with a colon (@samp{:}). @xref{Constant
Variables}.
A Lisp _expression_ that you can evaluate is called a @dfn{form}.
Evaluating a form always produces a result, which is a Lisp object. In
--- 209,223 ----
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
to use them as constants in a program. An attempt to change their
! values results in a @code{setting-constant} error. @xref{Constant
Variables}.
A Lisp _expression_ that you can evaluate is called a @dfn{form}.
Evaluating a form always produces a result, which is a Lisp object. In
==> Remove sentence about variables starting with ':', since that is irrelevant
==> to this node, and it is in the referenced node anyway.
==> Added index entries so that all of the notations will be listed together
==> in the index
***************
*** 252,257 ****
--- 253,259 ----
@node Printing Notation
@subsection Printing Notation
@cindex printing notation
+ @cindex notation, printing
Many of the examples in this manual print text when they are
evaluated. If you execute example code in a Lisp Interaction buffer
==> Added index entries so that all of the notations will be listed together
==> in the index
***************
*** 262,269 ****
Examples in this manual indicate printed text with @address@hidden,
irrespective of where that text goes. The value returned by
! evaluating the form (here @code{bar}) follows on a separate line with
! @address@hidden
@example
@group
--- 264,271 ----
Examples in this manual indicate printed text with @address@hidden,
irrespective of where that text goes. The value returned by
! evaluating the form (in the example below: @code{bar}) follows on a
! separate line with @address@hidden
@example
@group
==> The first time I read this I thought the "form" was (here @code{bar}), so I
==> reworded to make it more apparent that 'here' was not a made up function
==> name for the example.
***************
*** 277,282 ****
--- 279,285 ----
@node Error Messages
@subsection Error Messages
@cindex error message notation
+ @cindex notation, error message
Some examples signal errors. This normally displays an error message
in the echo area. We show the error message on a line starting with
==> Added index entries so that all of the notations will be listed together
==> in the index
***************
*** 291,296 ****
--- 294,300 ----
@node Buffer Text Notation
@subsection Buffer Text Notation
@cindex buffer text notation
+ @cindex notation, buffer text
Some examples describe modifications to the contents of a buffer, by
showing the ``before'' and ``after'' versions of the text. These
==> Added index entries so that all of the notations will be listed together
==> in the index
***************
*** 355,365 ****
arguments default to @code{nil}). Do not write @code{&optional} when
you call the function.
! The keyword @code{&rest} (which must be followed by a single argument
! name) indicates that any number of arguments can follow. The single
! following argument name will have a value, as a variable, which is a
! list of all these remaining arguments. Do not write @code{&rest} when
! you call the function.
Here is a description of an imaginary function @code{foo}:
--- 359,369 ----
arguments default to @code{nil}). Do not write @code{&optional} when
you call the function.
! The keyword @code{&rest} (which must be followed by a single
! argument name) indicates that any number of arguments can follow. The
! argument name following @code{&rest} will have, as its value, a list
! of all the remaining arguments passed to the function. Do not write
! @code{&rest} when you call the function.
Here is a description of an imaginary function @code{foo}:
==> I didn't like the wording of this paragraph, so here is what to me
==> is a better wording
***************
*** 450,457 ****
@cindex variable descriptions
@cindex option descriptions
! A @dfn{variable} is a name that can hold a value. Although any
! variable can be set by the user, certain variables that exist
specifically so that users can change them are called @dfn{user
options}. Ordinary variables and user options are described using a
format like that for functions except that there are no arguments.
--- 454,461 ----
@cindex variable descriptions
@cindex option descriptions
! A @dfn{variable} is a name that can hold a value. Although most
! variables can be set by the user, certain variables that exist
specifically so that users can change them are called @dfn{user
options}. Ordinary variables and user options are described using a
format like that for functions except that there are no arguments.
==> there are read only variables
***************
*** 518,529 ****
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
! 20.3, the value is 20.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
! 20.3, the value is 3.
@end defvar
@node Acknowledgements
--- 522,533 ----
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
! 20.3, the value is @code{20}.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
! 20.3, the value is @code{3}.
@end defvar
@node Acknowledgements
==> since these are return values, I thought they should have @code{}'s
intro.texi