Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
[[de:Emacs]]
[[es:Emacs]]
[[fr:Emacs]]
[[ja:Emacs]]
[[sr:Emacs]]
[[zh-hans:Emacs]]
[[Wikipedia:Emacs|Emacs]] is an extensible, customizable, self-documenting real-
time display editor. At the core of Emacs lies an [[Wikipedia:Emacs Lisp|Emacs
Lisp]] interpreter, the language in which the majority of Emacs' built-in
functionality and extensions are implemented. GNU Emacs uses GTK as its X toolkit,
though it functions equally well within a CLI environment. The text-editing
capabilities of Emacs are often compared to that of [[vim]].
== Installation ==
If you want to fully enjoy all the extended features of Emacs without installing a
daunting amount of dependencies, you can use the PKGBUILD to customize your needs.
Using anything else than {{ic|gtk3}} you can get rid of gconf. Image and sound
support can be disabled as well. Run {{ic|./configure --help}} in Emacs source
folder to list all available options.
{{hc|PKGBUILD|<nowiki>
# ...
./configure --prefix=/usr --sysconfdir=/etc --libexecdir=/usr/lib \
--localstatedir=/var --with-x-toolkit=gtk2 --with-xft \
--without-gconf --without-sound
# ...
</nowiki>}}
== Running Emacs ==
Before launching emacs, you should know how to close it (especially if you run it
in a terminal): use the
{{ic|Ctrl+x}}{{ic|Ctrl+c}} key sequence.
$ emacs
$ emacs -nw
or, for fast loading (no .emacs) and editing within CLI:
$ emacs -Q -nw
If you installed the nox version, 'emacs' and 'emacs -nw' will be the same.
$ emacs filename.txt
By default, Emacs starts with a color theme showing hyperlinks in dark blue. To
start Emacs on a text terminal without any color theme or scheme:
This will cause all text to appear in the foreground color of the terminal —
normally white text on a black background, or black text on a white background.
In order to avoid reloading the Emacs config file every time Emacs starts, you can
run Emacs as a daemon:
$ emacs --daemon
$ emacsclient -nc
Which creates a new frame {{ic|-c}} (use {{ic|-t}} if you prefer to use it in the
terminal) and does not hog the terminal {{ic|-n}} ({{ic|--no-wait}}).
Note that some programs such as Mutt or Git (for commit messages) wait for the
editor to finish, so you cannot use the {{ic|-n}} parameter.
If your default editor is set to use it, you will have to specify an alternate
editor (''e.g.'' {{ic|emacsclient -a "" -t}}) for those programs.
A systemd unit is included in Emacs 26.1. The unit is installed with Emacs, but it
must be enabled after installing Emacs:
Run this command as the user you want to run the Emacs server as; do not run the
command as root. After the service is started, Emacs is ready. The unit file is
stored in /usr/lib/systemd/user/emacs.service. Here is the contents of the unit
file for reference:
{{hc|/usr/lib/systemd/user/emacs.service|<nowiki>
[Unit]
Description=Emacs text editor
Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/
[Service]
Type=simple
ExecStart=/usr/bin/emacs --fg-daemon
ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"
Environment=SSH_AUTH_SOCK=%t/keyring/ssh
Restart=on-failure
[Install]
WantedBy=default.target
</nowiki>}}
Note that systemd user units do not inherit environment variables from a login
shell (like {{ic|~/.bash_profile}}), so you may want to set the variables in {{ic|
~/.pam_environment}} instead. See [[Systemd/User]] for more information.
If you start emacs as a daemon, you may want to set the {{ic|VISUAL}} and {{ic|
EDITOR}} environment variables to {{ic|emacsclient}} so that programs that start an
editor use emacsclient instead of starting a new full instance of the editor.
Programs that use an external editor include email programs (for editing the
message), Git (for editing the commit message), and less (the {{ic|v}} command for
editing the displayed file). Do not use the {{ic|-n}} ({{ic|--nowait}}) option to
emacsclient, since programs typically expect editing to be finished when the editor
exits.
It is also recommended to change any GUI start menu entries (or equivalent) for
Emacs to point to emacsclient instead of emacs, so that the emacs daemon is used
instead of starting a new emacs process.
== Getting help ==
Emacs has a built-in tutorial which can be accessed by clicking the first link on
the splash screen and selecting ''Help->Emacs Tutorial'' from the menu or by
pressing {{ic|C-h t}}.
Emacs also includes a set of reference cards, useful for beginners and experts
alike, see {{ic|/usr/share/emacs/<version>/etc/refcards/}} (substitute <version>
for your version of emacs).
If you really want to master Emacs, the most recommended source of documentation
remains the official manuals:
* Emacs: the complete Emacs user manual.
* Emacs FAQ.
* Emacs Lisp Intro: if you never used any programming language before.
* Elisp: if you are already familiar with a programming language.
Some users prefer to read books using 'info' because of its convenient shortcuts,
its paragraphs adapting to window width and the font adapted to current screen
resolution. Some find it less irritating to the eyes. Finally you can easily copy
content from the book to any Emacs buffer, and you can even execute Lisp code
snippets directly from the examples.
You may want to read the '''Info''' book to know more about it: '''C-h i m info
<RET>'''.
Press '''?''' while in info mode for a quick list of shortcuts.
== Customization ==
One of Emacs's main features is its extensibility and the ease of configuration.
Emacs has a built-in customization engine. You can do {{ic|M-x customize}} which
displays a list of customization options. For how to use this interface, see the
Easy Customization info node: {{ic|(info "(emacs) Easy Customization")}}. You can
set customization opens just for one Emacs session or save them into a
[[#Configuration file]] so that they are saved across Emacs sessions. Note that
this is what the customization interface does if you select "Apply and Save."
To prompt for the root password before opening /etc/hosts with root permissions:
To connect to 'remotehost' as 'you' via SSH and open the file ~/example.txt:
/ssh:you@remotehost|sudo:remotehost:/etc/hosts
TRAMP supports much more than the examples above might indicate. For more
information refer to the TRAMP info manual, which is distributed with Emacs.
By default, Git provides support for using Emacs' Emerge mode as a merge tool.
However you may prefer the Ediff mode. Unfortunately this mode is not supported by
git for technical reasons. There is still a way to use it by evaluating some elisp
code upon emacs call.
{{hc|.gitconfig|<nowiki>
[mergetool.ediff]
cmd = emacs --eval \" (progn (defun ediff-write-merge-buffer () (let ((file
ediff-merge-store-file)) (set-buffer ediff-buffer-C) (write-region (point-min)
(point-max) file) (message \\\"Merge buffer saved in: %s\\\" file) (set-buffer-
modified-p nil) (sit-for 1))) (setq ediff-quit-hook 'kill-emacs ediff-quit-merge-
hook 'ediff-write-merge-buffer) (ediff-merge-files-with-
ancestor \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$BASE\\\" nil \\\"$MERGED\\\"))\"
[merge]
tool = ediff
</nowiki>}}
If you want an instant startup you can use the '''-q''' parameter. If you want to
launch Emacs quickly while preserving at least a part of your configuration, you
can call Emacs with
emacs -q -l ~/.emacs-light
where the light configuration file loads only what you need for Ediff.
Some users like this behavior to avoid the so-called 'emacs pinky'. If you want to
try it on X, just run
Now, if you ever need to upcase an region, just use the default {{ic|C-x C-u}}
keybinding, which calls the {{ic|upcase-region}} function.
If you are missing your Caps Lock function, map it as both "Shift" at same time.
Opening a new file in the same {{ic|emacs-session}} requires the use of {{ic|
emacsclient}}. {{ic|emacs}} command can be itself wrapped to do the smarter job to
open the file if the session exists.
To start session you need to {{ic|start-server}}. This snippet will create server
in first session of emacs. Add this to your {{ic|emacs}} configuration file.
{{hc|.emacs or .emacs.d/init.el|
(require 'server)
(unless (server-running-p)
(server-start))
}}
Shell alias method is not adequate for this since you also need to pass variables
or start the independent session of your own. Add this to the {{ic|.bashrc}} or any
rc file of your shell. This will make your {{ic|$ emacs}} command behave like
emacsclient if the argument is passed.
<nowiki>
function emacs {
if [[ $# -eq 0 ]]; then
/usr/bin/emacs # "emacs" is function, will cause recursion
return
fi
args=($*)
for ((i=0; i <= ${#args}; i++)); do
local a=${args[i]}
# NOTE: -c for creating new frame
if [[ ${a:0:1} == '-' && ${a} != '-c' ]]; then
/usr/bin/emacs ${args[*]}
return
fi
done
setsid emacsclient -n -a /usr/bin/emacs ${args[*]}
} </nowiki>
You can use several configurations and tell Emacs to load one or the other.
{{hc|.emacs|
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/plugins" nil t)
(load "~/.emacs.d/theme" nil t)
}}
This is the full configuration we load for the daemon. But the ''plugins'' file is
huge and slow to load. If we want to spawn a new Emacs instance that does not need
the ''plugins'' features, it can be cumbersome to load it everytime in the long
run.
{{hc|.emacs-light|
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/theme" nil t)
}}
You can define variables in your configuration file that can be later one modified
locally for a file.
Now in any file you can define local variables in two ways, see
[https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-
Variables.html the manual for complete details ]
Note that for the values to take effect, you will need to call {{ic|M-x revert-
buffer}}.
Custom variables are considered unsafe by default. If you try to open a file that
contains local variable redefining custom variables, Emacs will ask you for
confirmation.
You can declare the variable as secure, thus removing the Emacs prompt for
confirmation. You need to specify a predicate that any new value has to verify so
that it can be considered safe.
In the previous example, if you attempt to set anything else than a string, Emacs
will consider it insecure.
You can have let Emacs tell you the name of the face where the point is. Use the
''customize-face'' function for that. The facility will show you how to set colors,
bold, underline, etc.
Emacs in console can handle 256 colors, but you will have to use an appropriate
terminal for that. For instance URxvt has support for 256 colors. You can use the
''list-colors-display'' for a comprehensive list of supported colors. This is
highly terminal-dependent.
See also:
* https://www.emacswiki.org/emacs/ColorThemes
* https://www.gnu.org/software/emacs/manual/html_node/emacs/Custom-Themes.html
Emacs is a powerful LaTeX editor. This is mostly due to the fact you can adapt or
create a LaTeX mode to fit your needs best.
Still, there might be some challenges, like SyncTeX support. First you need to make
sure your TeX distribution has it. If you installed TeX Live manually, you may need
to install the ''synctex'' package.
# umask 022 && tlmgr install synctex
Simple command:
zathura --fork
We can use
to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes
matter and must be escaped appropriately."
:safe 'stringp)
Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-
mode, you will have to set the viewer accordingly.
Now open a LaTeX source file with Emacs, compile the document, and launch the
viewer. Zathura will spawn. If you press {{ic|Ctrl+Left click}} Emacs should place
the point at the corresponding position.
Alternatively, you can simply tell emacs to colour systemd files (services, timer,
etc.), by adding this to your init file:
To use the [[Xorg]] clipboard in emacs-nox, [[install]] {{Pkg|xclip}} and add the
following function to {{ic|~/.emacs}} [https://lists.gnu.org/archive/html/help-gnu-
emacs/2014-08/msg00189.html]
{{bc|1=
;; use xclip to copy/paste in emacs-nox
(unless window-system
(when (getenv "DISPLAY")
(defun xclip-cut-function (text &optional push)
(with-temp-buffer
(insert text)
(call-process-region (point-min) (point-max) "xclip" nil 0 nil "-i" "-
selection" "clipboard")))
(defun xclip-paste-function()
(let ((xclip-output (shell-command-to-string "xclip -o -selection
clipboard")))
(unless (string= (car kill-ring) xclip-output)
xclip-output )))
(setq interprogram-cut-function 'xclip-cut-function)
(setq interprogram-paste-function 'xclip-paste-function)
))
}}
== Packages ==
Third-party package archives can be added. The most widely used of these is
[https://melpa.org/ MELPA].
Some packages may require you to make changes to your configuration file in order
to activate them so that their features are available during an Emacs session. For
example, if you install {{Pkg|auctex}}, you will need to add
{{bc|
(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)}}
to your configuration file. Other packages should let you know how to activate them
in the commentary section of their source code or in their README.
== Troubleshooting ==
=== Emacs fails to start with the error message 'Undefined color:
"WINDOW_FOREGROUND"' ===
You need to install either the {{Pkg|mcpp}} package or the {{Pkg|gcc}} package. The
C preprocessor ''cpp'' is used to preprocess [[X resources]] by ''xrdb''. If a C
preprocessor is not installed on the system, ''xrdb'' silently skips running the C
preprocessor and the symbol WINDOW_FOREGROUND is not expanded to a hexadecimal
color code.
By default, the Emacs shell will show raw escape sequences used to print colors. In
other words, it will display strange symbols in place of the desired colored
output.
If when you start emacs in X windows all the characters in the main window are
white boxes with black borders (the ones you see if you try to view characters for
which you do not have the correct font installed), you need to install {{Pkg|xorg-
fonts-75dpi}} and/or {{Pkg|xorg-fonts-100dpi}} and restart X windows.
{{Tip|To eliminate startup time, users may want to consider running Emacs [[#As a
systemd unit]].}}
$ emacs -q
* You may need to monitor any network packets sent from your computer (using a
program like Wireshark) to see if there is any strange behavior.
* A simple way to search for the cause is to comment-out (i.e., prefix lines with
';') suspect sections of your {{ic|~/.emacs}} (or {{ic|~/.emacs.d/init.el}}) then
start Emacs again to see if there is any change. Keep in mind use of "require" and
"load" can slow the startup down, especially when used with larger extensions.
They should, as a rule, only be used when their target is either: needed once Emacs
starts or provides little more than "autoloads" for an extension. Otherwise, use
the 'autoload function directly. For example, instead of:
(require 'anything)
you might use:
The most common cause of this error is the 'load-path' variable not including the
path to the directory within which the extension is located. To solve this, add
the appropriate path to the list to be searched prior to attempting to load the
extension:
When attempting to use packages for extensions and Emacs has been configured with a
prefix other than '/usr', the load-path will need to be updated. Place the
following in {{ic|~/.emacs}} prior to the instructions provided by the package:
If compiling Emacs by hand, keep in mind that the default prefix is '/usr/local'.
A way to solve it is just put the line above on your startup file, {{ic|~/.emacs}}:
(require 'iso-transl)
And no, it is not a bug, but a feature of new Emacs versions. Reading the
subsequent messages about it on the mail list, we found it
(http://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00179.html):
:''It seems that nothing is loaded automatically because there is a choice betwee
iso-transl and iso-acc. Both seem to provide an input method with C-x 8 or Alt-
<accent> prefix, but what you and I are doing is just pressing a dead key (^, �, `,
~, �) for the accent and then another key to "compose" the accented character. And
there is no Alt key used in this! And according to documentation it seems be
appropriate for 8-bit encodings, so it should be pretty useless in UTF-8. I
reported this bug when it was introduced, but the bug seems to be classified as a
feature ... Maybe it's just because the file is auto-loaded though pretty useless.
''
=== C-M-% and some other bindings do not work in emacs nox ===
This is because terminals are more limited than Xorg. Some terminals may handle
more bindings than other, though. Two solutions:
* either use the graphical version,
* or change the binding to a supported one.
Example:
{{hc|.emacs|
(global-set-key (kbd "C-M-y") 'query-replace-regexp)
}}
Due to its single-threaded nature, many operations block Emacs. This could happen
in a few ways. For example, Emacs may be waiting for input from you (e.g. you've
opened the minibuffer in one frame but are trying to work in another).
Alternatively, Emacs could be running code that simply takes a while to finish. Or
perhaps you've run across a bug. There are several ways of trying to unblock Emacs
without killing the Emacs process.
* Try pressing {{ic|C-g}}. Depending on what Emacs is doing, you may need to press
it multiple times.
* Try pressing {{ic|ESC ESC ESC}}.
* From another terminal, run {{ic|killall -SIGUSR2 emacs}}
{{hc||
head=$ ~/.bashrc or ~/.zshrc |output=export LANG\='en_US.UTF-8'
export LC_ALL\="en_US.UTF-8"
export TERM\=xterm-256color
}}
It can be a source of errors since in Linux distributions the correct values use
lowercase utf (e.g. en_US.utf-8)
=== Shift + Arrow keys not working in emacs within tmux ===
{{hc|~/.tmux.conf|
setw -g xterm-keys on
}}
Because this will break other key combinations, put the following in your emacs
config.
{{hc|~/.emacs|
(defadvice terminal-init-screen
;; The advice is named `tmux', and is run before `terminal-init-screen' runs.
(before tmux activate)
;; Docstring. This describes the advice and is made available inside emacs;
;; for example when doing C-h f terminal-init-screen RET
"Apply xterm keymap, allowing use of keys passed through tmux."
;; This is the elisp code that is run before `terminal-init-screen'.
(if (getenv "TMUX")
(let ((map (copy-keymap xterm-function-map)))
(set-keymap-parent map (keymap-parent input-decode-map))
(set-keymap-parent input-decode-map map))))
}}
KDE users may observe that the Emacs window does not resize properly, but rather,
the resized portion
is transparent and mouse clicks are sent to the underlying window. To correct this
behavior, change
KDE's GTK3 theme to something other than oxygen-gtk. For instance, use the Emacs
theme which is included with {{Pkg|gtk3}}.
To force Emacs to maximize completely in KDE, click the Emacs icon in the title
bar, and select More Actions > Special Window Settings. Then in the "Size &
Position" tab, select "Obey geometry restrictions", choose "Force" in the dropdown
menu, and select "No" from the radio buttons on the right.
== Alternatives ==
=== mg ===
== See also ==