diff options
Diffstat (limited to 'doc/emacs/custom.texi')
| -rw-r--r-- | doc/emacs/custom.texi | 143 |
1 files changed, 120 insertions, 23 deletions
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 3fd655048b4..fae5433f877 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -380,7 +380,7 @@ lines of code to your initialization file, to set the variable file. For example: @example -(setq custom-file "~/.emacs-custom.el") +(setq custom-file "~/.config/emacs-custom.el") (load custom-file) @end example @@ -390,14 +390,14 @@ Emacs versions, like this: @example (cond ((< emacs-major-version 22) ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) + (setq custom-file "~/.config/custom-21.el")) ((and (= emacs-major-version 22) (< emacs-minor-version 3)) ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.custom-22.el")) + (setq custom-file "~/.config/custom-22.el")) (t ;; @r{Emacs version 22.3 or later.} - (setq custom-file "~/.emacs-custom.el"))) + (setq custom-file "~/.config/emacs-custom.el"))) (load custom-file) @end example @@ -765,6 +765,8 @@ expects (@pxref{Examining}). * Locals:: Per-buffer values of variables. * File Variables:: How files can specify variable values. * Directory Variables:: How variable values can be specified by directory. +* Connection Variables:: Variables which are valid for buffers with a + remote default directory. @end menu @node Examining @@ -799,6 +801,7 @@ Its value is 70 Automatically becomes buffer-local when set. This variable is safe as a file local variable if its value satisfies the predicate ‘integerp’. + Probably introduced at or before Emacs version 18. Documentation: Column beyond which automatic line-wrapping should happen. @@ -1358,7 +1361,8 @@ files in that subdirectory. @example ((nil . ((indent-tabs-mode . t) - (fill-column . 80))) + (fill-column . 80) + (mode . auto-fill))) (c-mode . ((c-file-style . "BSD") (subdirs . nil))) ("src/imported" @@ -1367,13 +1371,16 @@ files in that subdirectory. @end example @noindent -This sets @samp{indent-tabs-mode} and @code{fill-column} for any file -in the directory tree, and the indentation style for any C source -file. The special @code{subdirs} element is not a variable, but a -special keyword which indicates that the C mode settings are only to -be applied in the current directory, not in any subdirectories. -Finally, it specifies a different @file{ChangeLog} file name for any -file in the @file{src/imported} subdirectory. +This sets the variables @samp{indent-tabs-mode} and @code{fill-column} +for any file in the directory tree, and the indentation style for any +C source file. The special @code{mode} element specifies the minor +mode to be enabled. So @code{(mode . auto-fill)} specifies that the +minor mode @code{auto-fill-mode} needs to be enabled. The special +@code{subdirs} element is not a variable, but a special keyword which +indicates that the C mode settings are only to be applied in the +current directory, not in any subdirectories. Finally, it specifies a +different @file{ChangeLog} file name for any file in the +@file{src/imported} subdirectory. If the @file{.dir-locals.el} file contains multiple different values for a variable using different mode names or directories, the values @@ -1443,6 +1450,52 @@ variables are handled in the same way as unsafe file-local variables do not visit a file directly but perform work within a directory, such as Dired buffers (@pxref{Dired}). +@node Connection Variables +@subsection Per-Connection Local Variables +@cindex local variables, for all remote connections +@cindex connection-local variables +@cindex per-connection local variables + + Most of the variables reflect the situation on the local machine. +Often, they must use a different value when you operate in buffers +with a remote default directory. Think about the shell to be applied +when calling @code{shell} -- it might be @file{/bin/bash} on your +local machine, and @file{/bin/ksh} on a remote machine. + + This can be accomplished with @dfn{connection-local variables}. +Directory and file local variables override connection-local +variables. Unsafe connection-local variables are handled in the same +way as unsafe file-local variables (@pxref{Safe File Variables}). + +@findex connection-local-set-profile-variables +@findex connection-local-set-profiles + Connection-local variables are declared as a group of +variables/value pairs in a @dfn{profile}, using the +@code{connection-local-set-profile-variables} function. The function +@code{connection-local-set-profiles} activates profiles for a given +criteria, identifying a remote machine: + +@example +(connection-local-set-profile-variables 'remote-ksh + '((shell-file-name . "/bin/ksh") + (shell-command-switch . "-c"))) + +(connection-local-set-profile-variables 'remote-bash + '((shell-file-name . "/bin/bash") + (shell-command-switch . "-c"))) + +(connection-local-set-profiles + '(:application tramp :machine "remotemachine") 'remote-ksh) +@end example + + This code declares two different profiles, @code{remote-ksh} and +@code{remote-bash}. The profile @code{remote-ksh} is applied to all +buffers which have a remote default directory matching the regexp +@code{"remotemachine} as host name. Such a criteria can also +discriminate for the properties @code{:protocol} (this is the Tramp +method) or @code{:user} (a remote user name). The @code{nil} criteria +matches all buffers with a remote default directory. + @node Key Bindings @section Customizing Key Bindings @cindex key bindings @@ -2166,16 +2219,28 @@ as a function from Lisp programs. @cindex init file @cindex .emacs file @cindex ~/.emacs file +@cindex ~/.config/emacs file @cindex Emacs initialization file @cindex startup (init file) When Emacs is started, it normally tries to load a Lisp program from an @dfn{initialization file}, or @dfn{init file} for short. This file, if it exists, specifies how to initialize Emacs for you. Emacs -looks for your init file using the filenames @file{~/.emacs}, -@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to -use any one of these three names (@pxref{Find Init}). Here, @file{~/} -stands for your home directory. +looks for your init file using the filenames +@file{~/.config/emacs},. @file{~/.emacs}, @file{~/.config/emacs.el}, +@file{~/.emacs.el}, @file{~/.config/emacs.d/init.el} or +@file{~/.emacs.d/init.el}; you can choose to use any one of these +names (@pxref{Find Init}). Here, @file{~/} stands for your home +directory. + + While the @file{~/.emacs} and @file{~/.emacs.d/init.el} locations +are backward-compatible to older Emacs versions, and the rest of this +chapter will use them to name your initialization file, it is better practice +to group all of your dotfiles under @file{.config} so that if you have +to troubleshoot a problem that might be due to a bad init file, or +archive a collection of them, it can be done by renaming or +copying that directory. Note that the @file{.config} versions +don't have a leading dot on the basename part of the file. You can use the command line switch @samp{-q} to prevent loading your init file, and @samp{-u} (or @samp{--user}) to specify a @@ -2233,6 +2298,7 @@ Manual}. * Terminal Init:: Each terminal type can have an init file. * Find Init:: How Emacs finds the init file. * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +* Early Init File:: Another init file, which is read early on. @end menu @node Init Syntax @@ -2580,15 +2646,16 @@ library. @xref{Hooks}. @node Find Init @subsection How Emacs Finds Your Init File - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). + Normally Emacs uses your home directory to find +@file{~/.config/emacs} or @file{~/.emacs}; that's what @samp{~} means +in a file name. @xref{General Variables, HOME}. If none of +@file{~/.config/emacs}, @file{~/.emacs}, @file{~/.config/emacs.el} nor +@file{~/.emacs.el} is found, Emacs looks for +@file{~/.config/emacs.d/init.el} or @file{~/.emacs.d/init.el} (these, +like @file{~/.emacs.el}, can be byte-compiled). However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are +tries to find your own initialization files, not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user. @@ -2634,6 +2701,36 @@ instance: @noindent Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. +@node Early Init File +@subsection The Early Init File +@cindex early init file + + Most customizations for Emacs should be put in the normal init file, +@file{.config/emacs} or @file{~/.config/emacs.d/init.el}. However, it is sometimes desirable +to have customizations that take effect during Emacs startup earlier than the +normal init file is processed. Such customizations can be put in the early +init file, @file{~/.config/emacs.d/early-init.el} or @file{~/.emacs.d/early-init.el}. This file is loaded before the +package system and GUI is initialized, so in it you can customize variables +that affect frame appearance as well as the package initialization process, +such as @code{package-enable-at-startup}, @code{package-load-list}, and +@code{package-user-dir}. Note that variables like @code{package-archives} +which only affect the installation of new packages, and not the process of +making already-installed packages available, may be customized in the regular +init file. @xref{Package Installation}. + + We do not recommend that you move into @file{early-init.el} +customizations that can be left in the normal init files. That is +because the early init file is read before the GUI is initialized, so +customizations related to GUI features will not work reliably in +@file{early-init.el}. By contrast, the normal init files are read +after the GUI is initialized. If you must have customizations in the +early init file that rely on GUI features, make them run off hooks +provided by the Emacs startup, such as @code{window-setup-hook} or +@code{tty-setup-hook}. @xref{Hooks}. + + For more information on the early init file, @pxref{Init File,,, +elisp, The Emacs Lisp Reference Manual}. + @node Authentication @section Keeping Persistent Authentication Information |