# HG changeset patch # User Eli Zaretskii # Date 1230307256 0 # Node ID f78a8298540c3bf6b9f30205c69fd7b49f06c3ff # Parent 0205517814da13c7a7af4a67dbb2be82acb3eef3 (Directory Variables): Explain what is a "project". Add indexing. Improve wording. Add a footnote about using _dir-locals.el on MS-DOS. diff -r 0205517814da -r f78a8298540c doc/emacs/custom.texi --- a/doc/emacs/custom.texi Fri Dec 26 15:05:11 2008 +0000 +++ b/doc/emacs/custom.texi Fri Dec 26 16:00:56 2008 +0000 @@ -1262,27 +1262,43 @@ @node Directory Variables @subsection Per-Directory Local Variables -@cindex local variables in directories +@cindex local variables, for all files in a directory @cindex directory local variables - - Emacs provides a mechanism 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 -@file{.dir-locals.el}, in a directory. When opening a file, Emacs -searches for @file{.dir-locals.el} starting in the file's directory -and then moving up the directory hierarchy. If -@file{.dir-locals.el} 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 +@cindex per-directory local variables + + A software @dfn{project} is a collection of files on which you work +together as part of the project. Usually, the project's files are +kept in one or more directories. Occasionally, you may wish to define +Emacs settings that are common to all the files that belong to the project. + Emacs provides two ways to specify settings that are applicable to +files in a specific directory: you can put a special file in that +directory, or you can define a @dfn{project class} for that directory. + +@cindex @file{.dir-locals.el} file + If you put a file with a special name @file{.dir-locals.el}@footnote{ +On MS-DOS, the name of this file should be @file{_dir-locals.el}, due +to limitations of the DOS filesystems. If the filesystem is limited +to 8+3 file names, the name of the file will be truncated by the OS to +@file{_dir-loc.el}. +} in a directory, Emacs will read it when it visits any file in that +directory or any of its subdirectories, and apply the settings it +specifies to the file's buffer. Emacs searches for +@file{.dir-locals.el} starting in the directory of the visited file, +and moving up the directory tree. (To avoid slowdown, this search is +skipped for remote files.) + + The @file{.dir-locals.el} file should hold a specially-constructed +list. This list maps Emacs mode names (symbols) to alists; each alist +specifies values for variables to use when the respective mode is +turned on. The special mode name @samp{nil} means that its alist +applies to any mode. Instead of a mode name, you can specify a string +that is a name of a subdirectory of the project's directory; then the +corresponding alist applies to all the files in that subdirectory. + + Here's an example of a @file{.dir-locals.el} file: + @example ((nil . ((indent-tabs-mode . t) (tab-width . 4) @@ -1293,21 +1309,26 @@ . ((nil . ((change-log-default-name . "ChangeLog.local")))))) @end 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 variables is to explicitly -define a project class using @code{dir-locals-set-class-variables}, and then -to tell Emacs which directory roots correspond to that class, using -@code{dir-locals-set-directory-class}. You can put calls to these functions in -your @file{.emacs}; this can be useful when you can't put -@file{.dir-locals.el} in the directory for some reason. For -example, you could apply settings to an unwritable directory this -way: +@noindent +This example shows some settings for a hypothetical project. It sets +@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for +any file in the project's directory tree, and it sets the indentation +style for any C or Java source file. Finally, it specifies a different +@file{ChangeLog} file name for any file in the @file{src/imported} +subdirectory of the directory where you put the @file{.dir-locals.el} +file. + +@findex dir-locals-set-class-variables +@findex dir-locals-set-directory-class + Another method of specifying directory-local variables is to explicitly +define a project class using @code{dir-locals-set-class-variables}, and +then tell Emacs which directories correspond to that class, using +@code{dir-locals-set-directory-class}. You can put calls to these functions +in your @file{~/.emacs} init file; this can be useful when you can't put +@file{.dir-locals.el} in the directory for some reason, or if you want +to keep in a single place settings for several directories that don't +have a common parent. For example, you could apply settings to an +unwritable directory this way: @example (dir-locals-set-class-variables 'unwritable-directory