From 27d1f87a35539846cc11238f1feaa6b7e6138775 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Tue, 15 May 2012 23:43:06 +0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 11 +++++++++++ doc/lispref/display.texi | 12 +++++++----- doc/lispref/functions.texi | 8 +++++--- doc/lispref/modes.texi | 16 +++++++++------- doc/lispref/variables.texi | 21 ++++++++++++--------- lisp/ChangeLog | 2 ++ lisp/help.el | 5 ++++- 7 files changed, 50 insertions(+), 25 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 935815bc00c..2cf433d0940 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2012-05-15 Chong Yidong + + * 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 * commands.texi (Recursive Editing): recursive-edit is a diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index bc2a905a043..9110d6962e4 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2663,11 +2663,13 @@ makes @code{modeline} an alias for the @code{mode-line} face. (put 'modeline 'face-alias 'mode-line) @end example -@defun 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). -@end defun +@defmac define-obsolete-face-alias obsolete-face current-face when +This macro defines @code{obsolete-face} as an alias for +@var{current-face}, 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). +@end defmac @node Auto Faces @subsection Automatic Face Assignment diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 21f365efe56..1d37b1b220e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1179,12 +1179,14 @@ equivalent to the following: In addition, you can mark a certain a particular calling convention for a function as obsolete: -@defun set-advertised-calling-convention function signature +@defun 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 @@ this: @example (set-advertised-calling-convention - 'sit-for '(seconds &optional nodisp)) + 'sit-for '(seconds &optional nodisp) "22.1") @end example @end defun diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index e42011c34a2..83a38b60bca 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -735,13 +735,15 @@ modes. It is normally bound to @kbd{C-h m}. It uses the value of the variable @code{major-mode} (@pxref{Major Modes}), which is why every major mode command needs to set that variable. -@deffn Command describe-mode -This function displays the documentation of the current major mode. - -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}.) +@deffn 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}). + +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 diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 6f54acea26a..93fb4d5f873 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1853,16 +1853,19 @@ variable with a new name. @code{make-obsolete-variable} declares that the old name is obsolete and therefore that it may be removed at some stage in the future. -@defun make-obsolete-variable obsolete-name current-name &optional when +@defun make-obsolete-variable obsolete-name current-name when &optional access-type This function makes the byte compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is -the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If @var{current-name} -is a string, this is the message and there is no replacement variable. - -If provided, @var{when} should be a string indicating when the -variable was first made obsolete---for example, a date or a release -number. +@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, +it is the variable's new name; then the warning message says to use +@var{current-name} instead of @var{obsolete-name}. If +@var{current-name} 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). + +The optional argument @var{access-type}, if non-@code{nil}, 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 diff --git a/lisp/ChangeLog b/lisp/ChangeLog index d6c5b0e9886..b4428860cb3 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,7 @@ 2012-05-15 Chong Yidong + * help.el (describe-mode): Doc fix. + * net/gnutls.el (gnutls-min-prime-bits): Default to 256 (Bug#11267). 2012-05-06 Troels Nielsen (tiny change) diff --git a/lisp/help.el b/lisp/help.el index 1a6aa9d13d2..317d5cf8f46 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -783,7 +783,10 @@ descriptions of the minor modes, each on a separate page. 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) -- 2.39.2