Re: Emacs Lisp reference: address@hidden vs body...

[Juri Linkov]

>     I noticed a small inconsistency in the Emacs Lisp Reference manual.
>     Some functions have their argument `body' renamed to `forms'
>     in the documentation, some not.
>
> How about if you change `forms' and `body-forms' to `body'.
>
>       Some use the Texinfo command
>     address@hidden' to produce dots, some use `...' literally.
>
> It could make no difference in the @def... line.
> You could run TeX and see.
> Maybe address@hidden could tell you.

Karl suggested using @dots{} because it makes a difference to TeX
where three periods end up too close together.

In the patch below I replaced `...' with address@hidden' only in related
functions/macros where one function uses address@hidden' but another related
function uses `...', so the visual difference will be noticeable,
especially when these functions will appear on one printed page.

Also I replaced `forms' with `body' only in closely related functions:
in `with-local-quit' (because `while-no-input' uses `body') and in
`save-excursion' (because `save-restriction' uses `body').

Index: lispref/buffers.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/buffers.texi,v
retrieving revision 1.44
diff -c -r1.44 buffers.texi
*** lispref/buffers.texi        20 Aug 2005 11:58:09 -0000      1.44
--- lispref/buffers.texi        14 Oct 2005 09:07:16 -0000
***************
*** 202,208 ****
  existing buffer.
  @end defun
  
! @defspec save-current-buffer body...
  The @code{save-current-buffer} special form saves the identity of the
  current buffer, evaluates the @var{body} forms, and finally restores
  that buffer as current.  The return value is the value of the last
--- 202,208 ----
  existing buffer.
  @end defun
  
! @defspec save-current-buffer address@hidden
  The @code{save-current-buffer} special form saves the identity of the
  current buffer, evaluates the @var{body} forms, and finally restores
  that buffer as current.  The return value is the value of the last
***************
*** 215,221 ****
  remains current.
  @end defspec
  
! @defmac with-current-buffer buffer-or-name body...
  The @code{with-current-buffer} macro saves the identity of the current
  buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
  forms, and finally restores the buffer.  The return value is the value
--- 215,221 ----
  remains current.
  @end defspec
  
! @defmac with-current-buffer buffer-or-name address@hidden
  The @code{with-current-buffer} macro saves the identity of the current
  buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
  forms, and finally restores the buffer.  The return value is the value
***************
*** 227,233 ****
  existing buffer.
  @end defmac
  
! @defmac with-temp-buffer body...
  @anchor{Definition of with-temp-buffer}
  The @code{with-temp-buffer} macro evaluates the @var{body} forms
  with a temporary buffer as the current buffer.  It saves the identity of
--- 227,233 ----
  existing buffer.
  @end defmac
  
! @defmac with-temp-buffer address@hidden
  @anchor{Definition of with-temp-buffer}
  The @code{with-temp-buffer} macro evaluates the @var{body} forms
  with a temporary buffer as the current buffer.  It saves the identity of
Index: lispref/commands.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/commands.texi,v
retrieving revision 1.71
diff -c -r1.71 commands.texi
*** lispref/commands.texi       10 Aug 2005 14:29:00 -0000      1.71
--- lispref/commands.texi       14 Oct 2005 09:07:22 -0000
***************
*** 2434,2440 ****
  Emacs version 18.
  @end defvar
  
