[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107997: Misc docfixes.

[Chong Yidong]

------------------------------------------------------------
revno: 107997
committer: Chong Yidong <address@hidden>
branch nick: emacs-24
timestamp: Tue 2012-05-15 23:43:06 +0800
message:
  Misc docfixes.
  Suggested by Martin Rudalics.
  
  * doc/lispref/display.texi (Face Functions): Fix define-obsolete-face-alias.
  
  * doc/lispref/functions.texi (Obsolete Functions): Fix doc for
  set-advertised-calling-convention.
  
  * doc/lispref/modes.texi (Mode Help): Fix describe-mode.
  
  * doc/lispref/variables.texi (Variable Aliases): Fix make-obsolete-variable.
  
  * lisp/help.el (describe-mode): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/functions.texi
  doc/lispref/modes.texi
  doc/lispref/variables.texi
  lisp/ChangeLog
  lisp/help.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-05-15 09:38:50 +0000
+++ b/doc/lispref/ChangeLog     2012-05-15 15:43:06 +0000
@@ -1,3 +1,14 @@
+2012-05-15  Chong Yidong  <address@hidden>
+
+       * functions.texi (Obsolete Functions): Fix doc for
+       set-advertised-calling-convention.
+
+       * modes.texi (Mode Help): Fix describe-mode.
+
+       * display.texi (Face Functions): Fix define-obsolete-face-alias.
+
+       * variables.texi (Variable Aliases): Fix make-obsolete-variable.
+
 2012-05-15  Martin Rudalics  <address@hidden>
 
        * commands.texi (Recursive Editing): recursive-edit is a

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-05-15 09:38:50 +0000
+++ b/doc/lispref/display.texi  2012-05-15 15:43:06 +0000
@@ -2663,11 +2663,13 @@
 (put 'modeline 'face-alias 'mode-line)
 @end example
 
address@hidden define-obsolete-face-alias obsolete-face current-face &optional 
when
-This function defines a face alias and marks it as obsolete, indicating
-that it may be removed in future.  The optional string @var{when}
-indicates when the face was made obsolete (for example, a release number).
address@hidden defun
address@hidden define-obsolete-face-alias obsolete-face current-face when
+This macro defines @code{obsolete-face} as an alias for
address@hidden, and also marks it as obsolete, indicating that it
+may be removed in future.  @var{when} should be a string indicating
+when @code{obsolete-face} was made obsolete (usually a version number
+string).
address@hidden defmac
 
 @node Auto Faces
 @subsection Automatic Face Assignment

=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi        2012-05-05 00:37:30 +0000
+++ b/doc/lispref/functions.texi        2012-05-15 15:43:06 +0000
@@ -1179,12 +1179,14 @@
 In addition, you can mark a certain a particular calling convention
 for a function as obsolete:
 
address@hidden set-advertised-calling-convention function signature
address@hidden set-advertised-calling-convention function signature when
 This function specifies the argument list @var{signature} as the
 correct way to call @var{function}.  This causes the Emacs byte
 compiler to issue a warning whenever it comes across an Emacs Lisp
 program that calls @var{function} any other way (however, it will
-still allow the code to be byte compiled).
+still allow the code to be byte compiled).  @var{when} should be a
+string indicating when the variable was first made obsolete (usually a
+version number string).
 
 For instance, in old versions of Emacs the @code{sit-for} function
 accepted three arguments, like this
@@ -1199,7 +1201,7 @@
 
 @example
 (set-advertised-calling-convention
-  'sit-for '(seconds &optional nodisp))
+  'sit-for '(seconds &optional nodisp) "22.1")
 @end example
 @end defun
 

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-05-15 09:38:50 +0000
+++ b/doc/lispref/modes.texi    2012-05-15 15:43:06 +0000
@@ -735,13 +735,15 @@
 variable @code{major-mode} (@pxref{Major Modes}), which is why every
 major mode command needs to set that variable.
 
address@hidden Command describe-mode
-This function displays the documentation of the current major mode.
address@hidden Command describe-mode &optional buffer
+This command displays the documentation of the current buffer's major
+mode and minor modes.  It uses the @code{documentation} function to
+retrieve the documentation strings of the major and minor mode
+commands (@pxref{Accessing Documentation}).
 
-The @code{describe-mode} function calls the @code{documentation}
-function using the value of @code{major-mode} as an argument.  Thus, it
-displays the documentation string of the major mode command.
-(@xref{Accessing Documentation}.)
+If called from Lisp with a non-nil @var{buffer} argument, this
+function displays the documentation for that buffer's major and minor
+modes, rather than those of the current buffer.
 @end deffn
 
 @node Derived Modes

=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi        2012-04-26 00:31:47 +0000
+++ b/doc/lispref/variables.texi        2012-05-15 15:43:06 +0000
@@ -1853,16 +1853,19 @@
 the old name is obsolete and therefore that it may be removed at some
 stage in the future.
 
address@hidden make-obsolete-variable obsolete-name current-name &optional when
address@hidden make-obsolete-variable obsolete-name current-name when &optional 
access-type
 This function makes the byte compiler warn that the variable
address@hidden is obsolete.  If @var{current-name} is a symbol, it is
-the variable's new name; then the warning message says to use
address@hidden instead of @var{obsolete-name}.  If @var{current-name}
-is a string, this is the message and there is no replacement variable.
address@hidden is obsolete.  If @var{current-name} is a symbol,
+it is the variable's new name; then the warning message says to use
address@hidden instead of @var{obsolete-name}.  If
address@hidden is a string, this is the message and there is no
+replacement variable.  @var{when} should be a string indicating when
+the variable was first made obsolete (usually a version number
+string).
 
-If provided, @var{when} should be a string indicating when the
-variable was first made obsolete---for example, a date or a release
-number.
+The optional argument @var{access-type}, if address@hidden, should
+should specify the kind of access that will trigger obsolescence
+warnings; it can be either @code{get} or @code{set}.
 @end defun
 
   You can make two variables synonyms and declare one obsolete at the

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-05-15 15:16:13 +0000
+++ b/lisp/ChangeLog    2012-05-15 15:43:06 +0000
@@ -1,5 +1,7 @@
 2012-05-15  Chong Yidong  <address@hidden>
 
+       * help.el (describe-mode): Doc fix.
+
        * net/gnutls.el (gnutls-min-prime-bits): Default to 256 (Bug#11267).
 
 2012-05-06  Troels Nielsen  <address@hidden>  (tiny change)

=== modified file 'lisp/help.el'
--- a/lisp/help.el      2012-02-28 08:17:21 +0000
+++ b/lisp/help.el      2012-05-15 15:43:06 +0000
@@ -783,7 +783,10 @@
 
 For this to work correctly for a minor mode, the mode's indicator
 variable \(listed in `minor-mode-alist') must also be a function
-whose documentation describes the minor mode."
+whose documentation describes the minor mode.
+
+If called from Lisp with a non-nil BUFFER argument, display
+documentation for the major and minor modes of that buffer."
   (interactive "@")
   (unless buffer (setq buffer (current-buffer)))
   (help-setup-xref (list #'describe-mode buffer)