find-file and friends doc string improvements

[Kevin Rodgers]

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