masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-05 03:39:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve documentation of directory-local variables

Browse source 
* lisp/files.el (hack-local-variables, normal-mode)
(after-find-file, find-file-hook): Mention directory-local
variables in the doc strings.  Suggested by Marcin Borkowski
<mbork@mbork.pl>.

* doc/emacs/custom.texi (File Variables, Directory Variables):
Clarify that directory-local variables are overridden by
file-local ones.
This commit is contained in:
Eli Zaretskii 2018-09-22 12:06:51 +03:00
parent c9c9756d21
commit 8b8a4c0aeb
2 changed files with 16 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

11
doc/emacs/custom.texi
View file

@ -1059,6 +1059,10 @@ local variable specifications; it automatically makes these variables
local to the buffer, and sets them to the values specified in the local to the buffer, and sets them to the values specified in the
file. file.
File local variables override directory local variables
(@pxref{Directory Variables}), if any are specified for a file's
directory.
@menu @menu
* Specifying File Variables:: Specifying file local variables. * Specifying File Variables:: Specifying file local variables.
* Safe File Variables:: Making sure file local variables are safe. * Safe File Variables:: Making sure file local variables are safe.
@ -1309,7 +1313,12 @@ confirmation about processing @code{eval} variables.
Sometimes, you may wish to define the same set of local variables to Sometimes, you may wish to define the same set of local variables to
all the files in a certain directory and its subdirectories, such as all the files in a certain directory and its subdirectories, such as
the directory tree of a large software project. This can be the directory tree of a large software project. This can be
accomplished with @dfn{directory-local variables}. accomplished with @dfn{directory-local variables}. File local
variables override directory local variables, so if some of the files
in a directory need specialized settings, you can specify the settings
for the majority of the directory's files in directory variables, and
then define file local variables in a few files which need the general
settings overridden.
@cindex @file{.dir-locals.el} file @cindex @file{.dir-locals.el} file
The usual way to define directory-local variables is to put a file The usual way to define directory-local variables is to put a file

9
lisp/files.el
View file

@ -493,7 +493,8 @@ The functions are called in the order given until one of them returns non-nil.")
(defcustom find-file-hook nil (defcustom find-file-hook nil
"List of functions to be called after a buffer is loaded from a file. "List of functions to be called after a buffer is loaded from a file.
The buffer's local variables (if any) will have been processed before the The buffer's local variables (if any) will have been processed before the
functions are called." functions are called. This includes directory-local variables, if any,
for the file's directory."
:group 'find-file :group 'find-file
:type 'hook :type 'hook
:options '(auto-insert) :options '(auto-insert)
@ -2369,7 +2370,7 @@ the file contents into it using `insert-file-contents-literally'."
_after-find-file-from-revert-buffer _after-find-file-from-revert-buffer
nomodes) nomodes)
"Called after finding a file and by the default revert function. "Called after finding a file and by the default revert function.
Sets buffer mode, parses local variables. Sets buffer mode, parses file-local and directory-local variables.
Optional args ERROR, WARN, and NOAUTO: ERROR non-nil means there was an Optional args ERROR, WARN, and NOAUTO: ERROR non-nil means there was an
error in reading the file. WARN non-nil means warn if there error in reading the file. WARN non-nil means warn if there
exists an auto-save file more recent than the visited file. exists an auto-save file more recent than the visited file.
@ -2454,7 +2455,7 @@ unless NOMODES is non-nil."
(defun normal-mode (&optional find-file) (defun normal-mode (&optional find-file)
"Choose the major mode for this buffer automatically. "Choose the major mode for this buffer automatically.
Also sets up any specified local variables of the file. Also sets up any specified local variables of the file or its directory.
Uses the visited file name, the -*- line, and the local variables spec. Uses the visited file name, the -*- line, and the local variables spec.
This function is called automatically from `find-file'. In that case, This function is called automatically from `find-file'. In that case,
@ -3485,6 +3486,8 @@ DIR-NAME is the name of the associated directory. Otherwise it is nil."
(defun hack-local-variables (&optional handle-mode) (defun hack-local-variables (&optional handle-mode)
"Parse and put into effect this buffer's local variables spec. "Parse and put into effect this buffer's local variables spec.
For buffers visitying files, also puts into effect directory-local
variables.
Uses `hack-local-variables-apply' to apply the variables. Uses `hack-local-variables-apply' to apply the variables.
If HANDLE-MODE is nil, we apply all the specified local If HANDLE-MODE is nil, we apply all the specified local