Misc fixes for Lisp manual.

* doc/lispref/intro.texi (A Sample Function Description): Fix incorrect
markup, undoing previous change.
(A Sample Variable Description): Minor clarifications and markup
improvements.

* doc/lispref/elisp.texi (Top):
* doc/lispref/text.texi (Text): Fix menu order.

4 files changed, 39 insertions, 28 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0fb57469f0f..62b86e756cf 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2012-07-06  Chong Yidong  <cyd@gnu.org>
+
+        * intro.texi (A Sample Function Description): Fix incorrect
+        markup, undoing previous change.
+        (A Sample Variable Description): Minor clarifications and markup
+        improvements.
+
+        * elisp.texi (Top):
+        * text.texi (Text): Fix menu order.
+
 2012-07-06  Richard Stallman  <rms@gnu.org>
 
         * intro.texi (Evaluation Notation, A Sample Function Description):
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 824934a5ceb..60abd718f8e 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1123,9 +1123,9 @@ Text
 * Case Changes::            Case conversion of parts of the buffer.
 * Text Properties::         Assigning Lisp property lists to text characters.
 * Substitution::            Replacing a given character wherever it appears.
-* Transposition::           Swapping two portions of a buffer.
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
+* Transposition::           Swapping two portions of a buffer.
 * Base 64::                 Conversion to or from base 64 encoding.
 * Checksum/Hash::           Computing cryptographic hashes.
 * Parsing HTML/XML::        Parsing HTML and XML.
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index a86079b1df2..d4877b50b62 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -379,24 +379,25 @@ More generally,
 @end example
 @end defun
 
-  Any argument whose name contains the name of a type (e.g.,
-@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
-type.  A plural of a type (such as @var{buffers}) often means a list of
-objects of that type.  An argument named @var{object} may be of any type.
-(For a list of Emacs object types, @pxref{Lisp Data Types}.)  An argument
-with some other sort of name (e.g., @var{new-file}) is discussed
-specifically in the description of the function.  In some sections,
-features common to the arguments of several functions are described at
-the beginning.
-
-  For a more complete description of arguments modified by
-@code{&optional} and @code{&rest}, @pxref{Lambda Expressions}.
+  By convention, any argument whose name contains the name of a type
+(e.g.@: @var{integer}, @var{integer1} or @var{buffer}) is expected to
+be of that type.  A plural of a type (such as @var{buffers}) often
+means a list of objects of that type.  An argument named @var{object}
+may be of any type.  (For a list of Emacs object types, @pxref{Lisp
+Data Types}.)  An argument with any other sort of name
+(e.g.@: @var{new-file}) is specific to the function; if the function
+has a documentation string, the type of the argument should be
+described there (@pxref{Documentation}).
+
+  @xref{Lambda Expressions}, for a more complete description of
+arguments modified by @code{&optional} and @code{&rest}.
 
   Command, macro, and special form descriptions have the same format,
-but the word `Function' is replaced by `Command', `Macro', or `Special
-Form', respectively.  Commands are simply functions that may be called
-interactively; macros process their arguments differently from functions
-(the arguments are not evaluated), but are presented the same way.
+but the word @samp{Function} is replaced by @samp{Command},
+@samp{Macro}, or @samp{Special Form}, respectively.  Commands are
+simply functions that may be called interactively; macros process
+their arguments differently from functions (the arguments are not
+evaluated), but are presented the same way.
 
   The descriptions of macros and special forms use a more complex
 notation to specify optional and repeated arguments, because they can
@@ -445,14 +446,14 @@ from @var{body}, which includes all remaining elements of the form.
 @cindex variable descriptions
 @cindex option descriptions
 
-  A @dfn{variable} is a name that can be bound to an object; binding
-is frequently referred to as @dfn{setting}, and the object to which
-a variable is set is often called a @dfn{value} that the variable
-@dfn{holds}.  Although nearly all variables can be set by the user,
-certain variables exist specifically so that users can change them;
-these 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.
+  A @dfn{variable} is a name that can be @dfn{bound} (or @dfn{set}) to
+an object.  The object to which a variable is bound is called a
+@dfn{value}; we say also that variable @dfn{holds} that value.
+Although nearly all variables can be set by the user, certain
+variables exist specifically so that users can change them; these 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.
 
   Here is a description of the imaginary @code{electric-future-map}
 variable.@refill
@@ -463,8 +464,8 @@ Future mode.  The functions in this map allow you to edit commands you
 have not yet thought about executing.
 @end defvar
 
-  User option descriptions have the same format, but `Variable' is
-replaced by `User Option'.
+  User option descriptions have the same format, but @samp{Variable}
+is replaced by @samp{User Option}.
 
 @node Version Info
 @section Version Information
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index d670a85a464..c1e12ccf3a3 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -51,9 +51,9 @@ the character after point.
 * Case Changes::     Case conversion of parts of the buffer.
 * Text Properties::  Assigning Lisp property lists to text characters.
 * Substitution::     Replacing a given character wherever it appears.
-* Transposition::    Swapping two portions of a buffer.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
+* Transposition::    Swapping two portions of a buffer.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
 * Parsing HTML/XML:: Parsing HTML and XML.