find-file and friends doc string improvements

[Kevin Rodgers <ihs_4664@yahoo.com>]

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