[PATCH] intro.texi

[PATCH] intro.texi

[Joshua Varner]

[-- Attachment #1.1: Type: text/plain, Size: 8213 bytes --]

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 ****
@cindex boolean
@cindex false

! 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 @dfn{@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}.
==> 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 non-@code{nil} 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 non-@code{nil} 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}.

@node Evaluation Notation
@subsection Evaluation Notation
@cindex evaluation notation
@cindex documentation notation

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}.

@node Evaluation Notation
@subsection Evaluation Notation
@cindex evaluation notation
@cindex documentation notation
+ @cindex notation, evaluation
+ @cindex notation, documentation

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 @samp{@print{}},
irrespective of where that text goes. The value returned by
! evaluating the form (here @code{bar}) follows on a separate line with
! @samp{@result{}}.

@example
@group
--- 264,271 ----

Examples in this manual indicate printed text with @samp{@print{}},
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 @samp{@result{}}.

@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

[-- Attachment #1.2: Type: text/html, Size: 10755 bytes --]

[-- Attachment #2: intro.texi --]
[-- Type: application/x-texinfo, Size: 7996 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: [PATCH] intro.texi

[Richard M. Stallman]

Many of your suggested changes are good; I will comment on the ones
that I don't plan to use.

    ! In Lisp, the symbol @dfn{@code{nil}} has three separate meanings: it
    is a symbol with the name @samp{nil}; it is the logical truth value

We don't write @dfn around @code.

    @cindex documentation notation
    + @cindex notation, evaluation
    + @cindex notation, documentation

Having two index entries in the same place that start with the same
word is redundant; it would be better to add

    @cindex notation

    Examples in this manual indicate printed text with @samp{@print{}},
    irrespective of where that text goes. The value returned by
    ! evaluating the form (here @code{bar}) follows on a separate line with
    ! @samp{@result{}}.

    @example
    @group
    --- 264,271 ----

    Examples in this manual indicate printed text with @samp{@print{}},
    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 @samp{@result{}}.

Using "here" is conventional, so it is good enough.

    @defvar emacs-major-version
    The major version number of Emacs, as an integer. For Emacs version
    ! 20.3, the value is @code{20}.

We don't write @code around values that are numbers.
It looks better not to do so.