* find-file and friends doc string improvements
@ 2004-04-09 22:01 Kevin Rodgers
2004-04-11 2:35 ` Richard Stallman
0 siblings, 1 reply; 2+ messages in thread
From: Kevin Rodgers @ 2004-04-09 22:01 UTC (permalink / raw)
find-file's doc string doesn't describe the effects of setting
find-file-visit-truename or find-file-run-dired. Here's a patch that
adds 2 short sentences to its doc string, and which provides references
from the 5 related commands back to it. It also cleans up the
find-alternate-file and -other-window doc strings, and adds a reference
to buffer-read-only in toggle-read-only's doc string.
2004-04-08 Kevin Rodgers <ihs_4664@yahoo.com>
* lisp/files.el (find-file): Describe the effect of setting
find-file-visit-truename and find-file-run-dired.
(find-file-other-window, find-file-other-frame,
find-file-read-only): Reference find-file.
(find-file-read-only-other-window,
find-file-read-only-other-frame): Reference find-file-read-only.
(find-alternate-file, find-alternate-file-other-window):
Describe consistenly.
(toggle-read-only): Reference `buffer-read-only'.
*** emacs-21.3/lisp/files.el Thu Oct 24 07:07:56 2002
--- emacs-21.3/lisp/files.el Thu Apr 8 10:44:43 2004
***************
*** 726,736 ****
(defun find-file (filename &optional wildcards)
"Edit file FILENAME.
! Switch to a buffer visiting file FILENAME,
! creating one if none already exists.
! Interactively, or if WILDCARDS is non-nil in a call from Lisp,
! expand wildcards (if any) and visit multiple files. Wildcard expansion
! can be suppressed by setting `find-file-wildcards'."
(interactive "FFind file: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
--- 726,740 ----
(defun find-file (filename &optional wildcards)
"Edit file FILENAME.
! Switch to a buffer visiting file FILENAME, creating one if none
! already exists. If `find-file-visit-truename' is set, a buffer
! visiting the same file under a different name will be selected.
!
! Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand
! wildcards (if any) and visit multiple files. Wildcard expansion can
! be suppressed by setting `find-file-wildcards'.
!
! If `find-file-run-dired' is set, run \\[dired] when FILENAME is a directory."
(interactive "FFind file: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
***************
*** 738,748 ****
(switch-to-buffer value))))
(defun find-file-other-window (filename &optional wildcards)
! "Edit file FILENAME, in another window.
! May create a new window, or reuse an existing one.
! See the function `display-buffer'.
! Interactively, or if WILDCARDS is non-nil in a call from Lisp,
! expand wildcards (if any) and visit multiple files."
(interactive "FFind file in other window: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
--- 742,753 ----
(switch-to-buffer value))))
(defun find-file-other-window (filename &optional wildcards)
! "Edit file FILENAME as with `find-file', in another window.
! May create a new window, or reuse an existing one. See the function
! `display-buffer'.
!
! Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand
! wildcards (if any) and visit multiple files."
(interactive "FFind file in other window: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
***************
*** 753,763 ****
(switch-to-buffer-other-window value))))
(defun find-file-other-frame (filename &optional wildcards)
! "Edit file FILENAME, in another frame.
! May create a new frame, or reuse an existing one.
! See the function `display-buffer'.
! Interactively, or if WILDCARDS is non-nil in a call from Lisp,
! expand wildcards (if any) and visit multiple files."
(interactive "FFind file in other frame: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
--- 758,769 ----
(switch-to-buffer-other-window value))))
(defun find-file-other-frame (filename &optional wildcards)
! "Edit file FILENAME as with `find-file', in another frame.
! May create a new frame, or reuse an existing one. See the function
! `display-buffer'.
!
! Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand
! wildcards (if any) and visit multiple files."
(interactive "FFind file in other frame: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
***************
*** 768,775 ****
(switch-to-buffer-other-frame value))))
(defun find-file-read-only (filename &optional wildcards)
! "Edit file FILENAME but don't allow changes.
! Like `find-file' but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only: \np")
(find-file filename wildcards)
--- 774,781 ----
(switch-to-buffer-other-frame value))))
(defun find-file-read-only (filename &optional wildcards)
! "Edit file FILENAME as with `find-file', but don't allow changes.
! Marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only: \np")
(find-file filename wildcards)
***************
*** 777,784 ****
(current-buffer))
(defun find-file-read-only-other-window (filename &optional wildcards)
! "Edit file FILENAME in another window but don't allow changes.
! Like \\[find-file-other-window] but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other window: \np")
(find-file-other-window filename wildcards)
--- 783,790 ----
(current-buffer))
(defun find-file-read-only-other-window (filename &optional wildcards)
! "Edit file FILENAME as with `find-file-read-only', in another window.
! Like \\[find-file-other-window], but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other window: \np")
(find-file-other-window filename wildcards)
***************
*** 786,793 ****
(current-buffer))
(defun find-file-read-only-other-frame (filename &optional wildcards)
! "Edit file FILENAME in another frame but don't allow changes.
! Like \\[find-file-other-frame] but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other frame: \np")
(find-file-other-frame filename wildcards)
--- 792,799 ----
(current-buffer))
(defun find-file-read-only-other-frame (filename &optional wildcards)
! "Edit file FILENAME as with `find-file-read-only', in another frame.
! Like \\[find-file-other-frame], but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other frame: \np")
(find-file-other-frame filename wildcards)
***************
*** 795,802 ****
(current-buffer))
(defun find-alternate-file-other-window (filename)
! "Find file FILENAME as a replacement for the file in the next window.
! This command does not select that window."
(interactive
(save-selected-window
(other-window 1)
--- 801,808 ----
(current-buffer))
(defun find-alternate-file-other-window (filename)
! "Edit file FILENAME as a replacement for the buffer in the next window.
! This command does not select that window or kill its previous buffer."
(interactive
(save-selected-window
(other-window 1)
***************
*** 815,823 ****
(find-alternate-file filename))))
(defun find-alternate-file (filename)
! "Find file FILENAME, select its buffer, kill previous buffer.
If the current buffer now contains an empty file that you just visited
! \(presumably by mistake), use this command to visit the file you really want."
(interactive
(let ((file buffer-file-name)
(file-name nil)
--- 821,830 ----
(find-alternate-file filename))))
(defun find-alternate-file (filename)
! "Edit file FILENAME as a replacement for the buffer in the selected window.
If the current buffer now contains an empty file that you just visited
! \(presumably by mistake), use this command to visit the file you really want.
! This command kills the previous buffer."
(interactive
(let ((file buffer-file-name)
(file-name nil)
***************
*** 2851,2857 ****
(defun toggle-read-only (&optional arg)
"Change whether this buffer is visiting its file read-only.
! With arg, set read-only iff arg is positive.
If visiting file read-only and `view-read-only' is non-nil, enter view mode."
(interactive "P")
(cond
--- 2858,2864 ----
(defun toggle-read-only (&optional arg)
"Change whether this buffer is visiting its file read-only.
! With arg, set `buffer-read-only' iff arg is positive.
If visiting file read-only and `view-read-only' is non-nil, enter view mode."
(interactive "P")
(cond
--
Kevin Rodgers
^ permalink raw reply [flat|nested] 2+ messages in thread* Re: find-file and friends doc string improvements
2004-04-09 22:01 find-file and friends doc string improvements Kevin Rodgers
@ 2004-04-11 2:35 ` Richard Stallman
0 siblings, 0 replies; 2+ messages in thread
From: Richard Stallman @ 2004-04-11 2:35 UTC (permalink / raw)
Cc: gnu-emacs-bug
Some of those changes are good, but there are some problems.
If `find-file-visit-truename' is set, a buffer
! visiting the same file under a different name will be selected.
!
Please avoid the passive voice when writing documentation.
It makes text harder to read and sometimes causes vagueness.
! "Edit file FILENAME, in another window.
! May create a new window, or reuse an existing one.
! See the function `display-buffer'.
! Interactively, or if WILDCARDS is non-nil in a call from Lisp,
! expand wildcards (if any) and visit multiple files."
(interactive "FFind file in other window: \np")
(let ((value (find-file-noselect filename nil nil wildcards)))
(if (listp value)
--- 742,753 ----
(switch-to-buffer value))))
(defun find-file-other-window (filename &optional wildcards)
! "Edit file FILENAME as with `find-file', in another window.
! May create a new window, or reuse an existing one. See the function
! `display-buffer'.
!
! Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand
! wildcards (if any) and visit multiple files."
The current text has line breaks that make it easier to read.
Filling the text to make longer lines would not be an improvement.
***************
*** 768,775 ****
(switch-to-buffer-other-frame value))))
(defun find-file-read-only (filename &optional wildcards)
! "Edit file FILENAME but don't allow changes.
! Like `find-file' but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only: \np")
(find-file filename wildcards)
--- 774,781 ----
(switch-to-buffer-other-frame value))))
(defun find-file-read-only (filename &optional wildcards)
! "Edit file FILENAME as with `find-file', but don't allow changes.
! Marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only: \np")
(find-file filename wildcards)
***************
*** 777,784 ****
(current-buffer))
(defun find-file-read-only-other-window (filename &optional wildcards)
! "Edit file FILENAME in another window but don't allow changes.
! Like \\[find-file-other-window] but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other window: \np")
(find-file-other-window filename wildcards)
--- 783,790 ----
(current-buffer))
(defun find-file-read-only-other-window (filename &optional wildcards)
! "Edit file FILENAME as with `find-file-read-only', in another window.
! Like \\[find-file-other-window], but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
(interactive "fFind file read-only other window: \np")
(find-file-other-window filename wildcards)
Those are good changes. The rest of the changes are also good.
If someone would like to install them, that would be good.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2004-04-11 2:35 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-04-09 22:01 find-file and friends doc string improvements Kevin Rodgers
2004-04-11 2:35 ` Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).