From 4abcdac823a757bffc204f5eb074eb09ad69e58a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 15 Aug 2012 01:10:38 +0800 Subject: [PATCH] More doc fixes. * lisp/minibuffer.el (read-file-name): Doc fix. * character.c (Fcharacterp): Doc fix (Bug#12076). * data.c (Findirect_variable): Doc fix (Bug#11040). * editfns.c (Fsave_current_buffer): Doc fix (Bug#11542). Fixes: debbugs:11542 debbugs:11040 debbugs:12076 debbugs:10881 --- lisp/ChangeLog | 2 ++ lisp/minibuffer.el | 34 ++++++++++++++++++++++------------ src/ChangeLog | 5 +++++ src/character.c | 3 +++ src/data.c | 10 ++++++---- src/editfns.c | 4 ++-- 6 files changed, 40 insertions(+), 18 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 8d27fc65185..606be46b118 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,7 @@ 2012-08-14 Chong Yidong + * minibuffer.el (read-file-name): Doc fix (Bug#10881). + * emacs-lisp/regexp-opt.el (regexp-opt-charset): Doc fix (Bug#12085). diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 5c2c14d1fdb..cc2638d58de 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -2259,14 +2259,24 @@ such as making the current buffer visit no file in the case of (defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate) "Read file name, prompting with PROMPT and completing in directory DIR. Value is not expanded---you must call `expand-file-name' yourself. -Default name to DEFAULT-FILENAME if user exits the minibuffer with -the same non-empty string that was inserted by this function. - (If DEFAULT-FILENAME is omitted, the visited file name is used, - except that if INITIAL is specified, that combined with DIR is used. - If DEFAULT-FILENAME is a list of file names, the first file name is used.) -If the user exits with an empty minibuffer, this function returns -an empty string. (This can only happen if the user erased the -pre-inserted contents or if `insert-default-directory' is nil.) + +DIR is the directory to use for completing relative file names. +It should be an absolute directory name, or nil (which means the +current buffer's value of `default-directory'). + +DEFAULT-FILENAME specifies the default file name to return if the +user exits the minibuffer with the same non-empty string inserted +by this function. If DEFAULT-FILENAME is a string, that serves +as the default. If DEFAULT-FILENAME is a list of strings, the +first string is the default. If DEFAULT-FILENAME is omitted or +nil, then if INITIAL is non-nil, the default is DIR combined with +INITIAL; otherwise, if the current buffer is visiting a file, +that file serves as the default; otherwise, the default is simply +the string inserted into the minibuffer. + +If the user exits with an empty minibuffer, return an empty +string. (This happens only if the user erases the pre-inserted +contents, or if `insert-default-directory' is nil.) Fourth arg MUSTMATCH can take the following values: - nil means that the user can exit with any input. @@ -2283,10 +2293,10 @@ Fourth arg MUSTMATCH can take the following values: Fifth arg INITIAL specifies text to start with. -If optional sixth arg PREDICATE is non-nil, possible completions and -the resulting file name must satisfy (funcall PREDICATE NAME). -DIR should be an absolute directory name. It defaults to the value of -`default-directory'. +Sixth arg PREDICATE, if non-nil, should be a function of one +argument; then a file name is considered an acceptable completion +alternative only if PREDICATE returns non-nil with the file name +as its argument. If this command was invoked with the mouse, use a graphical file dialog if `use-dialog-box' is non-nil, and the window system or X diff --git a/src/ChangeLog b/src/ChangeLog index 22f2ca18775..956d6922d2e 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,8 +1,13 @@ 2012-08-14 Chong Yidong + * character.c (Fcharacterp): Doc fix (Bug#12076). + + * data.c (Findirect_variable): Doc fix (Bug#11040). + * chartab.c (Fmap_char_table): Doc fix (Bug#12061). * editfns.c (Fformat): Doc fix (Bug#12059). + (Fsave_current_buffer): Doc fix (Bug#11542). 2012-08-14 Barry OReilly (tiny change) diff --git a/src/character.c b/src/character.c index bdb0eead740..b2acf36ec15 100644 --- a/src/character.c +++ b/src/character.c @@ -258,6 +258,9 @@ multibyte_char_to_unibyte_safe (int c) DEFUN ("characterp", Fcharacterp, Scharacterp, 1, 2, 0, doc: /* Return non-nil if OBJECT is a character. +In Emacs Lisp, characters are represented by character codes, which +are non-negative integers. The function `max-char' returns the +maximum character code. usage: (characterp OBJECT) */) (Lisp_Object object, Lisp_Object ignore) { diff --git a/src/data.c b/src/data.c index 3e278e8bac3..d0ef5734abc 100644 --- a/src/data.c +++ b/src/data.c @@ -808,10 +808,12 @@ indirect_variable (struct Lisp_Symbol *symbol) DEFUN ("indirect-variable", Findirect_variable, Sindirect_variable, 1, 1, 0, doc: /* Return the variable at the end of OBJECT's variable chain. -If OBJECT is a symbol, follow all variable indirections and return the final -variable. If OBJECT is not a symbol, just return it. -Signal a cyclic-variable-indirection error if there is a loop in the -variable chain of symbols. */) +If OBJECT is a symbol, follow its variable indirections (if any), and +return the variable at the end of the chain of aliases. See Info node +`(elisp)Variable Aliases'. + +If OBJECT is not a symbol, just return it. If there is a loop in the +chain of aliases, signal a `cyclic-variable-indirection' error. */) (Lisp_Object object) { if (SYMBOLP (object)) diff --git a/src/editfns.c b/src/editfns.c index 806c80c1936..5ac012c8378 100644 --- a/src/editfns.c +++ b/src/editfns.c @@ -946,8 +946,8 @@ usage: (save-excursion &rest BODY) */) } DEFUN ("save-current-buffer", Fsave_current_buffer, Ssave_current_buffer, 0, UNEVALLED, 0, - doc: /* Save the current buffer; execute BODY; restore the current buffer. -Executes BODY just like `progn'. + doc: /* Record which buffer is current; execute BODY; make that buffer current. +BODY is executed just like `progn'. usage: (save-current-buffer &rest BODY) */) (Lisp_Object args) { -- 2.39.2