[Emacs-diffs] Changes to emacs/doc/emacs/custom.texi,v

[Michael W. Olson]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael W. Olson <mwolson>      08/05/19 22:36:10

Index: doc/emacs/custom.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/custom.texi,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- doc/emacs/custom.texi       5 Apr 2008 23:01:19 -0000       1.9
+++ doc/emacs/custom.texi       19 May 2008 22:36:08 -0000      1.10
@@ -796,6 +796,7 @@
                          of Emacs to run on particular occasions.
 * Locals::             Per-buffer values of variables.
 * File Variables::      How files can specify variable values.
+* Directory Variables:: How variable values can be specified by directory.
 @end menu
 
 @node Examining
@@ -1262,6 +1263,65 @@
 for confirmation when it finds these forms for the @code{eval}
 variable.
 
address@hidden Directory Variables
address@hidden Per-Directory Local Variables
address@hidden local variables in directories
address@hidden directory local variables
+
+  Emacs provides a way to specify local variable values per-directory.
+This can be done one of two ways.
+
+  The first approach is to put a special file, named
address@hidden, in a directory.  When opening a file, Emacs
+searches for @file{.dir-settings.el} starting in the file's directory
+and then moving up the directory hierarchy.  If
address@hidden is found, Emacs applies variable settings from
+the file to the new buffer.  If the file is remote, Emacs skips this
+search, because it would be too slow.
+
+  The file should hold a specially-constructed list.  This list maps
+Emacs mode names (symbols) to alists; each alist maps variable names
+to values.  The special mode name @samp{nil} means that the alist
+should be applied to all buffers.  Finally, a string key can be used
+to specify an alist which applies to a relative subdirectory in the
+project.
+
address@hidden
+((nil . ((indent-tabs-mode . t)
+         (tab-width . 4)
+         (fill-column . 80)))
+ (c-mode . ((c-file-style . "BSD")))
+ (java-mode . ((c-file-style . "BSD")))
+ ("src/imported"
+  . ((nil . ((change-log-default-name . "ChangeLog.local"))))))
address@hidden example
+
+  This example shows some settings for a hypothetical project.  This
+sets @samp{indent-tabs-mode} to @samp{t} for any file in the source
+tree, and it sets the indentation style for any C or Java source file
+to @samp{BSD}.  Finally, it specifies a different @file{ChangeLog}
+file name for any file in the project that appears beneath the
+directory @file{src/imported}.
+
+  The second approach to directory-local settings is to explicitly
+define a project class using @code{define-project-bindings}, and then
+to tell Emacs which directory roots correspond to that class, using
address@hidden  You can put calls to these functions in
+your @file{.emacs}; this can useful when you can't put
address@hidden in the directory for some reason.  For
+example, you could apply settings to an unwriteable directory this
+way:
+
address@hidden
+(define-project-bindings 'unwriteable-directory
+   '((nil . ((some-useful-setting . value)))))
+
+(set-directory-project "/usr/include/" 'unwriteable-directory)
address@hidden example
+
+  Unsafe directory-local variables are handled in the same way as
+unsafe file-local variables.
+
 @node Key Bindings
 @section Customizing Key Bindings
 @cindex key bindings