! @defmac while-no-input body...
  This construct runs the @var{body} forms and returns the value of the
  last one---but only if no input arrives.  If any input arrives during
  the execution of the @var{body} forms, it aborts them (working much
--- 2434,2440 ----
  Emacs version 18.
  @end defvar
  
! @defmac while-no-input address@hidden
  This construct runs the @var{body} forms and returns the value of the
  last one---but only if no input arrives.  If any input arrives during
  the execution of the @var{body} forms, it aborts them (working much
***************
*** 2658,2680 ****
  address@hidden, then @code{quit-flag} has no special effect.
  @end defvar
  
! @defmac with-local-quit address@hidden
! This macro executes @var{forms} in sequence, but allows quitting, at
  least locally, within @var{body} even if @code{inhibit-quit} was
  address@hidden outside this construct.  It returns the value of the
! last form in @var{forms}, unless exited by quitting, in which case
  it returns @code{nil}.
  
  If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
! it only executes the @var{forms}, and setting @code{quit-flag} causes
  a normal quit.  However, if @code{inhibit-quit} is address@hidden so
  that ordinary quitting is delayed, a address@hidden @code{quit-flag}
  triggers a special kind of local quit.  This ends the execution of
! @var{forms} and exits the @code{with-local-quit} form with
  @code{quit-flag} still address@hidden, so that another (ordinary) quit
  will happen as soon as that is allowed.  If @code{quit-flag} is
! already address@hidden at the beginning of @var{forms}, the local quit
! happens immediately and they don't execute at all.
  
  This macro is mainly useful in functions that can be called from
  timers, @code{pre-command-hook}, @code{post-command-hook} and other
--- 2658,2680 ----
  address@hidden, then @code{quit-flag} has no special effect.
  @end defvar
  
! @defmac with-local-quit address@hidden
! This macro executes @var{body} forms in sequence, but allows quitting, at
  least locally, within @var{body} even if @code{inhibit-quit} was
  address@hidden outside this construct.  It returns the value of the
! last form in @var{body}, unless exited by quitting, in which case
  it returns @code{nil}.
  
  If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
! it only executes the @var{body}, and setting @code{quit-flag} causes
  a normal quit.  However, if @code{inhibit-quit} is address@hidden so
  that ordinary quitting is delayed, a address@hidden @code{quit-flag}
  triggers a special kind of local quit.  This ends the execution of
! @var{body} and exits the @code{with-local-quit} body with
  @code{quit-flag} still address@hidden, so that another (ordinary) quit
  will happen as soon as that is allowed.  If @code{quit-flag} is
! already address@hidden at the beginning of @var{body}, the local quit
! happens immediately and the body doesn't execute at all.
  
  This macro is mainly useful in functions that can be called from
  timers, @code{pre-command-hook}, @code{post-command-hook} and other
Index: lispref/compile.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/compile.texi,v
retrieving revision 1.23
diff -c -r1.23 compile.texi
*** lispref/compile.texi        10 Aug 2005 14:29:00 -0000      1.23
--- lispref/compile.texi        14 Oct 2005 09:07:22 -0000
***************
*** 401,407 ****
    These features permit you to write code to be evaluated during
  compilation of a program.
  
! @defspec eval-and-compile body
  This form marks @var{body} to be evaluated both when you compile the
  containing code and when you run it (whether compiled or not).
  
--- 401,407 ----
    These features permit you to write code to be evaluated during
  compilation of a program.
  
! @defspec eval-and-compile address@hidden
  This form marks @var{body} to be evaluated both when you compile the
  containing code and when you run it (whether compiled or not).
  
***************
*** 410,416 ****
  preferable when @var{body} is large.
  @end defspec
  
! @defspec eval-when-compile body
  This form marks @var{body} to be evaluated at compile time but not when
  the compiled program is loaded.  The result of evaluation by the
  compiler becomes a constant which appears in the compiled program.  If
--- 410,416 ----
  preferable when @var{body} is large.
  @end defspec
  
! @defspec eval-when-compile address@hidden
  This form marks @var{body} to be evaluated at compile time but not when
  the compiled program is loaded.  The result of evaluation by the
  compiler becomes a constant which appears in the compiled program.  If
***************
*** 470,476 ****
  @c This is implemented with a defun, but conceptually it is
  @c a special form.
  
! @defspec with-no-warnings body...
  In execution, this is equivalent to @code{(progn @var{body}...)},
  but the compiler does not issue warnings for anything that occurs
  inside @var{body}.
--- 470,476 ----
  @c This is implemented with a defun, but conceptually it is
  @c a special form.
  
! @defspec with-no-warnings address@hidden
  In execution, this is equivalent to @code{(progn @var{body}...)},
  but the compiler does not issue warnings for anything that occurs
  inside @var{body}.
Index: lispref/customize.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/customize.texi,v
retrieving revision 1.47
diff -c -r1.47 customize.texi
*** lispref/customize.texi      10 Aug 2005 14:29:00 -0000      1.47
--- lispref/customize.texi      14 Oct 2005 09:07:22 -0000
***************
*** 119,125 ****
  
    The way to declare new customization groups is with @code{defgroup}.
  
! @defmac defgroup group members doc [keyword value]...
  Declare @var{group} as a customization group containing @var{members}.
  Do not quote the symbol @var{group}.  The argument @var{doc} specifies
  the documentation string for the group.  It should not start with a
--- 119,125 ----
  
    The way to declare new customization groups is with @code{defgroup}.
  
! @defmac defgroup group members doc [keyword address@hidden
  Declare @var{group} as a customization group containing @var{members}.
  Do not quote the symbol @var{group}.  The argument @var{doc} specifies
  the documentation string for the group.  It should not start with a
Index: lispref/display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/display.texi,v
retrieving revision 1.189
diff -c -r1.189 display.texi
*** lispref/display.texi        3 Oct 2005 06:39:08 -0000       1.189
--- lispref/display.texi        14 Oct 2005 09:07:29 -0000
***************
*** 403,409 ****
  Secondly, ``done'' is more explicit.
  @end defun
  
! @defmac dotimes-with-progress-reporter (var count [result]) message body...
  This is a convenience macro that works the same way as @code{dotimes}
  does, but also reports loop progress using the functions described
  above.  It allows you to save some typing.
--- 403,409 ----
  Secondly, ``done'' is more explicit.
  @end defun
  
! @defmac dotimes-with-progress-reporter (var count [result]) message 
address@hidden
  This is a convenience macro that works the same way as @code{dotimes}
  does, but also reports loop progress using the functions described
  above.  It allows you to save some typing.
***************
*** 1721,1727 ****
  customize using the Customization buffer (@pxref{Easy Customization,,,
  emacs, The GNU Emacs Manual}).
  
! @defmac defface face spec doc [keyword value]...
  This declares @var{face} as a customizable face that defaults
  according to @var{spec}.  You should not quote the symbol @var{face},
  and it should not end in @samp{-face} (that would be redundant).  The
--- 1721,1727 ----
  customize using the Customization buffer (@pxref{Easy Customization,,,
  emacs, The GNU Emacs Manual}).
  
! @defmac defface face spec doc [keyword address@hidden
  This declares @var{face} as a customizable face that defaults
  according to @var{spec}.  You should not quote the symbol @var{face},
  and it should not end in @samp{-face} (that would be redundant).  The
Index: lispref/files.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/files.texi,v
retrieving revision 1.86
diff -c -r1.86 files.texi
*** lispref/files.texi  10 Sep 2005 15:51:28 -0000      1.86
--- lispref/files.texi  14 Oct 2005 09:07:33 -0000
***************
*** 625,631 ****
  files that the user does not need to know about.
  @end deffn
  
! @defmac with-temp-file file body...
  @anchor{Definition of with-temp-file}
  The @code{with-temp-file} macro evaluates the @var{body} forms with a
  temporary buffer as the current buffer; then, at the end, it writes the
--- 625,631 ----
  files that the user does not need to know about.
  @end deffn
  
! @defmac with-temp-file file address@hidden
  @anchor{Definition of with-temp-file}
  The @code{with-temp-file} macro evaluates the @var{body} forms with a
  temporary buffer as the current buffer; then, at the end, it writes the
Index: lispref/modes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/modes.texi,v
retrieving revision 1.123
diff -c -r1.123 modes.texi
*** lispref/modes.texi  8 Sep 2005 22:00:58 -0000       1.123
--- lispref/modes.texi  14 Oct 2005 09:07:39 -0000
***************
*** 1154,1160 ****
  @var{hookvars}.
  @end defun
  
! @defmac delay-mode-hooks body...
  This macro executes @var{body} like @code{progn}, but all calls to
  @code{run-mode-hooks} inside @var{body} delay running their hooks.
  They will be run by the first call to @code{run-mode-hooks} after exit
--- 1154,1160 ----
  @var{hookvars}.
  @end defun
  
! @defmac delay-mode-hooks address@hidden
  This macro executes @var{body} like @code{progn}, but all calls to
  @code{run-mode-hooks} inside @var{body} delay running their hooks.
  They will be run by the first call to @code{run-mode-hooks} after exit
***************
*** 1364,1370 ****
    The macro @code{define-minor-mode} offers a convenient way of
  implementing a mode in one self-contained definition.
  
! @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] 
keyword-args... body...
  @tindex define-minor-mode
  This macro defines a new minor mode whose name is @var{mode} (a
  symbol).  It defines a command named @var{mode} to toggle the minor
--- 1364,1370 ----
    The macro @code{define-minor-mode} offers a convenient way of
  implementing a mode in one self-contained definition.
  
! @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] 
address@hidden address@hidden
  @tindex define-minor-mode
  This macro defines a new minor mode whose name is @var{mode} (a
  symbol).  It defines a command named @var{mode} to toggle the minor
***************
*** 1492,1498 ****
   :group 'hunger)
  @end smallexample
  
! @defmac define-global-minor-mode global-mode mode turn-on keyword-args...
  This defines a global minor mode named @var{global-mode} whose meaning
  is to enable the buffer-local minor mode @var{mode} in every buffer.
  To turn on the minor mode in a buffer, it uses the function
--- 1492,1498 ----
   :group 'hunger)
  @end smallexample
  
! @defmac define-global-minor-mode global-mode mode turn-on address@hidden
  This defines a global minor mode named @var{global-mode} whose meaning
  is to enable the buffer-local minor mode @var{mode} in every buffer.
  To turn on the minor mode in a buffer, it uses the function
Index: lispref/positions.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/positions.texi,v
retrieving revision 1.56
diff -c -r1.56 positions.texi
*** lispref/positions.texi      8 Sep 2005 22:00:58 -0000       1.56
--- lispref/positions.texi      14 Oct 2005 09:07:41 -0000
***************
*** 829,841 ****
  described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
  Configurations}).
  
