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.
Thanks,
Josh
*** intro.texi 10 Aug 2005 14:29:00 -0000 1.30
--- intro.texi 1 Sep 2005 13:32:32 -0000
***************
*** 175,181 ****
<at> cindex boolean
<at> cindex false
! In Lisp, the symbol <at> code{nil} has three separate meanings: it
is a symbol with the name <at> samp{nil}; it is the logical truth value
<at> var{false}; and it is the empty list---the list of zero elements.
When used as a variable, <at> code{nil} always has the value <at> code{nil}.
--- 175,181 ----
<at> cindex boolean
<at> cindex false
! In Lisp, the symbol <at> dfn{ <at> code{nil}} has three separate meanings: it
is a symbol with the name <at> samp{nil}; it is the logical truth value
<at> var{false}; and it is the empty list---the list of zero elements.
When used as a variable, <at> code{nil} always has the value <at> code{nil}.
==> nil is defined here, but there was no dfn.
***************
*** 197,203 ****
(not
nil)
; <at> r{Emphasize the truth value <at> var{false}}
<at> end example
! <at> cindex <at> code{t} and truth
<at> cindex true
In contexts where a truth value is expected, any non- <at> code{nil} value
is considered to be <at> var{true}. However, <at> code{t} is the preferred way
--- 197,203 ----
(not
nil)
; <at> r{Emphasize the truth value <at> var{false}}
<at> end example
! <at> cindex <at> code{t}, uses of
<at> cindex true
In contexts where a truth value is expected, any non- <at> code{nil} value
is considered to be <at> var{true}. However, <at> code{t} is the preferred way
==> Make this index entry consistent with nil entry
***************
*** 209,222 ****
In Emacs Lisp, <at> code{nil} and <at> 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 <at> code{setting-constant} error. The same is true of
! any symbol whose name starts with a colon ( <at> samp{:}). <at> xref{Constant
Variables}.
<at> node Evaluation Notation
<at> subsection Evaluation Notation
<at> cindex evaluation notation
<at> cindex documentation notation
A Lisp expression that you can evaluate is called a <at> dfn{form}.
Evaluating a form always produces a result, which is a Lisp object. In
--- 209,223 ----
In Emacs Lisp, <at> code{nil} and <at> 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 <at> code{setting-constant} error. <at> xref{Constant
Variables}.
<at> node Evaluation Notation
<at> subsection Evaluation Notation
<at> cindex evaluation notation
<at> cindex documentation notation
+ <at> cindex notation, evaluation
+ <at> cindex notation, documentation
A Lisp expression that you can evaluate is called a <at> 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 ----
<at> node Printing Notation
<at> subsection Printing Notation
<at> cindex printing notation
+ <at> 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 <at> samp{ <at> print{}},
irrespective of where that text goes. The value returned by
! evaluating the form (here <at> code{bar}) follows on a separate line with
! <at> samp{ <at> result{}}.
<at> example
<at> group
--- 264,271 ----
Examples in this manual indicate printed text with <at> samp{ <at> print{}},
irrespective of where that text goes. The value returned by
! evaluating the form (in the example below: <at> code{bar}) follows on a
! separate line with <at> samp{ <at> result{}}.
<at> example
<at> group
==> The first time I read this I thought the "form" was (here <at> 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 ----
<at> node Error Messages
<at> subsection Error Messages
<at> cindex error message notation
+ <at> 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 ----
<at> node Buffer Text Notation
<at> subsection Buffer Text Notation
<at> cindex buffer text notation
+ <at> 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 <at> code{nil}). Do not write <at> code{&optional} when
you call the function.
! The keyword <at> 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 <at> code{&rest} when
! you call the function.
Here is a description of an imaginary function <at> code{foo}:
--- 359,369 ----
arguments default to <at> code{nil}). Do not write <at> code{&optional} when
you call the function.
! The keyword <at> code{&rest} (which must be followed by a single
! argument name) indicates that any number of arguments can follow. The
! argument name following <at> code{&rest} will have, as its value, a list
! of all the remaining arguments passed to the function. Do not write
! <at> code{&rest} when you call the function.
Here is a description of an imaginary function <at> code{foo}:
==> I didn't like the wording of this paragraph, so here is what to me
==> is a better wording
***************
*** 450,457 ****
<at> cindex variable descriptions
<at> cindex option descriptions
! A <at> 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 <at> 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 ----
<at> cindex variable descriptions
<at> cindex option descriptions
! A <at> 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 <at> 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 ****
<at> defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
! 20.3, the value is 20.
<at> end defvar
<at> defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
! 20.3, the value is 3.
<at> end defvar
<at> node Acknowledgements
--- 522,533 ----
<at> defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
! 20.3, the value is <at> code{20}.
<at> end defvar
<at> defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
! 20.3, the value is <at> code{3}.
<at> end defvar
<at> node Acknowledgements
==> since these are return values, I thought they should have <at> code{}'s