From fc3c00413ac4bf59e2a2e4c21ecaaac53e9fd8fa Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Thu, 1 Jul 2021 10:19:48 +0200 Subject: [PATCH] Doc cleanup * doc/lispref/files.texi (File Locks, Changing Files) (File Name Components, File Name Expansion, Magic File Names): * lisp/files.el (locate-dominating-stop-dir-regexp) (auto-mode-alist, set-auto-mode, file-name-with-extension) (backup-directory-alist, wildcard-to-regexp) (save-buffers-kill-terminal): Doc fixes. * etc/NEWS: Fix typos. --- doc/lispref/files.texi | 12 ++++++------ etc/NEWS | 31 ++++++++++++++++--------------- lisp/files.el | 18 +++++++++--------- 3 files changed, 31 insertions(+), 30 deletions(-) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index dd9ce2cd011..5238597a465 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -718,7 +718,7 @@ Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. The file lock is really a file, a symbolic link with a special name, stored in the same directory as the file you are editing. The name is -constructed by prepending @file{.#} to the filename of the buffer. +constructed by prepending @file{.#} to the file name of the buffer. The target of the symbolic link will be of the form @code{@var{user}@@@var{host}.@var{pid}:@var{boot}}, where @var{user} is replaced with the current username (from @code{user-login-name}), @@ -1932,7 +1932,7 @@ is a symbolic link and @var{flag} is @code{nofollow}. @defun set-file-extended-attributes filename attribute-alist This function sets the Emacs-recognized extended file attributes for -@code{filename}. The second argument @var{attribute-alist} should be +@var{filename}. The second argument @var{attribute-alist} should be an alist of the same form returned by @code{file-extended-attributes}. The return value is @code{t} if the attributes are successfully set, otherwise it is @code{nil}. @@ -2145,7 +2145,7 @@ stripped if there is one. For example: Note that this function will error if @var{filename} or @var{extension} are empty, or if the @var{filename} is shaped like a -directory (i.e. if @code{directory-name-p} returns non-@code{nil}). +directory (i.e., if @code{directory-name-p} returns non-@code{nil}). @end defun @defun file-name-sans-extension filename @@ -2434,7 +2434,7 @@ might begin with a literal @samp{~}, you can use @code{(concat (file-name-as-directory directory) filename)} instead of @code{(expand-file-name filename directory)}. -Filenames containing @samp{.} or @samp{..} are simplified to their +File names containing @samp{.} or @samp{..} are simplified to their canonical form: @example @@ -3476,11 +3476,11 @@ identifies the remote system. This identifier string can include a host name and a user name, as well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename +system. For example, the remote identifier string for the file name @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can +file names, that means they are stored on the same file system and can be accessed locally with respect to each other. This means, for example, that it is possible to start a remote process accessing both files at the same time. Implementers of file name handlers need to diff --git a/etc/NEWS b/etc/NEWS index 7e95c20498c..605c4d228fc 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -173,7 +173,7 @@ looking at the doc string of a function that belongs to one of these groups. --- -** Improved "find definition" feature of *Help* buffers. +** Improved "find definition" feature of "*Help*" buffers. Now clicking on the link to find the definition of functions generated by 'cl-defstruct', or variables generated by 'define-derived-mode', for example, will go to the exact place where they are defined. @@ -906,7 +906,7 @@ String or list of strings specifying switches for Git log under VC. +++ *** New Summary buffer sort options for extra headers. The extra header sort option ('C-c C-s C-x') prompts for a header -and fails if no sort function has been defined. Sorting by +and fails if no sort function has been defined. Sorting by Newsgroups ('C-c C-s C-u') has been pre-defined. +++ @@ -1176,8 +1176,8 @@ can provide a better overview in a long list of available bindings. *** New keybinding 'C-h R' prompts for a manual to display and displays it. --- -*** Closing the *Help* buffer from the toolbar now buries the buffer. -In previous Emacs versions, the *Help* buffer was killed instead when +*** Closing the "*Help*" buffer from the toolbar now buries the buffer. +In previous Emacs versions, the "*Help*" buffer was killed instead when clicking the "X" icon in the tool bar. +++ @@ -1232,10 +1232,11 @@ There's also a Cham greeting in "etc/HELLO". --- *** New input methods for Lakota language orthographies. -Two orthographies are represented here, the Suggested Lakota Orthography -and what is known as the White Hat Orthography. Input methods lakota-slo-prefix, -lakota-slo-postfix, and lakota-white-hat-postfix have been added. -There is also a Lakota greeting in "etc/HELLO". +Two orthographies are represented here, the Suggested Lakota +Orthography and what is known as the White Hat Orthography. Input +methods 'lakota-slo-prefix', 'lakota-slo-postfix', and +'lakota-white-hat-postfix' have been added. There is also a Lakota +greeting in "etc/HELLO". ** Ispell @@ -2137,7 +2138,7 @@ Shift while typing 'C-a', i.e. 'C-S-a', will now highlight the text. +++ *** ERT can now output more verbose test failure reports. -If the EMACS_TEST_VERBOSE environment variable is set, failure +If the 'EMACS_TEST_VERBOSE' environment variable is set, failure summaries will include the failing condition. ** Miscellaneous @@ -2148,7 +2149,7 @@ This can be used to transform (and suppress) strings from entering the kill ring. --- -*** `C-u M-x dig' will now prompt for a query type to use. +*** 'C-u M-x dig' will now prompt for a query type to use. +++ *** rcirc now supports SASL authentication. @@ -2592,10 +2593,6 @@ GPG key servers can now be queried for keys with the 'M-x epa-search-keys' command. Keys can then be added to your personal key ring. -+++ -** Function 'lm-maintainer' was replaced with 'lm-maintainers'. -The former is now declared obsolete. - * New Modes and Packages in Emacs 28.1 @@ -2905,6 +2902,10 @@ These variables describe facts about the SQL standard and product-specific additions. There should be no need for users to customize them. +--- +** Function 'lm-maintainer' is replaced with 'lm-maintainers'. +The former is now declared obsolete. + * Lisp Changes in Emacs 28.1 @@ -3078,7 +3079,7 @@ been added, and takes a callback to handle the return status. +++ ** New function 'file-name-with-extension'. This function allows a canonical way to set/replace the extension of a -filename string. +file name. +++ ** New function 'file-backup-file-names'. diff --git a/lisp/files.el b/lisp/files.el index 39f4ca65b1d..859c193db99 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -1011,7 +1011,7 @@ Any directory whose name matches this regexp will be treated like a kind of root directory by `locate-dominating-file', which will stop its search when it bumps into it. The default regexp prevents fruitless and time-consuming attempts to find -special files in directories in which filenames are interpreted as hostnames, +special files in directories in which file names are interpreted as host names, or mount points potentially requiring authentication as a different user.") (defun locate-dominating-file (file name) @@ -2959,7 +2959,7 @@ ARC\\|ZIP\\|LZH\\|LHA\\|ZOO\\|[JEW]AR\\|XPI\\|RAR\\|CBR\\|7Z\\|SQUASHFS\\)\\'" . ("\\.xmp\\'" . image-mode) ("\\.xwd\\'" . image-mode) ("\\.yuv\\'" . image-mode))) - "Alist of filename patterns vs corresponding major mode functions. + "Alist of file name patterns vs corresponding major mode functions. Each element looks like (REGEXP . FUNCTION) or (REGEXP FUNCTION NON-NIL). \(NON-NIL stands for anything that is not nil; the value does not matter.) Visiting a file whose name matches REGEXP specifies FUNCTION as the @@ -3152,7 +3152,7 @@ To find the right major mode, this function checks for a -*- mode tag checks for a `mode:' entry in the Local Variables section of the file, checks if it uses an interpreter listed in `interpreter-mode-alist', matches the buffer beginning against `magic-mode-alist', -compares the filename against the entries in `auto-mode-alist', +compares the file name against the entries in `auto-mode-alist', then matches the buffer beginning against `magic-fallback-mode-alist'. If `enable-local-variables' is nil, or if the file name matches @@ -4901,8 +4901,8 @@ The extension (in a file name) is the part that begins with the last \".\". Trims a leading dot from the EXTENSION so that either \"foo\" or \".foo\" can be given. -Errors if the filename or extension are empty, or if the given -filename has the format of a directory. +Errors if the FILENAME or EXTENSION are empty, or if the given +FILENAME has the format of a directory. See also `file-name-sans-extension'." (let ((extn (string-trim-left extension "[.]"))) @@ -4941,7 +4941,7 @@ See also `backup-directory-alist'." (function :tag "Function"))) (defcustom backup-directory-alist nil - "Alist of filename patterns and backup directory names. + "Alist of file name patterns and backup directory names. Each element looks like (REGEXP . DIRECTORY). Backups of files with names matching REGEXP will be made in DIRECTORY. DIRECTORY may be relative or absolute. If it is absolute, so that all matching files @@ -4954,7 +4954,7 @@ For the common case of all backups going into one directory, the alist should contain a single element pairing \".\" with the appropriate directory name. -If this variable is nil, or it fails to match a filename, the backup +If this variable is nil, or it fails to match a file name, the backup is made in the original file's directory. On MS-DOS filesystems without long names this variable is always @@ -6780,7 +6780,7 @@ See also `make-auto-save-file-name'." (defun wildcard-to-regexp (wildcard) "Given a shell file name pattern WILDCARD, return an equivalent regexp. -The generated regexp will match a filename only if the filename +The generated regexp will match a file name only if the file name matches that wildcard according to shell rules. Only wildcards known by `sh' are supported." (let* ((i (string-match "[[.*+\\^$?]" wildcard)) @@ -7500,7 +7500,7 @@ If the current frame has no client, kill Emacs itself using With prefix ARG, silently save all file-visiting buffers, then kill. -If emacsclient was started with a list of filenames to edit, then +If emacsclient was started with a list of file names to edit, then only these files will be asked to be saved." (interactive "P") (if (frame-parameter nil 'client) -- 2.39.2