! @defspec save-excursion address@hidden
  @cindex mark excursion
  @cindex point excursion
  @cindex current buffer excursion
  The @code{save-excursion} special form saves the identity of the current
  buffer and the values of point and the mark in it, evaluates
! @var{forms}, and finally restores the buffer and its saved values of
  point and the mark.  All three saved values are restored even in case of
  an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
  
--- 829,841 ----
  described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
  Configurations}).
  
! @defspec save-excursion address@hidden
  @cindex mark excursion
  @cindex point excursion
  @cindex current buffer excursion
  The @code{save-excursion} special form saves the identity of the current
  buffer and the values of point and the mark in it, evaluates
! @var{body}, and finally restores the buffer and its saved values of
  point and the mark.  All three saved values are restored even in case of
  an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
  
***************
*** 855,862 ****
  use @code{save-window-excursion} inside @code{save-excursion}
  (@pxref{Window Configurations}).
  
! The value returned by @code{save-excursion} is the result of the last of
! @var{forms}, or @code{nil} if no @var{forms} are given.
  
  @example
  @group
--- 855,862 ----
  use @code{save-window-excursion} inside @code{save-excursion}
  (@pxref{Window Configurations}).
  
! The value returned by @code{save-excursion} is the result of the last
! form in @var{body}, or @code{nil} if no body forms were given.
  
  @example
  @group
