https://wiki.archlinux.org/api.php?action=feedcontributions&user=Oblique&feedformat=atomArchWiki - User contributions [en]2024-03-29T02:29:25ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_X1_Carbon_(Gen_5)&diff=501124Lenovo ThinkPad X1 Carbon (Gen 5)2017-12-05T13:29:57Z<p>Oblique: Add second solution for the Trackpoint/Trackpad bug</p>
<hr />
<div>[[Category:Lenovo]]<br />
[[ja:Lenovo ThinkPad X1 Carbon (Gen 5)]]<br />
{{Related articles start}}<br />
{{Related|Lenovo ThinkPad X1 Carbon}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 2)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 3)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 4)}}<br />
{{Related articles end}}<br />
<br />
{{tip| A great resource for thinkpads is http://www.thinkwiki.org/wiki/ThinkWiki}}<br />
<br />
== Model description ==<br />
<br />
Lenovo ThinkPad X1 Carbon, Gen 5.<br />
<br />
To ensure you have this version, run ''dmidecode'':<br />
<br />
{{bc|# dmidecode -t system &#124; grep Version<br />
<br />
Version: ThinkPad X1 Carbon 5th<br />
}}<br />
<br />
=== Support ===<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration#iwlwifi]] || {{Yes}}<br />
|-<br />
| Native Ethernet with [http://shop.lenovo.com/us/en/itemdetails/4X90F84315/460/D60A78A4A48A422E9761BD184AD3750A Dongle] || {{Yes}}<br />
|-<br />
| Mobile broadband || {{Yes}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Yes}}<br />
|-<br />
| [[TrackPoint]] || {{Yes}}*<br />
|-<br />
| Camera || {{Yes}}<br />
|-<br />
| Fingerprint Reader || {{No}}<br />
|-<br />
| [[Power management]] || {{Yes}}<br />
|-<br />
| [[Bluetooth]] || {{Yes}}<br />
|-<br />
| microSD card reader || {{Yes}}<br />
|}<br />
<br />
* Lenovo uses several different trackpoint types in the 5th generation X1 Carbon. Only the standard ALPS variant has Linux support.<br />
<br />
===Fingerprint Reader===<br />
The fingerprint reader included with this model `138a:0097 Validity Sensors, Inc` currently lacks a linux driver. [https://bugs.freedesktop.org/show_bug.cgi?id=94536 libfprint bugreport]. Synaptics (which has acquired 'Validity Sensors') has unofficially said that they cannot disclose the protocol, but may possibly release a binary driver.<br />
<br />
Open source Linux driver is being developed by reverse engineering the Windows driver. [https://github.com/nmikhailov/Validity90]<br />
<br />
===Bug: Fans blowing at max speed after resuming===<br />
There is a bug in the current kernel, causing the fans to often go on full throttle non-stop after resuming from suspend-to-ram.<br />
<br />
'''This bug is fixed since the kernel 4.12.4-1.'''<br />
<br />
Set of patches available for older version: https://bugzilla.kernel.org/show_bug.cgi?id=196129#c26<br />
<br />
If you have an older version of the kernel, you need to manually patch the kernel or work around the issue by repeatedly suspend (<kbd>Fn+4</kbd>) and resume (<kbd>Fn</kbd>) until it resumes without the fans starting with a short burst of activity. For me, the issue arises in about 2/3 resumes without the patches and never with kernel <br />
4.12.0-2 with patches.<br />
<br />
===Bug: Trackpoint/Trackpad not working===<br />
Several different trackpoints are used with the X1 Carbon Gen 5. There are at least three different trackpoints in use. You can identify them in dmesg as either LEN0071, LEN0072 or LEN0073. <br />
<br />
There is a bug in Synaptics drivers that prevent both Trackpoint and Trackpad to function properly if Trackpoint is enabled at boot. This issue affects the Elantech trackpoint as well as one of the ALPS variants. <br />
<br />
If you have the Elantech trackpoint, identified as LEN0073 you will see the following in your dmesg log.<br />
<br />
kernel: psmouse serio1: TouchPad at isa0060/serio1/input0 lost sync at byte 1<br />
kernel: psmouse serio1: TouchPad at isa0060/serio1/input0 lost sync at byte 1<br />
kernel: psmouse serio1: TouchPad at isa0060/serio1/input0 lost sync at byte 1<br />
kernel: psmouse serio1: TouchPad at isa0060/serio1/input0 lost sync at byte 1<br />
kernel: psmouse serio1: TouchPad at isa0060/serio1/input0 lost sync at byte 1<br />
kernel: psmouse serio1: issuing reconnect request<br />
<br />
====Solution 1====<br />
Installing {{AUR|linux-tp-x1-carbon-5th}} fixes this, see https://gist.github.com/ursm/6d1007f44a1d6beeb670b3c3a6a78ea4. Note that this only works on the Elantech trackpoint (LEN0073).<br />
<br />
====Solution 2====<br />
Since kernel v4.14 you can workaround this by adding {{ic|1=psmouse.synaptics_intertouch=1}} to your [[kernel parameters]].<br />
<br />
===Bug: System occasionally hanging during startup===<br />
I run Arch Linux with KDE and SDDM as login manager, and every second or third boot my system hangs on startup before X starts. This is caused by a bug in version 0.16.0 of SDDM, reported here:<br />
<br />
https://github.com/sddm/sddm/issues/905<br />
<br />
It can be solved by letting SDDM wait a little bit before starting. Just create the file '''/etc/systemd/system/sddm.service.d/override.conf''' with this content:<br />
{{bc|1=[Service]<br />
ExecStartPre=/bin/sleep 2<br />
}}<br />
<br />
== Configuration ==<br />
<br />
=== Keyboard Fn Shortcuts ===<br />
* Fn+4 sends XF86Sleep (puts computer to sleep by default)<br />
* Fn+S sends Alt_L+Sys_Req<br />
* Fn+P sends Pause<br />
* Fn+B sends Control_L+Break<br />
* Fn+K sends Scroll_Lock<br />
* Fn+Space toggles the keyboard backlight<br />
* Fn by itself sends XF86WakeUp (wakes computer from sleep by default)<br />
<br />
=== Display ===<br />
<br />
There are two options for displays:<br />
<br />
* 14" FHD IPS (1920 x 1080): Works<br />
* 14" WQHD (2560 x 1440): Works<br />
<br />
=== Backlight Control ===<br />
I had issues with the thinkpad_acpi module in linux-4.12 and linux-4.13. When loaded no acpi events are generated for Fn+F5 and Fn+F6 keypress by default, because<br />
{{bc|<br />
kernel: thinkpad_acpi: This ThinkPad has standard ACPI backlight brightness control, supported by the ACPI video driver<br />
kernel: thinkpad_acpi: Disabling thinkpad-acpi brightness events by default...<br />
kernel: thinkpad_acpi: Standard ACPI backlight interface available, not loading native one<br />
}}<br />
Setting the acpi_brightness=vendor kernel parameter helped but gave issues with brightness save/restore. In linux-4.14 this issue is resolved.<br />
<br />
=== TrackPoint Scrolling ===<br />
TrackPoint Scrolling is working out of the box in GNOME and MATE.<br />
In some WindowManagers, the TrackPoint middle-button scrolling can be enabled by [[installing]] the {{Pkg|xorg-xinput}} package from the [[official repositories]] and appending the following line to your [[.xinitrc]]:<br />
{{bc|xinput set-prop "TPPS/2 IBM TrackPoint" "libinput Scroll Method Enabled" 0 0 1}}<br />
<br />
=== Lenovo ThinkPad Thunderbolt 3 Dockingstation ===<br />
The USB-C Dock is a Thunderbolt 3 device. Plugging it in results in a whole lot of PCI entries:<br />
<br />
06:00.0 PCI bridge: Intel Corporation JHL6540 Thunderbolt 3 Bridge (C step) [Alpine Ridge 4C 2016] (rev 02)<br />
07:00.0 PCI bridge: Intel Corporation JHL6540 Thunderbolt 3 Bridge (C step) [Alpine Ridge 4C 2016] (rev 02)<br />
07:01.0 PCI bridge: Intel Corporation JHL6540 Thunderbolt 3 Bridge (C step) [Alpine Ridge 4C 2016] (rev 02)<br />
07:02.0 PCI bridge: Intel Corporation JHL6540 Thunderbolt 3 Bridge (C step) [Alpine Ridge 4C 2016] (rev 02)<br />
07:04.0 PCI bridge: Intel Corporation JHL6540 Thunderbolt 3 Bridge (C step) [Alpine Ridge 4C 2016] (rev 02)<br />
3c:00.0 USB controller: Intel Corporation Device 15d4 (rev 02)<br />
<br />
The dock works nearly perfect out of the box with Kernel 4.10.13. Even hot plugging works: unplugging the dock while a display is connected just lets all the devices disappear. Replugging it later works, all the USB devices come back up automagically, thought you might need to issue a xrandr to get the display showing again (tested with Xorg based i3 setup).<br />
<br />
<br />
==== Ethernet ====<br />
<br />
The r8152 based USB Ethernet Port does not work out of the box. It gives the message:<br />
[ 7.574773] r8152 4-1.1:1.0 (unnamed net_device) (uninitialized): Unknown version 0x6010<br />
Installing {{AUR|r8152-dkms}} fixes this (the DKMS module adds the version 0x6010 to the module).<br />
<br />
==== USB ====<br />
<br />
In order for the internal USB hub in the dock to work without having to boot with the dock connected to your computer, you need to set "Security Level" to "No Security" under Thuderbolt settings in BIOS. Also remember to enable the "Support in pre boot environment" for USB peripherals connected to the dock to work at all.<br />
<br />
=== HP Thunderbolt 3 Dock ===<br />
The HP Thunderbolt 3 Dock is working out of the box.<br />
<br />
=== Lenovo p27h-10 (USB Type C) ===<br />
Charging while using the monitor via USB-Type-C is working but the dock functionality needs investigation (e.g. speakers, mouse, directly from the monitor).</div>Obliquehttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=276828Software access point2013-09-27T20:13:31Z<p>Oblique: </p>
<hr />
<div>[[ru:Software Access Point]]<br />
[[Category:Wireless Networking]]<br />
{{Article summary start}}<br />
{{Article summary text|Basic setup of wifi access point.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Network Configuration}}<br />
{{Article summary wiki|Wireless Setup}}<br />
{{Article summary wiki|Ad-hoc networking}}<br />
{{Article summary wiki|Internet Share}}<br />
{{Article summary end}}<br />
A software access point is used when you want your computer to act as an wifi access point for the local wireless network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
* A nl80211 compatible wireless device (e.g. ath9k)<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''wifi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wifi Link Layer ==<br />
<br />
The actual Wifi link is established via the {{Pkg|hostapd}} package. That package is compatible with WPA2.<br />
<br />
[[pacman|Install]] the {{Pkg|hostapd}} package from the [[Official Repositories|official repositories]].<br />
<br />
Create the config file of hostapd {{ic|/etc/hostapd/hostapd.conf}}. <br />
<br />
Adjust the options as necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}.<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWifiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal WiFi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is more simple, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dialup connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT aproach is more versatile, as it clearly separates wifi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own. <br />
<br />
If you use [[netctl]], see [[Bridge with netctl]] for details (just do not add {{ic|tap0}} used in that example).<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet Share]] for details.<br />
<br />
On that article, the device connected to the lan is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Scripts ==<br />
<br />
[https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap] script combines {{Pkg|hostapd}}, [[dnsmasq]] and [[iptables]] to create a NATed Access Point.<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/RTFM-AP hostapd Linux documentation page]<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wifi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Obliquehttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=276827Software access point2013-09-27T20:12:21Z<p>Oblique: /* NAT Setup */</p>
<hr />
<div>[[ru:Software Access Point]]<br />
[[Category:Wireless Networking]]<br />
{{Article summary start}}<br />
{{Article summary text|Basic setup of wifi access point.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Network Configuration}}<br />
{{Article summary wiki|Wireless Setup}}<br />
{{Article summary wiki|Ad-hoc networking}}<br />
{{Article summary wiki|Internet Share}}<br />
{{Article summary end}}<br />
A software access point is used when you want your computer to act as an wifi access point for the local wireless network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
* A nl80211 compatible wireless device (e.g. ath9k)<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''wifi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wifi Link Layer ==<br />
<br />
The actual Wifi link is established via the {{Pkg|hostapd}} package. That package is compatible with WPA2.<br />
<br />
[[pacman|Install]] the {{Pkg|hostapd}} package from the [[Official Repositories|official repositories]].<br />
<br />
Create the config file of hostapd {{ic|/etc/hostapd/hostapd.conf}}. <br />
<br />
Adjust the options as necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}.<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWifiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal WiFi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is more simple, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dialup connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT aproach is more versatile, as it clearly separates wifi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own. <br />
<br />
If you use [[netctl]], see [[Bridge with netctl]] for details (just do not add {{ic|tap0}} used in that example).<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet Share]] for details.<br />
<br />
On that article, the device connected to the lan is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/RTFM-AP hostapd Linux documentation page]<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wifi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Obliquehttps://wiki.archlinux.org/index.php?title=Emacs&diff=259425Emacs2013-05-28T23:41:31Z<p>Oblique: /* Shift + Arrow keys are not working if Emacs is inside Tmux */</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Text editors]]<br />
[[de:Emacs]]<br />
[[fr:Emacs]]<br />
[[sr:Emacs]]<br />
[[zh-CN:Emacs]]<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Tutorial on acquiring and using the Emacs text editor.}}<br />
{{Article summary end}}<br />
<br />
[[Wikipedia:Emacs|Emacs]] is the 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. GTK is the default X toolkit used as of GNU Emacs 22, though it functions equally well within a CLI environment. The text-editing capabilities of Emacs are often compared to that of [[vim]].<br />
<br />
== Installation ==<br />
Emacs comes in several variants (sometimes referred to as ''emacsen''). The most common of these is [http://www.gnu.org/software/emacs/ GNU Emacs].<br />
<br />
[[pacman|Install]] {{Pkg|emacs}}, available in the [[Official Repositories]]. If you usually work in a terminal, you may prefer the {{Pkg|emacs-nox}} variant without GTK (nor sound and other fancy stuff).<br />
<br />
Another common variant is {{Pkg|xemacs}}.<br />
<br />
==Running Emacs==<br />
<br />
Before launching emacs, you should know how to close it (especially if you run it in a terminal) : use the<br />
{{keypress|Ctrl+x}}{{keypress|Ctrl+c}} key sequence.<br />
<br />
===Normal way===<br />
To start Emacs run:<br />
<br />
$ emacs<br />
<br />
or, to use it from the console:<br />
<br />
$ emacs -nw<br />
<br />
If you installed the nox version, 'emacs' and 'emacs -nw' will be the same.<br />
<br />
A file name can also be provided to open that file immediately:<br />
<br />
$ emacs filename.txt<br />
===No Colors===<br />
By default, Emacs starts with a color theme showing hyperlinks in dark blue. To start Emacs without any color theme or scheme:<br />
<br />
$ emacs -nw --color=no<br />
<br />
This will cause all text to appear in white color only.<br />
<br />
===As a daemon===<br />
Emacs can take some time to start since it has to load the .emacs file each time. Besides, you may want to access the same files from differant instances. Since version 23, Emacs is capable to run as a daemon to which users can connect. To run Emacs as a daemon:<br />
<br />
$ emacs --daemon<br />
<br />
You are likely to start the daemon at startup time and to connect a window to the daemon. Besides, it is possible to connect ''both'' graphical and console clients to the daemon at the same time and make the GUI to start quickly.<br />
<br />
If you want to connect to the daemon simply use the folowing command (note that it will start a graphical client if called in a graphical environment or a console client if called in a console like a tty):<br />
<br />
$ emacsclient<br />
<br />
If you still want a console client no matter you are in a graphical environment then use:<br />
<br />
$ emacsclient -t<br />
<br />
Furthermore, you can add the {{ic|-a ""}} parameter.<br />
Now, the first time you call the command, it will start emacs as a daemon, so that it remains running in background to improve startup time for future calls (and to remember buffers as well).<br />
<br />
You could use the following shell configuration:<br />
<br />
{{bc|1=<br />
alias emacs='emacsclient -t -a ""'<br />
EDITOR='emacsclient -t -a ""'<br />
}}<br />
but it has some caveats: many program will fail to load the external editor because of the spaces in the command.<br />
<br />
A more convenient and reliable solution is to write your own script:<br />
{{hc|/bin/em|<br />
#!/bin/sh<br />
emacsclient -a "" -t "$@"<br />
}}<br />
then make it executable:<br />
# chmod 755 /bin/em<br />
<br />
Now 'em' will work just as expected.<br />
<br />
With xfce, if you want to tell it to use {{ic|emacsclient -c}} instead of {{ic|emacs %f}} when opening a new file, you can change your modify your emacs.desktop like so:<br />
{{hc|/usr/share/applications/emacs.desktop|<br />
## This line has been commented out:<br />
#Exec&#61;emacs %f<br />
<br />
## For this line<br />
Exec&#61;emacsclient -c<br />
<br />
## or, if using the preceeding script, uncomment this line instead<br />
#Exec&#61;em<br />
}}<br />
<br />
This way, a client will be called each time you open up a file and so be very fast!<br />
<br />
===As a systemd unit===<br />
<br />
Note that this method has some caveats though. It seems there is a limited shell environment which will restrict shell calls, most notably for compilation mode. You'd be better off using the emacs daemon.<br />
<br />
Create a systemd unit for emacs:<br />
{{hc|/etc/systemd/system/emacs@.service|<nowiki><br />
[Unit]<br />
Description=Emacs: the extensible, self-documenting text editor<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/emacs --daemon<br />
ExecStop=/usr/bin/emacsclient --eval "(progn (setq kill-emacs-hook 'nil) (kill-emacs))"<br />
Restart=always<br />
User=%i<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
You need to enable the unit so that it gets started on every boot:<br />
{{bc|<br />
systemctl enable emacs@<username><br />
}}<br />
<br />
To actually use the unit, either reboot or start the unit manually:<br />
{{bc|<br />
systemctl start emacs@<username><br />
}}<br />
<br />
== Quick Start ==<br />
Although Emacs is complex, it will not take long to begin to understand the benefits which the level of customization and extensibility bring. Furthermore, the comprehensive variety of extensions already available allows it to be transformed into a powerful environment for almost any form of text-editing.<br />
<br />
Emacs has an excellent built-in tutorial which can be accessed by clicking the first link on the splash screen; by selecting ''Help->Emacs Tutorial'' from the menu or by pressing 'F1' followed by 't'. This page is designed to be an additional resource for getting started with Emacs.<br />
<br />
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).<br />
<br />
===Basic terminology and convention===<br />
Emacs uses some terminology and conventions which may seem unusual at first and will be introduced where appropriate. However, there is some terminology which should be introduced before-hand, as it is fundamental to working with Emacs.<br />
<br />
The one piece of terminology which must be introduced early is the concept of ''buffers''. A buffer is a representation of data within Emacs. For example, when a file is opened in Emacs, that file is read from disk and its contents stored in a buffer, which allows it to be edited and saved back to disk later. Buffers are not limited to text, and can also contain images and widgets. Work is in progress to allow buffers to even display applications! Another way to think of it: data available on disk is referred to as a 'file', whereas data available in Emacs is referred to as a 'buffer'.<br />
<br />
The convention for key sequences in Emacs may be unfamiliar. Namely:<br />
<br />
'''C-x''' refers to Control-x<br />
<br />
'''M-x''' refers to Meta-x<br />
<br />
{{Note|'Meta' corresponds to the Alt key in most cases. Alternatively, the Esc key can be used.}}<br />
<br />
For example, to exit Emacs use the following key sequence: '''C-x C-c'''. This can be read as "Hold Control and press 'x'. Release. Hold Control and press 'c'." Although Emacs provides a menu bar, it is recommended practise to focus on learning the key sequences. This guide will refer to keybindings with the convention used in Emacs from now on.<br />
<br />
===Movement===<br />
Cursor movement is very similar to other graphical editors. The mouse and arrow keys can be used to change the position of the cursor (referred to as ''point'' in Emacs). The standard movement commands performed by the arrow keys also have more accessible bindings in Emacs. To move forward one character, use '''C-f''' and to move one character backward, '''C-b'''. '''C-n''' and '''C-p''' can be used to move to the next and previous lines, respectively. Again, it is generally recommended to use these key-sequences in preference to the mouse and/or arrow keys.<br />
<br />
As might be expected, Emacs provides more advanced movement commands, including moving by word and sentence. '''M-f''' moves forward one word and '''M-b''' will move point one word backward. Similarly, '''M-e''' moves point one sentence forward and '''M-a''' one sentence backward.<br />
<br />
Until now, all of the movement commands introduced have been relative to point. '''M-<''' can be used to move point to the beginning of the buffer, with its counterpart, '''M->''', moving to the end of the buffer. To move point to a specific line number, use '''M-g g'''. '''M-g g''' will prompt for the desired line number. Also, to move to the start or end of the current line, use '''C-a''' or '''C-e''', respectively.<br />
<br />
{{Note|Keybindings for these commands, or indeed any command, may differ ''slightly'' depending on which modes are currently active. However, it is unusual for the replacement command not to provide equivalent functionality. See [[Emacs#Modes|Modes]] for more information.}}<br />
<br />
===Files and buffers===<br />
Emacs provides a series of commands to act upon files, the most common of which will be detailed here. '''C-x C-f''' is used to open a file (this command is called 'find-file' in Emacs). Should the file specified not exist, Emacs will open an empty buffer. Saving a buffer will create the file with the buffer's contents. '''C-x C-s''' can be used to save a buffer. To save a buffer with a different filename, use '''C-x C-w''' (this is a mnemonic for the command 'write-file'), which will prompt for the new filename before writing it to disk. It is also possible to ensure all buffers are saved with '''C-x s''', which, should a buffer be modified since its last save, a prompt will be displayed asking which action to take.<br />
<br />
{{Note|'''C-x C-f''' does not read the file from disk again if a buffer corresponding to the file is still opened. To re-read the file from disk, kill the buffer ('''C-x k''') prior to '''C-x C-f''' or use '''M-x revert-buffer'''.}}<br />
<br />
Many interactive commands such as "find-file" or "write-file" prompt for input in the bottom-most line of the Emacs window. This line is referred to as the ''minibuffer''. The minibuffer supports many basic editing commands as well as tab-completion similar to that which is available in many *nix shells. '''<TAB>''' can be pressed twice in succession to display a list of completions, and if desired, the mouse can be also be used to select a completion from that list. Completion in the minibuffer is available for many forms of input including commands and filenames.<br />
<br />
The minibuffer also provides a history feature. The previous items entered for a command can be recalled using the '''Up Arrow''' or '''C-p'''.<br />
<br />
To exit the minibuffer at any time, press '''C-g'''.<br />
<br />
After opening several files, a way to switch between them is needed. Opening a file corresponding to a buffer already available in Emacs, will cause Emacs to switch to that buffer. But this is not the most effective way. Emacs provides '''C-x b''', which prompts for the new buffer to be displayed (tab-completion is available here). By entering the name of a buffer which does not exist, a new buffer with that name will be created.<br />
<br />
{{Note|To switch to the previous buffer use '''C-x b <RET>''', as the previous buffer is the default.}}<br />
<br />
A list of all open buffers can be displayed using '''C-x C-b'''. Should a buffer no longer be required, it can be removed with '''C-x k'''.<br />
<br />
===Editing===<br />
Many editing commands exist within Emacs. Perhaps the most important command which has not yet been introduced is 'undo', which can be performed via '''C-_''' or '''C-/'''. Movement commands generally also have a corresponding delete command. For example, '''M-<backspace>''' can be used to delete a word backwards, and '''M-d''' to delete a word forwards. To delete to the end of the line, or the end of the sentence, use '''C-k''' or '''M-k''', respectively.<br />
<br />
It is a rule-of-thumb that no line be allowed to exceed 80 characters. This aids readability, especially in cases where the line wraps at the edge of a window. Automatically inserting (or removing) line separator(s) is known as ''filling'' in Emacs. A paragraph can be filled using '''M-q'''.<br />
<br />
Characters and words can be transposed using '''C-t''' and '''M-t''', respectively. For example: <code>Hello World!</code> → <code>World! Hello</code><br />
<br />
The case of words is also readily adjustable. '''M-l''' downcases a word from point (<code>HELLO</code> → <code>hello</code>); '''M-u''' upcases a word from point (<code>hello</code> → <code>HELLO</code>) and '''M-c''' capitalizes the first character of a word from point while downcasing the remainder (<code>hElLo</code> → <code>Hello</code>).<br />
<br />
===Killing, yanking and regions===<br />
A region is a section of text between two positions. One of those positions is referred to as ''mark'', and the other is point. '''C-<SPC>''' is used to set the position of mark, after which point can be moved to create a region. Within GNU Emacs 23.1 onwards, this region is visible by default. There are a number of commands which act upon regions, among the most commonly used are ''killing'' commands.<br />
<br />
In Emacs, cut and paste are referred to as ''kill'' and ''yank'', respectively. Many commands which delete more than one character (including many of those in the above section, such as '''C-k''' and '''M-d''') actually cut the text and append it to what is known as the ''kill-ring''. The kill-ring is simply a list of killed text. The kill-ring stores up to the last 60 kills by default. Successive kills are concatenated and stored at the head of the list.<br />
<br />
'''C-w''' and '''M-w''' can be used to kill and copy a region, respectively.<br />
<br />
To insert killed text into a buffer (known as 'yanking'), use '''C-y'''. '''C-y''' can be used multiple times in succession to yank text repeatedly. As mentioned, previous kills are stored in a list, however '''C-y''' only retrieves the first of them. The earlier kills can be accessed via '''M-y'''. This will remove the text inserted by 'yank' initially, replacing it with the text killed earlier. '''M-y''' must be used immediately following '''C-y''' and can be used in many times succession to cycle through the kill-ring.<br />
<br />
===Search and replace===<br />
Searching for a string is common practise in text-editing. This can be performed using '''C-s''' (to search forward) or '''C-r''' (to search backward). These commands prompt for the string for which to search. Searching is performed incrementally, and so it will match the next (or previous) occurrence as you type. To move to the next or previous match, press '''C-s''' or '''C-r''' again, respectively. Once a match has been found, '''<RET>''' can be used to end the search. Alternatively, should you wish to return to the location you initiated the search, use '''C-g'''.<br />
<br />
Once a search is completed (i.e., was not aborted with '''C-g''' or similar), the string which was searched for will be the default for any following search. To make use of this, press '''C-s C-s''' or '''C-r C-r''' to search forward or backward again, respectively.<br />
<br />
I-search has some useful commands. Use '''M-e''' to edit the search field. Use<br />
'''M-c''' to toggle case-sensitive matching.<br />
<br />
Regular Expression searches behave identically to the searching described above except for the command to initiate the search. Use '''C-M-s''' or '''C-M-r''' to initiate a regexp search forward or backward, respectively. Once a Regular Expression search has commenced, '''C-s''' and '''C-r''' can be used to search forward or backward, just as with string searches.<br />
<br />
In addition to searching, it is also possible to perform string and regular expression replacement (via '''M-%''' and '''C-M-%''', respectively). Prompts are provided for both the initial and replacement text, and then another prompt for the action to perform on the highlighted match. Although many options are available (the full list is available by pressing '''?'''), the most commonly used are '''y''', to perform replacement, '''n''', to skip this match, and '''!''' to replace this, and all following matches.<br />
<br />
===Prefix arguments===<br />
<br />
'''C-u''' corresponds to the 'universal-argument' command. Providing a 'universal-argument' is a way to provide more information to a command (this information is referred to as a 'prefix argument'). For instance<br />
<br />
C-u 80 %<br />
<br />
will insert a line of percent signs. Or<br />
<br />
C-u 4 M-d<br />
<br />
Will delete 4 words. In this case, we provided the amount of words desired to the command invoked by '''M-d'''.<br />
<br />
You can make it a little quicker by using the equivalent '''M-<number>''' as universal argument.<br />
<br />
M-80 %<br />
<br />
===Indentation<br />
Indentation is usually performed with either '''<TAB>''', to indent a single line, or with '''C-M-\''', to indent a region. If the region is active (''i.e.'' highlighted), then '''<TAB>''' will also indent region.<br />
<br />
Exactly how text is indented usually depends on the ''major-mode'' which is active. Major-modes often define indentation styles specialising in indenting a certain type of text. (See [[Emacs#Modes|Modes]] for more information.)<br />
<br />
In some cases, a suitable major-mode may not exist for a file type, in which case, manual indentation may be necessary. Create a region (see [[Emacs#Killing, yanking and regions|Killing, yanking and regions]]) then perform indentation with '''C-u <n> C-x <TAB>''' (where '<n>' is the number of columns which the text within the region should be indented). For example:<br />
<br />
Increase the region's indentation by four columns:<br />
<br />
C-u 4 C-x <TAB><br />
<br />
Decrease the region's indentation by two columns.<br />
<br />
C-u -2 C-x <TAB><br />
<br />
===Windows and frames===<br />
Emacs is designed for convenient editing of many files at a time. This is achieved by dividing the Emacs interface into three levels. Namely, buffers, which have already been introduced, as well as ''windows'' and ''frames''.<br />
<br />
A ''window'' is a viewport used for displaying a buffer. A window can display only one buffer at a time, however one buffer can be displayed in many windows. Beneath each window exists a ''mode-line'', which displays information for that buffer.<br />
<br />
A ''frame'' is an Emacs "window" (in standard terminology. i.e., 'window' in the sense of the modern desktop paradigm) which contains a title bar, menu bar and one or more 'windows' (in Emacs terminology. i.e., the above definition of 'window').<br />
<br />
From now on the definition of these terms as they exist in Emacs will be used.<br />
<br />
To split the window vertically or horizontally, use '''C-x 2''' or '''C-x 3''', respectively. This has the effect of creating another window in the current frame. To cycle between multiple windows, use '''C-x o'''.<br />
<br />
The opposite of splitting a window, is deleting it. To delete the current window, use '''C-x 0''' and '''C-x 1''' to delete all windows except the current.<br />
<br />
As with windows, it is also possible to create and delete frames. '''C-x 5 2''' creates a frame. With '''C-x 5 0''' to delete the current frame and '''C-x 5 1''' to delete all except the current frame.<br />
<br />
{{Note|These commands do not affect buffers. For example, deleting a window does not kill the buffer it displays.}}<br />
<br />
===Modes===<br />
An Emacs mode is an extension written in Emacs Lisp that controls the behaviour of the buffer it is attached to. Usually it provides indentation, syntax highlighting and keybindings for editing that form of text. Sophisticated modes can turn Emacs into a full-fledged IDE (Integrated Development Environment). Emacs will generally use a file's extension to determine which mode should be loaded.<br />
<br />
Useful modes for editing shell scripts are sh-mode, line-number-mode and column-number-mode. They can be used in parallel and are invoked by:<br />
<br />
'''M-x sh-mode <RET>'''<br />
<br />
'''M-x column-number-mode <RET>'''<br />
<br />
line-number-mode is enabled by default, though, it can be toggled on/off by issuing the command again:<br />
<br />
'''M-x line-number-mode <RET>'''<br />
<br />
sh-mode is a ''major-mode''. Major-modes adjust Emacs, and often also provide a specialised set of commands, for editing a particular type of text. Only one major-mode can be active in each buffer. In addition to syntax highlighting, and indentation support, sh-mode defines several commands to help write shell scripts. The following shows a few of those commands:<br />
<br />
'''C-c (''' Insert a function definition<br />
<br />
'''C-c C-f''' Insert a 'for' loop<br />
<br />
'''C-c TAB''' Insert an 'if' statement<br />
<br />
'''C-c C-w''' Insert a 'while' loop<br />
<br />
'''C-c C-l''' Insert an indexed loop from 1 to n<br />
<br />
'line-number-mode' and 'column-number-mode', are ''minor-modes''. Minor-modes can be used to extend a major-mode and any number of minor-modes can be enabled at once.<br />
<br />
==Tips and tricks==<br />
While the previous sections has given an overview of the basic editing commands available, it has not given an indication of the possibilities of Emacs. This section will cover some more advanced techniques and functionality.<br />
<br />
We cannot cover everything as it would be too long. So this section will only serve as a ''demo'' for some dazzling features of Emacs.<br />
<br />
See [[#Documentation|Documentation]] to get access to more in-depth detail about all features.<br />
<br />
===TRAMP===<br />
TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:<br />
<br />
To prompt for the root password before opening /etc/hosts with root permissions:<br />
<br />
C-x C-f /su::/etc/hosts<br />
<br />
To connect to 'myhost' as 'myuser' via SSH and open the file ~/example.txt:<br />
<br />
C-x C-f /ssh:myuser@myhost:~/example.txt<br />
<br />
The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'. TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.<br />
<br />
===Keyboard macros and registers===<br />
This section will provide a practical demonstration of the use of a couple of more powerful editing features. Namely, ''keyboard macros'' and ''registers''.<br />
<br />
The aim will be to produce a listing of a series of characters and their corresponding position in this list. While it is possible to format each of them by hand, this would be slow and error-prone. Alternatively, some of Emacs' more powerful editing functionality could be leveraged. Before describing a solution, some details behind the techniques which will be used follow.<br />
<br />
The first feature which will be introduced is ''registers''. Registers are used to store and retrieve a variety of data types ranging from numbers to window configurations. Each register is given a name of a single character: this character is used to access the register.<br />
<br />
The other which will be demonstrated is ''keyboard macros''. A keyboard macro stores a sequence of commands so they can be easily repeated later. These changes will now be performed step-by-step.<br />
<br />
Starting with a buffer containing our set of characters:<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
Prepare a register by invoking the `number-to-register' command ('''C-x r n''') then storing the number '0' in register 'k':<br />
<br />
C-x r n k<br />
<br />
With point at the beginning of the buffer, start a keyboard macro ('''C-x (''') and begin to format the characters:<br />
<br />
C-x ( C-f M-4 .<br />
<br />
Insert ('''C-x r i''') and increment ('''C-x r +''') the register 'k'. The prefix argument ('''C-u''') is used to leave point positioned after the inserted text:<br />
<br />
C-u C-x r i k C-x r + k<br />
<br />
Complete the formatting by inserting a newline. Emacs can then repeat that process, beginning from the point where we started defining the keyboard macro, for the rest of the characters. '''C-x e''' completes then invokes the keyboard macro. The prefix argument, '''M-0''', causes the macro to repeat until it comes across an error. In this case it aborts once it reaches the end of the buffer.<br />
<br />
<RET> M-0 C-x e<br />
<br />
The result:<br />
<br />
A....0<br />
B....1<br />
C....2<br />
[...]<br />
x....49<br />
y....50<br />
z....51<br />
<br />
If you want to save your macro for leter use, you must give it a name and save it to your configuration file:<br />
name-last-kbd-macro <br />
insert-kbd-macro<br />
<br />
All defined macros are stored in the macro ring. To cycle between macros, use<br />
'''C-x C-k C-n''' next macro<br />
'''C-x C-k C-p''' previous macro<br />
<br />
You can also use registers to save virtually anything.<br />
<br />
'''C-x r SPC''' Copy current point (position) to register<br />
'''C-x r w''' Copy current window configuration to register.<br />
'''C-x r j''' Restore register.<br />
<br />
So if you often work with windows side by side, for different project, you can save the configuration for the different projects and easily switch from one view to the other.<br />
<br />
You can list used registers with the '''list-registers''' command.<br />
<br />
===Regular expressions===<br />
From the Emacs Manual: "A regular expression, or ''regexp'' for short, is a pattern that denotes a (possibly infinite) set of strings." This section will not go into any detail regarding regular expressions themselves (as there is simply too much to cover). It will however provide a quick demonstration of their power. See [http://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html#Regular-Expressions Regular Expressions] section in the Emacs Manual for further reading.<br />
<br />
Given the same scenario presented above: A list of characters which are to be formatted to represent their respective position in the list. (see [[Emacs#Keyboard macros and registers|Keyboard macros and registers]]). Again, starting with a buffer containing.<br />
<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
At the beginning of the buffer, use '''C-M-%''' (if the key-sequence is difficult to perform, it may be more comfortable to use '''M-x query-replace-regexp'''). At the prompt:<br />
\(.\)<br />
which simply matches one character. Then, when prompted for the replacement:<br />
\1....\#^J<br />
{{Note|'^J' represents where a newline should be placed, it should not be entered into the prompt. The newline must instead be inserted literally using '''C-q C-j'''.}}<br />
The replacement expression reads: "Insert the matched text between the first set of parentheses (in this case, a single character), followed by 4 periods then insert an automatically incremented number followed by a newline.<br />
<br />
Finally, press '''!''' to apply this across the entire buffer. All of the formatting that was performed in the previous section was performed with a single regexp replacement.<br />
<br />
===Rectangular selections===<br />
<br />
A very powerful feature you may expect from advanced text editors is the possibility to select and edit text in a rectangular area.<br />
<br />
This also works in Emacs. Select your text as usual with '''C-SPC'''. Now you can use several rectangular command.<br />
<br />
'''C-x r t''' Replace rectangle with text.<br />
'''C-x r k''' Kill (and save in kill-ring) rectangle.<br />
'''C-x r y''' Yank rectangle.<br />
'''C-x r o''' Blank out rectangle.<br />
<br />
Note that the command will not affect text outside the rectangle, even though it is highlighted. <br />
<br />
=== Bookmarks ===<br />
<br />
Emacs can remember a list of visited files.<br />
<br />
'''C-x r m''' Add current buffer to bookmarks.<br />
'''C-x r b''' Open a buffer from bookmarks.<br />
'''C-x r l''' List bookmarks.<br />
<br />
===Elisp interpreter===<br />
<br />
Emacs can evaluate any elisp expression at anytime with the '''eval-last-sexp''' function (bound to '''C-x C-e''' by default). Emacs always spawn a '''*scratch*''' buffer when you start it. It will not be saved to disk, so feel free to add any pice of text / code you want. It is especially useful for elisp evaluation. Note that this buffer starts using the '''lisp-interaction-mode''' by default.<br />
<br />
Alternatively Emacs provides a top-level elisp interpreter with the '''ielm''' command.<br />
<br />
=== Smart window switch ===<br />
<br />
The traditional window switch with '''C-x o''' can be cumbersome to use in the long run.<br />
The '''windmove''' commands provide a more convenient way to do this. All you have to do is to hold down {{keypress|Shift}} while pointing at a window with the arrow keys.<br />
<br />
To activate the windmove keys, use the following in your configuration file:<br />
<br />
{{hc|~/.emacs|<br />
(when (fboundp 'windmove-default-keybindings)<br />
(windmove-default-keybindings))<br />
}}<br />
<br />
===Shell calls===<br />
<br />
Use '''M-!''' to call an external command. Use a prefix argument ('''C-u M-!''') to output the result to current buffer at point.<br />
<br />
You can use '''M-|''' on a region to use it as input for a command. For instance<br />
<br />
'''C-u M-| sort -u RET'''<br />
<br />
will sort region, remove duplicates and replace the region with the result.<br />
<br />
===Shell buffers===<br />
<br />
You can spawn a shell buffer and execute commands just like you would do in any terminal.<br />
A classic shell buffer can be spawned with the '''shell''' command.<br />
<br />
Emacs features a very powerful shell entirely written in Emacs Lisp, the '''eshell'''. The major advantage over shells like csh or zsh is that the native shell language is elisp itself. So you can use all advanced feature of elisp for your shell functions.<br />
<br />
=== Show matching parentheses ===<br />
<br />
You can use the '''show-paren''' mode.<br />
By default, there’s a small delay before showing a matching parenthesis. Set the '''show-paren-delay''' to 0 to deactivate.<br />
<br />
{{hc|~/.emacs|<br />
(show-paren-mode 1)<br />
(setq show-paren-delay 0)<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
You can choose the dictionnary with<br />
'''M-x ispell-change-dictionary'''<br />
<br />
To check a single work use '''M-$'''.<br />
You can start checking the whole buffer with<br />
'''M-x ispell-buffer'''<br />
<br />
You can enable on-the-fly spell checking by enabling the '''flyspell-mode'''. For source code files you can restrict the mode to comments by using the '''flyspell-prog-mode''' instead.<br />
<br />
=== Tables ===<br />
<br />
Emacs comes with some powerful functions to handle and generate tables for various languages. Let's show an example.<br />
<br />
Fruits Quantity<br />
Apples 5<br />
Melons 2<br />
<br />
Now select the previous content in a region, and run<br />
table-capture<br />
<br />
Use two spaces for the column delimiter, and a line brak ('''C-q C-j''') for the row delimiter.<br />
This will lead to the following result.<br />
<br />
+------+--------+<br />
|Fruits|Quantity|<br />
+------+--------+<br />
|Apples|5 |<br />
+------+--------+<br />
|Melons|2 |<br />
+------+--------+<br />
<br />
You can revert back the operation with <br />
table-release<br />
There is a lot of handy ''table-*'' functions, like ''table-insert-row'', ''table-span-cell'', ''table-widen-cell'', etc.<br />
<br />
Finally, the ultimate purpose of the ''table'' functions is to convert it to the desired markup language.<br />
Use the ''table-generate-source'' for that.<br />
For LaTeX, the previous table would result in<br />
<br />
% This LaTeX table template is generated by emacs 24.2.1<br />
\begin{tabular}{|l|l|}<br />
\hline<br />
Fruits & Quantity \\<br />
\hline<br />
Apples & 5 \\<br />
\hline<br />
Melons & 2 \\<br />
\hline<br />
\end{tabular}<br />
<br />
Using the table mode you can also do some spreadsheet work like sum on rows and columns, but you will quickly find it limited. Besides it is quite slow. Have a look at the [[#Agenda, spreadsheet and document authoring|org-mode]] for much more powerful possibilities.<br />
<br />
=== Agenda, spreadsheet and document authoring ===<br />
<br />
Emacs can offer powerful office features thanks to the famous and powerful [http://orgmode.org/ Org mode]. This mode is part of the standard Emacs distribution.<br />
<br />
Org mode is originally a powerful TODO and Agenda agent, but has quickly evolved to a much wider set of features.<br />
There is simply too much to tell about Org that we cannot aford even to skim over all the features. So we will only whet your appetite with a few exemples.<br />
<br />
Open a new file TODO.org file, Org mode should be loaded. If not, switch to it with '''M-x org-mode'''.<br />
{{hc|TODO.org|<br />
* First entry<br />
** Subentry<br />
Some comments<br />
*** Subsubentry<br />
* Second entry<br />
- List item 1<br />
- List item 2<br />
}}<br />
<br />
Now a few useful bindings.<br />
* '''TAB''' to cycle-fold current entry.<br />
* '''S-TAB''' to cycle-fold all entries.<br />
* '''M-RET''' to start a new item on the same level as the current one.<br />
* '''M-<left>''' and '''M-<right>''' to change level.<br />
* '''M-<up>''' and '''M-<down>''' to move item together with all its subsections.<br />
* '''S-<left>''' and '''S-<right>''' to change status. On list items it will change the item style.<br />
* '''S-<up>''' and '''S-<down>''' to change priority.<br />
* '''C-c ^''' to sort all subentries of the current entry.<br />
* '''C-c .''' to add a timestamp to the current entry. Use {{keypress|Shift}} and arrows to skip days or weeks. Use the mouse on the calendar or press {{keypress|Enter}} on a specific day to choose it.<br />
<br />
The spreadsheet features are very comprehensive. Let's give an excerpt from the manual:<br />
<br />
{{bc|<nowiki><br />
Finally, just to whet your appetite for what can be done with the<br />
fantastic `calc.el' package, here is a table that computes the Taylor<br />
series of degree `n' at location `x' for a couple of functions.<br />
<br />
|---+-------------+---+-----+--------------------------------------|<br />
| | Func | n | x | Result |<br />
|---+-------------+---+-----+--------------------------------------|<br />
| # | exp(x) | 1 | x | 1 + x |<br />
| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |<br />
| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |<br />
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |<br />
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |<br />
| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |<br />
|---+-------------+---+-----+--------------------------------------|<br />
#+TBLFM: $5=taylor($2,$4,$3);n3<br />
</nowiki>}}<br />
Org mode recognizes a table when the pipe '''|''' is the first non-whitespace character on line. In the previous text, no line was drawn. This is done automatically when '''TAB''' is pressed after an entry or the '''|-''' sequence. The result column was not written by hand neither, it is computed from the calc formula on the last line. Use '''C-u C-c C-c''' to recompute all values in a table.<br />
<br />
There is also some handy row and column manipulation bindings like those for the TODO file. {{keypress|Alt}} plus arrows will move columns and arrows.<br />
<br />
For more in-depth details, refer to the official manual: '''C-h i m Org mode RET'''.<br />
<br />
=== Refactoring and smart completion ===<br />
<br />
If you are looking for popular programming features found in most IDE (such as Eclipse), the [http://cedet.sourceforge.net/semantic.shtml Semantic] tool will do the job. It is part of Emacs standard distribution. Currently C, C++, Scheme, Javascript, Java, HTML, and Make are well supported. You can find a table on the current support state on the [http://cedet.sourceforge.net/languagesupport.shtml CEDET page].<br />
<br />
Open a file in your favorite programming landuage supported by Semantic and turn on the Semantic minor mode with<br />
M-x semantic-mode<br />
Semantic will work for a few seconds parsing the libraries included from your file (in C that would mostly be the standard library for instance).<br />
<br />
==== Features ====<br />
<br />
Once done, you can start using the great Semantic features:<br />
;Smart completion<br />
Press '''C-c , SPC''' to complete a symbol at point. If it is an argument, it will check for type correctness.<br />
<br />
;Jump to symbol<br />
Press '''C-c , j''' to prompt for a symbol and jump to its definition. You can use auto-completion with '''TAB'''. Use a capital '''J''' to search for symbol accross files.<br />
<br />
;List symbol calls<br />
Press '''C-c , g''' to prompt for a symbol and list the places where it is being referred to. You can use '''n''' and '''p''' to navigate through the resulting entries. Press '''RET''' to toggle details, and '''RET''' again on a reference to jump to it. Use a capital '''G''' in the first command to work across files.<br />
<br />
;Refactoring<br />
First list use of the symbol you want to refactor with the aforementioned command. Now press '''(''' to start defining a macro on the symbol. This is actually much more powerful than refactoring since you can apply any function to the symbol and even act on its surrounding symbols. Press '''C-x )''' to finish the macro and '''E''' to call it.<br />
<br />
;Describe symbol<br />
Call the following function to display details on a symbol.<br />
semantic-ia-show-summary<br />
This can be very useful for complexe data structures and function prototypes. There is no binding by default.<br />
<br />
==== Configuration ====<br />
<br />
Here follows a sample configuration for use of Semantic with all supported programming languages: an example binding and a display configuration.<br />
;; Semantic with ghost display (allows M-n and M-p to browse completion).<br />
(semantic-mode 1)<br />
(define-key my-keys-minor-mode-map (kbd "C-c , d") 'semantic-ia-show-summary)<br />
(setq semantic-complete-inline-analyzer-displayor-class 'semantic-displayor-ghost)<br />
<br />
You can also add some specialization for a specific language. Here for C:<br />
(add-hook<br />
'c-mode-hook<br />
(lambda ()<br />
(local-set-key (kbd "M-TAB") 'semantic-complete-analyze-inline)<br />
(local-set-key "." 'semantic-complete-self-insert)<br />
(local-set-key ">" 'semantic-complete-self-insert)))<br />
<br />
==== Further reading ====<br />
<br />
You can access the info manual directly from Emacs: '''C-h i m Semantic RET'''.<br />
<br />
=== Using Emacs as git mergetool ===<br />
<br />
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.<br />
<br />
{{hc|.gitconfig|<nowiki><br />
[mergetool.ediff]<br />
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\\\"))\" <br />
<br />
[merge]<br />
tool = ediff<br />
</nowiki>}}<br />
<br />
Note that the command has to be on a single line.<br />
In the above example, we launch a new instance of Emacs. You might want to use emacsclient for quicker startup; it is not recommended though since the Ediff call is not really clean: it could mess with your current Emacs session.<br />
<br />
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<br />
emacs -q -l ~/.emacs-light<br />
where the light configuration file loads only what you need for Ediff.<br />
<br />
See [http://kerneltrap.org/mailarchive/git/2007/7/1/250424 kerneltrap.org] and [http://stackoverflow.com/questions/1817370/using-ediff-as-git-mergetool stackoverflow] for more details on this trick and the Ediff issue.<br />
<br />
==Customization==<br />
<br />
Emacs can configured by editing {{ic|~/.emacs}} or using '''M-x customize'''. This section will focus on editing {{ic|~/.emacs}} by hand, and provide some example customizations to demonstrate commonly-configured aspects of Emacs. The customize command provides a simple interface to make adjustments, though it may become restricting as you grow more familiar with Emacs.<br />
<br />
All of the examples here can be performed while Emacs is running. To evaluate the expression within Emacs, use:<br />
<br />
'''C-M-x''' with point anywhere within the expression.<br />
<br />
or<br />
<br />
'''C-x C-e''' with point following the last ')'<br />
<br />
For some users, typing 'yes' and 'no' in prompts can quickly become tiring. To instead use the 'y' and 'n' keys at these prompts:<br />
<br />
(defalias 'yes-or-no-p 'y-or-n-p)<br />
<br />
To stop the cursor blinking, use:<br />
<br />
(blink-cursor-mode -1)<br />
<br />
Similarly, to enable column-number-mode, as discussed in the previous section:<br />
<br />
(column-number-mode 1)<br />
<br />
The similarities between the previous two commands are not a coincidence: blink-cursor-mode and column-number-mode are both minor-modes. As a rule, minor-modes can be enabled given positive argument or disabled with a negative argument. Should the argument be omitted, the minor-mode will be toggled on/off.<br />
<br />
Here are some more examples of minor-modes. The following will disable the scroll bars, menu-bar and tool-bar, respectively.<br />
<br />
(scroll-bar-mode -1)<br />
(menu-bar-mode -1)<br />
(tool-bar-mode -1)<br />
<br />
The variable, 'auto-mode-alist', can be modified to change the major-mode used by default for certain file names. The following example will make the default major-mode for '.tut' and '.req' files 'text-mode'.<br />
<br />
(setq auto-mode-alist<br />
(append<br />
'(("\\.tut$" . text-mode)<br />
("\\.req$" . text-mode))<br />
auto-mode-alist))<br />
<br />
Settings can also be applied on a per-mode basis. A common method for this is to add a function to a ''hook''. For example, to force indentation to use spaces instead of tabs, but only in text-mode:<br />
<br />
(add-hook 'text-mode-hook (lambda () (setq indent-tabs-mode nil)))<br />
<br />
Similarly, to only use spaces for indentation everywhere:<br />
<br />
(setq-default indent-tabs-mode nil)<br />
<br />
Keybindings can be adjusted in two ways. The first of which is 'define-key'. 'define-key' creates a keybinding for a command but only in one mode. The example below will make '''F8''' delete any whitespace from the end of each line of a 'text-mode' buffer:<br />
<br />
(define-key text-mode-map (kbd "<f8>") 'delete-trailing-whitespace)<br />
<br />
The other method is 'global-set-key'. This is used to bind a key to a command everywhere. To bind 'query-replace-regexp' ('''C-M-%''') to '<f7>'.<br />
<br />
(global-set-key (kbd "<f7>") 'query-replace-regexp)<br />
<br />
Binding a command to an alternate key does not replace any existing bindings. Which is to say, 'query-replace-regexp' would be bound to both '''F7''' and '''C-M-%''' after the above example.<br />
<br />
Almost anything within Emacs can be configured. Browsing through the [http://emacswiki.org/ Emacs Wiki] should give a solid place to start.<br />
<br />
=== Multiple configurations ===<br />
<br />
You can use several configurations and tell Emacs to load one or the other.<br />
<br />
For example, let's define two configuration files.<br />
<br />
{{hc|.emacs|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/plugins" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
This is the full configuration we load for the deamon. But the ''plugins'' file is huge and slow to load. If we want to spaqn a new Emacs instance that does not need the ''plutings'' features, it can be cumbersome to load it everytime in the long time.<br />
<br />
{{hc|.emacs-light|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
And now we launch Emacs with<br />
emacs -q -l ~/.emacs-light<br />
You can create an alias to ease the call.<br />
<br />
=== Loading extensions ===<br />
<br />
You can load extensions using the ''require'' function. For instance<br />
(require 'mediawiki)<br />
<br />
If you try using the same configuration file on a machine where mediawiki is not installed, Emacs will primpt for an error. Besides, all extension-specific code would be parsed for nothing.<br />
<br />
The trick is to test the return value of ''require'':<br />
<br />
(if (require 'mediawiki nil t)<br />
(progn<br />
(setq mediawiki-site-alist '(<br />
("ArchLinux" "https://wiki.archlinux.org/" "UserName" "" "Main Page")<br />
)<br />
)<br />
(setq mediawiki-mode-hook<br />
(lambda ()<br />
(visual-line-mode 1)<br />
(turn-off-auto-fill)<br />
))<br />
)) <br />
<br />
=== Local and custom variables ===<br />
<br />
You can define variables in your configuration file that can be later one modified locally for a file.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation")<br />
<br />
Now in any file you can define local variables in two ways:<br />
* On the very first line, write<br />
// -*- my-compiler:g++; mode:c++ -*-<br />
* If you cannot (or do not want to) write this on the first line, you can put it at the end:<br />
// Local Variables:<br />
// my-compiler: g++<br />
// mode: c++<br />
// End:<br />
<br />
Note that the beginning characters need to be comments for the current language, that's why here we used two backslashes for C++. For Elisp you would use<br />
;; -*- mode:emacs-lisp -*-<br />
<br />
There is two functions that may help you in defining the variables: ''add-file-local-variable'' and ''add-file-local-variable-prop-line''.<br />
<br />
Finally, custom variable are considered insecure by default. If you try to open a file that contains local variable redefining insecure custom variables, Emacs will ask you for confirmation.<br />
<br />
If you know what you are doing, 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.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation" :safe 'stringp)<br />
<br />
In the previous example, if you attempt to set anything else than a string, Emacs will consider it insecure.<br />
<br />
=== Custom colors and theme ===<br />
<br />
Colors can be easily customized using the ''face'' facility.<br />
(set-face-background 'region "color-17")<br />
(set-face-foreground 'region "white")<br />
(set-face-bold-p 'font-lock-builtin-face t ) <br />
<br />
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.<br />
<br />
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.<br />
<br />
=== SyncTeX support ===<br />
<br />
Emacs is definitely one of the most powerful LaTeX editor. This is mostly due to the fact you can adapt or create a LaTeX mode to fit your needs best.<br />
<br />
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.<br />
# umask 022 && tlmgr install synctex<br />
<br />
SyncTeX support is viewer-dependent. Here we will use Zathura as an example, so the code needs to be adapted if you want to use another PDF viewer.<br />
<br />
(defcustom tex-my-viewer "zathura --fork -s -x \"emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"'\"'\"%{input}\"'\"'\")) (goto-line %{line}))'\"" <br />
"PDF Viewer for TeX documents. You may want to fork the viewer<br />
so that it detects when the same document is launched twice, and<br />
persists when Emacs gets closed.<br />
<br />
Simple command:<br />
<br />
zathura --fork<br />
<br />
We can use<br />
<br />
emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"%{input}\")) (goto-line %{line}))'<br />
<br />
to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes matter and must be escaped appropriately."<br />
:safe 'stringp)<br />
<br />
Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-mode, you will have to set the viewer accordingly.<br />
<br />
Now open a LaTeX source file with Emacs, compile the document, and launch the viewer. Zathura will spawn. If you press {{keypress|Ctrl+Left click}} Emacs should place the point at the corresponding position.<br />
<br />
== Documentation ==<br />
<br />
You may find yourself overwhelmed by the amount of Emacs features. You may find it difficult to know how to use Emacs Lisp to customize your favorite mods, or even to create your own modes / packages. Thankfully Emacs takes a strong point to auto-documenting everything: its internals, current configuration, bindings, etc. Almost everything is documented.<br />
<br />
===Contextual help===<br />
Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. The following is a listing of some of the most helpful of these:<br />
<br />
'''C-h a''' Find a command matching a description.<br />
<br />
'''C-h b''' List all active keybindings.<br />
<br />
'''C-h f''' Describe the given function.<br />
<br />
'''C-h k''' Find which command a key is bound to.<br />
<br />
'''C-h m''' Display information regarding the currently active modes.<br />
<br />
'''C-h t''' Start the Emacs tutorial.<br />
<br />
'''C-h v''' Describe the given function.<br />
<br />
'''C-h w''' Find which key(s) a command is bound to.<br />
<br />
=== The Manuals ===<br />
<br />
If you really want to master Emacs, the most recommanded source of documentation remains the official manuals:<br />
* Emacs: the complete Emacs user manual.<br />
* Emacs FAQ.<br />
* Emacs Lisp Intro: if you never used any programming language before.<br />
* Elisp: if you are already familiar with a programming language.<br />
<br />
You can access it as PDFs from [http://www.gnu.org/software/emacs/manual/ GNU.org] or directly from Emacs itself thanks to the embedded 'info' reader: '''C-h i'''. Press '''m''' to choose a book.<br />
<br />
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.<br />
<br />
You may want to read the '''Info''' book to know more about it: '''C-h i m info <RET>'''.<br />
Press '''?''' while in info mode for a quick list of shortcuts.<br />
<br />
== Extensions ==<br />
<br />
While Emacs includes hundreds of modes, libraries and other extensions, there are many more available to further Emacs' capabilities. The majority of these come with instructions detailing any changes needed to be made to {{ic|~/.emacs}}. These instructions are generally found in the comment block at the beginning of an elisp source file, or in a README (or similar) should the extension consist of multiple source files.<br />
<br />
A number of popular extensions are available as packages in the 'community' repository, and more still are available via the [[AUR]]. The name of such packages have a 'emacs-' prefix (for example, emacs-lua-mode). In many cases, the changes which need to be made to {{ic|~/.emacs}} are shown during the installation of the package.<br />
<br />
Should instructions describing how to activate a specific extension not be available in the aforementioned location(s), check for a corresponding page in the [http://emacswiki.org/ Emacs Wiki], which will almost certainly provide an example configuration. The Emacs Wiki is also an excellent resource for discovering even more extensions.<br />
<br />
You can also use the [http://tromey.com/elpa/ Emacs Lisp Package Archive (ELPA)] to automatically install packages. See the website for instructions. ELPA is included with Emacs 24 (the newest version of Emacs); it is an accepted part of the Emacs ecosystem.<br />
<br />
=== Emacs MediaWiki ===<br />
Since we are at it, you may be a contributor to Arch Linux Wiki, or any Mediawiki-based website. Then emacs will become your best friend thanks to the [[Emacs Mediawiki]] extension. Check the dedicated page for more details.<br />
<br />
== Troubleshooting ==<br />
<br />
===Colored output issues===<br />
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.<br />
<br />
Including the following into {{ic|~/.emacs}} amends the problem:<br />
(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)<br />
<br />
===Menus appear empty===<br />
A bug exists in GNU Emacs 23.1 (using the GTK toolkit) which may cause some menus to appear empty. This appears to be fixed in Emacs' CVS trunk. The corresponding [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=550541 Debian bug report] contains a workaround.<br />
<br />
=== Problems displaying characters in X Windows ===<br />
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.<br />
<br />
=== Slow startup ===<br />
Slow startup times are often caused by one of two things.<br />
<br />
To determine which it might be, run Emacs with:<br />
<br />
$ emacs -q<br />
<br />
If Emacs still starts slowly, refer to [[Emacs#Incorrect network configuration|Incorrect network configuration]]. If not, it is almost certainly a [[Emacs#Init file loads slowly|problem in your .emacs]].<br />
<br />
* Mistakes, particularly in /etc/hosts, will often result in a 5+ second delay when starting Emacs. Refer to '[[Configuring_network#Set_the_hostname|set the hostname]]' in the network configuration guide for information.<br />
<br />
* 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's 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:<br />
<br />
(require 'anything)<br />
<br />
you might use:<br />
<br />
(autoload 'anything "anything" "Select anything" t)<br />
<br />
=== Cannot open load file: ... ===<br />
<br />
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:<br />
<br />
(add-to-list 'load-path "/path/to/directory/")<br />
<br />
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:<br />
<br />
(add-to-list 'load-path "/usr/share/emacs/site-lisp")<br />
<br />
If compiling Emacs by hand, keep in mind that the default prefix is '/usr/local'.<br />
<br />
=== Dead-accent keys problem: '<dead-acute> is undefined' ===<br />
<br />
Searching about this bug on Google, we find this link:<br />
http://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00167.html<br />
<br />
Explaining the problem: in recent versions of<br />
b72<br />
Emacs, the normal way to use accent keys doesn't work as expected. Trying to accent a word like 'fiancé' will produce the message above.<br />
<br />
A way to solve it is just put the line above on your startup file, {{ic|~/.emacs}}:<br />
<br />
(require 'iso-transl)<br />
<br />
And no, it isn't 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):<br />
<br />
:''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<br />
a3b<br />
classified as a feature ... Maybe it's just because the file is auto-loaded though pretty useless. ''<br />
<br />
=== C-M-% and some other bindings do not work in emacs nox ===<br />
<br />
This is because terminals are more limited than Xorg. Some terminals may handle more bindings than other, though. Two solutions:<br />
* either use the graphical version,<br />
* or change the binding to a supported one.<br />
<br />
Example:<br />
{{hc|.emacs|<br />
(global-set-key (kbd "C-M-y") 'query-replace-regexp)<br />
}}<br />
<br />
=== Emacs client gets stuck when switching back to it ===<br />
<br />
If you are using Emacs daemon, then you should know that input is blocking. If one Emacs instance is in the minibuffer (after an '''M-x''' for instance), then all other instance will wait for it to finish. Press '''C-g''' to cancel any input to make sure this Emacs session is not blocking.<br />
<br />
=== Shift + Arrow keys not working in emacs within tmux ===<br />
<br />
First you must enable xterm-keys in your [[tmux]] config.<br />
{{hc|.tmux.conf|<br />
setw -g xterm-keys on<br />
}}<br />
<br />
But, this will break other key combinations. To fix them, put the following in your emacs config.<br />
{{hc|.emacs|<br />
;; handle tmux's xterm-keys<br />
;; put the following line in your ~/.tmux.conf:<br />
;; setw -g xterm-keys on<br />
(if (getenv "TMUX")<br />
(progn<br />
(let ((x 2) (tkey ""))<br />
(while (<&#61; x 8)<br />
;; shift<br />
(if (&#61; x 2)<br />
(setq tkey "S-"))<br />
;; alt<br />
(if (&#61; x 3)<br />
(setq tkey "M-"))<br />
;; alt + shift<br />
(if (&#61; x 4)<br />
(setq tkey "M-S-"))<br />
;; ctrl<br />
(if (&#61; x 5)<br />
(setq tkey "C-"))<br />
;; ctrl + shift<br />
(if (&#61; x 6)<br />
(setq tkey "C-S-"))<br />
;; ctrl + alt<br />
(if (&#61; x 7)<br />
(setq tkey "C-M-"))<br />
;; ctrl + alt + shift<br />
(if (&#61; x 8)<br />
(setq tkey "C-M-S-"))<br />
<br />
;; arrows<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d A" x)) (kbd (format "%s<up>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d B" x)) (kbd (format "%s<down>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d C" x)) (kbd (format "%s<right>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d D" x)) (kbd (format "%s<left>" tkey)))<br />
;; home<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d H" x)) (kbd (format "%s<home>" tkey)))<br />
;; end<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d F" x)) (kbd (format "%s<end>" tkey)))<br />
;; page up<br />
(define-key key-translation-map (kbd (format "M-[ 5 ; %d ~" x)) (kbd (format "%s<prior>" tkey)))<br />
;; page down<br />
(define-key key-translation-map (kbd (format "M-[ 6 ; %d ~" x)) (kbd (format "%s<next>" tkey)))<br />
;; insert<br />
(define-key key-translation-map (kbd (format "M-[ 2 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; delete<br />
(define-key key-translation-map (kbd (format "M-[ 3 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; f1<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d P" x)) (kbd (format "%s<f1>" tkey)))<br />
;; f2<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d Q" x)) (kbd (format "%s<f2>" tkey)))<br />
;; f3<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d R" x)) (kbd (format "%s<f3>" tkey)))<br />
;; f4<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d S" x)) (kbd (format "%s<f4>" tkey)))<br />
;; f5<br />
(define-key key-translation-map (kbd (format "M-[ 15 ; %d ~" x)) (kbd (format "%s<f5>" tkey)))<br />
;; f6<br />
(define-key key-translation-map (kbd (format "M-[ 17 ; %d ~" x)) (kbd (format "%s<f6>" tkey)))<br />
;; f7<br />
(define-key key-translation-map (kbd (format "M-[ 18 ; %d ~" x)) (kbd (format "%s<f7>" tkey)))<br />
;; f8<br />
(define-key key-translation-map (kbd (format "M-[ 19 ; %d ~" x)) (kbd (format "%s<f8>" tkey)))<br />
;; f9<br />
(define-key key-translation-map (kbd (format "M-[ 20 ; %d ~" x)) (kbd (format "%s<f9>" tkey)))<br />
;; f10<br />
(define-key key-translation-map (kbd (format "M-[ 21 ; %d ~" x)) (kbd (format "%s<f10>" tkey)))<br />
;; f11<br />
(define-key key-translation-map (kbd (format "M-[ 23 ; %d ~" x)) (kbd (format "%s<f11>" tkey)))<br />
;; f12<br />
(define-key key-translation-map (kbd (format "M-[ 24 ; %d ~" x)) (kbd (format "%s<f12>" tkey)))<br />
;; f13<br />
(define-key key-translation-map (kbd (format "M-[ 25 ; %d ~" x)) (kbd (format "%s<f13>" tkey)))<br />
;; f14<br />
(define-key key-translation-map (kbd (format "M-[ 26 ; %d ~" x)) (kbd (format "%s<f14>" tkey)))<br />
;; f15<br />
(define-key key-translation-map (kbd (format "M-[ 28 ; %d ~" x)) (kbd (format "%s<f15>" tkey)))<br />
;; f16<br />
(define-key key-translation-map (kbd (format "M-[ 29 ; %d ~" x)) (kbd (format "%s<f16>" tkey)))<br />
;; f17<br />
(define-key key-translation-map (kbd (format "M-[ 31 ; %d ~" x)) (kbd (format "%s<f17>" tkey)))<br />
;; f18<br />
(define-key key-translation-map (kbd (format "M-[ 32 ; %d ~" x)) (kbd (format "%s<f18>" tkey)))<br />
;; f19<br />
(define-key key-translation-map (kbd (format "M-[ 33 ; %d ~" x)) (kbd (format "%s<f19>" tkey)))<br />
;; f20<br />
(define-key key-translation-map (kbd (format "M-[ 34 ; %d ~" x)) (kbd (format "%s<f20>" tkey)))<br />
<br />
(setq x (+ x 1))<br />
))<br />
)<br />
)<br />
}}<br />
<br />
== Alternatives ==<br />
<br />
There are numerous implementations of Emacs. GNU/Emacs is probably the most popular. <br><br />
Lighter Emacs compatibile alternatives can be found in Arch repositories or in [https://aur.archlinux.org/ AUR].<br />
<br />
=== mg ===<br />
<br />
mg (originally called MicroGnuEmacs) is lightweight implementation of Emacs written in C.<br />
<br />
It's possible to install mg right away from {{ic|community}}<br />
# pacman -S mg<br />
or download source from official [http://homepage.boetes.org/software/mg/ page].<br />
<br />
=== zile ===<br />
<br />
According to the offical web [https://www.gnu.org/software/zile/ page] "GNU Zile is a lightweight Emacs clone. Zile is short for Zile Is Lossy Emacs. Zile has been written to be as similar as possible to Emacs; every Emacs user should feel at home.".<br />
<br />
zile can be found in {{ic|extra}}<br />
<br />
# pacman -S zile<br />
<br />
the latest taballs can be found in official GNU [http://ftp.sh.cvut.cz/MIRRORS/gnu/pub/gnu/zile/ mirrors].<br />
<br />
=== uemacs ===<br />
<br />
uemacs is "Micro-emacs version customized by Linus Torvalds".<br />
It can be found in [https://aur.archlinux.org/ AUR] as [https://aur.archlinux.org/packages.php?ID=31502 uemacs].<br />
<br />
== See also ==<br />
* [http://www.gnu.org/software/emacs/ GNU Emacs home page]<br />
* [http://www.gnu.org/software/emacs/manual/emacs.html GNU Emacs Manual]<br />
* [http://www.emacswiki.org/cgi-bin/wiki/ Emacs Wiki]<br />
* [http://wikemacs.org WikEmacs - a more readable, but less complete Emacs Wiki]<br />
* [http://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html Useful introduction to Emacs and its shortcuts]<br />
* [http://www.dina.kvl.dk/~abraham/religion/ The Church of Emacs]<br />
* [http://cs.iupui.edu/~kweimer/EmacsCheatSheet.pdf Emacs Cheat Sheet]<br />
* [http://repo.or.cz/w/emacs.git/blob/HEAD:/etc/refcards/refcard.pdf Official reference card]</div>Obliquehttps://wiki.archlinux.org/index.php?title=Emacs&diff=259423Emacs2013-05-28T22:10:01Z<p>Oblique: /* Troubleshooting */</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Text editors]]<br />
[[de:Emacs]]<br />
[[fr:Emacs]]<br />
[[sr:Emacs]]<br />
[[zh-CN:Emacs]]<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Tutorial on acquiring and using the Emacs text editor.}}<br />
{{Article summary end}}<br />
<br />
[[Wikipedia:Emacs|Emacs]] is the 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. GTK is the default X toolkit used as of GNU Emacs 22, though it functions equally well within a CLI environment. The text-editing capabilities of Emacs are often compared to that of [[vim]].<br />
<br />
== Installation ==<br />
Emacs comes in several variants (sometimes referred to as ''emacsen''). The most common of these is [http://www.gnu.org/software/emacs/ GNU Emacs].<br />
<br />
[[pacman|Install]] {{Pkg|emacs}}, available in the [[Official Repositories]]. If you usually work in a terminal, you may prefer the {{Pkg|emacs-nox}} variant without GTK (nor sound and other fancy stuff).<br />
<br />
Another common variant is {{Pkg|xemacs}}.<br />
<br />
==Running Emacs==<br />
<br />
Before launching emacs, you should know how to close it (especially if you run it in a terminal) : use the<br />
{{keypress|Ctrl+x}}{{keypress|Ctrl+c}} key sequence.<br />
<br />
===Normal way===<br />
To start Emacs run:<br />
<br />
$ emacs<br />
<br />
or, to use it from the console:<br />
<br />
$ emacs -nw<br />
<br />
If you installed the nox version, 'emacs' and 'emacs -nw' will be the same.<br />
<br />
A file name can also be provided to open that file immediately:<br />
<br />
$ emacs filename.txt<br />
===No Colors===<br />
By default, Emacs starts with a color theme showing hyperlinks in dark blue. To start Emacs without any color theme or scheme:<br />
<br />
$ emacs -nw --color=no<br />
<br />
This will cause all text to appear in white color only.<br />
<br />
===As a daemon===<br />
Emacs can take some time to start since it has to load the .emacs file each time. Besides, you may want to access the same files from differant instances. Since version 23, Emacs is capable to run as a daemon to which users can connect. To run Emacs as a daemon:<br />
<br />
$ emacs --daemon<br />
<br />
You are likely to start the daemon at startup time and to connect a window to the daemon. Besides, it is possible to connect ''both'' graphical and console clients to the daemon at the same time and make the GUI to start quickly.<br />
<br />
If you want to connect to the daemon simply use the folowing command (note that it will start a graphical client if called in a graphical environment or a console client if called in a console like a tty):<br />
<br />
$ emacsclient<br />
<br />
If you still want a console client no matter you are in a graphical environment then use:<br />
<br />
$ emacsclient -t<br />
<br />
Furthermore, you can add the {{ic|-a ""}} parameter.<br />
Now, the first time you call the command, it will start emacs as a daemon, so that it remains running in background to improve startup time for future calls (and to remember buffers as well).<br />
<br />
You could use the following shell configuration:<br />
<br />
{{bc|1=<br />
alias emacs='emacsclient -t -a ""'<br />
EDITOR='emacsclient -t -a ""'<br />
}}<br />
but it has some caveats: many program will fail to load the external editor because of the spaces in the command.<br />
<br />
A more convenient and reliable solution is to write your own script:<br />
{{hc|/bin/em|<br />
#!/bin/sh<br />
emacsclient -a "" -t "$@"<br />
}}<br />
then make it executable:<br />
# chmod 755 /bin/em<br />
<br />
Now 'em' will work just as expected.<br />
<br />
With xfce, if you want to tell it to use {{ic|emacsclient -c}} instead of {{ic|emacs %f}} when opening a new file, you can change your modify your emacs.desktop like so:<br />
{{hc|/usr/share/applications/emacs.desktop|<br />
## This line has been commented out:<br />
#Exec&#61;emacs %f<br />
<br />
## For this line<br />
Exec&#61;emacsclient -c<br />
<br />
## or, if using the preceeding script, uncomment this line instead<br />
#Exec&#61;em<br />
}}<br />
<br />
This way, a client will be called each time you open up a file and so be very fast!<br />
<br />
===As a systemd unit===<br />
<br />
Note that this method has some caveats though. It seems there is a limited shell environment which will restrict shell calls, most notably for compilation mode. You'd be better off using the emacs daemon.<br />
<br />
Create a systemd unit for emacs:<br />
{{hc|/etc/systemd/system/emacs@.service|<nowiki><br />
[Unit]<br />
Description=Emacs: the extensible, self-documenting text editor<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/emacs --daemon<br />
ExecStop=/usr/bin/emacsclient --eval "(progn (setq kill-emacs-hook 'nil) (kill-emacs))"<br />
Restart=always<br />
User=%i<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
You need to enable the unit so that it gets started on every boot:<br />
{{bc|<br />
systemctl enable emacs@<username><br />
}}<br />
<br />
To actually use the unit, either reboot or start the unit manually:<br />
{{bc|<br />
systemctl start emacs@<username><br />
}}<br />
<br />
== Quick Start ==<br />
Although Emacs is complex, it will not take long to begin to understand the benefits which the level of customization and extensibility bring. Furthermore, the comprehensive variety of extensions already available allows it to be transformed into a powerful environment for almost any form of text-editing.<br />
<br />
Emacs has an excellent built-in tutorial which can be accessed by clicking the first link on the splash screen; by selecting ''Help->Emacs Tutorial'' from the menu or by pressing 'F1' followed by 't'. This page is designed to be an additional resource for getting started with Emacs.<br />
<br />
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).<br />
<br />
===Basic terminology and convention===<br />
Emacs uses some terminology and conventions which may seem unusual at first and will be introduced where appropriate. However, there is some terminology which should be introduced before-hand, as it is fundamental to working with Emacs.<br />
<br />
The one piece of terminology which must be introduced early is the concept of ''buffers''. A buffer is a representation of data within Emacs. For example, when a file is opened in Emacs, that file is read from disk and its contents stored in a buffer, which allows it to be edited and saved back to disk later. Buffers are not limited to text, and can also contain images and widgets. Work is in progress to allow buffers to even display applications! Another way to think of it: data available on disk is referred to as a 'file', whereas data available in Emacs is referred to as a 'buffer'.<br />
<br />
The convention for key sequences in Emacs may be unfamiliar. Namely:<br />
<br />
'''C-x''' refers to Control-x<br />
<br />
'''M-x''' refers to Meta-x<br />
<br />
{{Note|'Meta' corresponds to the Alt key in most cases. Alternatively, the Esc key can be used.}}<br />
<br />
For example, to exit Emacs use the following key sequence: '''C-x C-c'''. This can be read as "Hold Control and press 'x'. Release. Hold Control and press 'c'." Although Emacs provides a menu bar, it is recommended practise to focus on learning the key sequences. This guide will refer to keybindings with the convention used in Emacs from now on.<br />
<br />
===Movement===<br />
Cursor movement is very similar to other graphical editors. The mouse and arrow keys can be used to change the position of the cursor (referred to as ''point'' in Emacs). The standard movement commands performed by the arrow keys also have more accessible bindings in Emacs. To move forward one character, use '''C-f''' and to move one character backward, '''C-b'''. '''C-n''' and '''C-p''' can be used to move to the next and previous lines, respectively. Again, it is generally recommended to use these key-sequences in preference to the mouse and/or arrow keys.<br />
<br />
As might be expected, Emacs provides more advanced movement commands, including moving by word and sentence. '''M-f''' moves forward one word and '''M-b''' will move point one word backward. Similarly, '''M-e''' moves point one sentence forward and '''M-a''' one sentence backward.<br />
<br />
Until now, all of the movement commands introduced have been relative to point. '''M-<''' can be used to move point to the beginning of the buffer, with its counterpart, '''M->''', moving to the end of the buffer. To move point to a specific line number, use '''M-g g'''. '''M-g g''' will prompt for the desired line number. Also, to move to the start or end of the current line, use '''C-a''' or '''C-e''', respectively.<br />
<br />
{{Note|Keybindings for these commands, or indeed any command, may differ ''slightly'' depending on which modes are currently active. However, it is unusual for the replacement command not to provide equivalent functionality. See [[Emacs#Modes|Modes]] for more information.}}<br />
<br />
===Files and buffers===<br />
Emacs provides a series of commands to act upon files, the most common of which will be detailed here. '''C-x C-f''' is used to open a file (this command is called 'find-file' in Emacs). Should the file specified not exist, Emacs will open an empty buffer. Saving a buffer will create the file with the buffer's contents. '''C-x C-s''' can be used to save a buffer. To save a buffer with a different filename, use '''C-x C-w''' (this is a mnemonic for the command 'write-file'), which will prompt for the new filename before writing it to disk. It is also possible to ensure all buffers are saved with '''C-x s''', which, should a buffer be modified since its last save, a prompt will be displayed asking which action to take.<br />
<br />
{{Note|'''C-x C-f''' does not read the file from disk again if a buffer corresponding to the file is still opened. To re-read the file from disk, kill the buffer ('''C-x k''') prior to '''C-x C-f''' or use '''M-x revert-buffer'''.}}<br />
<br />
Many interactive commands such as "find-file" or "write-file" prompt for input in the bottom-most line of the Emacs window. This line is referred to as the ''minibuffer''. The minibuffer supports many basic editing commands as well as tab-completion similar to that which is available in many *nix shells. '''<TAB>''' can be pressed twice in succession to display a list of completions, and if desired, the mouse can be also be used to select a completion from that list. Completion in the minibuffer is available for many forms of input including commands and filenames.<br />
<br />
The minibuffer also provides a history feature. The previous items entered for a command can be recalled using the '''Up Arrow''' or '''C-p'''.<br />
<br />
To exit the minibuffer at any time, press '''C-g'''.<br />
<br />
After opening several files, a way to switch between them is needed. Opening a file corresponding to a buffer already available in Emacs, will cause Emacs to switch to that buffer. But this is not the most effective way. Emacs provides '''C-x b''', which prompts for the new buffer to be displayed (tab-completion is available here). By entering the name of a buffer which does not exist, a new buffer with that name will be created.<br />
<br />
{{Note|To switch to the previous buffer use '''C-x b <RET>''', as the previous buffer is the default.}}<br />
<br />
A list of all open buffers can be displayed using '''C-x C-b'''. Should a buffer no longer be required, it can be removed with '''C-x k'''.<br />
<br />
===Editing===<br />
Many editing commands exist within Emacs. Perhaps the most important command which has not yet been introduced is 'undo', which can be performed via '''C-_''' or '''C-/'''. Movement commands generally also have a corresponding delete command. For example, '''M-<backspace>''' can be used to delete a word backwards, and '''M-d''' to delete a word forwards. To delete to the end of the line, or the end of the sentence, use '''C-k''' or '''M-k''', respectively.<br />
<br />
It is a rule-of-thumb that no line be allowed to exceed 80 characters. This aids readability, especially in cases where the line wraps at the edge of a window. Automatically inserting (or removing) line separator(s) is known as ''filling'' in Emacs. A paragraph can be filled using '''M-q'''.<br />
<br />
Characters and words can be transposed using '''C-t''' and '''M-t''', respectively. For example: <code>Hello World!</code> → <code>World! Hello</code><br />
<br />
The case of words is also readily adjustable. '''M-l''' downcases a word from point (<code>HELLO</code> → <code>hello</code>); '''M-u''' upcases a word from point (<code>hello</code> → <code>HELLO</code>) and '''M-c''' capitalizes the first character of a word from point while downcasing the remainder (<code>hElLo</code> → <code>Hello</code>).<br />
<br />
===Killing, yanking and regions===<br />
A region is a section of text between two positions. One of those positions is referred to as ''mark'', and the other is point. '''C-<SPC>''' is used to set the position of mark, after which point can be moved to create a region. Within GNU Emacs 23.1 onwards, this region is visible by default. There are a number of commands which act upon regions, among the most commonly used are ''killing'' commands.<br />
<br />
In Emacs, cut and paste are referred to as ''kill'' and ''yank'', respectively. Many commands which delete more than one character (including many of those in the above section, such as '''C-k''' and '''M-d''') actually cut the text and append it to what is known as the ''kill-ring''. The kill-ring is simply a list of killed text. The kill-ring stores up to the last 60 kills by default. Successive kills are concatenated and stored at the head of the list.<br />
<br />
'''C-w''' and '''M-w''' can be used to kill and copy a region, respectively.<br />
<br />
To insert killed text into a buffer (known as 'yanking'), use '''C-y'''. '''C-y''' can be used multiple times in succession to yank text repeatedly. As mentioned, previous kills are stored in a list, however '''C-y''' only retrieves the first of them. The earlier kills can be accessed via '''M-y'''. This will remove the text inserted by 'yank' initially, replacing it with the text killed earlier. '''M-y''' must be used immediately following '''C-y''' and can be used in many times succession to cycle through the kill-ring.<br />
<br />
===Search and replace===<br />
Searching for a string is common practise in text-editing. This can be performed using '''C-s''' (to search forward) or '''C-r''' (to search backward). These commands prompt for the string for which to search. Searching is performed incrementally, and so it will match the next (or previous) occurrence as you type. To move to the next or previous match, press '''C-s''' or '''C-r''' again, respectively. Once a match has been found, '''<RET>''' can be used to end the search. Alternatively, should you wish to return to the location you initiated the search, use '''C-g'''.<br />
<br />
Once a search is completed (i.e., was not aborted with '''C-g''' or similar), the string which was searched for will be the default for any following search. To make use of this, press '''C-s C-s''' or '''C-r C-r''' to search forward or backward again, respectively.<br />
<br />
I-search has some useful commands. Use '''M-e''' to edit the search field. Use<br />
'''M-c''' to toggle case-sensitive matching.<br />
<br />
Regular Expression searches behave identically to the searching described above except for the command to initiate the search. Use '''C-M-s''' or '''C-M-r''' to initiate a regexp search forward or backward, respectively. Once a Regular Expression search has commenced, '''C-s''' and '''C-r''' can be used to search forward or backward, just as with string searches.<br />
<br />
In addition to searching, it is also possible to perform string and regular expression replacement (via '''M-%''' and '''C-M-%''', respectively). Prompts are provided for both the initial and replacement text, and then another prompt for the action to perform on the highlighted match. Although many options are available (the full list is available by pressing '''?'''), the most commonly used are '''y''', to perform replacement, '''n''', to skip this match, and '''!''' to replace this, and all following matches.<br />
<br />
===Prefix arguments===<br />
<br />
'''C-u''' corresponds to the 'universal-argument' command. Providing a 'universal-argument' is a way to provide more information to a command (this information is referred to as a 'prefix argument'). For instance<br />
<br />
C-u 80 %<br />
<br />
will insert a line of percent signs. Or<br />
<br />
C-u 4 M-d<br />
<br />
Will delete 4 words. In this case, we provided the amount of words desired to the command invoked by '''M-d'''.<br />
<br />
You can make it a little quicker by using the equivalent '''M-<number>''' as universal argument.<br />
<br />
M-80 %<br />
<br />
===Indentation<br />
Indentation is usually performed with either '''<TAB>''', to indent a single line, or with '''C-M-\''', to indent a region. If the region is active (''i.e.'' highlighted), then '''<TAB>''' will also indent region.<br />
<br />
Exactly how text is indented usually depends on the ''major-mode'' which is active. Major-modes often define indentation styles specialising in indenting a certain type of text. (See [[Emacs#Modes|Modes]] for more information.)<br />
<br />
In some cases, a suitable major-mode may not exist for a file type, in which case, manual indentation may be necessary. Create a region (see [[Emacs#Killing, yanking and regions|Killing, yanking and regions]]) then perform indentation with '''C-u <n> C-x <TAB>''' (where '<n>' is the number of columns which the text within the region should be indented). For example:<br />
<br />
Increase the region's indentation by four columns:<br />
<br />
C-u 4 C-x <TAB><br />
<br />
Decrease the region's indentation by two columns.<br />
<br />
C-u -2 C-x <TAB><br />
<br />
===Windows and frames===<br />
Emacs is designed for convenient editing of many files at a time. This is achieved by dividing the Emacs interface into three levels. Namely, buffers, which have already been introduced, as well as ''windows'' and ''frames''.<br />
<br />
A ''window'' is a viewport used for displaying a buffer. A window can display only one buffer at a time, however one buffer can be displayed in many windows. Beneath each window exists a ''mode-line'', which displays information for that buffer.<br />
<br />
A ''frame'' is an Emacs "window" (in standard terminology. i.e., 'window' in the sense of the modern desktop paradigm) which contains a title bar, menu bar and one or more 'windows' (in Emacs terminology. i.e., the above definition of 'window').<br />
<br />
From now on the definition of these terms as they exist in Emacs will be used.<br />
<br />
To split the window vertically or horizontally, use '''C-x 2''' or '''C-x 3''', respectively. This has the effect of creating another window in the current frame. To cycle between multiple windows, use '''C-x o'''.<br />
<br />
The opposite of splitting a window, is deleting it. To delete the current window, use '''C-x 0''' and '''C-x 1''' to delete all windows except the current.<br />
<br />
As with windows, it is also possible to create and delete frames. '''C-x 5 2''' creates a frame. With '''C-x 5 0''' to delete the current frame and '''C-x 5 1''' to delete all except the current frame.<br />
<br />
{{Note|These commands do not affect buffers. For example, deleting a window does not kill the buffer it displays.}}<br />
<br />
===Modes===<br />
An Emacs mode is an extension written in Emacs Lisp that controls the behaviour of the buffer it is attached to. Usually it provides indentation, syntax highlighting and keybindings for editing that form of text. Sophisticated modes can turn Emacs into a full-fledged IDE (Integrated Development Environment). Emacs will generally use a file's extension to determine which mode should be loaded.<br />
<br />
Useful modes for editing shell scripts are sh-mode, line-number-mode and column-number-mode. They can be used in parallel and are invoked by:<br />
<br />
'''M-x sh-mode <RET>'''<br />
<br />
'''M-x column-number-mode <RET>'''<br />
<br />
line-number-mode is enabled by default, though, it can be toggled on/off by issuing the command again:<br />
<br />
'''M-x line-number-mode <RET>'''<br />
<br />
sh-mode is a ''major-mode''. Major-modes adjust Emacs, and often also provide a specialised set of commands, for editing a particular type of text. Only one major-mode can be active in each buffer. In addition to syntax highlighting, and indentation support, sh-mode defines several commands to help write shell scripts. The following shows a few of those commands:<br />
<br />
'''C-c (''' Insert a function definition<br />
<br />
'''C-c C-f''' Insert a 'for' loop<br />
<br />
'''C-c TAB''' Insert an 'if' statement<br />
<br />
'''C-c C-w''' Insert a 'while' loop<br />
<br />
'''C-c C-l''' Insert an indexed loop from 1 to n<br />
<br />
'line-number-mode' and 'column-number-mode', are ''minor-modes''. Minor-modes can be used to extend a major-mode and any number of minor-modes can be enabled at once.<br />
<br />
==Tips and tricks==<br />
While the previous sections has given an overview of the basic editing commands available, it has not given an indication of the possibilities of Emacs. This section will cover some more advanced techniques and functionality.<br />
<br />
We cannot cover everything as it would be too long. So this section will only serve as a ''demo'' for some dazzling features of Emacs.<br />
<br />
See [[#Documentation|Documentation]] to get access to more in-depth detail about all features.<br />
<br />
===TRAMP===<br />
TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:<br />
<br />
To prompt for the root password before opening /etc/hosts with root permissions:<br />
<br />
C-x C-f /su::/etc/hosts<br />
<br />
To connect to 'myhost' as 'myuser' via SSH and open the file ~/example.txt:<br />
<br />
C-x C-f /ssh:myuser@myhost:~/example.txt<br />
<br />
The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'. TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.<br />
<br />
===Keyboard macros and registers===<br />
This section will provide a practical demonstration of the use of a couple of more powerful editing features. Namely, ''keyboard macros'' and ''registers''.<br />
<br />
The aim will be to produce a listing of a series of characters and their corresponding position in this list. While it is possible to format each of them by hand, this would be slow and error-prone. Alternatively, some of Emacs' more powerful editing functionality could be leveraged. Before describing a solution, some details behind the techniques which will be used follow.<br />
<br />
The first feature which will be introduced is ''registers''. Registers are used to store and retrieve a variety of data types ranging from numbers to window configurations. Each register is given a name of a single character: this character is used to access the register.<br />
<br />
The other which will be demonstrated is ''keyboard macros''. A keyboard macro stores a sequence of commands so they can be easily repeated later. These changes will now be performed step-by-step.<br />
<br />
Starting with a buffer containing our set of characters:<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
Prepare a register by invoking the `number-to-register' command ('''C-x r n''') then storing the number '0' in register 'k':<br />
<br />
C-x r n k<br />
<br />
With point at the beginning of the buffer, start a keyboard macro ('''C-x (''') and begin to format the characters:<br />
<br />
C-x ( C-f M-4 .<br />
<br />
Insert ('''C-x r i''') and increment ('''C-x r +''') the register 'k'. The prefix argument ('''C-u''') is used to leave point positioned after the inserted text:<br />
<br />
C-u C-x r i k C-x r + k<br />
<br />
Complete the formatting by inserting a newline. Emacs can then repeat that process, beginning from the point where we started defining the keyboard macro, for the rest of the characters. '''C-x e''' completes then invokes the keyboard macro. The prefix argument, '''M-0''', causes the macro to repeat until it comes across an error. In this case it aborts once it reaches the end of the buffer.<br />
<br />
<RET> M-0 C-x e<br />
<br />
The result:<br />
<br />
A....0<br />
B....1<br />
C....2<br />
[...]<br />
x....49<br />
y....50<br />
z....51<br />
<br />
If you want to save your macro for leter use, you must give it a name and save it to your configuration file:<br />
name-last-kbd-macro <br />
insert-kbd-macro<br />
<br />
All defined macros are stored in the macro ring. To cycle between macros, use<br />
'''C-x C-k C-n''' next macro<br />
'''C-x C-k C-p''' previous macro<br />
<br />
You can also use registers to save virtually anything.<br />
<br />
'''C-x r SPC''' Copy current point (position) to register<br />
'''C-x r w''' Copy current window configuration to register.<br />
'''C-x r j''' Restore register.<br />
<br />
So if you often work with windows side by side, for different project, you can save the configuration for the different projects and easily switch from one view to the other.<br />
<br />
You can list used registers with the '''list-registers''' command.<br />
<br />
===Regular expressions===<br />
From the Emacs Manual: "A regular expression, or ''regexp'' for short, is a pattern that denotes a (possibly infinite) set of strings." This section will not go into any detail regarding regular expressions themselves (as there is simply too much to cover). It will however provide a quick demonstration of their power. See [http://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html#Regular-Expressions Regular Expressions] section in the Emacs Manual for further reading.<br />
<br />
Given the same scenario presented above: A list of characters which are to be formatted to represent their respective position in the list. (see [[Emacs#Keyboard macros and registers|Keyboard macros and registers]]). Again, starting with a buffer containing.<br />
<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz<br />
<br />
At the beginning of the buffer, use '''C-M-%''' (if the key-sequence is difficult to perform, it may be more comfortable to use '''M-x query-replace-regexp'''). At the prompt:<br />
\(.\)<br />
which simply matches one character. Then, when prompted for the replacement:<br />
\1....\#^J<br />
{{Note|'^J' represents where a newline should be placed, it should not be entered into the prompt. The newline must instead be inserted literally using '''C-q C-j'''.}}<br />
The replacement expression reads: "Insert the matched text between the first set of parentheses (in this case, a single character), followed by 4 periods then insert an automatically incremented number followed by a newline.<br />
<br />
Finally, press '''!''' to apply this across the entire buffer. All of the formatting that was performed in the previous section was performed with a single regexp replacement.<br />
<br />
===Rectangular selections===<br />
<br />
A very powerful feature you may expect from advanced text editors is the possibility to select and edit text in a rectangular area.<br />
<br />
This also works in Emacs. Select your text as usual with '''C-SPC'''. Now you can use several rectangular command.<br />
<br />
'''C-x r t''' Replace rectangle with text.<br />
'''C-x r k''' Kill (and save in kill-ring) rectangle.<br />
'''C-x r y''' Yank rectangle.<br />
'''C-x r o''' Blank out rectangle.<br />
<br />
Note that the command will not affect text outside the rectangle, even though it is highlighted. <br />
<br />
=== Bookmarks ===<br />
<br />
Emacs can remember a list of visited files.<br />
<br />
'''C-x r m''' Add current buffer to bookmarks.<br />
'''C-x r b''' Open a buffer from bookmarks.<br />
'''C-x r l''' List bookmarks.<br />
<br />
===Elisp interpreter===<br />
<br />
Emacs can evaluate any elisp expression at anytime with the '''eval-last-sexp''' function (bound to '''C-x C-e''' by default). Emacs always spawn a '''*scratch*''' buffer when you start it. It will not be saved to disk, so feel free to add any pice of text / code you want. It is especially useful for elisp evaluation. Note that this buffer starts using the '''lisp-interaction-mode''' by default.<br />
<br />
Alternatively Emacs provides a top-level elisp interpreter with the '''ielm''' command.<br />
<br />
=== Smart window switch ===<br />
<br />
The traditional window switch with '''C-x o''' can be cumbersome to use in the long run.<br />
The '''windmove''' commands provide a more convenient way to do this. All you have to do is to hold down {{keypress|Shift}} while pointing at a window with the arrow keys.<br />
<br />
To activate the windmove keys, use the following in your configuration file:<br />
<br />
{{hc|~/.emacs|<br />
(when (fboundp 'windmove-default-keybindings)<br />
(windmove-default-keybindings))<br />
}}<br />
<br />
===Shell calls===<br />
<br />
Use '''M-!''' to call an external command. Use a prefix argument ('''C-u M-!''') to output the result to current buffer at point.<br />
<br />
You can use '''M-|''' on a region to use it as input for a command. For instance<br />
<br />
'''C-u M-| sort -u RET'''<br />
<br />
will sort region, remove duplicates and replace the region with the result.<br />
<br />
===Shell buffers===<br />
<br />
You can spawn a shell buffer and execute commands just like you would do in any terminal.<br />
A classic shell buffer can be spawned with the '''shell''' command.<br />
<br />
Emacs features a very powerful shell entirely written in Emacs Lisp, the '''eshell'''. The major advantage over shells like csh or zsh is that the native shell language is elisp itself. So you can use all advanced feature of elisp for your shell functions.<br />
<br />
=== Show matching parentheses ===<br />
<br />
You can use the '''show-paren''' mode.<br />
By default, there’s a small delay before showing a matching parenthesis. Set the '''show-paren-delay''' to 0 to deactivate.<br />
<br />
{{hc|~/.emacs|<br />
(show-paren-mode 1)<br />
(setq show-paren-delay 0)<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
You can choose the dictionnary with<br />
'''M-x ispell-change-dictionary'''<br />
<br />
To check a single work use '''M-$'''.<br />
You can start checking the whole buffer with<br />
'''M-x ispell-buffer'''<br />
<br />
You can enable on-the-fly spell checking by enabling the '''flyspell-mode'''. For source code files you can restrict the mode to comments by using the '''flyspell-prog-mode''' instead.<br />
<br />
=== Tables ===<br />
<br />
Emacs comes with some powerful functions to handle and generate tables for various languages. Let's show an example.<br />
<br />
Fruits Quantity<br />
Apples 5<br />
Melons 2<br />
<br />
Now select the previous content in a region, and run<br />
table-capture<br />
<br />
Use two spaces for the column delimiter, and a line brak ('''C-q C-j''') for the row delimiter.<br />
This will lead to the following result.<br />
<br />
+------+--------+<br />
|Fruits|Quantity|<br />
+------+--------+<br />
|Apples|5 |<br />
+------+--------+<br />
|Melons|2 |<br />
+------+--------+<br />
<br />
You can revert back the operation with <br />
table-release<br />
There is a lot of handy ''table-*'' functions, like ''table-insert-row'', ''table-span-cell'', ''table-widen-cell'', etc.<br />
<br />
Finally, the ultimate purpose of the ''table'' functions is to convert it to the desired markup language.<br />
Use the ''table-generate-source'' for that.<br />
For LaTeX, the previous table would result in<br />
<br />
% This LaTeX table template is generated by emacs 24.2.1<br />
\begin{tabular}{|l|l|}<br />
\hline<br />
Fruits & Quantity \\<br />
\hline<br />
Apples & 5 \\<br />
\hline<br />
Melons & 2 \\<br />
\hline<br />
\end{tabular}<br />
<br />
Using the table mode you can also do some spreadsheet work like sum on rows and columns, but you will quickly find it limited. Besides it is quite slow. Have a look at the [[#Agenda, spreadsheet and document authoring|org-mode]] for much more powerful possibilities.<br />
<br />
=== Agenda, spreadsheet and document authoring ===<br />
<br />
Emacs can offer powerful office features thanks to the famous and powerful [http://orgmode.org/ Org mode]. This mode is part of the standard Emacs distribution.<br />
<br />
Org mode is originally a powerful TODO and Agenda agent, but has quickly evolved to a much wider set of features.<br />
There is simply too much to tell about Org that we cannot aford even to skim over all the features. So we will only whet your appetite with a few exemples.<br />
<br />
Open a new file TODO.org file, Org mode should be loaded. If not, switch to it with '''M-x org-mode'''.<br />
{{hc|TODO.org|<br />
* First entry<br />
** Subentry<br />
Some comments<br />
*** Subsubentry<br />
* Second entry<br />
- List item 1<br />
- List item 2<br />
}}<br />
<br />
Now a few useful bindings.<br />
* '''TAB''' to cycle-fold current entry.<br />
* '''S-TAB''' to cycle-fold all entries.<br />
* '''M-RET''' to start a new item on the same level as the current one.<br />
* '''M-<left>''' and '''M-<right>''' to change level.<br />
* '''M-<up>''' and '''M-<down>''' to move item together with all its subsections.<br />
* '''S-<left>''' and '''S-<right>''' to change status. On list items it will change the item style.<br />
* '''S-<up>''' and '''S-<down>''' to change priority.<br />
* '''C-c ^''' to sort all subentries of the current entry.<br />
* '''C-c .''' to add a timestamp to the current entry. Use {{keypress|Shift}} and arrows to skip days or weeks. Use the mouse on the calendar or press {{keypress|Enter}} on a specific day to choose it.<br />
<br />
The spreadsheet features are very comprehensive. Let's give an excerpt from the manual:<br />
<br />
{{bc|<nowiki><br />
Finally, just to whet your appetite for what can be done with the<br />
fantastic `calc.el' package, here is a table that computes the Taylor<br />
series of degree `n' at location `x' for a couple of functions.<br />
<br />
|---+-------------+---+-----+--------------------------------------|<br />
| | Func | n | x | Result |<br />
|---+-------------+---+-----+--------------------------------------|<br />
| # | exp(x) | 1 | x | 1 + x |<br />
| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |<br />
| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |<br />
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |<br />
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |<br />
| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |<br />
|---+-------------+---+-----+--------------------------------------|<br />
#+TBLFM: $5=taylor($2,$4,$3);n3<br />
</nowiki>}}<br />
Org mode recognizes a table when the pipe '''|''' is the first non-whitespace character on line. In the previous text, no line was drawn. This is done automatically when '''TAB''' is pressed after an entry or the '''|-''' sequence. The result column was not written by hand neither, it is computed from the calc formula on the last line. Use '''C-u C-c C-c''' to recompute all values in a table.<br />
<br />
There is also some handy row and column manipulation bindings like those for the TODO file. {{keypress|Alt}} plus arrows will move columns and arrows.<br />
<br />
For more in-depth details, refer to the official manual: '''C-h i m Org mode RET'''.<br />
<br />
=== Refactoring and smart completion ===<br />
<br />
If you are looking for popular programming features found in most IDE (such as Eclipse), the [http://cedet.sourceforge.net/semantic.shtml Semantic] tool will do the job. It is part of Emacs standard distribution. Currently C, C++, Scheme, Javascript, Java, HTML, and Make are well supported. You can find a table on the current support state on the [http://cedet.sourceforge.net/languagesupport.shtml CEDET page].<br />
<br />
Open a file in your favorite programming landuage supported by Semantic and turn on the Semantic minor mode with<br />
M-x semantic-mode<br />
Semantic will work for a few seconds parsing the libraries included from your file (in C that would mostly be the standard library for instance).<br />
<br />
==== Features ====<br />
<br />
Once done, you can start using the great Semantic features:<br />
;Smart completion<br />
Press '''C-c , SPC''' to complete a symbol at point. If it is an argument, it will check for type correctness.<br />
<br />
;Jump to symbol<br />
Press '''C-c , j''' to prompt for a symbol and jump to its definition. You can use auto-completion with '''TAB'''. Use a capital '''J''' to search for symbol accross files.<br />
<br />
;List symbol calls<br />
Press '''C-c , g''' to prompt for a symbol and list the places where it is being referred to. You can use '''n''' and '''p''' to navigate through the resulting entries. Press '''RET''' to toggle details, and '''RET''' again on a reference to jump to it. Use a capital '''G''' in the first command to work across files.<br />
<br />
;Refactoring<br />
First list use of the symbol you want to refactor with the aforementioned command. Now press '''(''' to start defining a macro on the symbol. This is actually much more powerful than refactoring since you can apply any function to the symbol and even act on its surrounding symbols. Press '''C-x )''' to finish the macro and '''E''' to call it.<br />
<br />
;Describe symbol<br />
Call the following function to display details on a symbol.<br />
semantic-ia-show-summary<br />
This can be very useful for complexe data structures and function prototypes. There is no binding by default.<br />
<br />
==== Configuration ====<br />
<br />
Here follows a sample configuration for use of Semantic with all supported programming languages: an example binding and a display configuration.<br />
;; Semantic with ghost display (allows M-n and M-p to browse completion).<br />
(semantic-mode 1)<br />
(define-key my-keys-minor-mode-map (kbd "C-c , d") 'semantic-ia-show-summary)<br />
(setq semantic-complete-inline-analyzer-displayor-class 'semantic-displayor-ghost)<br />
<br />
You can also add some specialization for a specific language. Here for C:<br />
(add-hook<br />
'c-mode-hook<br />
(lambda ()<br />
(local-set-key (kbd "M-TAB") 'semantic-complete-analyze-inline)<br />
(local-set-key "." 'semantic-complete-self-insert)<br />
(local-set-key ">" 'semantic-complete-self-insert)))<br />
<br />
==== Further reading ====<br />
<br />
You can access the info manual directly from Emacs: '''C-h i m Semantic RET'''.<br />
<br />
=== Using Emacs as git mergetool ===<br />
<br />
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.<br />
<br />
{{hc|.gitconfig|<nowiki><br />
[mergetool.ediff]<br />
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\\\"))\" <br />
<br />
[merge]<br />
tool = ediff<br />
</nowiki>}}<br />
<br />
Note that the command has to be on a single line.<br />
In the above example, we launch a new instance of Emacs. You might want to use emacsclient for quicker startup; it is not recommended though since the Ediff call is not really clean: it could mess with your current Emacs session.<br />
<br />
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<br />
emacs -q -l ~/.emacs-light<br />
where the light configuration file loads only what you need for Ediff.<br />
<br />
See [http://kerneltrap.org/mailarchive/git/2007/7/1/250424 kerneltrap.org] and [http://stackoverflow.com/questions/1817370/using-ediff-as-git-mergetool stackoverflow] for more details on this trick and the Ediff issue.<br />
<br />
==Customization==<br />
<br />
Emacs can configured by editing {{ic|~/.emacs}} or using '''M-x customize'''. This section will focus on editing {{ic|~/.emacs}} by hand, and provide some example customizations to demonstrate commonly-configured aspects of Emacs. The customize command provides a simple interface to make adjustments, though it may become restricting as you grow more familiar with Emacs.<br />
<br />
All of the examples here can be performed while Emacs is running. To evaluate the expression within Emacs, use:<br />
<br />
'''C-M-x''' with point anywhere within the expression.<br />
<br />
or<br />
<br />
'''C-x C-e''' with point following the last ')'<br />
<br />
For some users, typing 'yes' and 'no' in prompts can quickly become tiring. To instead use the 'y' and 'n' keys at these prompts:<br />
<br />
(defalias 'yes-or-no-p 'y-or-n-p)<br />
<br />
To stop the cursor blinking, use:<br />
<br />
(blink-cursor-mode -1)<br />
<br />
Similarly, to enable column-number-mode, as discussed in the previous section:<br />
<br />
(column-number-mode 1)<br />
<br />
The similarities between the previous two commands are not a coincidence: blink-cursor-mode and column-number-mode are both minor-modes. As a rule, minor-modes can be enabled given positive argument or disabled with a negative argument. Should the argument be omitted, the minor-mode will be toggled on/off.<br />
<br />
Here are some more examples of minor-modes. The following will disable the scroll bars, menu-bar and tool-bar, respectively.<br />
<br />
(scroll-bar-mode -1)<br />
(menu-bar-mode -1)<br />
(tool-bar-mode -1)<br />
<br />
The variable, 'auto-mode-alist', can be modified to change the major-mode used by default for certain file names. The following example will make the default major-mode for '.tut' and '.req' files 'text-mode'.<br />
<br />
(setq auto-mode-alist<br />
(append<br />
'(("\\.tut$" . text-mode)<br />
("\\.req$" . text-mode))<br />
auto-mode-alist))<br />
<br />
Settings can also be applied on a per-mode basis. A common method for this is to add a function to a ''hook''. For example, to force indentation to use spaces instead of tabs, but only in text-mode:<br />
<br />
(add-hook 'text-mode-hook (lambda () (setq indent-tabs-mode nil)))<br />
<br />
Similarly, to only use spaces for indentation everywhere:<br />
<br />
(setq-default indent-tabs-mode nil)<br />
<br />
Keybindings can be adjusted in two ways. The first of which is 'define-key'. 'define-key' creates a keybinding for a command but only in one mode. The example below will make '''F8''' delete any whitespace from the end of each line of a 'text-mode' buffer:<br />
<br />
(define-key text-mode-map (kbd "<f8>") 'delete-trailing-whitespace)<br />
<br />
The other method is 'global-set-key'. This is used to bind a key to a command everywhere. To bind 'query-replace-regexp' ('''C-M-%''') to '<f7>'.<br />
<br />
(global-set-key (kbd "<f7>") 'query-replace-regexp)<br />
<br />
Binding a command to an alternate key does not replace any existing bindings. Which is to say, 'query-replace-regexp' would be bound to both '''F7''' and '''C-M-%''' after the above example.<br />
<br />
Almost anything within Emacs can be configured. Browsing through the [http://emacswiki.org/ Emacs Wiki] should give a solid place to start.<br />
<br />
=== Multiple configurations ===<br />
<br />
You can use several configurations and tell Emacs to load one or the other.<br />
<br />
For example, let's define two configuration files.<br />
<br />
{{hc|.emacs|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/plugins" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
This is the full configuration we load for the deamon. But the ''plugins'' file is huge and slow to load. If we want to spaqn a new Emacs instance that does not need the ''plutings'' features, it can be cumbersome to load it everytime in the long time.<br />
<br />
{{hc|.emacs-light|<br />
(load "~/.emacs.d/main" nil t)<br />
(load "~/.emacs.d/functions" nil t)<br />
(load "~/.emacs.d/modes" nil t)<br />
(load "~/.emacs.d/theme" nil t)<br />
}}<br />
<br />
And now we launch Emacs with<br />
emacs -q -l ~/.emacs-light<br />
You can create an alias to ease the call.<br />
<br />
=== Loading extensions ===<br />
<br />
You can load extensions using the ''require'' function. For instance<br />
(require 'mediawiki)<br />
<br />
If you try using the same configuration file on a machine where mediawiki is not installed, Emacs will primpt for an error. Besides, all extension-specific code would be parsed for nothing.<br />
<br />
The trick is to test the return value of ''require'':<br />
<br />
(if (require 'mediawiki nil t)<br />
(progn<br />
(setq mediawiki-site-alist '(<br />
("ArchLinux" "https://wiki.archlinux.org/" "UserName" "" "Main Page")<br />
)<br />
)<br />
(setq mediawiki-mode-hook<br />
(lambda ()<br />
(visual-line-mode 1)<br />
(turn-off-auto-fill)<br />
))<br />
)) <br />
<br />
=== Local and custom variables ===<br />
<br />
You can define variables in your configuration file that can be later one modified locally for a file.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation")<br />
<br />
Now in any file you can define local variables in two ways:<br />
* On the very first line, write<br />
// -*- my-compiler:g++; mode:c++ -*-<br />
* If you cannot (or do not want to) write this on the first line, you can put it at the end:<br />
// Local Variables:<br />
// my-compiler: g++<br />
// mode: c++<br />
// End:<br />
<br />
Note that the beginning characters need to be comments for the current language, that's why here we used two backslashes for C++. For Elisp you would use<br />
;; -*- mode:emacs-lisp -*-<br />
<br />
There is two functions that may help you in defining the variables: ''add-file-local-variable'' and ''add-file-local-variable-prop-line''.<br />
<br />
Finally, custom variable are considered insecure by default. If you try to open a file that contains local variable redefining insecure custom variables, Emacs will ask you for confirmation.<br />
<br />
If you know what you are doing, 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.<br />
<br />
(defcustom my-compiler "gcc" "Some documentation" :safe 'stringp)<br />
<br />
In the previous example, if you attempt to set anything else than a string, Emacs will consider it insecure.<br />
<br />
=== Custom colors and theme ===<br />
<br />
Colors can be easily customized using the ''face'' facility.<br />
(set-face-background 'region "color-17")<br />
(set-face-foreground 'region "white")<br />
(set-face-bold-p 'font-lock-builtin-face t ) <br />
<br />
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.<br />
<br />
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.<br />
<br />
=== SyncTeX support ===<br />
<br />
Emacs is definitely one of the most powerful LaTeX editor. This is mostly due to the fact you can adapt or create a LaTeX mode to fit your needs best.<br />
<br />
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.<br />
# umask 022 && tlmgr install synctex<br />
<br />
SyncTeX support is viewer-dependent. Here we will use Zathura as an example, so the code needs to be adapted if you want to use another PDF viewer.<br />
<br />
(defcustom tex-my-viewer "zathura --fork -s -x \"emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"'\"'\"%{input}\"'\"'\")) (goto-line %{line}))'\"" <br />
"PDF Viewer for TeX documents. You may want to fork the viewer<br />
so that it detects when the same document is launched twice, and<br />
persists when Emacs gets closed.<br />
<br />
Simple command:<br />
<br />
zathura --fork<br />
<br />
We can use<br />
<br />
emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"%{input}\")) (goto-line %{line}))'<br />
<br />
to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes matter and must be escaped appropriately."<br />
:safe 'stringp)<br />
<br />
Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-mode, you will have to set the viewer accordingly.<br />
<br />
Now open a LaTeX source file with Emacs, compile the document, and launch the viewer. Zathura will spawn. If you press {{keypress|Ctrl+Left click}} Emacs should place the point at the corresponding position.<br />
<br />
== Documentation ==<br />
<br />
You may find yourself overwhelmed by the amount of Emacs features. You may find it difficult to know how to use Emacs Lisp to customize your favorite mods, or even to create your own modes / packages. Thankfully Emacs takes a strong point to auto-documenting everything: its internals, current configuration, bindings, etc. Almost everything is documented.<br />
<br />
===Contextual help===<br />
Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. The following is a listing of some of the most helpful of these:<br />
<br />
'''C-h a''' Find a command matching a description.<br />
<br />
'''C-h b''' List all active keybindings.<br />
<br />
'''C-h f''' Describe the given function.<br />
<br />
'''C-h k''' Find which command a key is bound to.<br />
<br />
'''C-h m''' Display information regarding the currently active modes.<br />
<br />
'''C-h t''' Start the Emacs tutorial.<br />
<br />
'''C-h v''' Describe the given function.<br />
<br />
'''C-h w''' Find which key(s) a command is bound to.<br />
<br />
=== The Manuals ===<br />
<br />
If you really want to master Emacs, the most recommanded source of documentation remains the official manuals:<br />
* Emacs: the complete Emacs user manual.<br />
* Emacs FAQ.<br />
* Emacs Lisp Intro: if you never used any programming language before.<br />
* Elisp: if you are already familiar with a programming language.<br />
<br />
You can access it as PDFs from [http://www.gnu.org/software/emacs/manual/ GNU.org] or directly from Emacs itself thanks to the embedded 'info' reader: '''C-h i'''. Press '''m''' to choose a book.<br />
<br />
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.<br />
<br />
You may want to read the '''Info''' book to know more about it: '''C-h i m info <RET>'''.<br />
Press '''?''' while in info mode for a quick list of shortcuts.<br />
<br />
== Extensions ==<br />
<br />
While Emacs includes hundreds of modes, libraries and other extensions, there are many more available to further Emacs' capabilities. The majority of these come with instructions detailing any changes needed to be made to {{ic|~/.emacs}}. These instructions are generally found in the comment block at the beginning of an elisp source file, or in a README (or similar) should the extension consist of multiple source files.<br />
<br />
A number of popular extensions are available as packages in the 'community' repository, and more still are available via the [[AUR]]. The name of such packages have a 'emacs-' prefix (for example, emacs-lua-mode). In many cases, the changes which need to be made to {{ic|~/.emacs}} are shown during the installation of the package.<br />
<br />
Should instructions describing how to activate a specific extension not be available in the aforementioned location(s), check for a corresponding page in the [http://emacswiki.org/ Emacs Wiki], which will almost certainly provide an example configuration. The Emacs Wiki is also an excellent resource for discovering even more extensions.<br />
<br />
You can also use the [http://tromey.com/elpa/ Emacs Lisp Package Archive (ELPA)] to automatically install packages. See the website for instructions. ELPA is included with Emacs 24 (the newest version of Emacs); it is an accepted part of the Emacs ecosystem.<br />
<br />
=== Emacs MediaWiki ===<br />
Since we are at it, you may be a contributor to Arch Linux Wiki, or any Mediawiki-based website. Then emacs will become your best friend thanks to the [[Emacs Mediawiki]] extension. Check the dedicated page for more details.<br />
<br />
== Troubleshooting ==<br />
<br />
===Colored output issues===<br />
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.<br />
<br />
Including the following into {{ic|~/.emacs}} amends the problem:<br />
(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)<br />
<br />
===Menus appear empty===<br />
A bug exists in GNU Emacs 23.1 (using the GTK toolkit) which may cause some menus to appear empty. This appears to be fixed in Emacs' CVS trunk. The corresponding [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=550541 Debian bug report] contains a workaround.<br />
<br />
=== Problems displaying characters in X Windows ===<br />
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.<br />
<br />
=== Slow startup ===<br />
Slow startup times are often caused by one of two things.<br />
<br />
To determine which it might be, run Emacs with:<br />
<br />
$ emacs -q<br />
<br />
If Emacs still starts slowly, refer to [[Emacs#Incorrect network configuration|Incorrect network configuration]]. If not, it is almost certainly a [[Emacs#Init file loads slowly|problem in your .emacs]].<br />
<br />
* Mistakes, particularly in /etc/hosts, will often result in a 5+ second delay when starting Emacs. Refer to '[[Configuring_network#Set_the_hostname|set the hostname]]' in the network configuration guide for information.<br />
<br />
* 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's 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:<br />
<br />
(require 'anything)<br />
<br />
you might use:<br />
<br />
(autoload 'anything "anything" "Select anything" t)<br />
<br />
=== Cannot open load file: ... ===<br />
<br />
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:<br />
<br />
(add-to-list 'load-path "/path/to/directory/")<br />
<br />
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:<br />
<br />
(add-to-list 'load-path "/usr/share/emacs/site-lisp")<br />
<br />
If compiling Emacs by hand, keep in mind that the default prefix is '/usr/local'.<br />
<br />
=== Dead-accent keys problem: '<dead-acute> is undefined' ===<br />
<br />
Searching about this bug on Google, we find this link:<br />
http://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00167.html<br />
<br />
Explaining the problem: in recent versions of<br />
b72<br />
Emacs, the normal way to use accent keys doesn't work as expected. Trying to accent a word like 'fiancé' will produce the message above.<br />
<br />
A way to solve it is just put the line above on your startup file, {{ic|~/.emacs}}:<br />
<br />
(require 'iso-transl)<br />
<br />
And no, it isn't 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):<br />
<br />
:''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<br />
a3b<br />
classified as a feature ... Maybe it's just because the file is auto-loaded though pretty useless. ''<br />
<br />
=== C-M-% and some other bindings do not work in emacs nox ===<br />
<br />
This is because terminals are more limited than Xorg. Some terminals may handle more bindings than other, though. Two solutions:<br />
* either use the graphical version,<br />
* or change the binding to a supported one.<br />
<br />
Example:<br />
{{hc|.emacs|<br />
(global-set-key (kbd "C-M-y") 'query-replace-regexp)<br />
}}<br />
<br />
=== Emacs client gets stuck when switching back to it ===<br />
<br />
If you are using Emacs daemon, then you should know that input is blocking. If one Emacs instance is in the minibuffer (after an '''M-x''' for instance), then all other instance will wait for it to finish. Press '''C-g''' to cancel any input to make sure this Emacs session is not blocking.<br />
<br />
=== Shift + Arrow keys are not working if Emacs is inside Tmux ===<br />
<br />
First you must enable xterm-keys in your [[tmux]] config.<br />
{{hc|.tmux.conf|<br />
setw -g xterm-keys on<br />
}}<br />
<br />
But, this will break other key combinations. To fix them, put the following in your emacs config.<br />
{{hc|.emacs|<br />
;; handle tmux's xterm-keys<br />
;; put the following line in your ~/.tmux.conf:<br />
;; setw -g xterm-keys on<br />
(if (getenv "TMUX")<br />
(progn<br />
(let ((x 2) (tkey ""))<br />
(while (<&#61; x 8)<br />
;; shift<br />
(if (&#61; x 2)<br />
(setq tkey "S-"))<br />
;; alt<br />
(if (&#61; x 3)<br />
(setq tkey "M-"))<br />
;; alt + shift<br />
(if (&#61; x 4)<br />
(setq tkey "M-S-"))<br />
;; ctrl<br />
(if (&#61; x 5)<br />
(setq tkey "C-"))<br />
;; ctrl + shift<br />
(if (&#61; x 6)<br />
(setq tkey "C-S-"))<br />
;; ctrl + alt<br />
(if (&#61; x 7)<br />
(setq tkey "C-M-"))<br />
;; ctrl + alt + shift<br />
(if (&#61; x 8)<br />
(setq tkey "C-M-S-"))<br />
<br />
;; arrows<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d A" x)) (kbd (format "%s<up>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d B" x)) (kbd (format "%s<down>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d C" x)) (kbd (format "%s<right>" tkey)))<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d D" x)) (kbd (format "%s<left>" tkey)))<br />
;; home<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d H" x)) (kbd (format "%s<home>" tkey)))<br />
;; end<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d F" x)) (kbd (format "%s<end>" tkey)))<br />
;; page up<br />
(define-key key-translation-map (kbd (format "M-[ 5 ; %d ~" x)) (kbd (format "%s<prior>" tkey)))<br />
;; page down<br />
(define-key key-translation-map (kbd (format "M-[ 6 ; %d ~" x)) (kbd (format "%s<next>" tkey)))<br />
;; insert<br />
(define-key key-translation-map (kbd (format "M-[ 2 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; delete<br />
(define-key key-translation-map (kbd (format "M-[ 3 ; %d ~" x)) (kbd (format "%s<delete>" tkey)))<br />
;; f1<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d P" x)) (kbd (format "%s<f1>" tkey)))<br />
;; f2<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d Q" x)) (kbd (format "%s<f2>" tkey)))<br />
;; f3<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d R" x)) (kbd (format "%s<f3>" tkey)))<br />
;; f4<br />
(define-key key-translation-map (kbd (format "M-[ 1 ; %d S" x)) (kbd (format "%s<f4>" tkey)))<br />
;; f5<br />
(define-key key-translation-map (kbd (format "M-[ 15 ; %d ~" x)) (kbd (format "%s<f5>" tkey)))<br />
;; f6<br />
(define-key key-translation-map (kbd (format "M-[ 17 ; %d ~" x)) (kbd (format "%s<f6>" tkey)))<br />
;; f7<br />
(define-key key-translation-map (kbd (format "M-[ 18 ; %d ~" x)) (kbd (format "%s<f7>" tkey)))<br />
;; f8<br />
(define-key key-translation-map (kbd (format "M-[ 19 ; %d ~" x)) (kbd (format "%s<f8>" tkey)))<br />
;; f9<br />
(define-key key-translation-map (kbd (format "M-[ 20 ; %d ~" x)) (kbd (format "%s<f9>" tkey)))<br />
;; f10<br />
(define-key key-translation-map (kbd (format "M-[ 21 ; %d ~" x)) (kbd (format "%s<f10>" tkey)))<br />
;; f11<br />
(define-key key-translation-map (kbd (format "M-[ 23 ; %d ~" x)) (kbd (format "%s<f11>" tkey)))<br />
;; f12<br />
(define-key key-translation-map (kbd (format "M-[ 24 ; %d ~" x)) (kbd (format "%s<f12>" tkey)))<br />
;; f13<br />
(define-key key-translation-map (kbd (format "M-[ 25 ; %d ~" x)) (kbd (format "%s<f13>" tkey)))<br />
;; f14<br />
(define-key key-translation-map (kbd (format "M-[ 26 ; %d ~" x)) (kbd (format "%s<f14>" tkey)))<br />
;; f15<br />
(define-key key-translation-map (kbd (format "M-[ 28 ; %d ~" x)) (kbd (format "%s<f15>" tkey)))<br />
;; f16<br />
(define-key key-translation-map (kbd (format "M-[ 29 ; %d ~" x)) (kbd (format "%s<f16>" tkey)))<br />
;; f17<br />
(define-key key-translation-map (kbd (format "M-[ 31 ; %d ~" x)) (kbd (format "%s<f17>" tkey)))<br />
;; f18<br />
(define-key key-translation-map (kbd (format "M-[ 32 ; %d ~" x)) (kbd (format "%s<f18>" tkey)))<br />
;; f19<br />
(define-key key-translation-map (kbd (format "M-[ 33 ; %d ~" x)) (kbd (format "%s<f19>" tkey)))<br />
;; f20<br />
(define-key key-translation-map (kbd (format "M-[ 34 ; %d ~" x)) (kbd (format "%s<f20>" tkey)))<br />
<br />
(setq x (+ x 1))<br />
))<br />
)<br />
)<br />
}}<br />
<br />
== Alternatives ==<br />
<br />
There are numerous implementations of Emacs. GNU/Emacs is probably the most popular. <br><br />
Lighter Emacs compatibile alternatives can be found in Arch repositories or in [https://aur.archlinux.org/ AUR].<br />
<br />
=== mg ===<br />
<br />
mg (originally called MicroGnuEmacs) is lightweight implementation of Emacs written in C.<br />
<br />
It's possible to install mg right away from {{ic|community}}<br />
# pacman -S mg<br />
or download source from official [http://homepage.boetes.org/software/mg/ page].<br />
<br />
=== zile ===<br />
<br />
According to the offical web [https://www.gnu.org/software/zile/ page] "GNU Zile is a lightweight Emacs clone. Zile is short for Zile Is Lossy Emacs. Zile has been written to be as similar as possible to Emacs; every Emacs user should feel at home.".<br />
<br />
zile can be found in {{ic|extra}}<br />
<br />
# pacman -S zile<br />
<br />
the latest taballs can be found in official GNU [http://ftp.sh.cvut.cz/MIRRORS/gnu/pub/gnu/zile/ mirrors].<br />
<br />
=== uemacs ===<br />
<br />
uemacs is "Micro-emacs version customized by Linus Torvalds".<br />
It can be found in [https://aur.archlinux.org/ AUR] as [https://aur.archlinux.org/packages.php?ID=31502 uemacs].<br />
<br />
== See also ==<br />
* [http://www.gnu.org/software/emacs/ GNU Emacs home page]<br />
* [http://www.gnu.org/software/emacs/manual/emacs.html GNU Emacs Manual]<br />
* [http://www.emacswiki.org/cgi-bin/wiki/ Emacs Wiki]<br />
* [http://wikemacs.org WikEmacs - a more readable, but less complete Emacs Wiki]<br />
* [http://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html Useful introduction to Emacs and its shortcuts]<br />
* [http://www.dina.kvl.dk/~abraham/religion/ The Church of Emacs]<br />
* [http://cs.iupui.edu/~kweimer/EmacsCheatSheet.pdf Emacs Cheat Sheet]<br />
* [http://repo.or.cz/w/emacs.git/blob/HEAD:/etc/refcards/refcard.pdf Official reference card]</div>Obliquehttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=256334Software access point2013-05-07T23:23:59Z<p>Oblique: /* NAT Setup */</p>
<hr />
<div>[[ru:Software Access Point]]<br />
[[Category:Wireless Networking]]<br />
<br />
A software access point is used when you want your computer to act as an wifi access point for the local wireless network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
* A nl80211 compatible wireless device (e.g. ath9k)<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''wifi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wifi Link Layer ==<br />
<br />
The actual Wifi link is established via the {{Pkg|hostapd}} package. That package is compatible with WPA2.<br />
<br />
[[pacman|Install]] the {{Pkg|hostapd}} package from the [[Official Repositories|official repositories]].<br />
<br />
Create the config file of hostapd {{ic|/etc/hostapd/hostapd.conf}}. <br />
<br />
Adjust the options as necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}.<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWifiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
<br />
== Network configuration ==<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal WiFi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is more simple, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dialup connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT aproach is more versatile, as it clearly separates wifi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, is possible to '''combine both things'''. For that, studying both articles would be necessary. (Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth)<br />
=== Bridge Setup ===<br />
See [[Bridge with netcfg]] for details.<br />
<br />
Note that, you '''should not''' add the wireless device (like {{ic|wlan0}}) to the bridge; hostapd will add it on its own.<br />
<br />
=== NAT Setup ===<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap]. This script combines [https://www.archlinux.org/packages/?name=hostapd hostapd], [[dnsmasq]] and [[iptables]] to create a NATed Access Point.<br />
<br />
See [[Internet Share]] for details.<br />
<br />
On that article, the device connected to the lan is {{ic|net0}}. That device would be in this case your wireless device (which probably is {{ic|wlan0}}).<br />
<br />
== Troubleshooting ==<br />
===WLAN is very slow===<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device by adding<br />
<br />
{{hc||<nowiki>[keyfile]<br />
unmanaged-devices=mac:<hwaddr></nowiki>}}<br />
<br />
to /etc/NetworkManager/NetworkManager.conf<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/RTFM-AP hostapd Linux documentation page]<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wifi Access Point]</div>Obliquehttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=256333Software access point2013-05-07T23:10:20Z<p>Oblique: /* NAT Setup */</p>
<hr />
<div>[[ru:Software Access Point]]<br />
[[Category:Wireless Networking]]<br />
<br />
A software access point is used when you want your computer to act as an wifi access point for the local wireless network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
* A nl80211 compatible wireless device (e.g. ath9k)<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''wifi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wifi Link Layer ==<br />
<br />
The actual Wifi link is established via the {{Pkg|hostapd}} package. That package is compatible with WPA2.<br />
<br />
[[pacman|Install]] the {{Pkg|hostapd}} package from the [[Official Repositories|official repositories]].<br />
<br />
Create the config file of hostapd {{ic|/etc/hostapd/hostapd.conf}}. <br />
<br />
Adjust the options as necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}.<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWifiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
<br />
== Network configuration ==<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal WiFi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is more simple, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dialup connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT aproach is more versatile, as it clearly separates wifi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, is possible to '''combine both things'''. For that, studying both articles would be necessary. (Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth)<br />
=== Bridge Setup ===<br />
See [[Bridge with netcfg]] for details.<br />
<br />
Note that, you '''should not''' add the wireless device (like {{ic|wlan0}}) to the bridge; hostapd will add it on its own.<br />
<br />
=== NAT Setup ===<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap]. This script combines hostapd, [[dnsmasq]] and [[iptables]] to create a NATed Access Point.<br />
<br />
See [[Internet Share]] for details.<br />
<br />
On that article, the device connected to the lan is {{ic|net0}}. That device would be in this case your wireless device (which probably is {{ic|wlan0}}).<br />
<br />
== Troubleshooting ==<br />
===WLAN is very slow===<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device by adding<br />
<br />
{{hc||<nowiki>[keyfile]<br />
unmanaged-devices=mac:<hwaddr></nowiki>}}<br />
<br />
to /etc/NetworkManager/NetworkManager.conf<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/RTFM-AP hostapd Linux documentation page]<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wifi Access Point]</div>Oblique