Index: lispref/streams.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/streams.texi,v
retrieving revision 1.29
diff -c -r1.29 streams.texi
*** lispref/streams.texi        10 Aug 2005 14:29:00 -0000      1.29
--- lispref/streams.texi        14 Oct 2005 09:07:41 -0000
***************
*** 663,669 ****
  the printed representation of a Lisp object as a string.
  @end defun
  
! @defmac with-output-to-string body...
  This macro executes the @var{body} forms with @code{standard-output} set
  up to feed output into a string.  Then it returns that string.
  
--- 663,669 ----
  the printed representation of a Lisp object as a string.
  @end defun
  
! @defmac with-output-to-string address@hidden
  This macro executes the @var{body} forms with @code{standard-output} set
  up to feed output into a string.  Then it returns that string.
  
Index: lispref/syntax.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/syntax.texi,v
retrieving revision 1.46
diff -c -r1.46 syntax.texi
*** lispref/syntax.texi 10 Aug 2005 14:29:00 -0000      1.46
--- lispref/syntax.texi 14 Oct 2005 09:07:43 -0000
***************
*** 512,518 ****
  the current buffer.
  @end defun
  
! @defmac with-syntax-table @var{table} @var{body}...
  @tindex with-syntax-table
  This macro executes @var{body} using @var{table} as the current syntax
  table.  It returns the value of the last form in @var{body}, after
--- 512,518 ----
  the current buffer.
  @end defun
  
! @defmac with-syntax-table @var{table} @address@hidden
  @tindex with-syntax-table
  This macro executes @var{body} using @var{table} as the current syntax
  table.  It returns the value of the last form in @var{body}, after
Index: lispref/text.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/text.texi,v
retrieving revision 1.107
diff -c -r1.107 text.texi
*** lispref/text.texi   8 Sep 2005 22:00:58 -0000       1.107
--- lispref/text.texi   14 Oct 2005 09:07:49 -0000
***************
*** 4265,4271 ****
    Output of messages into the @samp{*Messages*} buffer does not
  call these functions.
  
! @defmac combine-after-change-calls body...
  The macro executes @var{body} normally, but arranges to call the
  after-change functions just once for a series of several changes---if
  that seems safe.
--- 4265,4271 ----
    Output of messages into the @samp{*Messages*} buffer does not
  call these functions.
  
! @defmac combine-after-change-calls address@hidden
  The macro executes @var{body} normally, but arranges to call the
  after-change functions just once for a series of several changes---if
  that seems safe.

-- 
Juri Linkov
http://www.jurta.org/emacs/