Emacs编辑器

Emacs是可扩展的、可自定义的、自文档的实时显示编辑器。本手册描述了如何使用Emacs进行编辑以及定制它的一些方法;它对应于GNU Emacs版本27.1。

GNU Emacs的主页位于https://www.gnu.org/software/emacs/.
若要以其他格式查看本手册,请单击此处
。您还可以从FSF商店购买打印版。

有关扩展Emacs的信息,请参阅Emacs Lisp参考手册中的Emacs Lisp

这是GNU Emacs手册,针对Emacs版本27.1进行了更新。

版权所有©1985-1987,1993-2020自由软件基金会。

根据GNU自由文档许可证1.3版或自由软件基金会发布的任何更新版本的条款,允许复制、分发或修改本文档;不变部分为“GNU声明”、“分发”和“GNU通用公共许可证”,封面文本为“GNU手册”,封底文本如下(A)所示。该许可证的副本包含在标题为“GNU自由文档许可证”的部分中。

(a) FSF的封底正文是:“您有复制和修改本GNU手册的自由。从FSF购买拷贝支持它开发GNU和促进软件自由。“

Detailed Node Listing

Here are some other nodes which are really subnodes of the ones already listed, mentioned here so you can get to them in one step:

Next: , Previous: , Up: Top   [Contents][Index]

发行版

GNU Emacs是自由软件;这意味着在某些条件下,每个人都可以自由使用和自由重新分发它。GNU Emacs不属于公共领域;它是受版权保护的,并且对其分发有限制,但这些限制旨在允许好的合作公民想要做的一切。不允许的是试图阻止其他人进一步分享他们可能从您那里获得的任何版本的GNU Emacs。确切的条件可以在Emacs附带的GNU通用公共许可证中找到,也可以在本手册1中找到。请参阅复制

获得GNU Emacs副本的一种方式是从其他拥有它的人那里。你不需要征得我们的许可,也不需要告诉任何人,只需拷贝就行了。如果您可以访问互联网,您可以通过匿名FTP获得GNU Emacs的最新分发版本;有关更多信息,请参阅我们网站上的https://www.gnu.org/software/emacs

您还可以在购买计算机时收到GNU Emacs。计算机制造商可以按照适用于其他所有人的相同条款自由分发副本。这些条款要求他们向您提供完整的源代码,包括他们可能做出的任何更改,并允许您根据通用公共许可证的通常条款重新分发从他们那里收到的GNU Emacs。换句话说,当您获得程序时,程序必须对您免费,而不仅仅是制造商免费。

如果您觉得GNU Emacs有用,请向自由软件基金会捐赠以支持我们的工作。在美国,对自由软件基金会的捐款是免税的。如果您在工作场所使用GNU Emacs,请建议公司捐款。要捐款,请参阅https://my.fsf.org/donate/. 有关您可以提供帮助的其他方式,请参阅https://www.gnu.org/help/help.html.

我们还销售本手册的硬拷贝版本和Robert J. Chassell.编写的Emacs Lisp编程入门。您可以访问我们的在线商店https://shop.fsf.org/. 销售收入将用于支持基金会的目标:开发新的自由软件,并改进我们现有的程序,包括GNU Emacs。

如果您需要联系自由软件基金会,请参阅https://www.fsf.org/about/contact/,或写信给

自由软件基金会
富兰克林大街51号,五楼
马萨诸塞州波士顿,邮编:02110-1301.
美国

Next: , Previous: , Up: Top   [Contents][Index]

简介

您正在阅读关于GNU Emacs的文章,GNU Emacs是高级的、自文档化的、可定制的、可扩展的编辑器Emacs的GNU版本。(GNU(GNU’s Not Unix)中的“G”是发声的。)

我们称Emacs高级是因为它不只是简单地插入和删除文本。它可以控制子进程,自动缩进程序,一次显示多个文件,编辑远程文件,就像编辑本地文件一样,等等。Emacs编辑命令根据字符、单词、行、句子、段落和页面以及各种编程语言的表达式和注释进行操作。

自文档意味着您可以随时使用称为帮助命令的特殊命令来找出您的选项是什么,或者找出任何命令的作用,或者查找与给定主题相关的所有命令。请参阅帮助

可自定义意味着您可以通过简单的方式轻松地更改Emacs命令的行为。例如,如果您使用的编程语言的注释以“<**”开始,以“**>”结束,则可以告诉Emacs注释操作命令使用这些字符串(请参见注释)。再举一个例子,您可以将基本光标移动命令(上、下、左和右)重新绑定到键盘上您觉得舒服的任何键上。请参阅自定义

可扩展意味着您可以超越简单的自定义,创建全新的命令。新命令只是用Lisp语言编写的程序,由Emacs自己的Lisp解释器运行。甚至可以在编辑会话过程中重新定义现有命令,而不必重新启动Emacs。Emacs中的大多数编辑命令都是用Lisp编写的;少数例外可能是用Lisp编写的,但为了提高效率改用C语言实现。编写扩展就是编程,但非程序员可以在之后使用它。如果您想学习Emacs Lisp编程,请参阅Emacs Lisp编程入门中的序言

Next: , Previous: , Up: Top   [Contents][Index]

1 屏幕的组织方式

在图形显示器上,例如在使用X窗口系统的GNU/Linux上,Emacs占据一个图形窗口。在文本终端上,Emacs占据整个终端屏幕。我们将使用术语窗体来表示Emacs占据的图形窗口或终端屏幕。Emacs在这两种窗体上的行为非常相似。它通常只从一个窗体开始,但如果您愿意,也可以创建其他窗体(请参阅窗体)。

每个窗体由几个不同的区域组成。窗体顶部有一个菜单栏,允许您通过一系列菜单访问命令。在图形显示器上,菜单栏正下方是工具栏,这是一行图标,当您单击它们时,它们会执行编辑命令。在窗体的最底部是回显区,在此显示信息性消息,并在Emacs要求输入信息时在其中输入信息。

位于工具栏(如果存在)下方、回显区上方的窗体主区域称为窗口。此后,在本手册中,我们将在此意义上使用单词“窗口”。图形显示系统通常使用具有不同含义的词“窗口”;但是如上所述,我们将那些图形窗口称为“窗体”。

Emacs窗口显示缓冲区-您正在编辑或查看的文本或其他图形。在图形显示器上,窗口的一侧有一个滚动条,可用于在缓冲区中滚动。窗口的最后一行是状态栏。这将显示有关缓冲区中正在进行的操作的各种信息,例如是否存在未保存的更改、正在使用的编辑模式、当前行号等。

启动Emacs时,窗体中通常只有一个窗口。但是,您可以水平或垂直分割此窗口以创建多个窗口,每个窗口都可以独立显示一个缓冲区(请参阅窗口)。

在任何时候,都有一个窗口是选定窗口。在图形显示器上,所选窗口显示较突出的光标(通常为实心且闪烁);其他窗口显示较不突出的光标(通常为空心框)。在文本终端上,只有一个光标显示在所选窗口中。所选窗口中显示的缓冲区称为当前缓冲区,它是进行编辑的地方。大多数Emacs命令都隐式应用于当前缓冲区;显示在未选中窗口中的文本大多可见以供参考。如果在图形显示上使用多个窗体,则选择特定窗体将选择该窗体中的一个窗口。

Next: , Up: Screen   [Contents][Index]

1.1游标

选定窗口中的光标是大多数编辑命令生效的位置,称为游标2。许多Emacs命令将游标移动到缓冲区中的不同位置;例如,您可以通过单击鼠标键1(通常是左键)将游标放在所需位置。

默认情况下,所选窗口中的光标绘制为实心框,并在字符显示,但您应将游标视为在两个字符之间;它位于光标下的字符之前。例如,如果您的文本看起来像“frob”,而光标位于“b”上,则游标位于“o”和“b”之间。如果在该位置插入字符“”,则结果为“fro!b”,游标位于“”和“b”之间。因此,光标仍然停留在“b”上,如前所述。

如果在Emacs中编辑多个文件,每个文件都在自己的缓冲区中,则每个缓冲区都有自己的游标。如果稍后再次显示当前未显示的缓冲区,则它会记住其游标。此外,如果缓冲区显示在多个窗口中,则每个窗口都有自己的游标。

有关控制Emacs如何显示光标的选项,请参阅光标显示

Next: , Previous: , Up: Screen   [Contents][Index]

1.2回显区

窗体最底部的一栏是回音区。它用于显示用于各种目的的少量文本。

回显区之所以这样命名,是因为它的用途之一是回显,这意味着在您键入时显示多字符命令的字符。不回显单字符命令。如果您在输入命令时暂停超过一秒,则会回显多字符命令(请参阅快捷键)。然后,Emacs会回显到目前为止键入的所有命令字符,以提示您输入剩余部分。回显开始后,命令的剩余部分会在您键入它时立即回显。此行为旨在为自信的用户提供快速响应,同时为犹豫不决的用户提供最大反馈。

回显区还用于在命令无法执行其工作时显示错误信息。错误信息可能伴随有蜂鸣声或屏幕闪烁。

某些命令在回显区域显示信息性消息,以告诉您该命令执行了什么操作,或者为您提供一些特定信息。与错误信息不同,这些信息性消息不会伴随蜂鸣声或闪烁。例如,C-x=(按住Ctrl并键入x,然后松开Ctrl并键入=)将显示一条消息,描述该游标的字符、其在缓冲区中的位置以及其在窗口中的当前列。耗时较长的命令通常在工作时显示以“.”结尾的消息(有时还以百分比形式指示已取得的进展),并在补全时添加“补全”。

信息性回显区消息保存在名为*Messages*的特殊缓冲区中。(我们尚未解释缓冲区;有关它们的详细信息,请参阅缓冲区。)如果您错过了屏幕上短暂显示的消息,可以切换到*Messages*缓冲区再次查看。*Messages*缓冲区限制为一定的行数,由变量message-log-max指定。(我们也没有解释变量;有关它们的更多信息,请参阅变量。)超过此限制后,每当在末尾添加新消息行时,将从开头删除一行。

有关控制Emacs如何使用回显区的选项,请参阅显示自定义

回显区还用于显示迷你缓冲区,这是一个特殊窗口,您可以在其中为命令输入参数,例如要编辑的文件名。当迷你缓冲区正在使用时,回显区中显示的文本以提示字符串开头,活动光标出现在迷你缓冲区内,该窗口暂时被视为选中的窗口。您始终可以通过键入C-g来退出迷你缓冲区。请参见迷你缓冲区

Next: , Previous: , Up: Screen   [Contents][Index]

1.3状态栏

在每个窗口的底部是一个状态栏,它描述当前缓冲区中正在发生的事情。当只有一个窗口时,模式行显示在回声区域的正上方;它是窗体中倒数第二行。在图形显示上,状态栏以3D长方体外观绘制。Emacs通常还使用与未选择窗口不同的颜色绘制所选窗口的状态栏,以使其突出。

状态栏中显示的文本格式如下:

 cs:ch-fr  buf      pos line   (major minor)

在文本终端上,此文本后面跟着一系列延伸到窗口右边缘的破折号。这些破折号在图形显示上被省略。

cs字符串及其后面的冒号字符描述了用于当前缓冲区的字符集和换行符约定。通常,Emacs会自动为您处理这些设置,但有时拥有此信息很有用。

cs描述缓冲区中文本的字符集(请参阅编码系统)。如果它是破折号(‘-’),则表示没有特殊的字符集处理(下一段中描述的行尾约定可能除外)。“=”表示不进行任何转换,通常用于包含非文本数据的文件。其他字符表示各种编码系统-例如,‘1’表示ISO Latin-1。

在文本终端上,cs前面有两个额外的字符,用于描述键盘输入和终端输出的编码系统。此外,如果您使用输入法,cs前面会有标识输入法的字符串(请参阅输入法)。

cs>后面的字符通常是冒号。如果显示不同的字符串,则表示对文件进行编码的重要行尾约定。通常,文件中的文本行由换行符分隔,但有时还会使用另外两个约定。MS-DOS约定使用回车字符后跟换行符;编辑此类文件时,冒号将更改为反斜杠(‘\’)或‘(DOS)’,具体取决于操作系统。较旧的Macintosh系统使用的另一个约定是使用回车符而不是换行符;当编辑这样的文件时,冒号变为正斜杠(‘/’)或‘(Mac)’。在某些系统上,对于使用换行符作为行分隔符的文件,Emacs显示“(Unix)”,而不是冒号。

在为emacsclient创建的窗体上(请参阅调用emacsclient),下一个字符是“@”。此指示通常用于作为守护程序运行的Emacs进程的窗体(请参阅Emacs服务器)。

状态栏上的下一个元素是ch指示的字符串。如果窗口中显示的缓冲区与磁盘上的相应文件具有相同的内容,即如果缓冲区未修改,则会显示两个破折号(‘--’)。如果修改缓冲区,它将显示两个星号(‘**’)。对于只读缓冲区,如果修改了缓冲区,则显示“%*”,否则显示“%%”。

ch后面的字符通常是破折号(‘-’)。但是,如果当前缓冲区的默认目录(请参阅文件名)位于远程计算机上,则会显示“@”。

fr提供选定的窗体名(请参阅窗体)。它只出现在文本终端上。初始窗体的名称为“F1”。

buf是窗口中显示的缓冲区的名称。通常,这与您正在编辑的文件的名称相同。请参阅缓冲区

pos告诉您窗口顶部上方还是底部下方有其他文本。如果您的缓冲区很小,并且所有缓冲区在窗口中都可见,则pos为“all”。否则,如果查看的是缓冲区的开头,则为“Top”,如果查看的是缓冲区的末尾,则为“Bot”,或者为“nn%”,其中nn是窗口顶部以上的缓冲区的百分比。使用尺寸指示模式,您还可以显示缓冲区的尺寸。请参阅可选状态栏

line是字符“L”,后跟游标处的行号。(通过打开列号模式,也可以显示当前列号。请参阅可选状态栏。)

major是缓冲区中使用的主模式的名称。主模式是缓冲区的主要编辑模式,诸如文本模式、Lisp模式、C模式等。请参阅主模式。某些主模式在主模式名称后显示附加信息。例如,编译缓冲区和Shell缓冲区显示子进程的状态。

minor是一些已启用的辅模式的列表,它们是在主模式之上提供附加功能的可选编辑模式。请参阅辅模式

某些功能在打开时会与辅模式一起列出,即使它们不是真正的辅模式。‘Narrow’表示正在显示的缓冲区的编辑仅限于其文本的一部分(请参阅聚焦)。“Def”表示当前正在定义键盘宏(请参阅键盘宏)。

此外,如果Emacs在递归编辑级别内,则方括号(‘[…]‘)出现在模式周围的括号中。如果Emacs在另一个递归编辑级别中处于另一个递归编辑级别,则会出现双方括号,依此类推。由于递归编辑级别在全局范围内影响Emacs,因此这样的方括号出现在每个窗口的模式行中。请参阅递归编辑

您可以更改状态栏的外观及其内容的格式。请参阅可选状态栏。此外,状态栏是鼠标敏感的;单击模式行的不同部分可执行各种命令。请参阅状态栏鼠标操作。此外,将鼠标指针悬停在模式行的鼠标敏感部分上方会显示工具提示(请参阅工具提示),其中包含有关通过单击状态栏可以调用的命令的信息。

Previous: , Up: Screen   [Contents][Index]

1.4菜单栏

每个Emacs窗体的顶部通常都有一个菜单栏,您可以使用它来执行常见操作。没有必要在这里列出它们,因为您可以更容易地亲眼看到它们。

在支持鼠标的显示器上,您可以使用鼠标从菜单栏中选择命令。菜单项右边缘的箭头表示它通向子菜单或子菜单。菜单项末尾的“.”表示该命令将在实际执行任何操作之前提示您进一步输入。

菜单栏中的一些命令也有普通的按键绑定;如果是这样,则在项本身之后显示一个按键绑定。若要查看菜单项的完整命令名和文档,请键入C-h k,然后按常规方式使用鼠标选择菜单栏(请参阅按键帮助)。

您也可以通过按F10(运行命令menu-bar-open)来调用第一个菜单栏项目,而不是使用鼠标。然后,您可以使用箭头键或C-bC-f(左/右)、C-pC-n(上/下)来导航菜单。要激活选定的菜单项,请按RET;要取消菜单导航,请按C-gESCESCESC。(但是,请注意,当Emacs使用GUI工具包构建时,菜单由该工具包绘制和控制,用于取消菜单导航的键序列可能与上面的描述不同。)

在文本终端上,您可以选择访问回显区的菜单栏菜单。为此,将变量tty-menu-open-use-tmm自定义为非nil值。然后键入F10将运行命令tmm-menubar,而不是下拉菜单。(您还可以键入M-`,它始终调用tmm-menubar。)tmm-menubar允许您使用键盘选择菜单项。回显区中会出现一个临时选项。您可以使用向上和向下箭头键在菜单中移动到不同的项目,然后可以键入RET选择项目。每个菜单项也由字母或数字(通常是项目名称中某个单词的首字母)指定。此字母或数字与项目名称之间用“==>”分隔。您可以键入项目的字母或数字来选择项目。

Next: , Previous: , Up: Top   [Contents][Index]

2 用户输入类型

GNU Emacs主要设计用于键盘。虽然可以使用鼠标通过菜单栏和工具栏触发编辑命令,但效率不如使用键盘。因此,本手册主要介绍如何使用键盘进行编辑。

Emacs中的键盘输入基于ASCII的高度扩展版本。通过键入相应的键来输入简单字符,如‘a’、‘B>’、‘3>’、‘=’和空格字符(表示为SPC)。控制字符(如RETTABDELESCF1HomeLEFT)也是通过这种方式输入的,非英语键盘上的某些字符也是如此(请参见国际化)

Emacs还可以识别使用修饰键输入的控制字符。两个常用的修饰键是Control(通常标记为Ctrl)和Meta(通常标记为Alt)3。例如,Control-a是在按住Ctrl键的同时按a输入的,我们简称为C-a。类似地,Meta-a或简称M-a通过按住Alt键并按a来输入。修饰键还可以应用于非字母数字字符,例如,C-F1M-LEFT

您还可以使用以ESC开头的双字符序列键入元字符。因此,您可以通过键入ESCa来输入M-a。您可以通过键入ESCC-a来输入C-M-a(同时按住CtrlAlt,然后按a)。与Meta不同,ESC作为单独的字符输入。键入下一个字符时不要按住ESC;而是按ESC并松开它,然后输入下一个字符。此功能在Meta键功能不可靠的某些文本终端上非常有用。

Emacs支持3个额外的修饰键,请参见修饰键

在图形显示上,窗口管理器可能会拦截一些键盘输入,包括M-TABM-SPCC-M-dC-M-l。如果遇到此问题,您可以自定义窗口管理器,使其不拦截那些键,或者重新绑定受影响的Emacs命令(请参阅自定义)。

简单字符和控制字符以及某些非键盘输入(如鼠标单击)统称为输入事件。有关Emacs如何在内部处理输入事件的详细信息,请参阅Emacs Lisp参考手册中的输入事件

Next: , Previous: , Up: Top   [Contents][Index]

3 快捷键

一些Emacs命令仅由一个输入事件调用;例如,C-f在缓冲区中向前移动一个字符。其他命令需要调用两个或多个输入事件,例如C-x C-fC-x 4 C-f

键序列或简称快捷键是把有意义的一个或多个输入事件的序列作为一个单元。如果使用按键序列调用命令,我们将其称为完全键;例如,C-fC-x C-fC-x 4 C-f都是完全键。如果键序列不足以调用命令,我们将其称为前缀键;从前面的示例中,我们可以看到C-xC-x 4是前缀键。每个键序列要么是完全键,要么是前缀键。

前缀键与随后的输入事件相结合以形成更长的按键序列。例如,C-x是前缀键,因此单独键入C-x不会调用命令;相反,Emacs会等待进一步的输入(如果暂停时间超过一秒,则会回显C-x键以提示输入;请参阅回显区)。C-x与下一个输入事件组合形成两个事件的按键序列,该序列本身可以是前缀键(如C-x 4),也可以是完整键(如C-x C-f)。键序列的长度没有限制,但实际上它们很少超过三个或四个输入事件。

您不能将输入事件追加到完全键上。例如,因为C-f是一个完全键,所以C-f C-k是两个分离的键序列,而不是一个。

默认情况下,Emacs中的前缀键为C-c, C-h, C-x, C-x RET, C-x @, C-x a, C-x n, C-x r, C-x t, C-x v, C-x 4, C-x 5, C-x 6, ESC, M-gM-o. (F1F2C-hC-x 6的别名) 这个列表不是一成不变的;如果您自定义Emacs,您可以创建新的前缀键。您甚至可以删除一些标准的键序列,尽管不建议大多数用户这样做;例如,如果删除C-x 4的前缀定义,则C-x 4 C-f将成为无效的键序列。请参阅键绑定

在前缀键后键入帮助字符(C-hF1)将显示以该前缀开头的命令列表。此规则的唯一例外是ESC:ESCC-h等同于C-M-h,它执行完全不同的任务。但是,您可以使用F1显示以ESC开头的命令列表。

Next: , Previous: , Up: Top   [Contents][Index]

4 快捷键和命令

这本手册有很多段落告诉你特定的快捷键键有什么作用。但是Emacs不直接为快捷键分配含义。相反,Emacs为命名的命令分配含义,然后通过绑定到命令来赋予快捷键含义。

每个命令都有一个由程序员选择的名称。名称通常由几个用短划线分隔的英文单词组成;例如,next-lineforward-word。在内部,每个命令都是一种特殊类型的Lisp函数,与该命令相关联的操作通过运行该函数来执行。请参阅Emacs Lisp参考手册中的什么是函数

快捷键和命令之间的绑定记录在称为键映射的表中。请参阅键映射1>。

当我们说“C-n垂直下移一行”时,我们忽略了一个微妙的区别,这个区别在普通使用中并不相关,但对于Emacs定制至关重要。命令next-line是垂直向下移动。C-n有此效果是因为它绑定到next-line。如果将C-n重新绑定到命令forward-wordC-n将改为向前移动一个单词。

在本手册中,我们经常将C-n这样的快捷键称为命令,即使严格地说,快捷键是绑定到命令的。通常,在提到运行该命令的快捷键之后,我们会在括号中说明真正执行该工作的命令的名称。例如,我们会说“命令C-n(next-line)垂直下移一行”,即next-line命令是垂直下移一行,正常情况下C-n键绑定到该命令。

因为我们正在讨论定制,所以我们应该告诉您有关变量的内容。通常,命令的描述会说,“要更改这一点,请设置变量mumble-foo。”变量是用于存储值的名称。本手册中记录的大多数变量都用于自定义:Emacs的某些命令或其他部分会检查变量,并根据您设置的值采取不同的行为。您可以忽略有关变量的信息,直到您对自定义它们感兴趣为止。然后阅读有关变量的基本信息(请参阅变量),有关特定变量的信息就有意义了。

Next: , Previous: , Up: Top   [Contents][Index]

5 进入Emacs

调用Emacs的通常方式是使用shell命令emacs。在GUI终端上运行Unix shell的终端窗口中,您可以使用emacs &在后台运行Emacs;这样,Emacs就不会占用终端窗口,因此您可以使用它来运行其他shell命令。(有关在MS-Windows上启动Emacs的类似方法,请参阅Windows启动。)

当Emacs启动时,初始窗体中显示一个名为‘*GNU Emacs*’的特殊缓冲区。此启动屏幕包含有关Emacs的信息,并且链接指向对初学者有用的常见任务。例如,激活“Emacs Tutorial”链接将打开Emacs教程;这与命令C-h t(help-with-tutorial)的作用相同。要激活链接,可以将指针移到该链接上并键入RET,或者用鼠标键1(鼠标左键)单击该链接。

使用命令行参数,您可以告诉Emacs在启动时立即访问一个或多个文件。例如,emacs foo.txt使用一个缓冲区启动Emacs,该缓冲区显示文件“foo.txt”的内容。此功能的存在主要是为了与其他编辑器兼容,这些编辑器设计为从shell启动,用于简短的编辑会话。如果以这种方式调用Emacs,初始帧将被分成两个窗口-一个显示指定的文件,另一个显示启动屏幕。请参阅窗口

通常,每次要编辑文件时都重新启动Emacs是不必要的,也是浪费的。建议使用Emacs的方法是在登录后只启动一次,然后在同一个Emacs会话中进行所有编辑。有关访问多个文件的信息,请参阅文件。如果您以这种方式使用Emacs,则Emacs会话将积累有价值的上下文,如剪切板、寄存器、撤销历史和选区数据,这些都使得编辑更加方便。本手册稍后将介绍这些功能。

要在Emacs运行时编辑另一个程序中的文件,可以使用emacsclient帮助程序在现有Emacs会话中打开文件。请参阅Emacs服务器

Emacs接受其他命令行参数,这些参数告诉它加载某些Lisp文件,将初始窗体放在哪里,等等。请参阅Emacs调用

如果变量inhibit-startup-screen为非nil,则Emacs不显示启动屏幕。在这种情况下,如果在命令行上指定了一个或多个文件,则Emacs只显示这些文件;否则,它将显示名为*scratch*的缓冲区,该缓冲区可用于以交互方式计算Emacs Lisp表达式。请参见Lisp交互。您可以使用自定义功能(请参见轻松自定义)或通过编辑初始化文件(请参见初始化文件)来设置变量inhibit-startup-screen4

您还可以通过将变量initial-buffer-choice设置为命名文件或目录的字符串,强制Emacs在启动时显示该文件或目录。initial-buffer-choice的值也可以是一个函数(没有参数),它应该返回一个缓冲区,然后显示该缓冲区。如果initial-buffer-option不是nil,那么如果您在命令行上指定任何文件,Emacs仍然会访问它们,但最初不会显示它们。

Next: , Previous: , Up: Top   [Contents][Index]

6 退出Emacs

C-x C-c

终止Emacs(save-buffers-kill-terminal)。

C-z

在文本终端上挂起Emacs;在图形显示器上,图标化(或“最小化”)选定的窗体(suspend-frame)。

终止Emacs意味着终止Emacs程序。为此,请键入C-x C-c(save-buffers-kill-terminal)。使用两个字符的按键序列是为了增加意外键入的难度。如果在您键入C-x C-c时有任何修改过的文件访问缓冲区,Emacs会首先提示保存这些缓冲区。如果不全部保存,系统会再次要求确认,因为未保存的更改将丢失。Emacs还要求确认是否有任何子进程仍在运行,因为终止Emacs也会终止子进程(请参阅Shell)。

C-x C-c在使用Emacs作为服务器时会有特殊行为。如果您从客户端窗体中键入它,它将关闭客户端连接。请参阅Emacs服务器

当您终止Emacs时,Emacs可以选择性地记录某些会话信息,例如您当时正在访问的文件。此信息在下次启动Emacs时可用。请参阅保存Emacs会话

如果变量confirm-kill-emacs的值非nil,则C-x C-c假定其值是谓词函数(译者注: 返回值为布尔类型),并调用该函数。如果函数调用的结果为非nil,会话将被终止,否则Emacs将继续运行。用作confirm-kill-emacs值的一个方便函数是yes-or-no-p函数。confirm-kill-emacs的默认值为nil

如果变量confirm-kill-process的值为nil,则C-x C-c在终止Emacs启动的子进程之前不会要求确认。默认情况下,该值为t

要进一步自定义退出Emacs时发生的情况,请参阅GNU Emacs Lisp参考手册中的终止Emacs

要在不提示保存的情况下终止Emacs,请键入M-x kill-emacs

C-z运行命令suspend-frame。在图形显示上,此命令最小化(或图标化)选定的Emacs窗体,以允许您稍后将其恢复的方式将其隐藏(隐藏的确切方式取决于窗口系统)。在文本终端上,C-z命令挂起emacs,暂时停止程序并将控制权返回给父进程(通常是shell);在大多数shell中,挂起Emacs后,您可以使用shell命令%emacs恢复Emacs。

文本终端通常会监听某些特殊字符,这些字符的含义是终止或挂起您正在运行的程序。此终端功能在您处于Emacs中时关闭。在Emacs中,C-zC-x C-c作为快捷键键的含义源于在几个操作系统上使用C-zC-c作为停止或终止程序的字符,但这是它们与操作系统唯一的关系。您可以自定义这些键以运行您选择的任何命令(请参阅键绑定)。

Next: , Previous: , Up: Top   [Contents][Index]

7 基本编辑命令

在这里,我们将介绍如何输入文本、进行更正以及将文本保存到文件中的基础知识。如果您对本材料不熟悉,我们建议您首先运行Emacs实践学习教程,方法是键入C-h t(help-with-tutorial)。

Next: , Up: Basic   [Contents][Index]

7.1插入文本

您可以通过键入关联键插入普通图形字符(例如,“a”、“B”、“3”和“=”)。这将在游标处将字符添加到缓冲区。插入会将游标向前移动,因此该指针将保留在插入的文本之后。请参阅游标

若要结束一行并开始新行,请键入RET(newline)。(RET键可能标记为ReturnEnter,或者键盘上有一个外观滑稽的向左箭头,但我们在本手册中将其称为RET。)该命令将换行符插入缓冲区,然后根据主模式缩进(请参阅缩进)。如果游标在行尾,则效果是在它之后创建新的空行并缩进新行;如果游标在行的中间,则该行将在该位置拆分。要关闭自动缩进,您可以禁用电子缩进模式(请参阅缩进便利性)或键入C-j,它只插入换行符,而不自动缩进。

正如我们在本手册后面部分所解释的,您可以通过打开辅模式来更改Emacs处理文本插入的方式。例如,称为自动填充模式的辅模式会在行过长时自动拆分行(请参阅填充)。称为覆盖模式的辅模式会导致插入的字符替换(覆盖)现有文本,而不是将其推到右侧。请参阅辅模式

只有图形字符可以通过键入相关键来插入;其他键充当编辑命令,不会自行插入。例如,DEL默认情况下运行命令delete-back-char(某些模式将其绑定到不同的命令);它不插入文字“DEL”字符(ASCII字符代码127)。

若要插入非图形字符或键盘不支持的字符,请先通过键入C-q(quoted-insert)对其加引号C-q有两种使用方式:

要使用十进制或十六进制而不是八进制,请将变量read-quoted-char-radix设置为10或16。如果基数是16,字母af将作为字符代码的一部分,就像数字一样。忽略大小写。

可以通过以C-x 8开头的命令插入一些常见的Unicode字符。例如,C-x 8 [inserts,它是Unicode代码点U+2018左单引号,有时称为左单引号“弯曲引号”或“卷引号”。同样,C-x 8 ]C-x 8 {C-x 8 }分别插入弧形引号。此外,工作的Alt键类似于C-x 8(除非后面紧跟RET);例如,A-[类似于C-x 8 [并插入。若要查看哪些字符具有C-x 8速记,请键入C-x 8 C-h

或者,您可以使用命令C-x 8RET(insert-char)。这会提示使用迷你缓冲区输入字符的Unicode名称或编码。如果输入名称,该命令将提供补全(请参见补全)。如果输入编码,它应该是十六进制数字(Unicode的约定)或具有指定基数的数字,例如,#o23072(八进制);请参阅Emacs Lisp参考手册中的整数基础。然后,该命令将相应的字符插入到缓冲区中。

例如,以下所有代码都插入相同的字符:

C-x 8 RET left single quotation mark RET
C-x 8 RET left sin TAB RET
C-x 8 RET 2018 RET
C-x 8 [
A-[  (if the Alt key works)
`    (in Electric Quote mode)

C-qC-x 8 ...的数字参数指定要插入多少个字符副本(请参阅参数)。

此外,在某些上下文中,如果像这样使用重音符和撇号键入引号,则即使没有C-x 8命令,也会使用单引号将其转换为‘这种’形式。同样,使用双重音符和撇号键入引号``像这样‘’会将其转换为使用双引号的形式“像这样”。请参阅引号

Next: , Previous: , Up: Basic   [Contents][Index]

7.2更改游标的位置

要做的不仅仅是插入字符,您必须知道如何移动游标(请参阅游标)。键盘命令C-fC-bC-nC-p分别指向右、左、下和上。您还可以使用大多数键盘上的箭头键移动游标:RIGHTLEFTDOWNUP;但是,许多Emacs用户发现使用箭头键比使用控制键要慢,因为您需要将手移动到这些键所在的键盘区域。

您也可以单击鼠标左键将游标移动到单击的位置。Emacs还提供了以更复杂的方式移动点的各种附加键盘命令。

C-f

向前移动一个字符(forward-char)。

RIGHT

此命令(right-char)的行为类似于C-f,但游标位于从右向左的段落时除外(请参阅双向编辑)。

C-b

向后移动一个字符(backward-char)。

LEFT

此命令(left-char)的行为类似于C-b,除非当前段落是从右向左的(请参阅双向编辑)。

C-n
DOWN

向下移动一个屏幕行(next-line)。此命令尝试保持水平位置不变,因此如果您从一行的中间开始,则会移动到下一行的中间。

C-p
UP

上移一个屏幕行(previous-line)。此命令保留行内的位置,如C-n

C-a
Home

移至行首(move-beginning-of-line)。

C-e
End

移到行尾(move-end-of-line)。

M-f

向前移动一个字(forward-word)。请参阅

C-RIGHT
M-RIGHT

此命令(right-word)的行为与M-f类似,不同之处在于,如果当前段落是从右向左的,则它将向后移动一个单词。请参阅双向编辑

M-b

向后移动一个单词(backward-word)。请参阅

C-LEFT
M-LEFT

此命令(left-word)的行为与M-b类似,不同之处在于,如果当前段落是从右向左的,则它将向前移动一个单词。请参阅双向编辑

M-r

在不移动屏幕上的文本的情况下,将指针重新定位在窗口最中间文本行的左边距上;在随后的连续调用中,按循环顺序将指针移动到最顶行、最底行的左边距,依此类推(move-to-window-line-top-bottom)。

一个数字参数表示从窗口顶部开始向下计数,将游标放在哪个屏幕行上(零表示顶行)。负参数从底部向上计数行(-1表示底线)。有关数值参数的详细信息,请参阅参数

M-<

移动到缓冲区的顶部(beginning-of-buffer)。使用数字参数n,从顶部移动到路径的n/10在图形显示上,C-HOME执行同样的操作。

M->

移动到缓冲区末尾(end-of-buffer)。在图形显示上,C-END执行同样的操作。

C-v
PageDown
next

将显示屏向前滚动一屏,如有必要,在屏幕上移动游标(scroll-up-command)。请参阅滚动

M-v
PageUp
prior

向后滚动一屏,必要时在屏幕上移动游标(scroll-down-command)。请参阅滚动

M-g c

读取数字n并将指针移动到缓冲区位置n。位置1是缓冲区的开始。

M-g M-g
M-g g

读取数字n并将指针移动到行号n的开头(goto-line)。第1行是缓冲区的开始。如果游标处于打开状态或恰好在缓冲区中的数字之后,则这是n的默认设置。只需在迷你缓冲区中键入RET即可使用它。您还可以通过向M-g M-g提供数字前缀参数来指定n。有关M-g M-g在为其提供纯前缀参数时的行为,请参阅选择缓冲区

M-g TAB

读取一个数字n并移动到当前行中的列n。列0是最左边的列。如果使用前缀参数调用,请移动到参数的数字值指定的列号。

C-x C-n

将当前游标所在的列用作当前缓冲区中C-nC-p(set-target-column)的半永久目标列。当半永久性目标列生效时,这些命令始终在垂直移动后尝试移动到该列或尽可能靠近该列。目标列在取消之前保持有效。

C-u C-x C-n

取消目标列。此后,C-nC-p像往常一样尝试保持水平位置。

当缓冲区中的一行文本长于窗口宽度时,Emacs通常将其显示在两个或多个屏幕行上。为方便起见,C-nC-p逐行移动指针,等价键downup也是如此。通过将变量line-move-visual设置为nil,可以强制这些命令根据逻辑行(即根据缓冲区中的文本行)移动;如果一个逻辑行占据多个屏幕行,则光标将跳过附加的屏幕行。有关详细信息,请参阅连续行。有关如何设置line-move-visual等变量的信息,请参阅变量

C-nC-p不同,大多数适用于行的Emacs命令都适用于逻辑行。例如,C-a(move-beginning-of-line)和C-e(move-end-of-line)分别移动到逻辑行的开始和结束。每当我们遇到在屏幕行上工作的命令时,例如C-nC-p,我们都会指出这些命令。

line-move-visualnil时,您还可以将变量track-eol设置为非nil值。然后C-nC-p从逻辑行的末尾开始,移动到下一个逻辑行的末尾。正常情况下,track-eolnil

当您在缓冲区的最后一行使用它时,C-n通常会在缓冲区末尾停止。但是,如果将变量next-line-add-newlines设置为非nil值,则缓冲区最后一行上的C-n将在末尾创建一个附加行并向下移动。

Next: , Previous: , Up: Basic   [Contents][Index]

7.3擦除文本

DEL
BACKSPACE

删除游标之前的字符,或者如果选区处于活动状态(delete-back-char)。

Delete

删除游标之后的字符,如果选区处于活动状态,则将其删除(delete-ward-char)。

C-d

删除游标后的字符(delete-char)。

C-k

删除到行尾(kill-line)。

M-d

向前删除到下一个单词的末尾(kill-word)。

M-DEL
M-BACKSPACE

向后删除到前一个单词的开头(backward-kill-word)。

DEL(delete-back-char)命令删除游标之前的字符,将光标及其后面的字符向后移动。如果游标位于行的开头,则会删除前面的换行符,将此行与上一行合并。

但是,如果选区处于活动状态,则DEL会删除该区域中的文本。有关区域的说明,请参阅标记

在大多数键盘上,DEL标记为BACKSPACE,但在本手册中我们将其称为DEL。(不要将DELDelete键混淆;我们将稍后讨论Delete。)在某些文本终端上,Emacs可能无法正确识别DEL键。如果您遇到此问题,请参阅DEL不是Delete

Delete(delete-ward-char)命令以相反的方向删除:它删除游标之后的字符,即光标下的字符。如果点在一条线的末尾,这会将下面的线连接到这条线上。与DEL类似,如果选区处于活动状态,它会删除选区中的文本(请参阅标记)。

C-d(delete-char)删除游标之后的字符,与Delete类似,但与选区是否处于活动状态无关。

有关上述删除命令的详细信息,请参阅删除

C-k(kill-line)一次擦除(杀死)一行。如果您在行首或行中键入C-k,则会取消直到行尾的所有文本。如果您在行尾键入C-k,它会将该行与以下行连接起来。

有关C-k和相关命令的详细信息,请参阅剪切

Next: , Previous: , Up: Basic   [Contents][Index]

7.4撤消更改

C-/
C-x u
C-_

撤消一个撤消记录条目-通常相当于一个命令(undo)。(第一个键可能在文本模式显示器上不可用。)

Emacs记录缓冲区文本中所做更改的列表,因此您可以撤消最近的更改。这是使用undo命令补全的,该命令绑定到C-/(以及C-x uC-_)。通常,此命令会撤消上一次更改,将游标移回更改前的位置。撤消命令仅适用于缓冲区中的更改;您不能使用它来撤消光标移动。

虽然每个编辑命令通常会在撤消记录中创建一个单独的条目,但也可以将非常简单的命令组合在一起。有时,一个条目可能只包含复杂命令的一部分。

如果您重复C-/(或其别名),则每次重复都会撤消另一个较早的更改,返回到可用撤消信息的限制。如果所有记录的更改都已撤消,则撤消命令将显示一条错误消息,并且不执行任何操作。

若要了解有关撤消命令的详细信息,请参阅撤消

Next: , Previous: , Up: Basic   [Contents][Index]

7.5Files

您插入到Emacs缓冲区中的文本仅与Emacs会话的生命周期一样长。若要永久保留任何文本,必须将其放入文件

假设您的主目录中有一个名为test.emacs的文件。要开始在Emacs中编辑此文件,请键入

C-x C-f test.emacs RET

这里,文件名作为C-x C-f(find-file)的参数提供给命令。该命令使用迷你缓冲区读取参数,然后键入RET终止参数(请参阅迷你缓冲区)。

Emacs遵循此命令,访问文件:它创建一个缓冲区,将文件内容复制到缓冲区中,然后显示缓冲区进行编辑。如果更改文本,可以通过键入C-x C-s(save-buffer)保存文件中的新文本。这会将更改后的缓冲区内容复制回文件test.emacs,使其成为永久性内容。在保存之前,更改后的文本仅存在于Emacs中,文件test.emacs未更改。

要创建文件,只需使用C-x C-f访问它,就好像它已经存在一样。这将创建一个空缓冲区,您可以在其中插入要放入文件中的文本。Emacs实际上在您第一次使用C-x C-s保存此缓冲区时创建了该文件。

若要了解有关在Emacs中使用文件的详细信息,请参阅文件

Next: , Previous: , Up: Basic   [Contents][Index]

7.6帮助

如果忘记了快捷键的作用,可以通过键入C-h k(describe-key),然后键入感兴趣的键;例如,C-h k C-n告诉您C-n的作用。

前缀键C-h代表“帮助”。F1键用作C-h的别名。除了C-h k之外,还有许多其他帮助命令可提供不同类型的帮助。

有关详细信息,请参阅帮助

Next: , Previous: , Up: Basic   [Contents][Index]

7.7空行

以下是用于插入和删除空行的特殊命令和技术。

C-o

在光标后插入空行(open-line)。

C-x C-o

删除多个连续空行中的一个以外的所有行(delete-blank-lines)。

我们已经看到RET(newline)如何开始新的文本行。但是,如果您首先创建一个空行,然后在其中插入所需的文本,则可能更容易看到您正在执行的操作。使用键C-o(open-line)很容易做到这一点,它在换行符之后插入一个换行符,但将游标留在换行符前面。在C-o之后,键入新行的文本。

您可以通过多次键入C-o,或者通过给它一个指定要创建多少个空行的数字参数来创建几个空行。有关操作方法,请参阅参数。如果您有填充前缀,C-o命令将在新行上插入填充前缀(如果在行首键入)。请参阅填充前缀

删除多余空行的简单方法是使用命令C-x C-o(delete-blank-lines)。如果游标位于几个空行的运行范围内,C-x C-o将删除除一个空行之外的所有空行。如果游标在单个空行上,C-x C-o会将其删除。如果游标位于非空行上,C-x C-o将删除后面的所有空行(如果存在)。

Next: , Previous: , Up: Basic   [Contents][Index]

7.8连续行

有时,缓冲区中的一行文本(逻辑行)太长,窗口无法容纳,Emacs会将其显示为两个或多个屏幕行。这称为换行继续,长逻辑行称为连续行。在图形显示上,Emacs表示在左右窗口边缘用小弯曲箭头换行。在文本终端上,Emacs通过在右边距显示‘\’字符来指示换行。

大多数作用于行的命令作用于逻辑行,而不是屏幕行。例如,C-k会剪切逻辑行。如前所述,C-n(next-line)和C-p(previous-line)是特殊例外:它们分别将指针向下和向上移动一个屏幕行(请参阅移动游标)。

Emacs可以选择截断长逻辑行,而不是接续它们。这意味着每条逻辑线都占据一条屏幕行;如果长于窗口宽度,则不会显示该行的剩余部分。在图形显示上,一条截断的行由右边缘的小直箭头表示;在文本终端上,它由右边缘的“$”字符表示。请参阅行截断

默认情况下,连续行在窗口右边缘换行。由于换行可能发生在单词的中间,因此连续的行会很难阅读。通常的解决方案是在行太长之前插入换行符。如果您愿意,可以使用Auto Fill mode让Emacs在行过长时自动插入换行符。请参阅填充

有时,您可能需要编辑包含许多长逻辑行的文件,而通过添加换行符将它们全部拆分可能并不实际。在这种情况下,您可以使用Visual Line模式,该模式启用单词换行:Emacs不是精确地在窗口右边缘换行,而是在最靠近窗口右边缘的单词边界(即空格或制表符)换行。Visual Line mode还重新定义编辑命令,如C-aC-nC-k,以在屏幕行而不是逻辑行上操作。请参阅 Visual Line Mode.

Next: , Previous: , Up: Basic   [Contents][Index]

7.9光标位置信息

以下命令用于获取有关缓冲区各部分的大小和位置的信息,并对字数和行数进行计数。

M-x what-line

显示游标的行号。

M-x line-number-mode
M-x column-number-mode

切换当前行号或列号的自动显示。请参阅可选状态栏。如果要在每行之前显示行号,请参阅显示自定义

M-=

显示区域中存在的行数、字数和字符数(count-word-region)。有关选区的信息,请参阅标记

M-x count-words

显示缓冲区中存在的行数、字数和字符数。如果该选区处于活动状态(请参阅标记),则改为显示该选区的数字。

C-x =

显示游标之后的字符编码、游标的字符位置、游标的列(what-cursor-position)。

M-x hl-line-mode

启用或禁用当前行的高亮显示。请参见光标显示

M-x size-indication-mode

切换缓冲区大小的自动显示。请参阅可选状态栏

M-x what-line在回显区中显示当前行号。此命令通常是冗余的,因为当前行号显示在状态栏中(请参阅状态栏)。但是,如果聚焦缓冲区,状态栏将显示相对于可访问部分的行号(请参阅聚焦)。相比之下,what-line既显示相对于聚焦区域的行号,又显示相对于整个缓冲区的行号。

M-=(count-words-region)显示一条消息,报告选区中的行数、字数和字符数(有关选区的说明,请参阅标记)。使用前缀参数C-u M-=,该命令显示整个缓冲区的计数。

命令M-x count-words执行相同的任务,但具有不同的调用约定。如果选区处于活动状态,它将显示选区的计数,否则将显示缓冲区的计数。

命令C-x =(what-cursor-position)显示有关当前光标位置和该位置的缓冲区内容的信息。它在回显区显示为一行,如下所示:

Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53

在“Char:”之后,显示缓冲区中的游标所在的字符。括号内的文本显示相应的十进制、八进制和十六进制字符代码;有关C-x =如何显示字符信息的详细信息,请参阅国际字符。在‘point=’之后是游标位置的字符计数(缓冲区中的第一个字符是位置1,第二个字符是位置2,依此类推)。后面的数字是缓冲区中的总字符数,括号中的数字以总字符数的百分比表示位置。在‘column=’之后是游标的水平位置,以从窗口左边缘开始计数的列为单位。

如果用户选项what-cursor-show-names为非nil,则还会显示Unicode字符数据库定义的字符名称。然后,括号中的部分将变为:

(99, #o143, #x63, LATIN SMALL LETTER C)

如果缓冲区被聚焦,导致开头和结尾的某些文本暂时不可访问,C-x =将显示描述当前可访问范围的附加文本。例如,它可能会显示以下内容:

Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0

其中两个额外的数字给出了该游标被允许的最小和最大字符位置。这两个位置之间的字符是可访问的字符。请参阅聚焦

相关但不同的功能是display-line-numbers-mode(请参阅显示自定义)。

Next: , Previous: , Up: Basic   [Contents][Index]

7.10数值参数

在数学和计算术语中,参数表示“提供给函数或运算的数据”。您可以为任何Emacs命令提供数字参数(也称为前缀参数)。一些命令将参数解释为重复计数。例如,如果将C-f的参数设为10,则它会将点向前移动10个字符,而不是1个字符。使用这些命令时,没有任何参数等同于参数1,而负参数会导致它们朝相反的方向移动或操作。

指定数字参数的最简单方法是在按住Meta键的同时键入数字或减号。例如,

M-5 C-n

向下移动五行。键M-1M-2等等以及M--被绑定到为下一个命令设置参数的命令(数字参数负参数)。M--没有数字通常表示-1。

如果输入多个数字,则不需要按住Meta键输入第二个和后续数字。因此,要向下移动50行,请键入

M-5 0 C-n

请注意,张扬不会像您预期的那样插入5个‘0’副本并向下移动一行——‘0’被视为前缀参数的一部分。

(如果您确实要插入“0”的五个副本,该怎么办?键入M-5 C-u 0。这里,C-u终止前缀参数,以便下一次击键开始您想要执行的命令。请注意,C-u的这一含义仅适用于此情况。有关C-u的常见角色,请参见下面的内容。)

指定数字参数的另一种方法不是键入M-1M-2等,而是键入C-u(universal-argument),后跟一些数字,或后跟数字的减号(对于负参数)。不带数字的负号通常表示-1。

C-u本身就有“四次”的特殊含义:它将下一个命令的参数乘以四。C-u C-u将其乘以16。因此,C-u C-u C-f向前移动了16个字符。其他有用的组合有C-u C-nC-u C-u C-n(向下移动相当一部分屏幕)、C-u C-u C-o(留出16个空行)和C-u C-k(删除四行)。

您可以在自插入字符之前使用数字参数来插入该字符的多个副本。当字符不是数字时,这很简单;例如,C-u6 4 a 插入字符“a”的64个副本。但这不适用于插入数字;C-u6 4 1 指定参数641。您可以将参数与数字分隔,以便用另一个C-u插入;例如,C-u 6 4 C-u 1 执行插入字符“1”的64个副本。

有些命令关心是否有参数,但忽略其值。例如,命令M-q(fill-paragraph)填充文本;使用参数,它也会将文本对齐。(有关M-q的详细信息,请参阅填充。)对于这些命令,使用单个C-u指定参数就足够了。

有些命令使用参数的值作为重复计数,但在没有参数时会做一些特殊的事情。例如,带有参数n的命令C-k(kill-line)剪切n行,包括它们的终止换行符。但是C-k没有参数是特别的:它会删除下一个换行符之前的文本,或者,如果游标正好在行尾,它会删除换行符本身。因此,两个没有参数的C-k命令可以杀死一个非空行,就像C-k有一个参数一样。(有关C-k的详细信息,请参阅剪切。)

有几个命令将普通C-u与普通参数区别对待。它们可能会将只有一个负号的参数与处理为-1的参数有所不同。这些不寻常的情况会在出现时进行描述;它们的存在是为了使单个命令更方便,并且记录在该命令的文档字符串中。

我们使用术语前缀参数来强调您在命令之前键入这样的参数,并将它们与迷你缓冲区参数(请参阅迷你缓冲区)区分开来,后者是在调用命令之后输入的。

在图形显示上,C-0C-1等与M-0M-1等作用相同。

Previous: , Up: Basic   [Contents][Index]

7.11重复命令

许多简单的命令,例如使用单键调用或使用M-x command-name RET调用的命令,可以通过使用充当重复计数的数字参数调用它们来重复(请参阅参数)。但是,如果要重复输入的命令提示输入,或者以其他方式使用数字参数,则该方法将不起作用。

命令C-x z(repeat)提供了将一个Emacs命令重复多次的另一种方法。此命令重复前面的Emacs命令,不管是什么。重复命令使用的参数与以前使用的参数相同;它不会每次都读取新的参数。

要多次重复该命令,请键入其他z:每个z都重复该命令一次。当您键入z以外的字符或按下鼠标按钮时,重复结束。

例如,假设您键入C-u 2 0 C-d来删除20个字符。通过键入C-x z z z,您可以额外重复该命令(包括其参数)三次,以删除总共80个字符。第一个C-x z重复该命令一次,随后的每个z重复一次。


Next: , Previous: , Up: Top   [Contents][Index]

8 迷你缓冲区

迷你缓冲区是Emacs命令读取复杂参数的地方,比如文件名、缓冲区名、Emacs命令名或Lisp表达式。我们称它为“迷你缓冲区”,因为它是一个具有少量屏幕空间的专用缓冲区。您可以在迷你缓冲区中使用常用的Emacs编辑命令来编辑参数文本。

Next: , Up: Minibuffer   [Contents][Index]

8.1使用迷你缓冲区

当迷你缓冲区正在使用时,它会与光标一起出现在回显区中。迷你缓冲区以prompt开始,通常以冒号结束。提示符说明预期的输入类型,以及将如何使用它。提示符使用minibuffer-prompt字符样式突出显示(请参阅字符样式)。

输入迷你缓冲区参数的最简单方法是键入文本,然后RET提交参数并退出迷你缓冲区。或者,您也可以键入C-g,通过取消请求参数的命令来退出微型缓冲区(请参阅退出)。

有时,提示符会在冒号前的括号内显示默认参数。如果您只键入RET,则此默认值将用作参数。例如,读取缓冲区名称的命令通常将缓冲区名称显示为默认缓冲区名称;您可以键入RET在该默认缓冲区上操作。

如果您启用了Minibuffer Electric Default mode(一种全局辅模式),Emacs会在您修改迷你缓冲区的内容时立即隐藏默认参数(因为键入RET将不再提交该默认参数)。如果您键入原始的微型缓冲区文本,提示将再次显示默认值。此外,如果将变量minibuffer-eldef-shorten-default更改为非nil值,则默认参数将显示为‘[default-arg]’而不是‘(defaultdefault-arg)’,从而节省一些屏幕空间。要启用此辅模式,请键入M-x minibuffer-electric-default-mode

由于迷你缓冲区出现在回显区中,因此它可能与回显区的其他用途冲突。如果在迷你缓冲区处于活动状态时发出错误消息或信息性消息,则该消息会将迷你缓冲区隐藏几秒钟,或者直到您键入内容;然后迷你缓冲区才会返回。当迷你缓冲区正在使用时,Emacs不会回显击键。

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.2文件名的迷你缓冲区

C-x C-f(find-file)等命令使用迷你缓冲区读取文件名参数(请参阅基本文件)。当使用迷你缓冲区读取文件名时,它通常以一些以斜杠结尾的初始文本开始。这是默认目录。例如,它可能是这样开始的:

Find file: /u2/emacs/src/

这里,“Find file:”是提示符,“/u2/emacs/src/”是默认目录。如果您现在键入buffer.c作为输入,则指定文件/u2/emacs/src/buffer.c。有关默认目录的信息,请参阅文件名

可以通过键入M-n获得您可能需要的文件名的其他默认值,请参阅迷你缓冲区历史

您可以使用..指定父目录中的文件:/a/b/../foo.el等同于/a/foo.el。或者,您也可以使用M-DEL向后删除目录名(请参阅单词)。

要在完全不同的目录中指定文件,可以使用C-a C-k终止整个默认文件(请参阅迷你缓冲区编辑)。或者,您可以忽略默认设置,在默认目录后输入以斜杠或波浪号开头的绝对文件名。例如,您可以指定/etc/termcap,如下所示:

Find file: /u2/emacs/src//etc/termcap

双斜杠会导致Emacs忽略对中第二个斜杠之前的所有内容。在上面的示例中,/u2/emacs/src/被忽略,因此您提供的参数是/etc/termcap。如果终端允许,文件名中被忽略的部分将变暗。(要禁用此调暗,请使用命令M-xfile-name-shadow-mode关闭文件名阴影模式.)

在补全远程文件名(请参阅远程文件)时,双斜杠的行为略有不同:它导致Emacs仅忽略文件名部分,而保留剩余(方法、主机和用户名等)完好无损。在一行中键入三个斜杠将忽略远程文件名中的所有内容。请参阅Tramp手册中的文件名补全

Emacs将~/解释为您的主目录。因此,~/foo/bar.txt指定了一个名为bar.txt的文件,该文件位于名为foo的目录中,而该目录又位于您的主目录中。此外,~user-id/表示登录名为user-id的用户的主目录。忽略~前面的任何前导目录名:因此,/u2/emacs/~/foo/bar.txt等同于~/foo/bar.txt

在MS-Windows和MS-DOS系统上,用户并不总是有主目录,Emacs使用几种替代方法。有关MS-Windows,请参阅Windows HOME;有关MS-DOS,请参阅MS-DOS文件名。在这些系统上,即仅当user-id是当前用户的登录名时才支持~user-id/结构。

要防止Emacs在读取文件名时插入默认目录,请将变量insert-default-directory更改为nil。在这种情况下,迷你缓冲区开始为空。尽管如此,相对文件名参数仍然基于相同的默认目录进行解释。

您还可以在迷你缓冲区中输入远程文件名。请参阅远程文件

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.3在迷你缓冲区中编辑

迷你缓冲区是一个Emacs缓冲区,尽管这是一个特殊的缓冲区,并且可以使用常用的Emacs命令来编辑参数文本。(但是,提示为read-only的,不能更改。)

由于迷你缓冲区中的RET为提交参数,因此不能使用它插入换行符。您可以使用C-q C-j执行此操作,它插入一个C-j控制字符,在形式上相当于换行符(请参见插入文本)。或者,您也可以使用C-o(open-line)命令(请参阅空行)。

在迷你缓冲区中,TABSPC键通常绑定到补全命令,这些命令允许您轻松地填写所需的文本,而无需键入所有文本。请参阅补全。与5>RET一样,您可以使用C-q插入TABSPC或‘?’字符。

为方便起见,迷你缓冲区中的C-a(move-beginning-of-line)将指向参数文本的开头,而不是提示符的开头。例如,这允许您使用C-a C-k擦除整个参数。

当迷你缓冲区处于活动状态时,回显区的处理方式与普通Emacs窗口非常相似。例如,您可以切换到另一个窗口(使用C-x o),在那里编辑文本,然后返回到迷你缓冲区窗口补全参数。您甚至可以剪切另一个窗口中的文本,返回到迷你缓冲区窗口,然后将文本粘贴为参数。但是,对迷你缓冲区窗口有一些限制:例如,您不能拆分它。请参阅窗口

通常,迷你缓冲区窗口占据单个屏幕行。但是,如果您将两行或更多行的文本添加到迷你缓冲区中,它会自动扩展以容纳文本。变量resize-mini-windows控制迷你缓冲区的大小调整。默认值是grow-only,这意味着我们刚才描述的行为。如果该值为t,如果您从迷你缓冲区中删除一些文本行,则迷你缓冲区窗口也会自动缩小,最小只有一个屏幕行。如果该值为nil,则微型缓冲区窗口永远不会自动更改大小,但您可以在其上使用常用的窗口大小调整命令(请参阅窗口)。

变量max-mini-window-height控制调整迷你缓冲区窗口大小的最大高度。浮点数表示占窗体的比例;整数表示指定最大行数;nil表示不自动调整迷你缓冲区窗口的大小。默认值为0.25。

在任何窗口中都可以使用C-M-v命令来滚动显示在迷你缓冲区中的帮助文本。您还可以使用M-PageUpM-PageDown(或等效的M-priorM-next)滚动帮助文本。对于可能补全的长列表,这尤其有用。请参见其他窗口

在迷你缓冲区处于活动状态时,Emacs通常不允许大多数使用迷你缓冲区的命令。要在迷你缓冲区中允许这样的命令,请将变量enable-recursive-minibuffers设置为t。您可能还需要启用minibuffer-depth-indicate-mode,以便在递归使用迷你缓冲区时在迷你缓冲区提示符中显示当前的递归深度。

不活动时,迷你缓冲区处于minibuffer-inactive-mode,单击鼠标会显示*Messages*缓冲区。如果您为迷你缓冲区使用专用窗体,Emacs还会识别那里的某些关键点,例如,n来创建新窗体。

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.4补全功能

您通常可以使用名为补全的功能来帮助输入参数。这意味着在您键入部分参数后,Emacs可以根据到目前为止键入的内容填充剩余或其中的一部分。

当补全可用时,某些键(通常为TABRETSPC)在迷你缓冲区中表现为特殊的补全命令(请参阅补全命令)。这些命令尝试根据请求参数的命令提供的一组补全选项来补全迷你缓冲区中的文本。您通常可以键入来查看可供选择的补全列表。

虽然补全通常是在小缓冲区中补全的,但有时普通缓冲区中也可以使用该功能。请参见符号补全

Next: , Up: Completion   [Contents][Index]

8.4.1补全示例

这里有一个简单的例子可能会有所帮助。M-x使用迷你缓冲区读取命令的名称,因此补全是通过将迷你缓冲区文本与现有Emacs命令的名称进行匹配来实现的。假设您希望运行命令auto-fill-mode。您可以通过键入M-x auto-fill-modeRET来做到这一点,但是使用补全更容易。

如果键入M-x a uTABTAB将查找以“au”开头的补全选项(在本例中为命令名)。有几个选项,包括auto-fill-modeautoconf-mode,但它们都以auto开头,因此迷你缓冲区中的‘au’补全为‘auto’。(可以在Emacs会话中定义更多命令。例如,如果定义了名为authorize-me的命令,则Emacs只能在“aut”范围内补全。)

如果立即再次键入TAB,则无法确定下一个字符;它可能是“-”、“a”或“c”。因此它不会添加任何字符;相反,TAB会在另一个窗口中显示所有可能的补全列表。

接下来,键入-f。迷你缓冲区现在包含“auto-f”,并且唯一以此开头的命令名是auto-full-mode。如果现在键入TAB,补全操作会将参数“auto-fill-mode”的剩余填充到迷你缓冲区中。

因此,只需键入a uTAB-fTAB即可进入“auto-fill-mode”。

Next: , Previous: , Up: Completion   [Contents][Index]

8.4.2补全命令

以下是允许补全时在微型缓冲区中定义的补全命令列表。

TAB

尽可能补全迷你缓冲区中的文本;如果无法补全,则显示可能补全的列表(minibuffer-complete)。

SPC

在游标之前尽可能的补全迷你缓冲区文本中的一个单词(minibuffer-complete-word)。此命令不适用于经常包含空格的参数,例如文件名。

RET

将迷你缓冲区中的文本作为参数提交,可能首先补全(minibuffer-complete-and-exit)。请参见补全退出

?

显示补全列表(minibuffer-completion-help)。

TAB(minibuffer-complete)是最基本的补全命令。它搜索与现有迷你缓冲区文本匹配的所有可能的补全,并尝试尽可能多地补全。有关如何选择补全备选方案,请参阅补全风格

SPC(minibuffer-complete-word)像TAB一样补全,但只到下一个连字符或空格。如果在迷你缓冲区中有“auto-f”并键入SPC,它会发现补全是“auto-fill-mode”,但它只插入“ill-”,给出“auto-ill-”。此时,另一个SPC将一直补全到“auto-fill-mode”。

如果TABSPC无法补全,它会在另一个窗口中显示匹配的补全备选方案(如果有)的列表。您可以使用(minibuffer-completion-help)显示相同的列表。以下命令可以与补全列表一起使用:

M-v
PageUp
prior

在迷你缓冲区中键入M-v,选择显示补全列表的窗口(switch-to-completions)。这为使用下面的命令铺平了道路。PageUpprior执行相同的操作。您也可以通过其他方式选择窗口(请参阅窗口)。

RET
鼠标左键
鼠标中键

在补全列表缓冲区中时,这将在游标处选择补全(choose-completion)。

TAB
RIGHT

在补全列表缓冲区中,这些键移动到以下补全选项(next-completion)。

S-TAB
LEFT

在补全列表缓冲区中时,这些键移动到前一个补全选项(previous-completion)。

q

在补全列表缓冲区中时,这将退出显示它的窗口,并选择显示迷你缓冲区的窗口(quit-window)。

z

在补全列表缓冲区中时,取消它并删除显示它的窗口(kill-current-buffer)。

Next: , Previous: , Up: Completion   [Contents][Index]

8.4.3补全退出

当命令使用带有补全的迷你缓冲区读取参数时,它还控制当您键入RET(minibuffer-complete-and-exit)提交参数时发生的情况。有四种类型的行为:

Next: , Previous: , Up: Completion   [Contents][Index]

8.4.4如何选择补全备选方案

补全命令的工作方式是将可能的补全备选方案的大列表缩小到与您在迷你缓冲区中键入的内容相匹配的较小子集。在补全示例中,我们给出了一个简单的匹配示例。确定什么构成匹配的过程相当复杂。Emacs试图在大多数情况下提供看似合理的补全。

Emacs使用一个或多个补全风格-用于将迷你缓冲区文本与补全备选方案相匹配的标准集来执行补全。在补全过程中,Emacs会依次尝试每种补全风格。如果风格生成一个或多个匹配项,则将其用作补全备选方案的列表。如果某个风格没有生成匹配项,则Emacs会退回到下一个风格。

列表变量completion-styles指定要使用的补全风格。每个列表元素都是一个补全风格的名称(一个Lisp符号)。默认补全风格为(按顺序):

basic

匹配的补全替换必须与迷你缓冲区中游标之前的文本具有相同的开头。此外,如果在游标之后的微型缓冲区中有任何文本,则补全备选方案的剩余部分必须将该文本作为子字符串包含。

partial-completion

这种积极的补全风格将迷你缓冲区文本分成用连字符或空格分隔的单词,并分别补全每个单词。(例如,在补全命令名称时,“em-l-m”将补全为“emacs-lisp-mode”。)

此外,迷你缓冲区文本中的“*”被视为通配符-它匹配补全备选方案中相应位置的任何字符串。

emacs22

此补全风格类似于basic,不同之处在于它忽略了迷你缓冲区中游标之后的文本。之所以这样命名,是因为它对应于Emacs22中的补全行为。

还定义了以下其他补全风格,如果您愿意,可以将它们添加到补全风格中(请参阅自定义):

substring

匹配的补全选项必须将迷你缓冲区中的文本包含在游标之前,而将迷你缓冲区中的文本包含在游标之后,作为子字符串(顺序相同)。

因此,如果迷你缓冲区中的文本是“foobar‘,游标在”foo’和“bar‘之间,则该文本与‘afoobbarc’,匹配,其中abc可以是包括空字符串的任何字符串。

initials

这种非常激进的补全风格视图补全缩略词和缩写。例如,在补全命令名时,它将“lch”与“list-command-history”匹配。

还有一种非常简单的补全风格,称为emacs21。在此风格中,如果迷你缓冲区中的文本是“foobar”,则只考虑以“foobar”开头的匹配项。

通过设置变量completion-category-overrides,您可以在不同的情况下使用不同的补全风格。例如,默认设置表示为缓冲区名称仅使用basicsubstring

Previous: , Up: Completion   [Contents][Index]

8.4.5补全选项

在补全区分大小写的参数(如命令名)时,大小写非常重要。例如,在补全命令名称时,“AU”不会补全为“auto-fill-mode”。补全参数时忽略大小写差异,在这种情况下大小写无关紧要。

补全文件名时,如果变量read-file-name-completion-ignore-casenil,则忽略大小写差异。在具有区分大小写的文件名的系统(如GNU/Linux)上,默认值为nil;在具有不区分大小写的文件名的系统(如Microsoft Windows)上,默认值为非nil。补全缓冲区名称时,如果变量read-buffer-completion-ignore-casenil,则忽略大小写差异;默认值为nil

在补全文件名时,Emacs通常会省略某些被认为不太可能选择的备选方案,这由列表变量completion-ignored-extensions确定。列表中的每个元素都应该是一个字符串;任何以这样的字符串结尾的文件名都会被忽略,作为补全选项。任何以斜杠(/)结尾的元素都表示一个子目录名。completion-ignored-extensions的标准值有几个元素,包括“.o”“.elc”“~”。例如,如果目录包含“foo.c”和“foo.elc”,则“foo”将补全为“foo.c”。但是,如果所有可能的补全都以其他被忽略的字符串结尾,则它们不会被忽略:在上一个示例中,“foo.e”补全于“foo.elc”。在补全列表中显示补全备选选项时,Emacs忽略completion-ignored-extensions

Shell补全是文件名补全的扩展版本,请参阅Shell选项

如果completion-auto-help设置为nil,则补全命令永远不会显示补全列表缓冲区;您必须键入才能显示列表。如果值为lazy,则Emacs仅在第二次尝试补全时显示补全列表缓冲区。换句话说,如果没有要补全的内容,则第一个TAB回显“Next char not only”;第二个TAB显示补全列表缓冲区。

如果completion-cycle-threshold为非nil,则补全命令可以循环补全备选方案。通常,如果迷你缓冲区中的文本有多个可选补全选项,则补全命令最多会补全到最长的公共子字符串。如果将completion-cycle-threshold更改为t,则补全命令将改为补全到这些补全备选方案中的第一个;每次后续调用补全命令都会以循环方式将其替换为下一个补全备选方案。如果给completion-cycle-threshold一个数值n,则仅当有n或更少替代选项时,补全命令才会切换到此循环行为。

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.5迷你缓冲区历史记录

您使用迷你缓冲区输入的每个参数都保存在迷你缓冲区历史列表中,这样您以后就可以轻松地再次使用它。您可以使用以下参数将较早的参数快速提取到迷你缓冲区中:

M-p

移至迷你缓冲区历史记录中的上一项,即较早的参数(previous-history-element)。

M-n

移至迷你缓冲区历史记录中的下一项(next-history-element)。

UP
DOWN

M-pM-n类似,但在转到上一历史记录项目(previous-line-or-history-elementnext-line-or-history-element)之前移动到多行项目的上一行或下一行。

M-r regexp RET

移动到迷你缓冲区历史记录中与regexp匹配的较早项(previous-matching-history-element)。

M-s regexp RET

移动到迷你缓冲区历史记录中与regexp匹配的后一项(next-matching-history-element)。

在迷你缓冲区中时,M-p(previous-history-element)在迷你缓冲区历史列表中移动,一次移动一项。每个M-p从历史记录列表中取出一个较早的项到迷你缓冲区,替换其现有内容。键入M-n(next-history-element)以相反的方向遍历迷你缓冲区历史列表,将稍后的项提取到迷你缓冲区中。

如果在迷你缓冲区历史记录中没有以后的项目时在迷你缓冲区中键入M-n(例如,如果您以前没有键入过M-p),则Emacs会尝试从默认参数列表中提取:您可能会输入的值。你可以认为这是在穿越“未来的历史”。

文件名的“未来历史”包括几个您可能会觉得有用的备选方案,例如文件名或当前缓冲区中各点的URL。在这种情况下,放入“未来历史”中的默认值由选项file-name-at-point-functions的值中提到的函数控制。默认情况下,它的值调用ffap包(请参阅FFAP),该包尝试从游标周围的文本猜测默认文件或URL。要禁用这种猜测,请将该选项自定义为nil值,那么文件名的“未来历史”将只包括当前缓冲区访问的文件(如果有的话)和默认目录。

箭头键UPDOWN类似于M-pM-n,但是如果当前历史项目超过一行,则它们允许您在转到上一个或下一个历史项目之前移动到当前历史项目的上一行或下一行。

如果编辑由M-pM-n迷你缓冲区历史命令插入的文本,这不会更改其在历史记录列表中的条目。但是,当您提交已编辑的参数时,它确实会出现在历史记录列表的末尾。

您可以使用M-r(previous-matching-history-element)搜索历史列表中较旧的元素,使用M-s(next-matching-history-element)搜索较新的条目。这些命令中的每一个都要求将正则表达式作为参数,并将第一个匹配的条目提取到迷你缓冲区中。有关正则表达式的说明,请参阅正则表达式。数字前缀参数n表示提取n条匹配。这些命令是不寻常的,因为它们使用迷你缓冲区来读取正则表达式参数,即使它们是从迷你缓冲区调用的。正则表达式中的大写字母使搜索区分大小写(请参见松散搜索)。

您还可以使用增量搜索来搜索历史记录。请参阅iSearch迷你缓冲区

Emacs为几种不同类型的参数保存单独的历史记录列表。例如,有一个文件名列表,所有读取文件名的命令都使用该列表。其他历史记录列表包括缓冲区名称、命令名称(由M-x使用)和命令参数(由query-replace等命令使用)。

变量history-length指定迷你缓冲区历史列表的最大长度;如果列表太长,添加新元素会删除最旧的元素。如果值为t,则没有最大长度。

变量history-delete-duplicates指定是否删除历史记录中的重复项。如果它是非nil,则添加新元素将从列表中删除与其相等的所有其他元素。默认值为nil

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.6重复迷你缓冲区命令

使用迷你缓冲区一次的每个命令及其参数值都记录在一个特殊的历史列表中,即命令历史,以便您可以重复整个命令。特别是,由于M-x使用微型缓冲区读取命令名,因此这里记录了M-x的每次使用。

C-x ESC ESC

从命令历史记录重新执行最近的迷你缓冲区命令(repeat-complex-command)。

M-x list-command-history

显示整个命令历史记录,显示C-x ESC ESC可以重复的所有命令,最新的最先。

C- xESC ESC重新执行使用迷你缓冲区的最近命令。在没有参数的情况下,它重复最后一个这样的命令。数字参数指定要重复的命令;1表示最后一个命令,2表示上一个命令,依此类推。

C- x ESC ESC的工作方式是将前面的命令转换为Lisp表达式,然后输入用该表达式的文本初始化的迷你缓冲区。即使您不了解Lisp,显示哪个命令以供重复也可能是显而易见的。如果您只键入RET,则重复该命令不会改变。您还可以通过在执行命令之前编辑Lisp表达式来更改命令。执行的命令将添加到命令历史记录的前面,除非它与最近的项目相同。

进入C-x ESC ESC的迷你缓冲区后,可以使用常用的迷你缓冲区历史记录命令(请参阅微型缓冲区历史记录)在历史记录列表中移动。找到所需的前一个命令后,您可以像往常一样编辑其表达式,然后通过键入RET来执行它。

严格地说,增量搜索不使用迷你缓冲区。因此,尽管它的行为类似于复杂命令,但它通常不会出现在C-x ESC ESC的历史记录列表中. 通过将isearch-resume-in-command-history设置为非nil值,可以使增量搜索命令出现在历史记录中。请参阅增量搜索

以前使用迷你缓冲区的命令列表以Lisp列表的形式存储在变量command-history中。每个元素都是描述一个命令及其参数的Lisp表达式。Lisp程序可以通过使用command-history元素调用eval来重新执行命令。

Next: , Previous: , Up: Minibuffer   [Contents][Index]

8.7输入密码

有时,您可能需要在Emacs中输入密码。例如,当您告诉Emacs通过网络协议(如FTP)访问另一台计算机上的文件时,通常需要提供密码才能访问该计算机(请参阅远程文件)。

输入密码类似于使用迷你缓冲区。Emacs在回显区显示提示(例如‘password:’);在您键入所需的密码后,按RET提交密码。为防止其他人看到您的密码,您键入的每个字符都显示为点(“.”),而不是通常的格式。

输入密码时,无法使用与迷你缓冲区关联的大多数功能和命令。没有历史记录或补全,在提交密码之前,您不能使用Emacs更改窗口或执行任何其他操作。

键入密码时,可以按DEL向后删除,删除最后输入的字符。C-u删除您到目前为止键入的所有内容。C-g退出密码提示(请参阅退出)。C-y将当前剪切字内容插入到密码中(请参阅剪切)。您可以键入RETESC提交密码。任何其他自插入字符键都会将关联的字符插入到密码中,并且忽略所有其他输入。

Previous: , Up: Minibuffer   [Contents][Index]

8.8确认提示

Emacs命令可能要求您在执行过程中回答是或否的问题。这样的查询主要有两种类型。

对于第一种是或否查询,提示符以“(y or n)”结束. 您可以通过键入单个键“y”或“n”来回答查询,这将立即退出迷你缓冲区并传递响应。例如,如果您键入C-x C-w(write-file)保存缓冲区,并输入现有文件的名称,则Emacs会发出如下提示:

File ‘foo.el’ exists; overwrite?(y or n)

如果给出错误答案会产生严重后果,则通常使用第二种是或否查询;因此,它的提示以“(yes or no)”结尾。例如,如果在具有未保存更改的文件访问缓冲区上调用C-x k(kill-buffer),则Emacs会使用如下提示激活迷你缓冲区:

Buffer foo.el modified; kill anyway?(yes or no)

若要回答,必须在微型缓冲区中键入“yes”或“no”,后跟RET

对于这两种类型的是或否查询,迷你缓冲区的行为如前面各节中所述;您可以使用C-l将选定窗口重新居中,滚动窗口(使用C-vPageDown向前滚动,使用M-vPageUp)向后滚动),使用C-x o切换到另一个窗口,使用历史命令M-pM-n键入C-g取消查询,然后退出迷你缓冲区和查询命令(请参阅退出)。


Next: , Previous: , Up: Top   [Contents][Index]

9 按名称运行命令

每个Emacs命令都有一个可以用来运行它的名称。为方便起见,许多命令还具有键绑定。您可以通过键入快捷键来运行这些命令,也可以按名称运行它们。大多数Emacs命令没有键绑定,因此运行它们的唯一方式是按名称。(有关如何设置键绑定,请参阅按键绑定。)

按照惯例,命令名由一个或多个用连字符分隔的单词组成;例如,auto-fill-modemanual-entry。命令名称大多使用完整的英文单词,以便于记忆。

要按名称运行命令,请以M-x开头,键入命令名,然后以RET结束。M-x使用迷你缓冲区读取命令名。字符串“M-x”显示在迷你缓冲区的开头,作为提示,提醒您输入要运行的命令名。RET退出迷你缓冲区并运行该命令。有关迷你缓冲区的详细信息,请参阅迷你缓冲区

可以使用补全功能输入命令名。例如,要调用命令forward-char,您可以键入

M-x forward-char RET

或者

M-x forw TAB c RET

请注意,forward-char与您使用键C-f调用的命令相同。键绑定的存在不会阻止您按名称运行该命令。

M-x补全命令时,它将忽略声明为已过时的命令;对于这些命令,您必须键入其全名。过时的命令是那些存在更新的、更好的替代命令的命令,并且计划在将来的某些Emacs版本中删除这些命令。

若要取消M-x并且不运行命令,请键入C-g而不是输入命令名。这会将您带回命令级别。

要将数值参数传递给使用M-x调用的命令,请在M-x之前指定数值参数。当读取命令名时,参数值出现在提示符中,最后M-x将该参数传递给该命令。例如,要将数值参数42传递给命令forward-char,您可以键入C-u 42 M-x forward-charRET

当您使用M-x运行的命令具有键绑定时,Emacs会在运行该命令后在回显区中提到这一点。例如,如果您键入M-x forward-word,则消息显示您可以通过键入M-f来运行相同的命令。您可以通过将变量suggest-key-bindings设置为nil来关闭这些消息。suggest-key-bindings的值也可以是一个数字,在这种情况下,Emacs将在将绑定从显示中删除之前显示绑定的秒数。默认行为是显示绑定2秒。

在“M-x”提示符下键入的全名小于其全名后,仍可以调用没有键绑定的命令。如果这些速记比完整命令名短得多,则Emacs会回显区中提及这些速记,并且extended-command-suggest-shorter是非nilsuggest-key-bindings的设置也会影响这些提示。

在本手册中,当我们谈到按名称运行命令时,我们经常省略终止该名称的RET。因此,我们可以说M-x auto-fill-mode而不是M-xauto-fill-modeRET. 我们提到RET只是为了强调,例如当命令后面跟着参数时。

M-x通过运行命令execute-extended-command工作,该命令负责读取另一个命令的名称并调用它。


Next: , Previous: , Up: Top   [Contents][Index]

10帮助

Emacs提供了各种各样的帮助命令,都可以通过前缀键C-h(或等效的功能键F1)访问。以下各节将介绍这些帮助命令。您还可以键入C-h C-h以查看帮助命令列表(help-for-help)。您可以使用SPCDEL滚动列表,然后键入所需的帮助命令。若要取消,请键入C-g

许多帮助命令在特殊的帮助缓冲区中显示其信息。在此缓冲区中,您可以键入SPCDEL滚动,键入RET跟踪超链接。请参阅帮助模式

如果您正在寻找某个功能,但不知道它叫什么或在哪里查找,我们推荐三种方法。首先,尝试使用主题命令,然后尝试搜索手动索引,然后查看FAQ和软件包关键字。

C-h a topics RET

这将搜索名称与参数主题匹配的命令。参数可以是关键字、关键字列表或正则表达式(请参阅正则表达式)。请参阅主题

C-h i d m emacs RET i 主题 RET

这将在Emacs信息手册的索引中搜索主题,并显示找到的第一个匹配项。按,查看后续匹配。您可以使用一个正则表达式用作主题

C-h i d m emacs RET s 主题 RET

类似,但是它搜索手册的文本而不是索引。

C-h C-f

这将使用信息显示Emacs常见问题。

C-h p

这将根据关键字显示可用的Emacs包。请参阅包关键字

C-hF1在各种其他上下文中也意味着“帮助”。例如,您可以在前缀键之后键入它们,以查看可以跟随在前缀键之后的键的列表。(您还可以在此上下文中使用?。有几个前缀键不支持C-h?,因为它们为这些输入定义了其他含义,但它们都支持F1。)

Next: , Up: Help   [Contents][Index]

10.1帮助概述

以下是用于访问内置文档的帮助命令摘要。以下各节将更详细地介绍其中的大部分内容。

C-h a topics RET

显示名称与主题匹配的命令列表(apropos-command)。请参阅主题

C-h b

显示所有激活的键绑定;首先显示辅模式绑定,然后显示主模式的绑定,然后显示全局绑定(describe-bindings)。请参阅其他帮助

C-h c key

显示键序列快捷键绑定到的命令的名称(describe-key-briefly)。这里c代表“字符”。有关快捷键的更多信息,请使用C-h k。请参阅快捷键帮助

C-h d topics RET

显示其文档与主题(apropos-documentation)匹配的命令和变量。请参阅主题

C-h e

显示*Messages*缓冲区(view-echo-area-messages)。请参阅其他帮助

C-h f function RET

显示有关名为function(describe-function)的Lisp函数的文档。因为命令是Lisp函数,所以这也适用于命令。请参阅命令名称帮助

C-h h

显示HELLO文件,该文件显示各种字符集的示例。

C-h i

运行GNU文档浏览器Info(info)。Emacs手册可以在Info中找到。请参阅其他帮助

C-h k key

显示快捷键运行的命令的名称和文档(describe-key)。请参阅快捷键帮助

C-h l

显示最近300次按键的说明(view-lossage)。请参阅其他帮助

C-h m

显示当前主模式和辅模式的文档(describe-mode)。请参阅其他帮助

C-h n

显示Emacs最近更改的新闻(view-emacs-news)。请参阅帮助文件

C-h o symbol

显示名为symbol(describe-symbol)的Lisp符号的文档。这将显示各种符号的文档:函数、变量和字符样式。请参阅命令名称帮助

C-h p

按主题关键字查找包(finder-by-keyword)。请参阅包关键字。这将使用包菜单缓冲区列出包。请参阅

C-h P package RET

显示有关指定包的文档(describe-package)。请参阅包关键字

C-h r

在Info中显示Emacs手册(info-emacs-manual)。

C-h s

显示当前语法表(describe-syntax)的内容。请参阅其他帮助。语法表说明哪些字符是开始分隔符,哪些是单词的一部分,等等。有关详细信息,请参阅Emacs Lisp参考手册中的语法表

C-h t

进入Emacs交互式教程(教程帮助)。

C-h v var RET

显示Lisp变量var(describe-variable)的文档。请参阅命令名称帮助

C-h w command RET

显示命令名为command(where-is)的命令绑定了哪些按键。请参阅快捷键帮助

C-h C coding RET

描述编码系统编码(describe-coding-system)。请参阅编码系统

C-h C RET

描述当前使用的编码系统。

C-h F command RET

打开Info并转到记录Emacs命令命令(Info-goto-emacs-command-node)的节点。请参阅命令名称帮助

C-h I method RET

描述输入法方法(describe-input-method)。请参阅选择输入法

C-h K key

打开Info并转到记录键序列快捷键(Info-goto-emacs-key-command-node)的节点。请参阅快捷键帮助

C-h L language-env RET

显示有关语言环境language-env(describe-language-environment)中使用的字符集、编码系统和输入法的信息。请参阅语言环境

C-h S symbol RET

根据您正在编辑的编程语言(info-lookup-symbol)显示有关符号符号的信息文档。请参阅其他帮助

C-h .

如果游标在一个文本区域(display-local-help),则显示特殊文本区域的帮助消息。(例如,这些链接包括*Help*缓冲区中的链接。)请参阅帮助回显

Next: , Previous: , Up: Help   [Contents][Index]

10.2快捷键文档

用于获取键序列信息的帮助命令是C-h c(describe-key-briefly)和C-h k(describe-key)。

C-h ckey在回显区显示key绑定到的命令的名称。例如,C-h c C-f显示‘forward-char’。

C-h kkey类似,但提供了更多信息:它显示包含命令的文档字符串的帮助缓冲区,该字符串准确描述了命令的功能。

C-h Kkey显示Emacs手册中描述与key对应的命令的部分。

C-h c, C-h kC-h K 适用于任何类型的键序列,包括功能键、菜单和鼠标事件(但C-h c忽略鼠标移动事件除外)。例如,在C-h k之后,您可以从菜单栏中选择菜单项,以查看其运行的命令的文档字符串。

C-h wcommandRET列出绑定到command的按键。它会在回显区中显示列表。如果它显示该命令不在任何键上,这意味着您必须使用M-x来运行它。C-h w运行命令where-is

Next: , Previous: , Up: Help   [Contents][Index]

10.3按命令或变量名提供帮助

C-h f函数RET(describe-function)在窗口中显示Lisp函数函数的文档。因为命令是Lisp函数,所以您可以使用此方法查看您知道其名称的任何命令的文档。例如,

C-h f auto-fill-mode RET

显示auto-fill-mode的文档。这是获取未绑定到任何键(通常使用M-x运行的键)的命令文档的唯一方法。

C-h f对于您在Lisp程序中使用的Lisp函数也很有用。例如,如果您刚刚编写了表达式(make-vector len),并且希望检查您是否正确使用了make-vector,请键入C-h f make-vectorRET。由于C-h f允许所有函数名,而不仅仅是命令名,因此您可能会发现,您喜欢的一些在M-x中使用的完成缩写在C-h f中不起作用。在命令名中唯一的缩写在所有函数名中可能不是唯一的。

如果键入C-h fRET,它将描述游标周围缓冲区中最内层的Lisp表达式调用的函数,前提是函数名是有效的、已定义的Lisp函数。(当您输入参数时,该名称显示为默认值。)例如,如果游标位于文本‘(make-vector (car x)’之后,则包含游标的最内层列表是以‘(make-vector’开始的那个,因此C-h fRET描述了make-vector函数。

C-h f也可用于验证函数名是否拼写正确。如果C-h f的迷你缓冲区提示将缓冲区中的函数名显示为默认值,则意味着该名称被定义为Lisp函数。如果您确实不想查看文档,请键入C-g取消C-h f命令。

C-h v(describe-variable)类似于C-h f,但描述的是Lisp变量,而不是Lisp函数。如果它是已定义的Lisp变量的名称,则它的默认值是点前后的Lisp符号。请参阅变量

如果您安装了源文件,则描述Emacs变量和函数的帮助缓冲区通常具有指向相应源代码的超链接(请参阅超链接)。

要在手册中查找命令文档,请使用C-h F(Info-goto-emacs-command-node)。它了解各种手册,而不仅仅是Emacs手册,并且找到了正确的手册。

C-h o(describe-symbol)类似于C-h fC-h v,但它描述任何符号,可以是函数、变量或字符样式。如果符号有多个定义,比如它同时定义为函数和变量,则此命令将一个接一个地显示所有定义的文档。

Next: , Previous: , Up: Help   [Contents][Index]

10.4主题搜索

主题搜索命令回答类似于“处理文件的命令是什么?”。更准确地说,您指定了一个主题的模式,它表示一个单词、一个单词列表或一个正则表达式。

下面的每个主题搜索命令都读取微型缓冲区中的一个主题模式,搜索与该模式匹配的项目,并在不同的窗口中显示结果。

C-h a

搜索命令(apropos-command)。使用前缀参数,也可以搜索非交互函数。

M-x apropos

搜索函数和变量。由此可以找到交互功能(命令)和非交互功能。

M-x apropos-user-option

搜索用户可自定义的变量。使用前缀参数,还可以搜索不可自定义的变量。

M-x apropos-variable

搜索变量。使用前缀参数时,仅搜索可自定义变量。

M-x apropos-local-variable

搜索缓冲区局部变量。

M-x apropos-value

搜索值与指定模式匹配的变量。使用前缀参数,还可以搜索定义与模式匹配的函数,以及属性与模式匹配的Lisp符号。

M-x apropos-local-value

搜索值与指定模式匹配的缓冲区局部变量。

C-h d

搜索文档字符串与指定模式匹配的函数和变量(apropos-documentation)。

最简单的一种主题搜索的句型就是一个词。任何包含这个词的东西都符合这个模式。因此,要查找处理文件的命令,请键入C-h a fileRET。这将显示包含“file”的所有命令名列表,包括copy-filefind-file等等。每个命令名都有一个简短的描述和当前可以用来调用它的键的列表。在我们的示例中,可以通过键入C-x C-f来调用find-file

有关主题搜索缓冲区中列出的函数定义、变量或符号属性的更多信息,您可以使用鼠标左键鼠标中键单击它,或者移动到那里并键入RET

当您在主题搜索模式中指定多个单词时,名称必须至少包含两个单词才能匹配。因此,如果您正在寻找在游标之前删除文本块的命令,您可以尝试C-h a kill back backward behind before RET实际的命令名kill-backward将与此匹配;如果有命令kill-text-before,它也会匹配,因为它包含两个指定的单词。

为了获得更大的灵活性,您可以指定正则表达式(请参见正则表达式)。如果一个主题模式包含任何正则表达式特殊字符‘^$*+?.\[’,则该模式被解释为正则表达式。

遵循Emacs命令的命名约定,下面是一些在搜索模式中会很有用的单词。通过在C-h a中使用它们,您还将对命名约定有所了解。

char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default.

如果变量apropos-do-all是非nil,则大多数主题搜索命令的行为就像它们被赋予了前缀参数一样。有一个例外:apropos-variable没有前缀参数将始终搜索所有变量,无论apropos-do-all的值是什么。

默认情况下,除apropos-documentation之外的所有主题搜索命令都按字母顺序列出其结果。如果变量apropos-sort-by-scores是非nil,则这些命令会尝试猜测每个结果的相关性,并首先显示最相关的结果。apropos-documentation命令默认情况下按相关顺序列出其结果;要按字母顺序列出它们,请将变量apropos-documentation-sort-by-scores更改为nil

Next: , Previous: , Up: Help   [Contents][Index]

10.5帮助模式命令

帮助缓冲区提供与查看模式相同的命令(请参阅View Mode);例如,SPC向前滚动,DELS-SPC向后滚动。还提供了一些特殊命令:

RET

在游标上遵循交叉引用(help-follow)。

TAB

将游标移到下一个超链接(forward-button)。

S-TAB

将游标移回上一个超链接(backward-button)。

鼠标左键
鼠标中键

点击一个超链接。

C-c C-c

显示游标处有关符号的所有文档(help-follow-symbol)。

C-c C-f
r

跳转到下一个帮助主题(help-go-forward)。

C-c C-b
l

返回到上一个帮助主题(help-go-back)。

当函数名、变量名或字符样式名(请参阅字符样式)出现在帮助缓冲区的文档中时,它通常是带下划线的超链接。要查看相关文档,请将游标移至此处并键入RET(help-follow),或使用鼠标左键鼠标中键单击超链接。这样做将替换帮助缓冲区的内容;要回溯您的步骤,请键入C-c C-bl(help-go-back)。回溯步骤时,可以使用C-c C-fr(help-go-forward)继续。

帮助缓冲区还可以包含指向Info手册、源代码定义和URL(网页)的超链接。前两个是在Emacs中打开的,第三个是通过browse-url命令使用Web浏览器打开的(请参阅浏览器链接)。

在帮助缓冲区中,TAB(forward-button)将游标前移到下一个超链接,而S-TAB(backward-button)将游标移回上一个超链接。这些命令循环执行;例如,在最后一个超链接处键入TAB会返回到第一个超链接。

要查看有关文本中任何符号的所有文档,请将游标移动到该符号,然后键入C-c C-c(help-follow-symbol)。这显示了符号的所有含义的文档-作为变量、作为函数或作为字符样式。

Next: , Previous: , Up: Help   [Contents][Index]

10.6包的关键字搜索

Emacs中的大多数可选功能都分组到中。Emacs包含数百个内置软件包,还可以通过网络安装更多(请参阅)。

为了更容易地查找与主题相关的包,大多数包都根据它们所做的事情与一个或多个关键字相关联。键入C-h p(finder-by-keyword)调出包关键字列表,并说明关键字的含义。要查看给定关键字的包列表,请在该行键入RET;这将显示包菜单缓冲区中的包列表(请参见包菜单)。

C-h P(describe-package)提示输入包的名称(请参阅),并显示描述包的属性及其实现的功能的帮助缓冲区。缓冲区以按钮的形式列出与包相关的关键字。用鼠标左键鼠标中键单击一个按钮,查看与该关键字相关的其他软件包的列表。

Next: , Previous: , Up: Help   [Contents][Index]

10.7有关国际语言支持的帮助

有关特定语言环境的信息(请参阅语言环境),请键入C-h L(describe-language-environment)。这将显示一个帮助缓冲区,描述语言环境支持的语言,并列出相关的字符集、编码系统和输入法,以及该语言环境的一些示例文本。

命令C-h h(view-hello-file)显示文件etc/HELLO,该文件通过显示如何用多种语言说“hello”来演示各种字符集。

命令C-h I(describe-input-method)描述一种输入法-指定的输入法,或默认情况下当前使用的输入法。请参阅输入法

命令C-h C(describe-coding-system)描述编码系统-可以是指定的编码系统,也可以是当前使用的编码系统。请参阅编码系统

Next: , Previous: , Up: Help   [Contents][Index]

10.8其他帮助命令

C-h i(info)运行Info程序,该程序浏览结构化文档文件。C-h 4 i(info-other-window)执行相同的操作,但在另一个窗口中显示信息缓冲区。整个Emacs手册以及GNU系统的许多其他手册都可以在Info中找到。输入Info后键入h以运行有关使用Info的教程。

使用数字参数nC-h i选择Info缓冲区‘*info*<n>’。如果您想要同时浏览多个信息手册,这将非常有用。如果仅指定C-u作为前缀参数,C-h i会提示输入文档文件的名称,这样您就可以浏览在顶级信息菜单中没有条目的文件。

上述帮助命令C-h F functionRETC-h K key输入Info并直接转到函数快捷键的文档。

编辑程序时,如果您有编程语言手册的Info版本,则可以使用C-h S(info-lookup-symbol)在适当的手册中查找符号(关键字、函数或变量)的条目。此命令如何工作的详细信息取决于主模式。

如果发生意外情况,并且您不确定键入的内容,请使用C-h l(view-lossage)。C-h l显示您最近300次输入击键及其调用的命令。如果您看到不熟悉的命令,可以使用C-h kC-h f了解它们的作用。

若要查看最近的回显区消息,请使用C-h e(view-echo-area-messages)。这将显示保存这些消息的缓冲区*Messages*

每个Emacs主模式通常重新定义几个键,并对编辑工作方式进行其他更改。C-h m(describe-mode)显示有关当前主模式的文档,该文档通常描述在此模式中更改的命令和功能,以及它的键绑定。

C-h b(describe-bindings)和C-h s(describe-syntax)显示有关Emacs中当前环境的其他信息。C-h b显示当前有效的所有键绑定的列表:首先是当前辅模式的局部绑定,然后是当前主模式定义的局部绑定,最后是全局绑定(请参阅键绑定)。C-h s显示语法表的内容,并解释每个字符的语法(请参阅Emacs Lisp参考手册中的语法表)。

您可以通过在前缀键之后键入C-hF1(describe-prefix-bindings)来获取特定前缀键的子命令列表。(有几个前缀键并不是所有这些键都有效-那些为该键提供自己的绑定的前缀键。这些前缀键之一是ESC,因为ESCC-h实际上是C-M-h,它标记一个函数定义。但是,EscF1ESC? 工作正常。)

Next: , Previous: , Up: Help   [Contents][Index]

10.9帮助文件

除了内置的文档和手册之外,Emacs还包含其他几个文件,描述复制条件、发行说明、调试和报告错误的说明等主题。您可以使用以下命令查看这些文件。除了C-h g之外,它们的形式都是C-h C-char

C-h C-c

显示可以复制和重新分发Emacs的规则(describe-copying)。

C-h C-d

显示调试Emacs的帮助(view-emacs-debuting)。

C-h C-e

显示有关从何处获取外部包的信息(view-external-packages)。

C-h C-f

显示Emacs常见问题列表(view-emacs-FAQ)。

C-h g

有关GNU项目的信息,请访问页面(describe-gnu-project)。

C-h C-m

显示有关订购Emacs手册打印副本的信息(view-order-manuals)。

C-h C-n

显示新闻,其中列出了此版本的Emacs中的新功能(view-emacs-news)。

C-h C-o

显示如何订购或下载最新版本的Emacs和其他GNU软件(describe-distribution)。

C-h C-p

显示已知Emacs问题的列表,有时带有建议的解决方法(view-emacs-problems)。

C-h C-t

显示Emacs待办事项列表(view-emacs-todo)。

C-h C-w

显示GNU Emacs完全没有保修的完整详细信息(describe-no-warranty)。

Previous: , Up: Help   [Contents][Index]

10.10有关交互文本和工具提示的帮助

在Emacs中,交互文本(响应鼠标单击或RET执行特殊操作的文本)的延伸通常具有关联的帮助文本。这包括Emacs缓冲区中的超链接,以及部分状态行。在图形显示以及某些支持鼠标跟踪的文本终端上,将鼠标移到活动文本上会将帮助文本显示为工具提示。请参阅工具提示

在不支持鼠标跟踪的终端上,可以通过键入C-h .(display-local-help)显示缓冲区内游标处交互文本的帮助文本。这将在回显区中显示帮助文本。要在任何时候帮助文本可用时自动显示帮助文本,请将变量help-at-pt-display-when-idle设置为t


Next: , Previous: , Up: Top   [Contents][Index]

11标记与选区

许多Emacs命令在当前缓冲区的任意连续部分上操作。要为此类命令指定要操作的文本,请在其一端设置标记,然后将指针移到另一端。游标和标记之间的文本称为选区。选区始终在游标和标记之间延伸,无论文本中哪一个在前面;每次移动游标时,选区都会发生变化。

将标记设置在文本中的某个位置也会激活。当标记处于激活状态时,我们还表示选区处于激活状态;Emacs通过使用选区字符样式高亮显示其中的文本来指示其范围(请参阅字符样式自定义)。

这是默认情况下具有:extend t属性的少数几个字符样式之一,这意味着使用相同的字符样式来突出显示行尾和窗口边框之间的文本和空格。要仅突出显示文本,可以将此属性设置为nil

在某些非移动命令(包括更改缓冲区中的文本的任何命令)之后,Emacs会自动取消激活标记;这会关闭高亮显示。您还可以随时通过键入C-g来显式取消激活标记(请参阅退出)。

上述默认行为称为选区高亮模式。禁用选区高亮模式会将Emacs切换到另一种行为,在该行为中,该区域通常不会高亮显示。请参阅禁用选区高亮

在一个缓冲区中设置标记不会影响其他缓冲区中的标记。当您返回到具有激活标记的缓冲区时,该标记位于与以前相同的位置。当多个窗口显示相同的缓冲区时,它们可以具有不同的游标,从而具有不同的选区,但它们都共享一个共同的标记位置。请参阅窗口。通常,只有选定的窗口会高亮显示其区域;但是,如果变量highlight-nonselected-windows是非nil,则每个窗口都会高亮显示自己的选区。

还有另一种选区:矩形选区。请参见矩形

Next: , Up: Mark   [Contents][Index]

11.1设置标记

以下是设置标记的一些命令:

C-SPC

将标记设置在游标上,并将其激活(set-mark-command)。

C-@

一样的。

C-x C-x

将标记设置在游标上,并将其激活;然后将游标移动到标记原来所在的位置(exchange-point-and-mark)。

鼠标左键拖拽

设置游标和您拖过的文本周围的标记。

鼠标右键

将标记设置在游标上,然后将游标移动到您单击的位置(mouse-save-then-kill)。

Shift+方向键

如果标记处于非激活状态,则将标记设置在游标,然后移动游标。请参见Shift选择

设置标记的最常见方式是使用C-spc(set-mark-command)5. 这将在游标所在的位置设置标记,并将其激活。然后,您可以将游标移开,留下标记。

例如,假设您希望将部分缓冲区转换为大写。为此,请转到所需文本的一端,键入C-SPC,然后移动游标,直到高亮显示所需文本部分。现在键入C-x C-u(upcase-region)。这会将区域中的文本转换为大写,然后取消激活标记。

只要标记处于激活状态,您就可以通过键入C-g将其取消激活(请参阅退出)。在该选区上操作的大多数命令也会自动取消激活该标记,如上例中的C-x C-u

您也可以使用它来记住缓冲区中的一个位置(通过键入C-SPCC-SPC),然后跳回那里(通过键入C-u C-SPC),而不是设置标记以便对选区进行操作。有关详细信息,请参阅标记环

命令C-x C-x(exchange-point-and-mark)交换游标和标记的位置。如果您对游标的位置感到满意,但想要移动区域的另一端(标记所在的位置),则C-x C-x非常有用。如有必要,请再次使用C-x C-x将标记放在新位置,并将游标放回其原始位置。通常,如果标记处于非激活状态,此命令会首先在上次设置标记的位置重新激活标记,以确保选区保持高亮显示。但是,如果使用前缀参数调用它,则会使标记处于非激活状态,选区也不会高亮显示;您可以使用此参数以类似于C-u C-SPC的方式跳转到标记。

您也可以用鼠标设置标记。如果您按下鼠标左键(down-mouse-1)并在一系列文本上拖动鼠标,则会在您第一次按下鼠标按键的位置设置标记,并将游标放在您松开它的位置。或者,单击鼠标右键(mouse-3)将标记设置在游标上,然后将游标移动到您单击的位置。有关这些鼠标命令的详细说明,请参阅鼠标命令

最后,您可以通过在按住Shift键的同时键入某些光标移动命令(如S-RIGHTS-C-fS-C-n等)来设置标记。这称为Shift选择。它在移动游标之前的游标处设置标记,但仅当没有通过先前按住Shift键选择或鼠标命令设置的激活标记时。由鼠标命令和按住Shift键并选择设置的标记的行为与通常的标记略有不同:任何后续未移动的光标移动命令都会自动将其取消激活。有关详细信息,请参阅Shift选择

许多插入文本的命令(如C-y(yank))会在插入的文本的另一端设置标记,而不激活它。这使您可以轻松地返回到该位置(请参阅标记环)。当命令在回显区显示“Mark set”时,您可以看出该命令是这样做的。

在X下,每次激活选区更改时,Emacs都会将选区中的文本保存到主选择。这允许您通过单击鼠标中键将该文本插入到其他X应用程序中。请参阅主选择

Next: , Previous: , Up: Mark   [Contents][Index]

11.2用于标记文本对象的命令

以下是在文本对象(如单词、列表、段落或页面)周围放置游标和标记的命令:

M-@

在下一个单词的末尾设置标记(mark-word)。这不会移动游标。

C-M-@

在表达式的末尾设置标记(mark-sexp)。这不会移动游标。

M-h

将游标移动到当前段落的开头,并在末尾设置标记(mark-paragraph)。

C-M-h

将游标移到当前定义的开头,并在结尾处设置标记(mark-defun)。

C-x C-p

将游标移到当前页面的开头,并在末尾设置标记(mark-page)。

C-x h

将游标移动到缓冲区的开头,并在末尾设置标记(mark-whole-buffer)。

M-@(mark-word)在下一个单词的末尾设置标记(有关单词的信息,请参见单词)。重复调用此命令可通过一次前进一个单词来扩展选区。例外情况是,如果标记处于激活状态且位于游标之前,M-@将标记从其当前位置向后移动,一次一个单词。

该命令还接受一个数字参数n,该参数告诉它将标记前进n个单词。负参数-n将标记后移n个单词。

类似地,C-M-@(mark-sexp)将标记放在下一个表达式的末尾(请参见表达式)。重复调用将该选区扩展到后续表达式,而正或负数字参数将标记向前或向后移动指定数量的表达式。

上面列表中的其他命令同时设置游标和标记,以分隔缓冲区中的对象。M-h(mark-paragraph)标记段落(请参阅段落),C-M-h(mark-defun)标记顶级定义(请参阅按定义移动)和C-x C-p(mark-page)标记页(请参阅页面)重复调用再次扮演相同的角色,将选区扩展到连续的对象;类似地,数字参数指定移动标记的对象数。

C-x h(mark-whole-buffer)将整个缓冲区设置为选区,方法是将游标放在开头,将标记放在结尾。

Next: , Previous: , Up: Mark   [Contents][Index]

11.3选区的操作

一旦您有了一个选区,以下是您可以对其进行操作的一些方法:

当标记处于非激活状态时,某些命令具有默认行为,但如果标记处于激活状态,则会对选区进行操作。例如,M-$(ispell-word)通常会检查单词的拼写,但如果标记处于激活状态,则它会检查选区中的文本(请参阅拼写)。通常,如果选区为空(即,如果标记和点在同一位置),则此类命令使用其默认行为。如果希望它们在空选区上操作,请将变量use-empty-active-region更改为t

擦除中所述,DEL(backward-delete-char)和删除(delete-forward-char)命令也是如此。如果标记处于激活状态,则删除区域中的文本。(作为例外,如果您提供数字参数n,其中n不是1,则无论标记是否处于激活状态,这些命令都会删除n个字符)。如果将变量delete-active-region更改为nil,则当标记处于激活状态时,这些命令的作用不会有所不同。如果将值更改为kill,这些命令将剪切选区,而不是删除它(请参阅剪切)。

其他命令始终在该选区上操作,并且没有默认行为。此类命令的名称中通常包含单词region,如C-w(kill-region)和C-x C-u(upcase-region)。如果标记处于非激活状态,它们将对非激活选区——即游标与上次设置标记的位置之间的文本进行操作(请参阅标记环)。要禁用此行为,请将变量mark-even-if-inactive更改为nil。则如果标记处于非激活,则这些命令将改为发出错误信号。

默认情况下,即使标记处于激活状态,文本插入也会正常进行——例如,键入a会插入字符“a”,然后停用该标记。Delete Selection mode(一种次要模式)会修改此行为:如果启用该模式,则在标记处于活动状态时插入文本会导致首先删除选区中的文本。若要打开或关闭“Delete Selection mode”模式,请键入M-x delete-selection-mode

Next: , Previous: , Up: Mark   [Contents][Index]

11.4标记环

每个缓冲区都会在标记环中记住标记的先前位置。设置标记的命令也会将旧标记推到此环上。标记环的用途之一是记住您可能想要返回的位置。

C-SPC C-SPC

设置标记,将其推到标记环上,而不激活它。

C-u C-SPC

将游标移动到标记所在的位置,并从以前的标记环中恢复标记。

命令C-SPCC-SPC在您想要使用标记记住您可能希望返回的位置时非常方便。它会将当前游标推到标记环上,而不激活标记(这会导致Emacs高亮显示该区域)。这实际上是连续两次调用C-SPC(set-mark-command);第一个C-SPC设置标记,第二个C-SPC取消激活该标记。(当选区高亮模式关闭时,C-SPCC-SPC临时激活选区高亮模式;请参阅禁用选区高亮。)

要返回到标记位置,请使用带有前缀参数的set-mark-commandC-u C-SPC。此操作将指向标记所在的位置,如果标记处于激活状态,则会停用该标记。每个后续的C-u C-SPC跳转到存储在标记环中的先前位置。你以这种方式移动的位置不会丢失;它们会到达环的末端。

如果将 set-mark-command-repeat-pop 设置为非nil, 则在键入C-u C-SPC之后,你可以立即键入 C-SPC代替C-u C-SPC以在标记环中循环默认情况下,set-mark-command-repeat-popnil

每个缓冲区都有其自己的标记环。所有编辑命令都使用当前缓冲区的标记环。具体地说,C-u C-SPC始终保持在同一缓冲区中。

变量mark-ring-max指定要保留在标记环中的最大条目数。默认为16个条目。如果存在那么多条目,并且另一个条目被推送,则丢弃列表中最早的条目。重复C-u C-SPC循环更改在环中的当前位置。

如果你想一遍又一遍地移动回同一个地方,标记环可能不够方便。如果是这样,您可以将位置记录在寄存器中以备以后检索(请参阅在寄存器中保存位置)。

Next: , Previous: , Up: Mark   [Contents][Index]

11.5全局标记环

除了属于每个缓冲区的普通标记环之外,Emacs还具有单个全局标记环。如果自上一次标记设置后切换了缓冲区,则每次设置标记时,除了记录当前缓冲区自己的标记环外,还会将其记录在全局标记环中。因此,全局标记环会记录您所在的缓冲区序列,并为每个缓冲区记录您设置标记的位置。全局标记环的长度由global-mark-ring-max控制,默认为16。

命令C-x C-SPC(pop-global-mark)跳转到全局环中最新条目的缓冲区和位置。它还会旋转环,以便连续使用C-x C-SPC将您带到较早的缓冲区和标记位置。

Next: , Previous: , Up: Mark   [Contents][Index]

11.6Shift选择

如果在键入光标移动命令的同时按住Shift键,则会在移动点之前设置标记,以便选区从游标的原始位置延伸到其新位置。此功能称为shift选择。这类似于在其他编辑器中选择文本的方式。

通过按住Shift键选择设置的标记的行为与我们上面描述的稍有不同。首先,除了通常的取消激活标记的方法(如更改缓冲区文本或键入C-g)外,还可以通过任何非shift修饰的光标移动命令取消激活标记。其次,任何后续的shift修饰的光标移动命令都可以避免重新设置标记。因此,一系列移动的光标移动命令将连续调整选区。

仅当移动的光标移动键尚未绑定到单独的命令时,Shift选择才有效(请参阅自定义)。例如,如果将S-C-f绑定到另一个命令,则键入S-C-f将运行该命令,而不是执行C-f的Shift选定版本(forward-char)。

通过鼠标命令设置的标记与通过按住Shift键选择设置的标记的行为相同(请参阅设置标记)。例如,如果通过拖动鼠标指定选区,则可以使用shift修饰的光标移动命令继续扩展该选区。在这两种情况下,任何非Shift修饰的光标移动命令都会取消激活标记。

若要关闭Shift选择,请将shift-select-mode设置为nil。这样做并不会禁用通过鼠标命令设置标记。

Previous: , Up: Mark   [Contents][Index]

11.7禁用选区高亮模式

标记和选区的默认行为称为选区高亮模式,在该行为中,设置标记将激活标记并高亮显示选区。这是默认启用的辅模式。它可以使用M-x transient-mark-mode切换,或使用“选项”菜单中的“高亮已激活选区”菜单项进行切换。将其关闭会将Emacs切换到另一种操作模式:

关闭选区高亮模式时,您可以使用C-SPCC-SPCC-u C-x C-x临时激活该模式。

C-SPC C-SPC

将标记设置在游标(如普通C-SPC),只启用一次选区高亮模式,直到标记被取消激活。(这实际上不是一个单独的命令;您使用了两次C-SPC命令。)

C-u C-x C-x

交换游标和标记,激活标记并临时启用选区高亮模式,直到标记下一次取消激活。(这是C-x C-x命令exchange-point-and-mark,带有前缀参数。)

这些命令设置或激活标记,并仅在标记取消激活之前启用选区高亮模式。您可能想要使用它们的一个原因是,当选区高亮模式关闭时,某些命令在整个缓冲区而不是选区上操作。暂时启用选区高亮模式为您提供了一种在选区上使用这些命令的方法。

当您使用鼠标(请参阅设置标记)或按住Shift键选择(请参阅Shift选择)指定选区时,这同样会临时激活选区高亮模式并高亮显示该选区。

Next: , Previous: , Up: Top   [Contents][Index]

12剪切和移动文本

在Emacs中,剪切表示擦除文本并将其复制到剪切板中。Yanking </ e2>表示将文本从剪切板粘贴到缓冲区。(有些应用程序使用术语“剪切”和“粘贴”来表示类似的操作。)删除环之所以这样命名,是因为它可以可视化为排列在环中的一组文本块,您可以按循环顺序访问这些文本块。See Kill Ring.

Killing and yanking are the most common way to move or copy text within Emacs. It is very versatile, because there are commands for killing many different types of syntactic units.

Next: , Up: Killing   [Contents][Index]

12.1Deletion and Killing

Most commands which erase text from the buffer save it in the kill ring (see Kill Ring). These are known as kill commands, and their names normally contain the word ‘kill’ (e.g., kill-line). The kill ring stores several recent kills, not just the last one, so killing is a very safe operation: you don’t have to worry much about losing text that you previously killed. The kill ring is shared by all buffers, so text that is killed in one buffer can be yanked into another buffer.

When you use C-/ (undo) to undo a kill command (see Undo), that brings the killed text back into the buffer, but does not remove it from the kill ring.

On graphical displays, killing text also copies it to the system clipboard. See Cut and Paste.

Commands that erase text but do not save it in the kill ring are known as delete commands; their names usually contain the word ‘delete’. These include C-d (delete-char) and DEL (delete-backward-char), which delete only one character at a time, and those commands that delete only spaces or newlines. Commands that can erase significant amounts of nontrivial data generally do a kill operation instead.

You can also use the mouse to kill and yank. See Cut and Paste.

12.1.1 Deletion

Deletion means erasing text and not saving it in the kill ring. For the most part, the Emacs commands that delete text are those that erase just one character or only whitespace.

DEL
BACKSPACE

Delete the previous character, or the text in the region if it is active (delete-backward-char).

Delete

Delete the next character, or the text in the region if it is active (delete-forward-char).

C-d

Delete the next character (delete-char).

M-\

Delete spaces and tabs around point (delete-horizontal-space).

M-SPC

Delete spaces and tabs around point, leaving one space (just-one-space).

C-x C-o

Delete blank lines around the current line (delete-blank-lines).

M-^

Join two lines by deleting the intervening newline, along with any indentation following it (delete-indentation).

We have already described the basic deletion commands DEL (delete-backward-char), delete (delete-forward-char), and C-d (delete-char). See Erasing. With a numeric argument, they delete the specified number of characters. If the numeric argument is omitted or one, DEL and delete delete all the text in the region if it is active (see Using Region).

The other delete commands are those that delete only whitespace characters: spaces, tabs and newlines. M-\ (delete-horizontal-space) deletes all the spaces and tab characters before and after point. With a prefix argument, this only deletes spaces and tab characters before point. M-SPC (just-one-space) does likewise but leaves a single space before point, regardless of the number of spaces that existed previously (even if there were none before). With a numeric argument n, it leaves n spaces before point if n is positive; if n is negative, it deletes newlines in addition to spaces and tabs, leaving -n spaces before point. The command cycle-spacing acts like a more flexible version of just-one-space. It does different things if you call it repeatedly in succession. The first call acts like just-one-space, the next removes all whitespace, and a third call restores the original whitespace.

C-x C-o (delete-blank-lines) deletes all blank lines after the current line. If the current line is blank, it deletes all blank lines preceding the current line as well (leaving one blank line, the current line). On a solitary blank line, it deletes that line.

M-^ (delete-indentation) joins the current line and the previous line, by deleting a newline and all surrounding spaces, usually leaving a single space. See M-^.

The command delete-duplicate-lines searches the region for identical lines, and removes all but one copy of each. Normally it keeps the first instance of each repeated line, but with a C-u prefix argument it keeps the last. With a C-u C-u prefix argument, it only searches for adjacent identical lines. This is a more efficient mode of operation, useful when the lines have already been sorted. With a C-u C-u C-u prefix argument, it retains repeated blank lines.

12.1.2 Killing by Lines

C-k

Kill rest of line or one or more lines (kill-line).

C-S-backspace

Kill an entire line at once (kill-whole-line)

The simplest kill command is C-k (kill-line). If used at the end of a line, it kills the line-ending newline character, merging the next line into the current one (thus, a blank line is entirely removed). Otherwise, C-k kills all the text from point up to the end of the line; if point was originally at the beginning of the line, this leaves the line blank.

Spaces and tabs at the end of the line are ignored when deciding which case applies. As long as point is after the last non-whitespace character in the line, you can be sure that C-k will kill the newline. To kill an entire non-blank line, go to the beginning and type C-k twice.

In this context, “line” means a logical text line, not a screen line (see Continuation Lines).

When C-k is given a positive argument n, it kills n lines and the newlines that follow them (text on the current line before point is not killed). With a negative argument -n, it kills n lines preceding the current line, together with the text on the current line before point. C-k with an argument of zero kills the text before point on the current line.

If the variable kill-whole-line is non-nil, C-k at the very beginning of a line kills the entire line including the following newline. This variable is normally nil.

C-S-backspace (kill-whole-line) kills a whole line including its newline, regardless of the position of point within the line. Note that many text terminals will prevent you from typing the key sequence C-S-backspace.

12.1.3 Other Kill Commands

C-w

Kill the region (kill-region).

M-w

Copy the region into the kill ring (kill-ring-save).

M-d

Kill the next word (kill-word). 请参阅

M-DEL

Kill one word backwards (backward-kill-word).

C-x DEL

Kill back to beginning of sentence (backward-kill-sentence). See Sentences.

M-k

Kill to the end of the sentence (kill-sentence).

C-M-k

Kill the following balanced expression (kill-sexp). See Expressions.

M-z char

Kill through the next occurrence of char (zap-to-char).

M-x zap-up-to-char char

Kill up to, but not including, the next occurrence of char.

One of the commonly-used kill commands is C-w (kill-region), which kills the text in the region (see Mark). Similarly, M-w (kill-ring-save) copies the text in the region into the kill ring without removing it from the buffer. If the mark is inactive when you type C-w or M-w, the command acts on the text between point and where you last set the mark (see Using Region).

Emacs also provides commands to kill specific syntactic units: words, with M-DEL and M-d (see Words); balanced expressions, with C-M-k (see Expressions); and sentences, with C-x DEL and M-k (see Sentences).

The command M-z (zap-to-char) combines killing with searching: it reads a character and kills from point up to (and including) the next occurrence of that character in the buffer. A numeric argument acts as a repeat count; a negative argument means to search backward and kill text before point. A history of previously used characters is maintained and can be accessed via the M-p/M-n keystrokes. This is mainly useful if the character to be used has to be entered via a complicated input method. A similar command zap-up-to-char kills from point up to, but not including the next occurrence of a character, with numeric argument acting as a repeat count.

12.1.4 Options for Killing

Some specialized buffers contain read-only text, which cannot be modified and therefore cannot be killed. The kill commands work specially in a read-only buffer: they move over text and copy it to the kill ring, without actually deleting it from the buffer. Normally, they also beep and display an error message when this happens. But if you set the variable kill-read-only-ok to a non-nil value, they just print a message in the echo area to explain why the text has not been erased.

If you change the variable kill-do-not-save-duplicates to a non-nil value, identical subsequent kills yield a single kill-ring entry, without duplication.

12.2Yanking

Yanking means reinserting text previously killed. The usual way to move or copy text is to kill it and then yank it elsewhere.

C-y

Yank the last kill into the buffer, at point (yank).

M-y

Replace the text just yanked with an earlier batch of killed text (yank-pop). See Earlier Kills.

C-M-w

Cause the following command, if it is a kill command, to append to the previous kill (append-next-kill). See Appending Kills.

The basic yanking command is C-y (yank). It inserts the most recent kill, leaving the cursor at the end of the inserted text. It also sets the mark at the beginning of the inserted text, without activating the mark; this lets you jump easily to that position, if you wish, with C-u C-SPC (see Mark Ring).

With a plain prefix argument (C-u C-y), the command instead leaves the cursor in front of the inserted text, and sets the mark at the end. Using any other prefix argument specifies an earlier kill; e.g., C-u 4 C-y reinserts the fourth most recent kill. See Earlier Kills.

On graphical displays, C-y first checks if another application has placed any text in the system clipboard more recently than the last Emacs kill. If so, it inserts the clipboard’s text instead. Thus, Emacs effectively treats “cut” or “copy” clipboard operations performed in other applications like Emacs kills, except that they are not recorded in the kill ring. See Cut and Paste, for details.

Next: , Up: Yanking   [Contents][Index]

12.2.1 The Kill Ring

The kill ring is a list of blocks of text that were previously killed. There is only one kill ring, shared by all buffers, so you can kill text in one buffer and yank it in another buffer. This is the usual way to move text from one buffer to another. (There are several other methods: for instance, you could store the text in a register; see Registers. See Accumulating Text, for some other ways to move text around.)

The maximum number of entries in the kill ring is controlled by the variable kill-ring-max. The default is 60. If you make a new kill when this limit has been reached, Emacs makes room by deleting the oldest entry in the kill ring.

The actual contents of the kill ring are stored in a variable named kill-ring; you can view the entire contents of the kill ring with C-h v kill-ring.

Next: , Previous: , Up: Yanking   [Contents][Index]

12.2.2 Yanking Earlier Kills

As explained in Yanking, you can use a numeric argument to C-y to yank text that is no longer the most recent kill. This is useful if you remember which kill ring entry you want. If you don’t, you can use the M-y (yank-pop) command to cycle through the possibilities.

If the previous command was a yank command, M-y takes the text that was yanked and replaces it with the text from an earlier kill. So, to recover the text of the next-to-the-last kill, first use C-y to yank the last kill, and then use M-y to replace it with the previous kill. M-y is allowed only after a C-y or another M-y.

You can understand M-y in terms of a last-yank pointer which points at an entry in the kill ring. Each time you kill, the last-yank pointer moves to the newly made entry at the front of the ring. C-y yanks the entry which the last-yank pointer points to. M-y moves the last-yank pointer to a different entry, and the text in the buffer changes to match. Enough M-y commands can move the pointer to any entry in the ring, so you can get any entry into the buffer. Eventually the pointer reaches the end of the ring; the next M-y loops back around to the first entry again.

M-y moves the last-yank pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered.

M-y can take a numeric argument, which tells it how many entries to advance the last-yank pointer by. A negative argument moves the pointer toward the front of the ring; from the front of the ring, it moves around to the last entry and continues forward from there.

Once the text you are looking for is brought into the buffer, you can stop doing M-y commands and it will stay there. It’s just a copy of the kill ring entry, so editing it in the buffer does not change what’s in the ring. As long as no new killing is done, the last-yank pointer remains at the same place in the kill ring, so repeating C-y will yank another copy of the same previous kill.

When you call C-y with a numeric argument, that also sets the last-yank pointer to the entry that it yanks.

Previous: , Up: Yanking   [Contents][Index]

12.2.3 Appending Kills

Normally, each kill command pushes a new entry onto the kill ring. However, two or more kill commands in a row combine their text into a single entry, so that a single C-y yanks all the text as a unit, just as it was before it was killed.

Thus, if you want to yank text as a unit, you need not kill all of it with one command; you can keep killing line after line, or word after word, until you have killed it all, and you can still get it all back at once.

Commands that kill forward from point add onto the end of the previous killed text. Commands that kill backward from point add text onto the beginning. This way, any sequence of mixed forward and backward kill commands puts all the killed text into one entry without rearrangement. Numeric arguments do not break the sequence of appending kills. For example, suppose the buffer contains this text:

This is a line ∗of sample text.

with point shown by ∗. If you type M-d M-DEL M-d M-DEL, killing alternately forward and backward, you end up with ‘a line of sample’ as one entry in the kill ring, and ‘This is  text. in the buffer. (Note the double space between ‘is’ and ‘text’, which you can clean up with M-SPC or M-q.)

Another way to kill the same text is to move back two words with M-b M-b, then kill all four words forward with C-u M-d. This produces exactly the same results in the buffer and in the kill ring. M-f M-f C-u M-DEL kills the same text, all going backward; once again, the result is the same. The text in the kill ring entry always has the same order that it had in the buffer before you killed it.

If a kill command is separated from the last kill command by other commands (not just numeric arguments), it starts a new entry on the kill ring. But you can force it to combine with the last killed text, by typing C-M-w (append-next-kill) right beforehand. The C-M-w tells its following command, if it is a kill command, to treat the kill as part of the sequence of previous kills. As usual, the kill is appended to the previous killed text if the command kills forward, and prepended if the command kills backward. In this way, you can kill several separated pieces of text and accumulate them to be yanked back in one place.

A kill command following M-w (kill-ring-save) does not append to the text that M-w copied into the kill ring.

Next: , Previous: , Up: Killing   [Contents][Index]

12.3 “Cut and Paste” Operations on Graphical Displays

In most graphical desktop environments, you can transfer data (usually text) between different applications using a system facility called the clipboard. On X, two other similar facilities are available: the primary selection and the secondary selection. When Emacs is run on a graphical display, its kill and yank commands integrate with these facilities, so that you can easily transfer text between Emacs and other graphical applications.

By default, Emacs uses UTF-8 as the coding system for inter-program text transfers. If you find that the pasted text is not what you expected, you can specify another coding system by typing C-x RET x or C-x RET X. You can also request a different data type by customizing x-select-request-type. See Communication Coding.

12.3.1 Using the Clipboard

The clipboard is the facility that most graphical applications use for “cutting and pasting”. When the clipboard exists, the kill and yank commands in Emacs make use of it.

When you kill some text with a command such as C-w (kill-region), or copy it to the kill ring with a command such as M-w (kill-ring-save), that text is also put in the clipboard.

When an Emacs kill command puts text in the clipboard, the existing clipboard contents are normally lost. Optionally, you can change save-interprogram-paste-before-kill to t. Then Emacs will first save the clipboard to its kill ring, preventing you from losing the old clipboard data—at the risk of high memory consumption if that data turns out to be large.

Yank commands, such as C-y (yank), also use the clipboard. If another application “owns” the clipboard—i.e., if you cut or copied text there more recently than your last kill command in Emacs—then Emacs yanks from the clipboard instead of the kill ring.

Normally, rotating the kill ring with M-y (yank-pop) does not alter the clipboard. However, if you change yank-pop-change-selection to t, then M-y saves the new yank to the clipboard.

To prevent kill and yank commands from accessing the clipboard, change the variable select-enable-clipboard to nil.

Many X desktop environments support a feature called the clipboard manager. If you exit Emacs while it is the current “owner” of the clipboard data, and there is a clipboard manager running, Emacs transfers the clipboard data to the clipboard manager so that it is not lost. In some circumstances, this may cause a delay when exiting Emacs; if you wish to prevent Emacs from transferring data to the clipboard manager, change the variable x-select-enable-clipboard-manager to nil.

Since strings containing NUL bytes are usually truncated when passed through the clipboard, Emacs replaces such characters with “\0” before transferring them to the system’s clipboard.

Prior to Emacs 24, the kill and yank commands used the primary selection (see Primary Selection), not the clipboard. If you prefer this behavior, change select-enable-clipboard to nil, select-enable-primary to t, and mouse-drag-copy-region to t. In this case, you can use the following commands to act explicitly on the clipboard: clipboard-kill-region kills the region and saves it to the clipboard; clipboard-kill-ring-save copies the region to the kill ring and saves it to the clipboard; and clipboard-yank yanks the contents of the clipboard at point.

12.3.2 Cut and Paste with Other Window Applications

Under the X Window System, there exists a primary selection containing the last stretch of text selected in an X application (usually by dragging the mouse). Typically, this text can be inserted into other X applications by mouse-2 clicks. The primary selection is separate from the clipboard. Its contents are more fragile; they are overwritten each time you select text with the mouse, whereas the clipboard is only overwritten by explicit cut or copy commands.

Under X, whenever the region is active (see Mark), the text in the region is saved in the primary selection. This applies regardless of whether the region was made by dragging or clicking the mouse (see Mouse Commands), or by keyboard commands (e.g., by typing C-SPC and moving point; see Setting Mark).

If you change the variable select-active-regions to only, Emacs saves only temporarily active regions to the primary selection, i.e., those made with the mouse or with shift selection (see Shift Selection). If you change select-active-regions to nil, Emacs avoids saving active regions to the primary selection entirely.

To insert the primary selection into an Emacs buffer, click mouse-2 (mouse-yank-primary) where you want to insert it. See Mouse Commands.

MS-Windows provides no primary selection, but Emacs emulates it within a single Emacs session by storing the selected text internally. Therefore, all the features and commands related to the primary selection work on Windows as they do on X, for cutting and pasting within the same session, but not across Emacs sessions or with other applications.

12.3.3 Secondary Selection

In addition to the primary selection, the X Window System provides a second similar facility known as the secondary selection. Nowadays, few X applications make use of the secondary selection, but you can access it using the following Emacs commands:

M-Drag-mouse-1

Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it (mouse-set-secondary). The selected text is highlighted, using the secondary-selection face, as you drag. The window scrolls automatically if you drag the mouse off the top or bottom of the window, just like mouse-set-region (see Mouse Commands).

This command does not alter the kill ring.

M-mouse-1

Set one endpoint for the secondary selection (mouse-start-secondary); use M-mouse-3 to set the other end and complete the selection. This command cancels any existing secondary selection, when it starts a new one.

M-mouse-3

Set the secondary selection (mouse-secondary-save-then-kill), with one end at the position you click M-mouse-3, and the other at the position specified previously with M-mouse-1. This also puts the selected text in the kill ring. A second M-mouse-3 at the same place kills the text selected by the secondary selection just made.

M-mouse-2

Insert the secondary selection where you click, placing point at the end of the yanked text (mouse-yank-secondary).

Double or triple clicking of M-mouse-1 operates on words and lines, much like mouse-1.

If mouse-yank-at-point is non-nil, M-mouse-2 yanks at point. Then it does not matter precisely where you click, or even which of the frame’s windows you click on. See Mouse Commands.

Next: , Previous: , Up: Killing   [Contents][Index]

12.4Accumulating Text

Usually we copy or move text by killing it and yanking it, but there are other convenient methods for copying one block of text in many places, or for copying many scattered blocks of text into one place. Here we describe the commands to accumulate scattered pieces of text into a buffer or into a file.

M-x append-to-buffer

Append region to the contents of a specified buffer.

M-x prepend-to-buffer

Prepend region to the contents of a specified buffer.

M-x copy-to-buffer

Copy region into a specified buffer, deleting that buffer’s old contents.

M-x insert-buffer

Insert the contents of a specified buffer into current buffer at point.

M-x append-to-file

Append region to the contents of a specified file, at the end.

To accumulate text into a buffer, use M-x append-to-buffer. This reads a buffer name, then inserts a copy of the region into the buffer specified. If you specify a nonexistent buffer, append-to-buffer creates the buffer. The text is inserted wherever point is in that buffer. If you have been using the buffer for editing, the copied text goes into the middle of the text of the buffer, starting from wherever point happens to be at that moment.

Point in that buffer is left at the end of the copied text, so successive uses of append-to-buffer accumulate the text in the specified buffer in the same order as they were copied. Strictly speaking, append-to-buffer does not always append to the text already in the buffer—it appends only if point in that buffer is at the end. However, if append-to-buffer is the only command you use to alter a buffer, then point is always at the end.

M-x prepend-to-buffer is just like append-to-buffer except that point in the other buffer is left before the copied text, so successive uses of this command add text in reverse order. M-x copy-to-buffer is similar, except that any existing text in the other buffer is deleted, so the buffer is left containing just the text newly copied into it.

The command M-x insert-buffer can be used to retrieve the accumulated text from another buffer. This prompts for the name of a buffer, and inserts a copy of all the text in that buffer into the current buffer at point, leaving point at the beginning of the inserted text. It also adds the position of the end of the inserted text to the mark ring, without activating the mark. See Buffers, for background information on buffers.

Instead of accumulating text in a buffer, you can append text directly into a file with M-x append-to-file. This prompts for a filename, and adds the text of the region to the end of the specified file. The file is changed immediately on disk.

You should use append-to-file only with files that are not being visited in Emacs. Using it on a file that you are editing in Emacs would change the file behind Emacs’s back, which can lead to losing some of your editing.

Another way to move text around is to store it in a register. See Registers.

Next: , Previous: , Up: Killing   [Contents][Index]

12.5Rectangles

Rectangle commands operate on rectangular areas of the text: all the characters between a certain pair of columns, in a certain range of lines. Emacs has commands to kill rectangles, yank killed rectangles, clear them out, fill them with blanks or text, or delete them. Rectangle commands are useful with text in multicolumn formats, and for changing text into or out of such formats.

To specify a rectangle for a command to work on, set the mark at one corner and point at the opposite corner. The rectangle thus specified is called the region-rectangle. If point and the mark are in the same column, the region-rectangle is empty. If they are in the same line, the region-rectangle is one line high.

The region-rectangle is controlled in much the same way as the region is controlled. But remember that a given combination of point and mark values can be interpreted either as a region or as a rectangle, depending on the command that uses them.

A rectangular region can also be marked using the mouse: click and drag C-M-mouse-1 from one corner of the rectangle to the opposite.

C-x r k

Kill the text of the region-rectangle, saving its contents as the last killed rectangle (kill-rectangle).

C-x r M-w

Save the text of the region-rectangle as the last killed rectangle (copy-rectangle-as-kill).

C-x r d

Delete the text of the region-rectangle (delete-rectangle).

C-x r y

Yank the last killed rectangle with its upper left corner at point (yank-rectangle).

C-x r o

Insert blank space to fill the space of the region-rectangle (open-rectangle). This pushes the previous contents of the region-rectangle to the right.

C-x r N

Insert line numbers along the left edge of the region-rectangle (rectangle-number-lines). This pushes the previous contents of the region-rectangle to the right.

C-x r c

Clear the region-rectangle by replacing all of its contents with spaces (clear-rectangle).

M-x delete-whitespace-rectangle

Delete whitespace in each of the lines on the specified rectangle, starting from the left edge column of the rectangle.

C-x r t string RET

Replace rectangle contents with string on each line (string-rectangle).

M-x string-insert-rectangle RET string RET

Insert string on each line of the rectangle.

C-x SPC

Toggle Rectangle Mark mode (rectangle-mark-mode). When this mode is active, the region-rectangle is highlighted and can be shrunk/grown, and the standard kill and yank commands operate on it.

The rectangle operations fall into two classes: commands to erase or insert rectangles, and commands to make blank rectangles.

There are two ways to erase the text in a rectangle: C-x r d (delete-rectangle) to delete the text outright, or C-x r k (kill-rectangle) to remove the text and save it as the last killed rectangle. In both cases, erasing the region-rectangle is like erasing the specified text on each line of the rectangle; if there is any following text on the line, it moves backwards to fill the gap.

Killing a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that only records the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that different yank commands have to be used. Yank-popping is not defined for rectangles.

C-x r M-w (copy-rectangle-as-kill) is the equivalent of M-w for rectangles: it records the rectangle as the last killed rectangle, without deleting the text from the buffer.

To yank the last killed rectangle, type C-x r y (yank-rectangle). The rectangle’s first line is inserted at point, the rectangle’s second line is inserted at the same horizontal position one line vertically below, and so on. The number of lines affected is determined by the height of the saved rectangle.

For example, you can convert two single-column lists into a double-column list by killing one of the single-column lists as a rectangle, and then yanking it beside the other list.

You can also copy rectangles into and out of registers with C-x r r r and C-x r i r. See Rectangle Registers.

There are two commands you can use for making blank rectangles: C-x r c (clear-rectangle) blanks out existing text in the region-rectangle, and C-x r o (open-rectangle) inserts a blank rectangle.

M-x delete-whitespace-rectangle deletes horizontal whitespace starting from a particular column. This applies to each of the lines in the rectangle, and the column is specified by the left edge of the rectangle. The right edge of the rectangle does not make any difference to this command.

The command C-x r N (rectangle-number-lines) inserts line numbers along the left edge of the region-rectangle. Normally, the numbering begins from 1 (for the first line of the rectangle). With a prefix argument, the command prompts for a number to begin from, and for a format string with which to print the numbers (see Formatting Strings in The Emacs Lisp Reference Manual).

The command C-x r t (string-rectangle) replaces the contents of a region-rectangle with a string on each line. The string’s width need not be the same as the width of the rectangle. If the string’s width is less, the text after the rectangle shifts left; if the string is wider than the rectangle, the text after the rectangle shifts right.

The command M-x string-insert-rectangle is similar to string-rectangle, but inserts the string on each line, shifting the original text to the right.

The command C-x SPC (rectangle-mark-mode) toggles whether the region-rectangle or the standard region is highlighted (first activating the region if necessary). When this mode is enabled, commands that resize the region (C-f, C-n etc.) do so in a rectangular fashion, and killing and yanking operate on the rectangle. See Killing. The mode persists only as long as the region is active.

Unlike the standard region, the region-rectangle can have its corners extended past the end of buffer, or inside stretches of white space that point normally cannot enter, like in the middle of a TAB character.

When the region is in rectangle-mark-mode, C-x C-x runs the command rectangle-exchange-point-and-mark, which cycles between the four corners of the region-rectangle. This comes in handy if you want to modify the dimensions of the region-rectangle before invoking an operation on the marked text.

Previous: , Up: Killing   [Contents][Index]

12.6CUA Bindings

The command M-x cua-mode sets up key bindings that are compatible with the Common User Access (CUA) system used in many other applications.

When CUA mode is enabled, the keys C-x, C-c, C-v, and C-z invoke commands that cut (kill), copy, paste (yank), and undo respectively. The C-x and C-c keys perform cut and copy only if the region is active. Otherwise, they still act as prefix keys, so that standard Emacs commands like C-x C-c still work. Note that this means the variable mark-even-if-inactive has no effect for C-x and C-c (see Using Region).

To enter an Emacs command like C-x C-f while the mark is active, use one of the following methods: either hold Shift together with the prefix key, e.g., S-C-x C-f, or quickly type the prefix key twice, e.g., C-x C-x C-f.

To disable the overriding of standard Emacs binding by CUA mode, while retaining the other features of CUA mode described below, set the variable cua-enable-cua-keys to nil.

CUA mode by default activates Delete-Selection mode (see Mouse Commands) so that typed text replaces the active region. To use CUA without this behavior, set the variable cua-delete-selection to nil.

CUA mode provides enhanced rectangle support with visible rectangle highlighting. Use C-RET to start a rectangle, extend it using the movement commands, and cut or copy it using C-x or C-c. RET moves the cursor to the next (clockwise) corner of the rectangle, so you can easily expand it in any direction. Normal text you type is inserted to the left or right of each line in the rectangle (on the same side as the cursor).

You can use this rectangle support without activating CUA by calling the cua-rectangle-mark-mode command. There’s also the standard command rectangle-mark-mode, see Rectangles.

With CUA you can easily copy text and rectangles into and out of registers by providing a one-digit numeric prefix to the kill, copy, and yank commands, e.g., C-1 C-c copies the region into register 1, and C-2 C-v yanks the contents of register 2.

CUA mode also has a global mark feature which allows easy moving and copying of text between buffers. Use C-S-SPC to toggle the global mark on and off. When the global mark is on, all text that you kill or copy is automatically inserted at the global mark, and text you type is inserted at the global mark rather than at the current position.

For example, to copy words from various buffers into a word list in a given buffer, set the global mark in the target buffer, then navigate to each of the words you want in the list, mark it (e.g., with S-M-f), copy it to the list with C-c or M-w, and insert a newline after the word in the target list by pressing RET.


Next: , Previous: , Up: Top   [Contents][Index]

13Registers

Emacs registers are compartments where you can save text, rectangles, positions, and other things for later use. Once you save text or a rectangle in a register, you can copy it into the buffer once or many times; once you save a position in a register, you can jump back to that position once or many times.

Each register has a name that consists of a single character, which we will denote by r; r can be a letter (such as ‘a’) or a number (such as ‘1’); case matters, so register ‘a’ is not the same as register ‘A’. You can also set a register in non-alphanumeric characters, for instance ‘*’ or ‘C-d’. Note, it’s not possible to set a register in ‘C-g’ or ‘ESC’, because these keys are reserved for quitting (see Quitting).

A register can store a position, a piece of text, a rectangle, a number, a window configuration, or a file name, but only one thing at any given time. Whatever you store in a register remains there until you store something else in that register. To see what register r contains, use M-x view-register:

M-x view-register RET r

Display a description of what register r contains.

All of the commands that prompt for a register will display a preview window that lists the existing registers (if there are any) after a short delay. To change the length of the delay, customize register-preview-delay. To prevent this display, set that option to nil. You can explicitly request a preview window by pressing C-h or F1.

Bookmarks record files and positions in them, so you can return to those positions when you look at the file again. Bookmarks are similar in spirit to registers, so they are also documented in this chapter.

13.1Saving Positions in Registers

C-x r SPC r

Record the position of point and the current buffer in register r (point-to-register).

C-x r j r

Jump to the position and buffer saved in register r (jump-to-register).

Typing C-x r SPC (point-to-register), followed by a character r, saves both the position of point and the current buffer in register r. The register retains this information until you store something else in it.

The command C-x r j r switches to the buffer recorded in register r, pushes a mark, and moves point to the recorded position. (The mark is not pushed if point was already at the recorded position, or in successive calls to the command.) The contents of the register are not changed, so you can jump to the saved position any number of times.

If you use C-x r j to go to a saved position, but the buffer it was saved from has been killed, C-x r j tries to create the buffer again by visiting the same file. Of course, this works only for buffers that were visiting files.

13.2Saving Text in Registers

When you want to insert a copy of the same piece of text several times, it may be inconvenient to yank it from the kill ring, since each subsequent kill moves that entry further down the ring. An alternative is to store the text in a register and later retrieve it.

C-x r s r

Copy region into register r (copy-to-register).

C-x r i r

Insert text from register r (insert-register).

M-x append-to-register RET r

Append region to text in register r.

When register r contains text, you can use C-x r + (increment-register) to append to that register. Note that command C-x r + behaves differently if r contains a number. See Number Registers.

M-x prepend-to-register RET r

Prepend region to text in register r.

C-x r s r stores a copy of the text of the region into the register named r. If the mark is inactive, Emacs first reactivates the mark where it was last set. The mark is deactivated at the end of this command. See Mark. C-u C-x r s r, the same command with a prefix argument, copies the text into register r and deletes the text from the buffer as well; you can think of this as moving the region text into the register.

M-x append-to-register RET r appends the copy of the text in the region to the text already stored in the register named r. If invoked with a prefix argument, it deletes the region after appending it to the register. The command prepend-to-register is similar, except that it prepends the region text to the text in the register instead of appending it.

When you are collecting text using append-to-register and prepend-to-register, you may want to separate individual collected pieces using a separator. In that case, configure a register-separator and store the separator text in to that register. For example, to get double newlines as text separator during the collection process, you can use the following setting.

(setq register-separator ?+)
(set-register register-separator "\n\n")

C-x r i r inserts in the buffer the text from register r. Normally it leaves point after the text and sets the mark before, without activating it. With a prefix argument, it instead puts point before the text and the mark after.

13.3Saving Rectangles in Registers

A register can contain a rectangle instead of linear text. See Rectangles, for basic information on how to specify a rectangle in the buffer.

C-x r r r

Copy the region-rectangle into register r (copy-rectangle-to-register). With prefix argument, delete it as well.

C-x r i r

Insert the rectangle stored in register r (if it contains a rectangle) (insert-register).

The C-x r i r (insert-register) command, previously documented in Text Registers, inserts a rectangle rather than a text string, if the register contains a rectangle.

13.4Saving Window Configurations in Registers

You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later. See Windows, for information about window configurations.

C-x r w r

Save the state of the selected frame’s windows in register r (window-configuration-to-register).

C-x r f r

Save the state of all frames, including all their windows, in register r (frameset-to-register).

Use C-x r j r to restore a window or frame configuration. This is the same command used to restore a cursor position. When you restore a frame configuration, any existing frames not included in the configuration become invisible. If you wish to delete these frames instead, use C-u C-x r j r.

13.5Keeping Numbers in Registers

There are commands to store a number in a register, to insert the number in the buffer in decimal, and to increment it. These commands can be useful in keyboard macros (see Keyboard Macros).

C-u number C-x r n r

Store number into register r (number-to-register).

C-u number C-x r + r

If r contains a number, increment the number in that register by number. Note that command C-x r + (increment-register) behaves differently if r contains text. See Text Registers.

C-x r i r

Insert the number from register r into the buffer.

C-x r i is the same command used to insert any other sort of register contents into the buffer. C-x r + with no numeric argument increments the register value by 1; C-x r n with no numeric argument stores zero in the register.

13.6Keeping File Names in Registers

If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here’s the Lisp code used to put a file name into register r:

(set-register r '(file . name))

例如,

(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))

puts the file name shown in register ‘z’.

To visit the file whose name is in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frame configuration.)

Next: , Previous: , Up: Registers   [Contents][Index]

13.7Keyboard Macro Registers

If you need to execute a keyboard macro (see Keyboard Macros) frequently, it is more convenient to put it in a register or save it (see Save Keyboard Macro). C-x C-k x r (kmacro-to-register) stores the last keyboard macro in register r.

To execute the keyboard macro in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frameset.)

13.8Bookmarks

Bookmarks are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The prototypical use of bookmarks is to record where you were reading in various files.

C-x r m RET

Set the bookmark for the visited file, at point.

C-x r m bookmark RET

Set the bookmark named bookmark at point (bookmark-set).

C-x r M bookmark RET

Like C-x r m, but don’t overwrite an existing bookmark.

C-x r b bookmark RET

Jump to the bookmark named bookmark (bookmark-jump).

C-x r l

List all bookmarks (list-bookmarks).

M-x bookmark-save

Save all the current bookmark values in the default bookmark file.

To record the current position in the visited file, use the command C-x r m, which sets a bookmark using the visited file name as the default for the bookmark name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with C-x r b, and move to the position of the bookmark at the same time.

The command C-x r M (bookmark-set-no-overwrite) works like C-x r m, but it signals an error if the specified bookmark already exists, instead of overwriting it.

To display a list of all your bookmarks in a separate buffer, type C-x r l (list-bookmarks). If you switch to that buffer, you can use it to edit your bookmark definitions or annotate the bookmarks. Type C-h m in the bookmark buffer for more information about its special editing commands.

When you kill Emacs, Emacs saves your bookmarks, if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. Bookmarks are saved to the file ~/.emacs.d/bookmarks (for compatibility with older versions of Emacs, if you have a file named ~/.emacs.bmk, that is used instead). The bookmark commands load your default bookmark file automatically. This saving and loading is how bookmarks persist from one Emacs session to the next.

If you set the variable bookmark-save-flag to 1, each command that sets a bookmark will also save your bookmarks; this way, you don’t lose any bookmark values even if Emacs crashes. The value, if a number, says how many bookmark modifications should go by between saving. If you set this variable to nil, Emacs only saves bookmarks if you explicitly use M-x bookmark-save.

The variable bookmark-default-file specifies the file in which to save bookmarks by default.

If you set the variable bookmark-use-annotations to t, setting a bookmark will query for an annotation. If a bookmark has an annotation, it is automatically shown in a separate window when you jump to the bookmark.

Bookmark position values are saved with surrounding context, so that bookmark-jump can find the proper position even if the file is modified slightly. The variable bookmark-search-size says how many characters of context to record on each side of the bookmark’s position.

Here are some additional commands for working with bookmarks:

M-x bookmark-load RET filename RET

Load a file named filename that contains a list of bookmark values. You can use this command, as well as bookmark-write, to work with other files of bookmark values in addition to your default bookmark file.

M-x bookmark-write RET filename RET

Save all the current bookmark values in the file filename.

M-x bookmark-delete RET bookmark RET

Delete the bookmark named bookmark.

M-x bookmark-insert-location RET bookmark RET

Insert in the buffer the name of the file that bookmark bookmark points to.

M-x bookmark-insert RET bookmark RET

Insert in the buffer the contents of the file that bookmark bookmark points to.

Next: , Previous: , Up: Top   [Contents][Index]

14Controlling the Display

Since only part of a large buffer fits in the window, Emacs has to show only a part of it. This chapter describes commands and variables that let you specify which part of the text you want to see, and how the text is displayed.

Next: , Up: Display   [Contents][Index]

14.1Scrolling

If a window is too small to display all the text in its buffer, it displays only a portion of it. Scrolling commands change which portion of the buffer is displayed.

Scrolling forward or up advances the portion of the buffer displayed in the window; equivalently, it moves the buffer text upwards relative to the window. Scrolling backward or down displays an earlier portion of the buffer, and moves the text downwards relative to the window.

In Emacs, scrolling up or down refers to the direction that the text moves in the window, not the direction that the window moves relative to the text. This terminology was adopted by Emacs before the modern meaning of “scrolling up” and “scrolling down” became widespread. Hence, the strange result that PageDown scrolls up in the Emacs sense.

The portion of a buffer displayed in a window always contains point. If you move point past the bottom or top of the window, scrolling occurs automatically to bring it back onscreen (see Auto Scrolling). You can also scroll explicitly with these commands:

C-v
PageDown
next

Scroll forward by nearly a full window (scroll-up-command).

M-v
PageUp
prior

Scroll backward (scroll-down-command).

C-v (scroll-up-command) scrolls forward by nearly the whole window height. The effect is to take the two lines at the bottom of the window and put them at the top, followed by lines that were not previously visible. If point was in the text that scrolled off the top, it ends up on the window’s new topmost line. The PageDown (or next) key is equivalent to C-v.

M-v (scroll-down-command) scrolls backward in a similar way. The PageUp (or prior) key is equivalent to M-v.

The number of lines of overlap left by these scroll commands is controlled by the variable next-screen-context-lines, whose default value is 2. You can supply the commands with a numeric prefix argument, n, to scroll by n lines; Emacs attempts to leave point unchanged, so that the text and point move up or down together. C-v with a negative argument is like M-v and vice versa.

By default, these commands signal an error (by beeping or flashing the screen) if no more scrolling is possible, because the window has reached the beginning or end of the buffer. If you change the variable scroll-error-top-bottom to t, these commands move point to the farthest possible position. If point is already there, the commands signal an error.

Some users like scroll commands to keep point at the same screen position, so that scrolling back to the same screen conveniently returns point to its original position. You can enable this behavior via the variable scroll-preserve-screen-position. If the value is t, Emacs adjusts point to keep the cursor at the same screen position whenever a scroll command moves it off-window, rather than moving it to the topmost or bottommost line. With any other non-nil value, Emacs adjusts point this way even if the scroll command leaves point in the window. This variable affects all the scroll commands documented in this section, as well as scrolling with the mouse wheel (see Mouse Commands); in general, it affects any command that has a non-nil scroll-command property. See Property Lists in The Emacs Lisp Reference Manual.

Sometimes, particularly when you hold down keys such as C-v and M-v, activating keyboard auto-repeat, Emacs fails to keep up with the rapid rate of scrolling requested; the display doesn’t update and Emacs can become unresponsive to input for quite a long time. You can counter this sluggishness by setting the variable fast-but-imprecise-scrolling to a non-nil value. This instructs the scrolling commands not to fontify (see Font Lock) any unfontified text they scroll over, instead to assume it has the default face. This can cause Emacs to scroll to somewhat wrong buffer positions when the faces in use are not all the same size, even with single (i.e., without auto-repeat) scrolling operations.

As an alternative to setting fast-but-imprecise-scrolling you might prefer to enable jit-lock deferred fontification (see Font Lock). To do this, customize jit-lock-defer-time to a small positive number such as 0.25, or even 0.1 if you type quickly. This gives you less jerky scrolling when you hold down C-v, but the window contents after any action which scrolls into a fresh portion of the buffer will be momentarily unfontified.

The commands M-x scroll-up and M-x scroll-down behave similarly to scroll-up-command and scroll-down-command, except they do not obey scroll-error-top-bottom. Prior to Emacs 24, these were the default commands for scrolling up and down. The commands M-x scroll-up-line and M-x scroll-down-line scroll the current window by one line at a time. If you intend to use any of these commands, you might want to give them key bindings (see Init Rebinding).

Next: , Previous: , Up: Display   [Contents][Index]

14.2Recentering

C-l

Scroll the selected window so the current line is the center-most text line; on subsequent consecutive invocations, make the current line the top line, the bottom line, and so on in cyclic order. Possibly redisplay the screen too (recenter-top-bottom).

M-x recenter

Scroll the selected window so the current line is the center-most text line. Possibly redisplay the screen too.

C-M-l

Scroll heuristically to bring useful information onto the screen (reposition-window).

The C-l (recenter-top-bottom) command recenters the selected window, scrolling it so that the current screen line is exactly in the center of the window, or as close to the center as possible.

Typing C-l twice in a row (C-l C-l) scrolls the window so that point is on the topmost screen line. Typing a third C-l scrolls the window so that point is on the bottom-most screen line. Each successive C-l cycles through these three positions.

You can change the cycling order by customizing the list variable recenter-positions. Each list element should be the symbol top, middle, or bottom, or a number; an integer means to move the line to the specified screen line, while a floating-point number between 0.0 and 1.0 specifies a percentage of the screen space from the top of the window. The default, (middle top bottom), is the cycling order described above. Furthermore, if you change the variable scroll-margin to a non-zero value n, C-l always leaves at least n screen lines between point and the top or bottom of the window (see Auto Scrolling).

You can also give C-l a prefix argument. A plain prefix argument, C-u C-l, simply recenters the line showing point. A positive argument n moves line showing point n lines down from the top of the window. An argument of zero moves point’s line to the top of the window. A negative argument -n moves point’s line n lines from the bottom of the window. When given an argument, C-l does not clear the screen or cycle through different screen positions.

If the variable recenter-redisplay has a non-nil value, each invocation of C-l also clears and redisplays the screen; the special value tty (the default) says to do this on text-terminal frames only. Redisplaying is useful in case the screen becomes garbled for any reason (see Screen Garbled).

The more primitive command M-x recenter behaves like recenter-top-bottom, but does not cycle among screen positions.

C-M-l (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.

Next: , Previous: , Up: Display   [Contents][Index]

14.3Automatic Scrolling

Emacs performs automatic scrolling when point moves out of the visible portion of the text. Normally, automatic scrolling centers point vertically in the window, but there are several ways to alter this behavior.

If you set scroll-conservatively to a small number n, then moving point just a little off the screen (no more than n lines) causes Emacs to scroll just enough to bring point back on screen; if doing so fails to make point visible, Emacs scrolls just far enough to center point in the window. If you set scroll-conservatively to a large number (larger than 100), automatic scrolling never centers point, no matter how far point moves; Emacs always scrolls text just enough to bring point into view, either at the top or bottom of the window depending on the scroll direction. By default, scroll-conservatively is 0, which means to always center point in the window.

Another way to control automatic scrolling is to customize the variable scroll-step. Its value determines the number of lines by which to automatically scroll, when point moves off the screen. If scrolling by that number of lines fails to bring point back into view, point is centered instead. The default value is zero, which (by default) causes point to always be centered after scrolling.

A third way to control automatic scrolling is to customize the variables scroll-up-aggressively and scroll-down-aggressively, which directly specify the vertical position of point after scrolling. The value of scroll-up-aggressively should be either nil (the default), or a floating point number f between 0 and 1. The latter means that when point goes below the bottom window edge (i.e., scrolling forward), Emacs scrolls the window so that point is f parts of the window height from the bottom window edge. Thus, larger f means more aggressive scrolling: more new text is brought into view. The default value, nil, is equivalent to 0.5.

Likewise, scroll-down-aggressively is used when point goes above the top window edge (i.e., scrolling backward). The value specifies how far point should be from the top margin of the window after scrolling. Thus, as with scroll-up-aggressively, a larger value is more aggressive.

Note that the variables scroll-conservatively, scroll-step, and scroll-up-aggressively / scroll-down-aggressively control automatic scrolling in contradictory ways. Therefore, you should pick no more than one of these methods to customize automatic scrolling. In case you customize multiple variables, the order of priority is: scroll-conservatively, then scroll-step, and finally scroll-up-aggressively / scroll-down-aggressively.

The variable scroll-margin restricts how close point can come to the top or bottom of a window (even if aggressive scrolling specifies a fraction f that is larger than the window portion between the top and the bottom margins). Its value is a number of screen lines; if point comes within that many lines of the top or bottom of the window, Emacs performs automatic scrolling. By default, scroll-margin is 0. The effective margin size is limited to a quarter of the window height by default, but this limit can be increased up to half (or decreased down to zero) by customizing maximum-scroll-margin.

Next: , Previous: , Up: Display   [Contents][Index]

14.4Horizontal Scrolling

Horizontal scrolling means shifting all the lines sideways within a window, so that some of the text near the left margin is not displayed. When the text in a window is scrolled horizontally, text lines are truncated rather than continued (see Line Truncation). If a window shows truncated lines, Emacs performs automatic horizontal scrolling whenever point moves off the left or right edge of the screen. By default, all the lines in the window are scrolled horizontally together, but if you set the variable auto-hscroll-mode to the special value of current-line, only the line showing the cursor will be scrolled. To disable automatic horizontal scrolling entirely, set the variable auto-hscroll-mode to nil. Note that when the automatic horizontal scrolling is turned off, if point moves off the edge of the screen, the cursor disappears to indicate that. (On text terminals, the cursor is left at the edge instead.)

The variable hscroll-margin controls how close point can get to the window’s left and right edges before automatic scrolling occurs. It is measured in columns. For example, if the value is 5, then moving point within 5 columns of an edge causes horizontal scrolling away from that edge.

The variable hscroll-step determines how many columns to scroll the window when point gets too close to the edge. Zero, the default value, means to center point horizontally within the window. A positive integer value specifies the number of columns to scroll by. A floating-point number (whose value should be between 0 and 1) specifies the fraction of the window’s width to scroll by.

You can also perform explicit horizontal scrolling with the following commands:

C-x <

Scroll text in current window to the left (scroll-left).

C-x >

Scroll to the right (scroll-right).

C-x < (scroll-left) scrolls text in the selected window to the left by the full width of the window, less two columns. (In other words, the text in the window moves left relative to the window.) With a numeric argument n, it scrolls by n columns.

If the text is scrolled to the left, and point moves off the left edge of the window, the cursor will freeze at the left edge of the window, until point moves back to the displayed portion of the text. This is independent of the current setting of auto-hscroll-mode, which, for text scrolled to the left, only affects the behavior at the right edge of the window.

C-x > (scroll-right) scrolls similarly to the right. The window cannot be scrolled any farther to the right once it is displayed normally, with each line starting at the window’s left margin; attempting to do so has no effect. This means that you don’t have to calculate the argument precisely for C-x >; any sufficiently large argument will restore the normal display.

If you use those commands to scroll a window horizontally, that sets a lower bound for automatic horizontal scrolling. Automatic scrolling will continue to scroll the window, but never farther to the right than the amount you previously set by scroll-left. When auto-hscroll-mode is set to current-line, all the lines other than the one showing the cursor will be scrolled by that minimal amount.

Next: , Previous: , Up: Display   [Contents][Index]

14.5 Narrowing

Narrowing means focusing in on some portion of the buffer, making the rest temporarily inaccessible. The portion which you can still get to is called the accessible portion. Canceling the narrowing, which makes the entire buffer once again accessible, is called widening. The bounds of narrowing in effect in a buffer are called the buffer’s restriction.

Narrowing can make it easier to concentrate on a single subroutine or paragraph by eliminating clutter. It can also be used to limit the range of operation of a replace command or repeating keyboard macro.

C-x n n

Narrow down to between point and mark (narrow-to-region).

C-x n w

Widen to make the entire buffer accessible again (widen).

C-x n p

Narrow down to the current page (narrow-to-page).

C-x n d

Narrow down to the current defun (narrow-to-defun).

When you have narrowed down to a part of the buffer, that part appears to be all there is. You can’t see the rest, you can’t move into it (motion commands won’t go outside the accessible part), you can’t change it in any way. However, it is not gone, and if you save the file all the inaccessible text will be saved. The word ‘Narrow’ appears in the mode line whenever narrowing is in effect.

The primary narrowing command is C-x n n (narrow-to-region). It sets the current buffer’s restrictions so that the text in the current region remains accessible, but all text before the region or after the region is inaccessible. Point and mark do not change.

Alternatively, use C-x n p (narrow-to-page) to narrow down to the current page. See Pages, for the definition of a page. C-x n d (narrow-to-defun) narrows down to the defun containing point (see Defuns).

The way to cancel narrowing is to widen with C-x n w (widen). This makes all text in the buffer accessible again.

You can get information on what part of the buffer you are narrowed down to using the C-x = command. See Position Info.

Because narrowing can easily confuse users who do not understand it, narrow-to-region is normally a disabled command. Attempting to use this command asks for confirmation and gives you the option of enabling it; if you enable the command, confirmation will no longer be required for it. See Disabling.

Next: , Previous: , Up: Display   [Contents][Index]

14.6 View Mode

View mode is a minor mode that lets you scan a buffer by sequential screenfuls. It provides commands for scrolling through the buffer conveniently but not for changing it. Apart from the usual Emacs cursor motion commands, you can type SPC to scroll forward one windowful, S-SPC or DEL to scroll backward, and s to start an incremental search.

Typing q (View-quit) disables View mode, and switches back to the buffer and position before View mode was enabled. Typing e (View-exit) disables View mode, keeping the current buffer and position.

M-x view-buffer prompts for an existing Emacs buffer, switches to it, and enables View mode. M-x view-file prompts for a file and visits it with View mode enabled.

Next: , Previous: , Up: Display   [Contents][Index]

14.7 Follow Mode

Follow mode is a minor mode that makes two windows, both showing the same buffer, scroll as a single tall virtual window. To use Follow mode, go to a frame with just one window, split it into two side-by-side windows using C-x 3, and then type M-x follow-mode. From then on, you can edit the buffer in either of the two windows, or scroll either one; the other window follows it.

In Follow mode, if you move point outside the portion visible in one window and into the portion visible in the other window, that selects the other window—again, treating the two as if they were parts of one large window.

To turn off Follow mode, type M-x follow-mode a second time.

Next: , Previous: , Up: Display   [Contents][Index]

14.8 Text Faces

Emacs can display text in several different styles, called faces. Each face can specify various face attributes, such as the font, height, weight, slant, foreground and background color, and underlining or overlining. Most major modes assign faces to the text automatically, via Font Lock mode. See Font Lock, for more information about how these faces are assigned.

To see what faces are currently defined, and what they look like, type M-x list-faces-display. With a prefix argument, this prompts for a regular expression, and displays only faces with names matching that regular expression (see Regexps).

It’s possible for a given face to look different in different frames. For instance, some text terminals do not support all face attributes, particularly font, height, and width, and some support a limited range of colors. In addition, most Emacs faces are defined so that their attributes are different on light and dark frame backgrounds, for reasons of legibility. By default, Emacs automatically chooses which set of face attributes to display on each frame, based on the frame’s current background color. However, you can override this by giving the variable frame-background-mode a non-nil value. A value of dark makes Emacs treat all frames as if they have a dark background, whereas a value of light makes it treat all frames as if they have a light background.

You can customize a face to alter its attributes, and save those customizations for future Emacs sessions. See Face Customization, for details.

The default face is the default for displaying text, and all of its attributes are specified. Its background color is also used as the frame’s background color. See Colors.

Another special face is the cursor face. On graphical displays, the background color of this face is used to draw the text cursor. None of the other attributes of this face have any effect; the foreground color for text under the cursor is taken from the background color of the underlying text. On text terminals, the appearance of the text cursor is determined by the terminal, not by the cursor face.

You can also use X resources to specify attributes of any particular face. See Resources.

Emacs can display variable-width fonts, but some Emacs commands, particularly indentation commands, do not account for variable character display widths. Therefore, we recommend not using variable-width fonts for most faces, particularly those assigned by Font Lock mode.

Next: , Previous: , Up: Display   [Contents][Index]

14.9 Colors for Faces

Faces can have various foreground and background colors. When you specify a color for a face—for instance, when customizing the face (see Face Customization)—you can use either a color name or an RGB triplet.

14.9.1 Color Names

A color name is a pre-defined name, such as ‘dark orange’ or ‘medium sea green’. To view a list of color names, type M-x list-colors-display. To control the order in which colors are shown, customize list-colors-sort. If you run this command on a graphical display, it shows the full range of color names known to Emacs (these are the standard X11 color names, defined in X’s rgb.txt file). If you run the command on a text terminal, it shows only a small subset of colors that can be safely displayed on such terminals. However, Emacs understands X11 color names even on text terminals; if a face is given a color specified by an X11 color name, it is displayed using the closest-matching terminal color.

14.9.2 RGB Triplets

An RGB triplet is a string of the form ‘#RRGGBB’. Each of the primary color components is represented by a hexadecimal number between ‘00’ (intensity 0) and ‘FF’ (the maximum intensity). It is also possible to use one, three, or four hex digits for each component, so ‘red’ can be represented as ‘#F00’, ‘#fff000000’, or ‘#ffff00000000’. The components must have the same number of digits. For hexadecimal values A to F, either upper or lower case are acceptable.

The M-x list-colors-display command also shows the equivalent RGB triplet for each named color. For instance, ‘medium sea green’ is equivalent to ‘#3CB371’.

You can change the foreground and background colors of a face with M-x set-face-foreground and M-x set-face-background. These commands prompt in the minibuffer for a face name and a color, with completion, and then set that face to use the specified color. They affect the face colors on all frames, but their effects do not persist for future Emacs sessions, unlike using the customization buffer or X resources. You can also use frame parameters to set foreground and background colors for a specific frame; See Frame Parameters.

Next: , Previous: , Up: Display   [Contents][Index]

14.10 Standard Faces

Here are the standard faces for specifying text appearance. You can apply them to specific text when you want the effects they produce.

default

This face is used for ordinary text that doesn’t specify any face. Its background color is used as the frame’s background color.

bold

This face uses a bold variant of the default font.

italic

This face uses an italic variant of the default font.

bold-italic

This face uses a bold italic variant of the default font.

underline

This face underlines text.

fixed-pitch

This face forces use of a fixed-width font. It’s reasonable to customize this face to use a different fixed-width font, if you like, but you should not make it a variable-width font.

fixed-pitch-serif

This face is like fixed-pitch, except the font has serifs and looks more like traditional typewriting.

variable-pitch

This face forces use of a variable-width font.

shadow

This face is used for making the text less noticeable than the surrounding ordinary text. Usually this can be achieved by using shades of gray in contrast with either black or white default foreground color.

Here’s an incomplete list of faces used to highlight parts of the text temporarily for specific purposes. (Many other modes define their own faces for this purpose.)

highlight

This face is used for text highlighting in various contexts, such as when the mouse cursor is moved over a hyperlink.

isearch

This face is used to highlight the current Isearch match (see Incremental Search).

query-replace

This face is used to highlight the current Query Replace match (see Replace).

lazy-highlight

This face is used to highlight lazy matches for Isearch and Query Replace (matches other than the current one).

region

This face is used for displaying an active region (see Mark). When Emacs is built with GTK+ support, its colors are taken from the current GTK+ theme.

secondary-selection

This face is used for displaying a secondary X selection (see Secondary Selection).

trailing-whitespace

The face for highlighting excess spaces and tabs at the end of a line when show-trailing-whitespace is non-nil (see Useless Whitespace).

escape-glyph

The face for displaying control characters and escape sequences (see Text Display).

homoglyph

The face for displaying lookalike characters, i.e., characters that look like but are not the characters being represented (see Text Display).

nobreak-space

The face for displaying no-break space characters (see Text Display).

nobreak-hyphen

The face for displaying no-break hyphen characters (see Text Display).

The following faces control the appearance of parts of the Emacs frame:

mode-line

This face is used for the mode line of the currently selected window, and for menu bars when toolkit menus are not used. By default, it’s drawn with shadows for a raised effect on graphical displays, and drawn as the inverse of the default face on non-windowed terminals.

mode-line-inactive

Like mode-line, but used for mode lines of the windows other than the selected one (if mode-line-in-non-selected-windows is non-nil). This face inherits from mode-line, so changes in that face affect mode lines in all windows.

mode-line-highlight

Like highlight, but used for mouse-sensitive portions of text on mode lines. Such portions of text typically pop up tooltips (see Tooltips) when the mouse pointer hovers above them.

mode-line-buffer-id

This face is used for buffer identification parts in the mode line.

header-line

Similar to mode-line for a window’s header line, which appears at the top of a window just as the mode line appears at the bottom. Most windows do not have a header line—only some special modes, such Info mode, create one.

header-line-highlight

Similar to highlight and mode-line-highlight, but used for mouse-sensitive portions of text on header lines. This is a separate face because the header-line face might be customized in a way that does not interact well with highlight.

tab-line

Similar to mode-line for a window’s tab line, which appears at the top of a window with tabs representing window buffers. See Tab Line.

vertical-border

This face is used for the vertical divider between windows on text terminals.

minibuffer-prompt

This face is used for the prompt strings displayed in the minibuffer. By default, Emacs automatically adds this face to the value of minibuffer-prompt-properties, which is a list of text properties (see Text Properties in the Emacs Lisp Reference Manual) used to display the prompt text. (This variable takes effect when you enter the minibuffer.)

fringe

The face for the fringes to the left and right of windows on graphic displays. (The fringes are the narrow portions of the Emacs frame between the text area and the window’s right and left borders.) See Fringes.

cursor

The :background attribute of this face specifies the color of the text cursor. See Cursor Display.

tooltip

This face is used for tooltip text. By default, if Emacs is built with GTK+ support, tooltips are drawn via GTK+ and this face has no effect. See Tooltips.

mouse

This face determines the color of the mouse pointer.

The following faces likewise control the appearance of parts of the Emacs frame, but only on text terminals, or when Emacs is built on X with no toolkit support. (For all other cases, the appearance of the respective frame elements is determined by system-wide settings.)

scroll-bar

This face determines the visual appearance of the scroll bar. See Scroll Bars.

tool-bar

This face determines the color of tool bar icons. See Tool Bars.

tab-bar

This face determines the color of tab bar icons. See Tab Bars.

menu

This face determines the colors and font of Emacs’s menus. See Menu Bars.

tty-menu-enabled-face

This face is used to display enabled menu items on text-mode terminals.

tty-menu-disabled-face

This face is used to display disabled menu items on text-mode terminals.

tty-menu-selected-face

This face is used to display on text-mode terminals the menu item that would be selected if you click a mouse or press RET.

Next: , Previous: , Up: Display   [Contents][Index]

14.11 Text Scale

To increase the height of the default face in the current buffer, type C-x C-+ or C-x C-=. To decrease it, type C-x C--. To restore the default (global) face height, type C-x C-0. These keys are all bound to the same command, text-scale-adjust, which looks at the last key typed to determine which action to take.

Similarly, scrolling the mouse wheel with the Ctrl modifier pressed, when the mouse pointer is above buffer text, will increase or decrease the height of the default face, depending on the direction of the scrolling.

The final key of these commands may be repeated without the leading C-x. For instance, C-x C-= C-= C-= increases the face height by three steps. Each step scales the text height by a factor of 1.2; to change this factor, customize the variable text-scale-mode-step. A numeric argument of 0 to the text-scale-adjust command restores the default height, the same as typing C-x C-0.

The commands text-scale-increase and text-scale-decrease increase or decrease the height of the default face, just like C-x C-+ and C-x C-- respectively. You may find it convenient to bind to these commands, rather than text-scale-adjust.

The command text-scale-set scales the height of the default face in the current buffer to an absolute level specified by its prefix argument.

The above commands automatically enable the minor mode text-scale-mode if the current font scaling is other than 1, and disable it otherwise.

14.12 Font Lock mode

Font Lock mode is a minor mode, always local to a particular buffer, which assigns faces to (or fontifies) the text in the buffer. Each buffer’s major mode tells Font Lock mode which text to fontify; for instance, programming language modes fontify syntactically relevant constructs like comments, strings, and function names.

Font Lock mode is enabled by default in major modes that support it. To toggle it in the current buffer, type M-x font-lock-mode. A positive numeric argument unconditionally enables Font Lock mode, and a negative or zero argument disables it.

Type M-x global-font-lock-mode to toggle Font Lock mode in all buffers. To impose this setting for future Emacs sessions, customize the variable global-font-lock-mode (see Easy Customization), or add the following line to your init file:

(global-font-lock-mode 0)

If you have disabled Global Font Lock mode, you can still enable Font Lock for specific major modes by adding the function font-lock-mode to the mode hooks (see Hooks). For example, to enable Font Lock mode for editing C files, you can do this:

(add-hook 'c-mode-hook 'font-lock-mode)

Font Lock mode uses several specifically named faces to do its job, including font-lock-string-face, font-lock-comment-face, and others. The easiest way to find them all is to use M-x customize-group RET font-lock-faces RET. You can then use that customization buffer to customize the appearance of these faces. See Face Customization.

You can customize the variable font-lock-maximum-decoration to alter the amount of fontification applied by Font Lock mode, for major modes that support this feature. The value should be a number (with 1 representing a minimal amount of fontification; some modes support levels as high as 3); or t, meaning “as high as possible” (the default). To be effective for a given file buffer, the customization of font-lock-maximum-decoration should be done before the file is visited; if you already have the file visited in a buffer when you customize this variable, kill the buffer and visit the file again after the customization.

You can also specify different numbers for particular major modes; for example, to use level 1 for C/C++ modes, and the default level otherwise, use the value

'((c-mode . 1) (c++-mode . 1)))

Comment and string fontification (or “syntactic” fontification) relies on analysis of the syntactic structure of the buffer text. For the sake of speed, some modes, including Lisp mode, rely on a special convention: an open-parenthesis or open-brace in the leftmost column always defines the beginning of a defun, and is thus always outside any string or comment. Therefore, you should avoid placing an open-parenthesis or open-brace in the leftmost column, if it is inside a string or comment. See Left Margin Paren, for details.

Font Lock highlighting patterns already exist for most modes, but you may want to fontify additional patterns. You can use the function font-lock-add-keywords, to add your own highlighting patterns for a particular mode. For example, to highlight ‘FIXME:’ words in C comments, use this:

(add-hook 'c-mode-hook
          (lambda ()
           (font-lock-add-keywords nil
            '(("\\<\\(FIXME\\):" 1
               font-lock-warning-face t)))))

To remove keywords from the font-lock highlighting patterns, use the function font-lock-remove-keywords. See Search-based Fontification in The Emacs Lisp Reference Manual.

Fontifying large buffers can take a long time. To avoid large delays when a file is visited, Emacs initially fontifies only the visible portion of a buffer. As you scroll through the buffer, each portion that becomes visible is fontified as soon as it is displayed; this type of Font Lock is called Just-In-Time (or JIT) Lock. You can control how JIT Lock behaves, including telling it to perform fontification while idle, by customizing variables in the customization group ‘jit-lock’. See Specific Customization.

Next: , Previous: , Up: Display   [Contents][Index]

14.13 Interactive Highlighting

Highlight Changes mode is a minor mode that highlights the parts of the buffer that were changed most recently, by giving that text a different face. To enable or disable Highlight Changes mode, use M-x highlight-changes-mode.

Hi Lock mode is a minor mode that highlights text that matches regular expressions you specify. For example, you can use it to highlight all the references to a certain variable in a program source file, highlight certain parts in a voluminous output of some program, or highlight certain names in an article. To enable or disable Hi Lock mode, use the command M-x hi-lock-mode. To enable Hi Lock mode for all buffers, use M-x global-hi-lock-mode or place (global-hi-lock-mode 1) in your .emacs file.

Hi Lock mode works like Font Lock mode (see Font Lock), except that you specify explicitly the regular expressions to highlight. You can control them with the following commands. (The key bindings below that begin with C-x w are deprecated in favor of the global M-s h bindings, and will be removed in some future Emacs version.)

M-s h r regexp RET face RET
C-x w h regexp RET face RET

Highlight text that matches regexp using face face (highlight-regexp). The highlighting will remain as long as the buffer is loaded. For example, to highlight all occurrences of the word “whim” using the default face (a yellow background), type M-s h r whim RET RET. Any face can be used for highlighting, Hi Lock provides several of its own and these are pre-loaded into a list of default values. While being prompted for a face use M-n and M-p to cycle through them. A prefix numeric argument limits the highlighting to the corresponding subexpression.

Setting the option hi-lock-auto-select-face to a non-nil value causes this command (and other Hi Lock commands that read faces) to automatically choose the next face from the default list without prompting.

You can use this command multiple times, specifying various regular expressions to highlight in different ways.

M-s h u regexp RET
C-x w r regexp RET

Unhighlight regexp (unhighlight-regexp). If you invoke this from the menu, you select the expression to unhighlight from a list. If you invoke this from the keyboard, you use the minibuffer. It will show the most recently added regular expression; use M-n to show the next older expression and M-p to select the next newer expression. (You can also type the expression by hand, with completion.) When the expression you want to unhighlight appears in the minibuffer, press RET to exit the minibuffer and unhighlight it.

M-s h l regexp RET face RET
C-x w l regexp RET face RET

Highlight entire lines containing a match for regexp, using face face (highlight-lines-matching-regexp).

M-s h p phrase RET face RET
C-x w p phrase RET face RET

Highlight matches of phrase, using face face (highlight-phrase). phrase can be any regexp, but spaces will be replaced by matches to whitespace and initial lower-case letters will become case insensitive.

M-s h .
C-x w .

Highlight the symbol found near point, using the next available face (highlight-symbol-at-point).

M-s h w
C-x w b

Insert all the current highlighting regexp/face pairs into the buffer at point, with comment delimiters to prevent them from changing your program. (This key binding runs the hi-lock-write-interactive-patterns command.)

These patterns are extracted from the comments, if appropriate, if you invoke M-x hi-lock-find-patterns, or if you visit the file while Hi Lock mode is enabled (since that runs hi-lock-find-patterns).

M-s h f
C-x w i

Extract regexp/face pairs from comments in the current buffer (hi-lock-find-patterns). Thus, you can enter patterns interactively with highlight-regexp, store them into the file with hi-lock-write-interactive-patterns, edit them (perhaps including different faces for different parenthesized parts of the match), and finally use this command (hi-lock-find-patterns) to have Hi Lock highlight the edited patterns.

The variable hi-lock-file-patterns-policy controls whether Hi Lock mode should automatically extract and highlight patterns found in a file when it is visited. Its value can be nil (never highlight), ask (query the user), or a function. If it is a function, hi-lock-find-patterns calls it with the patterns as argument; if the function returns non-nil, the patterns are used. The default is ask. Note that patterns are always highlighted if you call hi-lock-find-patterns directly, regardless of the value of this variable.

Also, hi-lock-find-patterns does nothing if the current major mode’s symbol is a member of the list hi-lock-exclude-modes.

14.14 Window Fringes

On graphical displays, each Emacs window normally has narrow fringes on the left and right edges. The fringes are used to display symbols that provide information about the text in the window. You can type M-x fringe-mode to toggle display of the fringes or to modify their width. This command affects fringes in all frames; to modify fringes on the selected frame only, use M-x set-fringe-style. You can make your changes to the fringes permanent by customizing the variable fringe-mode.

The most common use of the fringes is to indicate a continuation line (see Continuation Lines). When one line of text is split into multiple screen lines, the left fringe shows a curving arrow for each screen line except the first, indicating that this is not the real beginning. The right fringe shows a curving arrow for each screen line except the last, indicating that this is not the real end. If the line’s direction is right-to-left (see Bidirectional Editing), the meanings of the curving arrows in the fringes are swapped.

The fringes indicate line truncation (see Line Truncation) with short horizontal arrows meaning there’s more text on this line which is scrolled horizontally out of view. Clicking the mouse on one of the arrows scrolls the display horizontally in the direction of the arrow.

The fringes can also indicate other things, such as buffer boundaries (see Displaying Boundaries), unused lines near the end of the window (see indicate-empty-lines), and where a program you are debugging is executing (see Debuggers).

The fringe is also used for drawing the cursor, if the current line is exactly as wide as the window and point is at the end of the line. To disable this, change the variable overflow-newline-into-fringe to nil; this causes Emacs to continue or truncate lines that are exactly as wide as the window.

If you customize fringe-mode to remove the fringes on one or both sides of the window display, the features that display on the fringe are not available. Indicators of line continuation and truncation are an exception: when fringes are not available, Emacs uses the leftmost and rightmost character cells to indicate continuation and truncation with special ASCII characters, see Continuation Lines, and Line Truncation. This reduces the width available for displaying text on each line, because the character cells used for truncation and continuation indicators are reserved for that purpose. Since buffer text can include bidirectional text, and thus both left-to-right and right-to-left paragraphs (see Bidirectional Editing), removing only one of the fringes still reserves two character cells, one on each side of the window, for truncation and continuation indicators, because these indicators are displayed on opposite sides of the window in right-to-left paragraphs.

Next: , Previous: , Up: Display   [Contents][Index]

14.15 Displaying Boundaries

Emacs can add an indicator to display a fill column position. The fill column indicator is a useful functionality especially in prog-mode to indicate the position of a specific column.

You can set the buffer-local variables display-fill-column-indicator and display-fill-column-indicator-character to activate the indicator and control how it looks, respectively.

Alternatively you can type M-x display-fill-column-indicator-mode or M-x global-display-fill-column-indicator-mode which enables the indicator locally or globally, respectively, and also chooses the character to use if none is already set. It is possible to use the first one to activate the indicator in a hook and the second one to enable it globally.

There are 2 buffer local variables and 1 face to customize this mode:

display-fill-column-indicator-column

Specifies the column number where the indicator should be set. It can take positive numerical values for the column or the special value t which means that the variable fill-column will be used.

Any other value disables the indicator. The default value is t.

display-fill-column-indicator-character

Specifies the character used for the indicator. This character can be any valid character including Unicode ones if the font supports them.

When the mode is enabled through the functions display-fill-column-indicator-mode or global-display-fill-column-indicator-mode, the initialization functions check if this variable is non-nil, otherwise the initialization tries to set it to U+2502 or ‘|’.

fill-column-indicator

Specifies the face used to display the indicator. It inherits its default values from the face shadow but without background color. To change the indicator color you need only set the foreground color of this face.

On graphical displays, Emacs can indicate the buffer boundaries in the fringes. If you enable this feature, the first line and the last line are marked with angle images in the fringes. This can be combined with up and down arrow images which say whether it is possible to scroll the window.

The buffer-local variable indicate-buffer-boundaries controls how the buffer boundaries and window scrolling is indicated in the fringes. If the value is left or right, both angle and arrow bitmaps are displayed in the left or right fringe, respectively.

If value is an alist (see Association Lists in the Emacs Lisp Reference Manual), each element (indicator . position) specifies the position of one of the indicators. The indicator must be one of top, bottom, up, down, or t which specifies the default position for the indicators not present in the alist. The position is one of left, right, or nil which specifies not to show this indicator.

For example, ((top . left) (t . right)) places the top angle bitmap in left fringe, the bottom angle bitmap in right fringe, and both arrow bitmaps in right fringe. To show just the angle bitmaps in the left fringe, but no arrow bitmaps, use ((top . left) (bottom . left)).

14.16 Useless Whitespace

It is easy to leave unnecessary spaces at the end of a line, or empty lines at the end of a buffer, without realizing it. In most cases, this trailing whitespace has no effect, but sometimes it can be a nuisance.

You can make trailing whitespace at the end of a line visible by setting the buffer-local variable show-trailing-whitespace to t. Then Emacs displays trailing whitespace, using the face trailing-whitespace.

This feature does not apply when point is at the end of the line containing the whitespace. Strictly speaking, that is trailing whitespace nonetheless, but displaying it specially in that case looks ugly while you are typing in new text. In this special case, the location of point is enough to show you that the spaces are present.

Type M-x delete-trailing-whitespace to delete all trailing whitespace. This command deletes all extra spaces at the end of each line in the buffer, and all empty lines at the end of the buffer; to ignore the latter, change the variable delete-trailing-lines to nil. If the region is active, the command instead deletes extra spaces at the end of each line in the region.

On graphical displays, Emacs can indicate unused lines at the end of the window with a small image in the left fringe (see Fringes). The image appears for screen lines that do not correspond to any buffer text, so blank lines at the end of the buffer stand out because they lack this image. To enable this feature, set the buffer-local variable indicate-empty-lines to a non-nil value. You can enable or disable this feature for all new buffers by setting the default value of this variable, e.g., (setq-default indicate-empty-lines t).

Whitespace mode is a buffer-local minor mode that lets you visualize many kinds of whitespace in the buffer, by either drawing the whitespace characters with a special face or displaying them as special glyphs. To toggle this mode, type M-x whitespace-mode. The kinds of whitespace visualized are determined by the list variable whitespace-style. Individual elements in that list can be toggled on or off in the current buffer by typing M-x whitespace-toggle-options. Here is a partial list of possible elements (see the variable’s documentation for the full list):

face

Enable all visualizations which use special faces. This element has a special meaning: if it is absent from the list, none of the other visualizations take effect except space-mark, tab-mark, and newline-mark.

trailing

Highlight trailing whitespace.

tabs

Highlight tab characters.

spaces

Highlight space and non-breaking space characters.

lines

Highlight lines longer than 80 columns. To change the column limit, customize the variable whitespace-line-column.

newline

Highlight newlines.

empty

Highlight empty lines at the beginning and/or end of the buffer.

big-indent

Highlight too-deep indentation. By default any sequence of at least 4 consecutive tab characters or 32 consecutive space characters is highlighted. To change that, customize the regular expression whitespace-big-indent-regexp.

space-mark

Draw space and non-breaking characters with a special glyph.

tab-mark

Draw tab characters with a special glyph.

newline-mark

Draw newline characters with a special glyph.

Global Whitespace mode is a global minor mode that lets you visualize whitespace in all buffers. To toggle individual features, use M-x global-whitespace-toggle-options.

14.17 Selective Display

Emacs has the ability to hide lines indented more than a given number of columns. You can use this to get an overview of a part of a program.

To hide lines in the current buffer, type C-x $ (set-selective-display) with a numeric argument n. Then lines with at least n columns of indentation disappear from the screen. The only indication of their presence is that three dots (‘’) appear at the end of each visible line that is followed by one or more hidden ones.

The commands C-n and C-p move across the hidden lines as if they were not there.

The hidden lines are still present in the buffer, and most editing commands see them as usual, so you may find point in the middle of the hidden text. When this happens, the cursor appears at the end of the previous line, after the three dots. If point is at the end of the visible line, before the newline that ends it, the cursor appears before the three dots.

To make all lines visible again, type C-x $ with no argument.

If you set the variable selective-display-ellipses to nil, the three dots do not appear at the end of a line that precedes hidden lines. Then there is no visible indication of the hidden lines. This variable becomes local automatically when set.

See also Outline Mode for another way to hide part of the text in a buffer.

Next: , Previous: , Up: Display   [Contents][Index]

14.18 Optional Mode Line Features

The buffer percentage pos indicates the percentage of the buffer above the top of the window. You can additionally display the size of the buffer by typing M-x size-indication-mode to turn on Size Indication mode. The size will be displayed immediately following the buffer percentage like this:

pos of size

Here size is the human readable representation of the number of characters in the buffer, which means that ‘k’ for 10^3, ‘M’ for 10^6, ‘G’ for 10^9, etc., are used to abbreviate.

The current line number of point appears in the mode line when Line Number mode is enabled. Use the command M-x line-number-mode to turn this mode on and off; normally it is on. The line number appears after the buffer percentage pos, with the letter ‘L’ to indicate what it is.

Similarly, you can display the current column number by turning on Column Number mode with M-x column-number-mode. The column number is indicated by the letter ‘C’. However, when both of these modes are enabled, the line and column numbers are displayed in parentheses, the line number first, rather than with ‘L’ and ‘C’. For example: ‘(561,2)’. See Minor Modes, for more information about minor modes and about how to use these commands.

In Column Number mode, the displayed column number counts from zero starting at the left margin of the window. If you would prefer for the displayed column number to count from one, you may set column-number-indicator-zero-based to nil.

If you have narrowed the buffer (see Narrowing), the displayed line number is relative to the accessible portion of the buffer. Thus, it isn’t suitable as an argument to goto-line. (Use what-line command to see the line number relative to the whole file.)

If the buffer is very large (larger than the value of line-number-display-limit), Emacs won’t compute the line number, because that would be too slow; therefore, the line number won’t appear on the mode-line. To remove this limit, set line-number-display-limit to nil.

Line-number computation can also be slow if the lines in the buffer are too long. For this reason, Emacs doesn’t display line numbers if the average width, in characters, of lines near point is larger than the value of line-number-display-limit-width. The default value is 200 characters.

Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time or customize the option display-time-mode. The information added to the mode line looks like this:

hh:mmPM l.ll

Here hh and mm are the hour and minute, followed always by ‘AM’ or ‘PM’. l.ll is the average number, collected for the last few minutes, of processes in the whole system that were either running or ready to run (i.e., were waiting for an available processor). (Some fields may be missing if your operating system cannot support them.) If you prefer time display in 24-hour format, set the variable display-time-24hr-format to t.

The word ‘Mail’ appears after the load level if there is mail for you that you have not read yet. On graphical displays, you can use an icon instead of ‘Mail’ by customizing display-time-use-mail-icon; this may save some space on the mode line. You can customize display-time-mail-face to make the mail indicator prominent. Use display-time-mail-file to specify the mail file to check, or set display-time-mail-directory to specify the directory to check for incoming mail (any nonempty regular file in the directory is considered to be newly arrived mail).

When running Emacs on a laptop computer, you can display the battery charge on the mode-line, by using the command display-battery-mode or customizing the variable display-battery-mode. The variable battery-mode-line-format determines the way the battery charge is displayed; the exact mode-line message depends on the operating system, and it usually shows the current battery charge as a percentage of the total charge.

On graphical displays, the mode line is drawn as a 3D box. If you don’t like this effect, you can disable it by customizing the mode-line face and setting its box attribute to nil. See Face Customization.

By default, the mode line of nonselected windows is displayed in a different face, called mode-line-inactive. Only the selected window is displayed in the mode-line face. This helps show which window is selected. When the minibuffer is selected, since it has no mode line, the window from which you activated the minibuffer has its mode line displayed using mode-line; as a result, ordinary entry to the minibuffer does not change any mode lines.

You can disable use of mode-line-inactive by setting variable mode-line-in-non-selected-windows to nil; then all mode lines are displayed in the mode-line face.

You can customize the mode line display for each of the end-of-line formats by setting each of the variables eol-mnemonic-unix, eol-mnemonic-dos, eol-mnemonic-mac, and eol-mnemonic-undecided to the strings you prefer.

14.19 How Text Is Displayed

Most characters are printing characters: when they appear in a buffer, they are displayed literally on the screen. Printing characters include ASCII numbers, letters, and punctuation characters, as well as many non-ASCII characters.

The ASCII character set contains non-printing control characters. Two of these are displayed specially: the newline character (Unicode code point U+000A) is displayed by starting a new line, while the tab character (U+0009) is displayed as a space that extends to the next tab stop column (normally every 8 columns). The number of spaces per tab is controlled by the buffer-local variable tab-width, which must have an integer value between 1 and 1000, inclusive. Note that the way the tab character in the buffer is displayed has nothing to do with the definition of TAB as a command.

Other ASCII control characters, whose codes are below U+0020 (octal 40, decimal 32), are displayed as a caret (‘^’) followed by the non-control version of the character, with the escape-glyph face. For instance, the ‘control-A’ character, U+0001, is displayed as ‘^A’.

The raw bytes with codes U+0080 (octal 200) through U+009F (octal 237) are displayed as octal escape sequences, with the escape-glyph face. For instance, character code U+0098 (octal 230) is displayed as ‘\230’. If you change the buffer-local variable ctl-arrow to nil, the ASCII control characters are also displayed as octal escape sequences instead of caret escape sequences. (You can also request that raw bytes be shown in hex, see display-raw-bytes-as-hex.)

Some non-ASCII characters have the same appearance as an ASCII space or hyphen (minus) character. Such characters can cause problems if they are entered into a buffer without your realization, e.g., by yanking; for instance, source code compilers typically do not treat non-ASCII spaces as whitespace characters. To deal with this problem, Emacs displays such characters specially: it displays U+00A0 (no-break space) with the nobreak-space face, and it displays U+00AD (soft hyphen), U+2010 (hyphen), and U+2011 (non-breaking hyphen) with the nobreak-hyphen face. To disable this, change the variable nobreak-char-display to nil. If you give this variable a non-nil and non-t value, Emacs instead displays such characters as a highlighted backslash followed by a space or hyphen.

You can customize the way any particular character code is displayed by means of a display table. See Display Tables in The Emacs Lisp Reference Manual.

On graphical displays, some characters may have no glyphs in any of the fonts available to Emacs. These glyphless characters are normally displayed as boxes containing the hexadecimal character code. Similarly, on text terminals, characters that cannot be displayed using the terminal encoding (see Terminal Coding) are normally displayed as question signs. You can control the display method by customizing the variable glyphless-char-display-control. You can also customize the glyphless-char face to make these characters more prominent on display. See Glyphless Character Display in The Emacs Lisp Reference Manual, for details.

Emacs tries to determine if the curved quotes ‘’ and ‘’ can be displayed on the current display. By default, if this seems to be so, then Emacs will translate the ASCII quotes (‘`’ and ‘'’), when they appear in messages and help texts, to these curved quotes. You can influence or inhibit this translation by customizing the user option text-quoting-style (see Keys in Documentation in The Emacs Lisp Reference Manual).

If the curved quotes , , , and are known to look just like ASCII characters, they are shown with the homoglyph face. Curved quotes that are known not to be displayable are shown as their ASCII approximations `, ', and " with the homoglyph face.

Next: , Previous: , Up: Display   [Contents][Index]

14.20 Displaying the Cursor

On a text terminal, the cursor’s appearance is controlled by the terminal, largely out of the control of Emacs. Some terminals offer two different cursors: a visible static cursor, and a very visible blinking cursor. By default, Emacs uses the very visible cursor, and switches to it when you start or resume Emacs. If the variable visible-cursor is nil when Emacs starts or resumes, it uses the normal cursor.

On a graphical display, many more properties of the text cursor can be altered. To customize its color, change the :background attribute of the face named cursor (see Face Customization). (The other attributes of this face have no effect; the text shown under the cursor is drawn using the frame’s background color.) To change its shape, customize the buffer-local variable cursor-type; possible values are box (the default), hollow (a hollow box), bar (a vertical bar), (bar . n) (a vertical bar n pixels wide), hbar (a horizontal bar), (hbar . n) (a horizontal bar n pixels tall), or nil (no cursor at all).

By default, the cursor stops blinking after 10 blinks, if Emacs does not get any input during that time; any input event restarts the count. You can customize the variable blink-cursor-blinks to control that: its value says how many times to blink without input before stopping. Setting that variable to a zero or negative value will make the cursor blink forever. To disable cursor blinking altogether, change the variable blink-cursor-mode to nil (see Easy Customization), or add the line

  (blink-cursor-mode 0)

to your init file. Alternatively, you can change how the cursor looks when it blinks off by customizing the list variable blink-cursor-alist. Each element in the list should have the form (on-type . off-type); this means that if the cursor is displayed as on-type when it blinks on (where on-type is one of the cursor types described above), then it is displayed as off-type when it blinks off.

Some characters, such as tab characters, are extra wide. When the cursor is positioned over such a character, it is normally drawn with the default character width. You can make the cursor stretch to cover wide characters, by changing the variable x-stretch-cursor to a non-nil value.

The cursor normally appears in non-selected windows as a non-blinking hollow box. (For a bar cursor, it instead appears as a thinner bar.) To turn off cursors in non-selected windows, change the variable cursor-in-non-selected-windows to nil.

To make the cursor even more visible, you can use HL Line mode, a minor mode that highlights the line containing point. Use M-x hl-line-mode to enable or disable it in the current buffer. M-x global-hl-line-mode enables or disables the same mode globally.

Next: , Previous: , Up: Display   [Contents][Index]

14.21 Line Truncation

As an alternative to continuation (see Continuation Lines), Emacs can display long lines by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. On graphical displays, a small straight arrow in the fringe indicates truncation at either end of the line. On text terminals, this is indicated with ‘$’ signs in the rightmost and/or leftmost columns.

Horizontal scrolling automatically causes line truncation (see Horizontal Scrolling). You can explicitly enable line truncation for a particular buffer with the command M-x toggle-truncate-lines. This works by locally changing the variable truncate-lines. If that variable is non-nil, long lines are truncated; if it is nil, they are continued onto multiple screen lines. Setting the variable truncate-lines in any way makes it local to the current buffer; until that time, the default value, which is normally nil, is in effect.

If a split window becomes too narrow, Emacs may automatically enable line truncation. See Split Window, for the variable truncate-partial-width-windows which controls this.

Next: , Previous: , Up: Display   [Contents][Index]

14.22 Visual Line Mode

Another alternative to ordinary line continuation is to use word wrap. Here, each long logical line is divided into two or more screen lines, like in ordinary line continuation. However, Emacs attempts to wrap the line at word boundaries near the right window edge. (If the line’s direction is right-to-left, it is wrapped at the left window edge instead.) This makes the text easier to read, as wrapping does not occur in the middle of words.

Word wrap is enabled by Visual Line mode, an optional minor mode. To turn on Visual Line mode in the current buffer, type M-x visual-line-mode; repeating this command turns it off. You can also turn on Visual Line mode using the menu bar: in the Options menu, select the ‘Line Wrapping in this Buffer’ submenu, followed by the ‘Word Wrap (Visual Line mode)’ menu item. While Visual Line mode is enabled, the mode line shows the string ‘wrap’ in the mode display. The command M-x global-visual-line-mode toggles Visual Line mode in all buffers.

In Visual Line mode, some editing commands work on screen lines instead of logical lines: C-a (beginning-of-visual-line) moves to the beginning of the screen line, C-e (end-of-visual-line) moves to the end of the screen line, and C-k (kill-visual-line) kills text to the end of the screen line.

To move by logical lines, use the commands M-x next-logical-line and M-x previous-logical-line. These move point to the next logical line and the previous logical line respectively, regardless of whether Visual Line mode is enabled. If you use these commands frequently, it may be convenient to assign key bindings to them. See Init Rebinding.

By default, word-wrapped lines do not display fringe indicators. Visual Line mode is often used to edit files that contain many long logical lines, so having a fringe indicator for each wrapped line would be visually distracting. You can change this by customizing the variable visual-line-fringe-indicators.

Previous: , Up: Display   [Contents][Index]

14.23 Customization of Display

This section describes variables that control miscellaneous aspects of the appearance of the Emacs screen. Beginning users can skip it.

If you want to have Emacs display line numbers for every line in the buffer, customize the buffer-local variable display-line-numbers; it is nil by default. This variable can have several different values to support various modes of line-number display:

t

Display (an absolute) line number before each non-continuation screen line that displays buffer text. If the line is a continuation line, or if the entire screen line displays a display or an overlay string, that line will not be numbered.

relative

Display relative line numbers before non-continuation lines which show buffer text. The line numbers are relative to the line showing point, so the numbers grow both up and down as lines become farther from the current line.

visual

This value causes Emacs to count lines visually: only lines actually shown on the display will be counted (disregarding any lines in invisible parts of text), and lines which wrap to consume more than one screen line will be numbered that many times. The displayed numbers are relative, as with relative value above. This is handy in modes that fold text, such as Outline mode (see Outline Mode), and when you need to move by exact number of screen lines.

anything else

Any other non-nil value is treated as t.

The command M-x display-line-numbers-mode provides a convenient way to turn on display of line numbers. This mode has a globalized variant, global-display-line-numbers-mode. The user option display-line-numbers-type controls which sub-mode of line-number display, described above, will these modes activate.

Note that line numbers are not displayed in the minibuffer and in the tooltips, even if you turn on display-line-numbers-mode globally.

When Emacs displays relative line numbers, you can control the number displayed before the current line, the line showing point. By default, Emacs displays the absolute number of the current line there, even though all the other line numbers are relative. If you customize the variable display-line-numbers-current-absolute to a nil value, the number displayed for the current line will be zero. This is handy if you don’t care about the number of the current line, and want to leave more horizontal space for text in large buffers.

In a narrowed buffer (see Narrowing) lines are normally numbered starting at the beginning of the narrowing. However, if you customize the variable display-line-numbers-widen to a non-nil value, line numbers will disregard any narrowing and will start at the first character of the buffer.

If the value of display-line-numbers-offset is non-zero, it is added to each absolute line number, and lines are counted from the beginning of the buffer, as if display-line-numbers-widen were non-nil. It has no effect when set to zero, or when line numbers are not absolute.

In selective display mode (see Selective Display), and other modes that hide many lines from display (such as Outline and Org modes), you may wish to customize the variables display-line-numbers-width-start and display-line-numbers-grow-only, or set display-line-numbers-width to a large enough value, to avoid occasional miscalculations of space reserved for the line numbers.

The line numbers are displayed in a special face line-number. The current line number is displayed in a different face, line-number-current-line, so you can make the current line’s number have a distinct appearance, which will help locating the line showing point. Additional faces line-number-major-tick and line-number-minor-tick can be used to highlight the line numbers of lines which are a multiple of certain numbers. Customize display-line-numbers-major-tick and display-line-numbers-minor-tick respectively to set those numbers.

If the variable visible-bell is non-nil, Emacs attempts to make the whole screen blink when it would normally make an audible bell sound. This variable has no effect if your terminal does not have a way to make the screen blink.

The variable echo-keystrokes controls the echoing of multi-character keys; its value is the number of seconds of pause required to cause echoing to start, or zero, meaning don’t echo at all. The value takes effect when there is something to echo. See Echo Area.

On graphical displays, Emacs displays the mouse pointer as an hourglass if Emacs is busy. To disable this feature, set the variable display-hourglass to nil. The variable hourglass-delay determines the number of seconds of busy time before the hourglass is shown; the default is 1.

If the mouse pointer lies inside an Emacs frame, Emacs makes it invisible each time you type a character to insert text, to prevent it from obscuring the text. (To be precise, the hiding occurs when you type a self-inserting character. See Inserting Text.) Moving the mouse pointer makes it visible again. To disable this feature, set the variable make-pointer-invisible to nil.

On graphical displays, the variable underline-minimum-offset determines the minimum distance between the baseline and underline, in pixels, for underlined text. By default, the value is 1; increasing it may improve the legibility of underlined text for certain fonts. (However, Emacs will never draw the underline below the current line area.) The variable x-underline-at-descent-line determines how to draw underlined text. The default is nil, which means to draw it at the baseline level of the font; if you change it to t, Emacs draws the underline at the same height as the font’s descent line. (If non-default line spacing was specified for the underlined text, see Line Height in The Emacs Lisp Reference Manual, Emacs draws the underline below the additional spacing.)

The variable overline-margin specifies the vertical position of an overline above the text, including the height of the overline itself, in pixels; the default is 2.

On some text terminals, bold face and inverse video together result in text that is hard to read. Call the function tty-suppress-bold-inverse-default-colors with a non-nil argument to suppress the effect of bold-face in this case.

Raw bytes are displayed in octal format by default, for example a byte with a decimal value of 128 is displayed as \200. To change display to the hexadecimal format of \x80, set the variable display-raw-bytes-as-hex to t.


Next: , Previous: , Up: Top   [Contents][Index]

15Searching and Replacement

Like other editors, Emacs has commands to search for occurrences of a string. Emacs also has commands to replace occurrences of a string with a different string. There are also commands that do the same thing, but search for patterns instead of fixed strings.

You can also search multiple files under the control of xref (see Identifier Search) or through the Dired A command (see Operating on Files), or ask the grep program to do it (see Grep Searching).

15.1Incremental Search

The principal search command in Emacs is incremental: it begins searching as soon as you type the first character of the search string. As you type in the search string, Emacs shows you where the string (as you have typed it so far) would be found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you plan to do next, you may or may not need to terminate the search explicitly with RET.

C-s

Incremental search forward (isearch-forward).

C-r

Incremental search backward (isearch-backward).

You can also invoke incremental search from the menu bar’s ‘Edit->Search’ menu.

15.1.1 Basics of Incremental Search

C-s

Begin incremental search (isearch-forward).

C-r

Begin reverse incremental search (isearch-backward).

C-s (isearch-forward) starts a forward incremental search. It reads characters from the keyboard, and moves point just past the end of the next occurrence of those characters in the buffer.

For instance, if you type C-s and then F, that puts the cursor after the first ‘F’ that occurs in the buffer after the starting point. If you then type O, the cursor moves to just after the first ‘FO’; the ‘F’ in that ‘FO’ might not be the first ‘F’ previously found. After another O, the cursor moves to just after the first ‘FOO’.

At each step, Emacs highlights the current match—the buffer text that matches the search string—using the isearch face (see Faces). See Search Customizations, for various options that customize this highlighting. The current search string is also displayed in the echo area.

If you make a mistake typing the search string, type DEL (isearch-delete-char). Each DEL cancels the last input item entered during the search. Emacs records a new input item whenever you type a command that changes the search string, the position of point, the success or failure of the search, the direction of the search, the position of the other end of the current search result, or the “wrappedness” of the search. See Error in Isearch, for more about dealing with unsuccessful search.

When you are satisfied with the place you have reached, type RET (isearch-exit). This stops searching, leaving the cursor where the search brought it. Also, any command not specially meaningful in searches stops the searching and is then executed. Thus, typing C-a exits the search and then moves to the beginning of the line; typing one of the arrow keys exits the search and performs the respective movement command; etc. RET is necessary only if the next command you want to type is a printing character, DEL, RET, or another character that is special within searches (C-q, C-w, C-r, C-s, C-y, M-y, M-r, M-c, M-e, and some others described below). You can fine-tune the commands that exit the search; see Not Exiting Isearch.

As a special exception, entering RET when the search string is empty launches nonincremental search (see Nonincremental Search). (This can be customized; see Search Customizations.)

To abandon the search and return to the place where you started, type ESC ESC ESC (isearch-cancel) or C-g C-g (isearch-abort).

When you exit the incremental search, it adds the original value of point to the mark ring, without activating the mark; you can thus use C-u C-SPC or C-x C-x to return to where you were before beginning the search. See Mark Ring. (Emacs only does this if the mark was not already active; if the mark was active when you started the search, both C-u C-SPC and C-x C-x will go to the mark.)

To search backwards, use C-r (isearch-backward) instead of C-s to start the search. A backward search finds matches that end before the starting point, just as a forward search finds matches that begin after it.

15.1.2 Repeating Incremental Search

Suppose you search forward for ‘FOO’ and find a match, but not the one you expected to find: the ‘FOO’ you were aiming for occurs later in the buffer. In this event, type another C-s (isearch-repeat-forward) to move to the next occurrence of the search string, or C-r (isearch-repeat-backward) to move to the previous occurrence. You can repeat these commands any number of times. Alternatively, you can supply a numeric prefix argument of n to C-s and C-r to find the nth next or previous occurrence. If you overshoot, you can cancel some C-s commands with DEL. Similarly, each C-r (isearch-repeat-backward) in a backward incremental search repeats the backward search.

If you pause for a little while during incremental search, Emacs highlights all the other possible matches for the search string that are present on the screen. This helps you anticipate where you can get to by typing C-s or C-r to repeat the search. The other matches are highlighted differently from the current match, using the customizable face lazy-highlight (see Faces). If you don’t like this feature, you can disable it by setting isearch-lazy-highlight to nil. For other customizations related to highlighting matches, see Search Customizations.

After exiting a search, you can search for the same string again by typing just C-s C-s. The first C-s is the key that invokes incremental search, and the second C-s means to search again for the last search string. Similarly, C-r C-r searches backward for the last search string. In determining the last search string, it doesn’t matter whether that string was searched for with C-s or C-r.

If you are searching forward but you realize you were looking for something before the starting point, type C-r to switch to a backward search, leaving the search string unchanged. Similarly, C-s in a backward search switches to a forward search.

If a search is failing and you ask to repeat it by typing another C-s, it starts again from the beginning of the buffer. Repeating a failing reverse search with C-r starts again from the end. This is called wrapping around, and ‘Wrapped’ appears in the search prompt once this has happened. If you keep on going past the original starting point of the search, it changes to ‘Overwrapped’, which means that you are revisiting matches that you have already seen.

To reuse earlier search strings, use the search ring. The commands M-p (isearch-ring-retreat) and M-n (isearch-ring-advance) move through the ring to pick a search string to reuse. These commands leave the selected search ring element in the minibuffer, where you can edit it. Type C-s/C-r or RET to accept the string and start searching for it. The number of most recently used search strings saved in the search ring is specified by the variable search-ring-max, 16 by default.

To edit the current search string in the minibuffer without replacing it with items from the search ring, type M-e (isearch-edit-string) or click mouse-1 in the minibuffer. Type RET, C-s or C-r to finish editing the string and search for it. Type C-f or RIGHT to add to the search string characters following point from the buffer from which you started the search.

15.1.3 Isearch Yanking

In many cases, you will want to use text at or near point as your search string. The commands described in this subsection let you do that conveniently.

C-w (isearch-yank-word-or-char) appends the next character or word at point to the search string. This is an easy way to search for another occurrence of the text at point. (The decision of whether to copy a character or a word is heuristic.) With a prefix numeric argument of n, append the next n characters or words.

C-M-w (isearch-yank-symbol-or-char) appends the next character or symbol at point to the search string. This is an easy way to search for another occurrence of the symbol at point. (The decision of whether to copy a character or a symbol is heuristic.) With a prefix numeric argument of n, append the next n characters or symbols.

M-s C-e (isearch-yank-line) appends the rest of the current line to the search string. If point is already at the end of a line, it appends the next line. With a prefix argument n, it appends the next n lines.

Similarly, C-M-z (isearch-yank-until-char) appends to the search string everything from point until the next occurrence of a specified character (not including that character). This is especially useful for keyboard macros, for example in programming languages or markup languages in which that character marks a token boundary. With a prefix numeric argument of n, the command appends everything from point to the nth occurrence of the specified character.

Within incremental search, C-y (isearch-yank-kill) appends the current kill to the search string. M-y (isearch-yank-pop), if called after C-y, replaces that appended text with an earlier kill, similar to the usual M-y (yank-pop) command (see Yanking). Clicking mouse-2 in the echo area appends the current X selection (see Primary Selection) to the search string (isearch-yank-x-selection).

C-M-d (isearch-del-char) deletes the last character from the search string, and C-M-y (isearch-yank-char) appends the character after point to the search string. An alternative method to add the character after point is to enter the minibuffer with M-e (see Repeat Isearch) and type C-f or RIGHT at the end of the search string in the minibuffer. Each C-f or RIGHT you type adds another character following point to the search string.

Normally, when the search is case-insensitive, text yanked into the search string is converted to lower case, so that the search remains case-insensitive (see case folding). However, if the value of the variable search-upper-case (see search-upper-case) is other than not-yanks, that disables this down-casing.

15.1.4 Errors in Incremental Search

If your string is not found at all, the echo area says ‘Failing I-Search’, and the cursor moves past the place where Emacs found as much of your string as it could. Thus, if you search for ‘FOOT’, and there is no ‘FOOT’, you might see the cursor after the ‘FOO’ in ‘FOOL’. In the echo area, the part of the search string that failed to match is highlighted using the face isearch-fail.

At this point, there are several things you can do. If your string was mistyped, use DEL to cancel a previous input item (see Basic Isearch), C-M-d to erase one character at a time, or M-e to edit it. If you like the place you have found, you can type RET to remain there. Or you can type C-g, which removes from the search string the characters that could not be found (the ‘T’ in ‘FOOT’), leaving those that were found (the ‘FOO’ in ‘FOOT’). A second C-g at that point cancels the search entirely, returning point to where it was when the search started.

The quit command, C-g, does special things during searches; just what it does depends on the status of the search. If the search has found what you specified and is waiting for input, C-g cancels the entire search, moving the cursor back to where you started the search. If C-g is typed when there are characters in the search string that have not been found—because Emacs is still searching for them, or because it has failed to find them—then the search string characters which have not been found are discarded from the search string. With them gone, the search is now successful and waiting for more input, so a second C-g will cancel the entire search.

15.1.5 Special Input for Incremental Search

In addition to characters described in the previous subsections, some of the other characters you type during incremental search have special effects. They are described here.

To toggle lax space matching (see lax space matching), type M-s SPC.

To toggle case sensitivity of the search, type M-c or M-s c. See case folding. If the search string includes upper-case letters, the search is case-sensitive by default.

To toggle whether or not the search will consider similar and equivalent characters as a match, type M-s '. See character folding. If the search string includes accented characters, that disables character folding during that search.

To toggle whether or not invisible text is searched, type M-s i (isearch-toggle-invisible). See Outline Search.

To toggle between non-regexp and regexp incremental search, type M-r or M-s r (isearch-toggle-regexp). See Regexp Search.

To toggle symbol mode, type M-s _. See Symbol Search.

To search for a newline character, type C-j as part of the search string.

To search for non-ASCII characters, use one of the following methods:

Typing M-s o in incremental search invokes isearch-occur, which runs occur with the current search string. See occur.

Typing M-% (isearch-query-replace) in incremental search invokes query-replace or query-replace-regexp (depending on search mode) with the current search string used as the string to replace. A negative prefix argument means to replace backward. See Query Replace. Typing C-M-% (isearch-query-replace-regexp) invokes query-replace-regexp with the current search string used as the regexp to replace.

Typing M-TAB in incremental search invokes isearch-complete, which attempts to complete the search string using the search ring (the previous search strings you used) as a list of completion alternatives. See Completion. In many operating systems, the M-TAB key sequence is captured by the window manager; you then need to rebind isearch-complete to another key sequence if you want to use it (see Rebinding).

You can exit the search while leaving the matches highlighted by typing M-s h r (isearch-highlight-regexp). This runs highlight-regexp (see Highlight Interactively), passing it the regexp derived from the search string and prompting you for the face to use for highlighting. To highlight whole lines containing matches (rather than just the matches), type M-s h l (isearch-highlight-lines-matching-regexp). In either case, to remove the highlighting, type M-s h u (unhighlight-regexp).

When incremental search is active, you can type C-h C-h (isearch-help-map) to access interactive help options, including a list of special key bindings. These key bindings are part of the keymap isearch-mode-map (see Keymaps).

When incremental search is active, typing M-s M-> will go to the last occurrence of the search string, and M-s M-< will go to the first occurrence. With a prefix numeric argument of n, these commands will go to the nth occurrence of the search string counting from the beginning or end of the buffer, respectively.

15.1.6 Not Exiting Incremental Search

This subsection describes how to control whether typing a command not specifically meaningful in searches exits the search before executing the command. It also describes three categories of commands which you can type without exiting the current incremental search, even though they are not themselves part of incremental search.

Normally, typing a command that is not bound by the incremental search exits the search before executing the command. Thus, the command operates on the buffer from which you invoked the search. However, if you customize the variable search-exit-option to append, the characters which you type that are not interpreted by the incremental search are simply appended to the search string. This is so you could include in the search string control characters, such as C-a, that would normally exit the search and invoke the command bound to them on the buffer.

Prefix Arguments

In incremental search, when you type a command that specifies a prefix argument (see Arguments), by default it will apply either to the next action in the search or to the command that exits the search. In other words, entering a prefix argument will not by itself terminate the search.

In previous versions of Emacs, entering a prefix argument always terminated the search. You can revert to this behavior by setting the variable isearch-allow-prefix to nil.

When isearch-allow-scroll is non-nil (see below), prefix arguments always have the default behavior described above, i.e., they don’t terminate the search, even if isearch-allow-prefix is nil.

Scrolling Commands

Normally, scrolling commands exit incremental search. If you change the variable isearch-allow-scroll to a non-nil value, that enables the use of the scroll-bar, as well as keyboard scrolling commands like C-v, M-v, and C-l (see Scrolling). This applies only to calling these commands via their bound key sequences—typing M-x will still exit the search. You can give prefix arguments to these commands in the usual way. This feature normally won’t let you scroll the current match out of visibility; but if you customize isearch-allow-scroll to the special value unlimited, that restriction is lifted.

The isearch-allow-scroll feature also affects some other commands, such as C-x 2 (split-window-below) and C-x ^ (enlarge-window), which don’t exactly scroll but do affect where the text appears on the screen. It applies to any command whose name has a non-nil isearch-scroll property. So you can control which commands are affected by changing these properties.

For example, to make C-h l usable within an incremental search in all future Emacs sessions, use C-h c to find what command it runs (see Key Help), which is view-lossage. Then you can put the following line in your init file (see Init File):

(put 'view-lossage 'isearch-scroll t)

This feature can be applied to any command that doesn’t permanently change point, the buffer contents, the match data, the current buffer, or the selected window and frame. The command must not itself attempt an incremental search. This feature is disabled if isearch-allow-scroll is nil (which it is by default).

Motion Commands

When isearch-yank-on-move is customized to shift, you can extend the search string by holding down the shift key while typing cursor motion commands. It will yank text that ends at the new position after moving point in the current buffer.

When isearch-yank-on-move is t, you can extend the search string without using the shift key for cursor motion commands, but it applies only for certain motion command that have the isearch-move property on their symbols.

15.1.7 Searching the Minibuffer

If you start an incremental search while the minibuffer is active, Emacs searches the contents of the minibuffer. Unlike searching an ordinary buffer, the search string is not shown in the echo area, because that is used to display the minibuffer.

If an incremental search fails in the minibuffer, it tries searching the minibuffer history. See Minibuffer History. You can visualize the minibuffer and its history as a series of pages, with the earliest history element on the first page and the current minibuffer on the last page. A forward search, C-s, searches forward to later pages; a reverse search, C-r, searches backwards to earlier pages. Like in ordinary buffer search, a failing search can wrap around, going from the last page to the first page or vice versa.

When the current match is on a history element, that history element is pulled into the minibuffer. If you exit the incremental search normally (e.g., by typing RET), it remains in the minibuffer afterwards. Canceling the search, with C-g, restores the contents of the minibuffer when you began the search.

Next: , Previous: , Up: Search   [Contents][Index]

15.2Nonincremental Search

Emacs also has conventional nonincremental search commands, which require you to type the entire search string before searching begins.

C-s RET string RET

Search for string.

C-r RET string RET

Search backward for string.

To start a nonincremental search, first type C-s RET. This enters the minibuffer to read the search string; terminate the string with RET, and then the search takes place. If the string is not found, the search command signals an error.

When you type C-s RET, the C-s invokes incremental search as usual. That command is specially programmed to invoke the command for nonincremental search, if the string you specify is empty. (Such an empty argument would otherwise be useless.) C-r RET does likewise, invoking the nonincremental backward-searching command.

Nonincremental search can also be invoked from the menu bar’s ‘Edit->Search’ menu.

You can also use two simpler commands, M-x search-forward and M-x search-backward. These commands look for the literal strings you specify, and don’t support any of the lax-search features (see Lax Search) except case folding.

15.3Word Search

A word search finds a sequence of words without regard to the type of punctuation between them. For instance, if you enter a search string that consists of two words separated by a single space, the search matches any sequence of those two words separated by one or more spaces, newlines, or other punctuation characters. This is particularly useful for searching text documents, because you don’t have to worry whether the words you are looking for are separated by newlines or spaces. Note that major modes for programming languages or other specialized modes can modify the definition of a word to suit their syntactic needs.

M-s w

If incremental search is active, toggle word search mode (isearch-toggle-word); otherwise, begin an incremental forward word search (isearch-forward-word).

M-s w RET words RET

Search for words, using a forward nonincremental word search.

M-s w C-r RET words RET

Search backward for words, using a nonincremental word search.

M-s M-w

Search the Web for the text in region.

To begin a forward incremental word search, type M-s w. If incremental search is not already active, this runs the command isearch-forward-word. If incremental search is already active (whether a forward or backward search), M-s w runs the command isearch-toggle-word, which switches to a word search while keeping the direction of the search and the current search string unchanged. You can toggle word search back off by typing M-s w again.

To begin a nonincremental word search, type M-s w RET for a forward search, or M-s w C-r RET for a backward search. These run the commands word-search-forward and word-search-backward respectively.

Incremental and nonincremental word searches differ slightly in the way they find a match. In a nonincremental word search, each word in the search string must exactly match a whole word. In an incremental word search, the matching is more lax: while you are typing the search string, its first and last words need not match whole words. This is so that the matching can proceed incrementally as you type. This additional laxity does not apply to the lazy highlight (see Incremental Search), which always matches whole words. While you are typing the search string, ‘Pending’ appears in the search prompt until you use a search repeating key like C-s.

The word search commands don’t perform character folding, and toggling lax whitespace matching (see lax space matching) has no effect on them.

To search the Web for the text in region, type M-s M-w. This command performs an Internet search for the words in region using the search engine whose URL is specified by the variable eww-search-prefix (see EWW in The Emacs Web Wowser Manual). If the region is not active, or doesn’t contain any words, this command prompts the user for a URL or keywords to search.

Next: , Previous: , Up: Search   [Contents][Index]

15.4Symbol Search

A symbol search is much like an ordinary search, except that the boundaries of the search must match the boundaries of a symbol. The meaning of symbol in this context depends on the major mode, and usually refers to a source code token, such as a Lisp symbol in Emacs Lisp mode. For instance, if you perform an incremental symbol search for the Lisp symbol forward-word, it would not match isearch-forward-word. This feature is thus mainly useful for searching source code.

M-s _

If incremental search is active, toggle symbol search mode (isearch-toggle-symbol); otherwise, begin an incremental forward symbol search (isearch-forward-symbol).

M-s .

Start a symbol incremental search forward with the symbol found near point added to the search string initially.

M-s _ RET symbol RET

Search forward for symbol, nonincrementally.

M-s _ C-r RET symbol RET

Search backward for symbol, nonincrementally.

To begin a forward incremental symbol search, type M-s _ (or M-s . if the symbol to search is near point). If incremental search is not already active, M-s _ runs the command isearch-forward-symbol and M-s . runs the command isearch-forward-symbol-at-point. With a numeric prefix argument of n, M-s . will search for the nthe next occurrence of the symbol at point; negative values of n search backwards. If incremental search is already active, M-s _ switches to a symbol search, preserving the direction of the search and the current search string; you can disable symbol search by typing M-s _ again. In incremental symbol search, while you are typing the search string, only the beginning of the search string is required to match the beginning of a symbol, and ‘Pending’ appears in the search prompt until you use a search repeating key like C-s.

To begin a nonincremental symbol search, type M-s _ RET for a forward search, or M-s _ C-r RET or a backward search. In nonincremental symbol searches, the beginning and end of the search string are required to match the beginning and end of a symbol, respectively.

The symbol search commands don’t perform character folding, and toggling lax whitespace matching (see lax space matching) has no effect on them.

Next: , Previous: , Up: Search   [Contents][Index]

15.5Regular Expression Search

A regular expression (or regexp for short) is a pattern that denotes a class of alternative strings to match. Emacs provides both incremental and nonincremental ways to search for a match for a regexp. The syntax of regular expressions is explained in the next section.

C-M-s

Begin incremental regexp search (isearch-forward-regexp).

C-M-r

Begin reverse incremental regexp search (isearch-backward-regexp).

Incremental search for a regexp is done by typing C-M-s (isearch-forward-regexp), by invoking C-s with a prefix argument (whose value does not matter), or by typing M-r within a forward incremental search. This command reads a search string incrementally just like C-s, but it treats the search string as a regexp rather than looking for an exact match against the text in the buffer. Each time you add text to the search string, you make the regexp longer, and the new regexp is searched for. To search backward for a regexp, use C-M-r (isearch-backward-regexp), C-r with a prefix argument, or M-r within a backward incremental search.

All of the special key sequences in an ordinary incremental search (see Special Isearch) do similar things in an incremental regexp search. For instance, typing C-s immediately after starting the search retrieves the last incremental search regexp used and searches forward for it. Incremental regexp and non-regexp searches have independent defaults. They also have separate search rings, which you can access with M-p and M-n. The maximum number of search regexps saved in the search ring is determined by the value of regexp-search-ring-max, 16 by default.

Unlike ordinary incremental search, incremental regexp search does not use lax space matching by default. To toggle this feature use M-s SPC (isearch-toggle-lax-whitespace). Then any SPC typed in incremental regexp search will match any sequence of one or more whitespace characters. The variable search-whitespace-regexp specifies the regexp for the lax space matching. See Special Isearch.

Also unlike ordinary incremental search, incremental regexp search cannot use character folding (see Lax Search). (If you toggle character folding during incremental regexp search with M-s ', the search becomes a non-regexp search and the search pattern you typed is interpreted as a literal string.)

In some cases, adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for ‘foo’ and you add ‘\|bar’, the cursor backs up in case the first ‘bar’ precedes the first ‘foo’. See Regexps.

Forward and backward regexp search are not symmetrical, because regexp matching in Emacs always operates forward, starting with the beginning of the regexp. Thus, forward regexp search scans forward, trying a forward match at each possible starting position. Backward regexp search scans backward, trying a forward match at each possible starting position. These search methods are not mirror images.

Nonincremental search for a regexp is done with the commands re-search-forward and re-search-backward. You can invoke these with M-x, or by way of incremental regexp search with C-M-s RET and C-M-r RET. When you invoke these commands with M-x, they search for the exact regexp you specify, and thus don’t support any lax-search features (see Lax Search) except case folding.

If you use the incremental regexp search commands with a prefix argument, they perform ordinary string search, like isearch-forward and isearch-backward. 请参阅增量搜索

Next: , Previous: , Up: Search   [Contents][Index]

15.6Syntax of Regular Expressions

This section (and this manual in general) describes regular expression features that users typically use. See Regular Expressions in The Emacs Lisp Reference Manual, for additional features used mainly in Lisp programs.

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character matches that same character and nothing else. The special characters are ‘$^.*+?[\’. The character ‘]’ is special if it ends a character alternative (see below). The character ‘-’ is special inside a character alternative. Any other character appearing in a regular expression is ordinary, unless a ‘\’ precedes it. (When you use regular expressions in a Lisp program, each ‘\’ must be doubled, see the example near the end of this section.)

For example, ‘f’ is not a special character, so it is ordinary, and therefore ‘f’ is a regular expression that matches the string ‘f’ and no other string. (It does not match the string ‘ff’.) Likewise, ‘o’ is a regular expression that matches only ‘o’. (When case distinctions are being ignored, these regexps also match ‘F’ and ‘O’, but we consider this a generalization of “the same string”, rather than an exception.)

Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string. As a trivial example, concatenating the regular expressions ‘f’ and ‘o’ gives the regular expression ‘fo’, which matches only the string ‘fo’. To do something less trivial, you need to use one of the special characters. Here is a list of them.

. (Period)

is a special character that matches any single character except a newline. For example, the regular expressions ‘a.b’ matches any three-character string that begins with ‘a’ and ends with ‘b’.

*

is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively any number of times, as many times as possible. Thus, ‘o*’ matches any number of ‘o’s, including no ‘o’s.

*’ always applies to the smallest possible preceding expression. Thus, ‘fo*’ has a repeating ‘o’, not a repeating ‘fo’. It matches ‘f’, ‘fo’, ‘foo’, and so on.

The matcher processes a ‘*’ construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the ‘*’-modified construct in case that makes it possible to match the rest of the pattern. For example, in matching ‘ca*ar’ against the string ‘caaar’, the ‘a*’ first tries to match all three ‘a’s; but the rest of the pattern is ‘ar’ and there is only ‘r’ left to match, so this try fails. The next alternative is for ‘a*’ to match only two ‘a’s. With this choice, the rest of the regexp matches successfully.

+

is a postfix operator, similar to ‘*’ except that it must match the preceding expression at least once. Thus, ‘ca+r’ matches the strings ‘car’ and ‘caaaar’ but not the string ‘cr’, whereas ‘ca*r’ matches all three strings.

?

is a postfix operator, similar to ‘*’ except that it can match the preceding expression either once or not at all. Thus, ‘ca?r’ matches ‘car’ or ‘cr’, and nothing else.

*?, +?, ??

are non-greedy variants of the operators above. The normal operators ‘*’, ‘+’, ‘?’ match as much as they can, as long as the overall regexp can still match. With a following ‘?’, they will match as little as possible.

Thus, both ‘ab*’ and ‘ab*?’ can match the string ‘a’ and the string ‘abbbb’; but if you try to match them both against the text ‘abbb’, ‘ab*’ will match it all (the longest valid match), while ‘ab*?’ will match just ‘a’ (the shortest valid match).

Non-greedy operators match the shortest possible string starting at a given starting point; in a forward search, though, the earliest possible starting point for match is always the one chosen. Thus, if you search for ‘a.*?$’ against the text ‘abbab’ followed by a newline, it matches the whole string. Since it can match starting at the first ‘a’, it does.

\{n\}

is a postfix operator specifying n repetitions—that is, the preceding regular expression must match exactly n times in a row. For example, ‘x\{4\}’ matches the string ‘xxxx’ and nothing else.

\{n,m\}

is a postfix operator specifying between n and m repetitions—that is, the preceding regular expression must match at least n times, but no more than m times. If m is omitted, then there is no upper limit, but the preceding regular expression must match at least n times.
\{0,1\}’ is equivalent to ‘?’.
\{0,\}’ is equivalent to ‘*’.
\{1,\}’ is equivalent to ‘+’.

[ … ]

is a character set, beginning with ‘[’ and terminated by ‘]’.

In the simplest case, the characters between the two brackets are what this set can match. Thus, ‘[ad]’ matches either one ‘a’ or one ‘d’, and ‘[ad]*’ matches any string composed of just ‘a’s and ‘d’s (including the empty string). It follows that ‘c[ad]*r’ matches ‘cr’, ‘car’, ‘cdr’, ‘caddaar’, etc.

You can also include character ranges in a character set, by writing the starting and ending characters with a ‘-’ between them. Thus, ‘[a-z]’ matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in ‘[a-z$%.]’, which matches any lower-case ASCII letter or ‘$’, ‘%’ or period. As another example, ‘[α-ωί]’ matches all lower-case Greek letters.

You can also include certain special character classes in a character set. A ‘[:’ and balancing ‘:]’ enclose a character class inside a character alternative. For instance, ‘[[:alnum:]]’ matches any letter or digit. See Char Classes in The Emacs Lisp Reference Manual, for a list of character classes.

To include a ‘]’ in a character set, you must make it the first character. For example, ‘[]a]’ matches ‘]’ or ‘a’. To include a ‘-’, write ‘-’ as the last character of the set, tho you can also put it first or after a range. Thus, ‘[]-]’ matches both ‘]’ and ‘-’.

To include ‘^’ in a set, put it anywhere but at the beginning of the set. (At the beginning, it complements the set—see below.)

When you use a range in case-insensitive search, you should write both ends of the range in upper case, or both in lower case, or both should be non-letters. The behavior of a mixed-case range such as ‘A-z’ is somewhat ill-defined, and it may change in future Emacs versions.

[^ … ]

[^’ begins a complemented character set, which matches any character except the ones specified. Thus, ‘[^a-z0-9A-Z]’ matches all characters except ASCII letters and digits.

^’ is not special in a character set unless it is the first character. The character following the ‘^’ is treated as if it were first (in other words, ‘-’ and ‘]’ are not special there).

A complemented character set can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.

^

is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, ‘^foo’ matches a ‘foo’ that occurs at the beginning of a line.

For historical compatibility reasons, ‘^’ can be used with this meaning only at the beginning of the regular expression, or after ‘\(’ or ‘\|’.

$

is similar to ‘^’ but matches only at the end of a line. Thus, ‘x+$’ matches a string of one ‘x’ or more at the end of a line.

For historical compatibility reasons, ‘$’ can be used with this meaning only at the end of the regular expression, or before ‘\)’ or ‘\|’.

\

has two functions: it quotes the special characters (including ‘\’), and it introduces additional special constructs.

Because ‘\’ quotes special characters, ‘\$’ is a regular expression that matches only ‘$’, and ‘\[’ is a regular expression that matches only ‘[’, and so on.

See the following section for the special constructs that begin with ‘\’.

Note: for historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, ‘*foo’ treats ‘*’ as ordinary since there is no preceding expression on which the ‘*’ can act. It is poor practice to depend on this behavior; it is better to quote the special character anyway, regardless of where it appears.

As a ‘\’ is not special inside a character alternative, it can never remove the special meaning of ‘-’ or ‘]’. So you should not quote these characters when they have no special meaning either. This would not clarify anything, since backslashes can legitimately precede these characters where they have special meaning, as in ‘[^\]’ ("[^\\]" for Lisp string syntax), which matches any single character except a backslash.

Next: , Previous: , Up: Search   [Contents][Index]

15.7Backslash in Regular Expressions

For the most part, ‘\’ followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with ‘\’ that have special meanings. The second character in the sequence is always an ordinary character when used on its own. Here is a table of ‘\’ constructs.

\|

specifies an alternative. Two regular expressions a and b with ‘\|’ in between form an expression that matches some text if either a matches it or b matches it. It works by trying to match a, and if that fails, by trying to match b.

Thus, ‘foo\|bar’ matches either ‘foo’ or ‘bar’ but no other string.

\|’ applies to the largest possible surrounding expressions. Only a surrounding ‘\( … \)’ grouping can limit the grouping power of ‘\|’.

Full backtracking capability exists to handle multiple uses of ‘\|’.

\( … \)

is a grouping construct that serves three purposes:

  1. To enclose a set of ‘\|’ alternatives for other operations. Thus, ‘\(foo\|bar\)x’ matches either ‘foox’ or ‘barx’.
  2. To enclose a complicated expression for the postfix operators ‘*’, ‘+’ and ‘?’ to operate on. Thus, ‘ba\(na\)*’ matches ‘bananana’, etc., with any (zero or more) number of ‘na’ strings.
  3. To record a matched substring for future reference.

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that is assigned as a second meaning to the same ‘\( … \) construct. In practice there is usually no conflict between the two meanings; when there is a conflict, you can use a shy group, described below.

\(?: … \)

specifies a shy group that does not record the matched substring; you can’t refer back to it with ‘\d’ (see below). This is useful in mechanically combining regular expressions, so that you can add groups for syntactic purposes without interfering with the numbering of the groups that are meant to be referred to.

\d

matches the same text that matched the dth occurrence of a ‘\( … \)’ construct. This is called a back reference.

After the end of a ‘\( … \)’ construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use ‘\’ followed by the digit d to mean “match the same text matched the dth time by the ‘\( … \)’ construct”.

The strings matching the first nine ‘\( … \)’ constructs appearing in a regular expression are assigned numbers 1 through 9 in the order that the open-parentheses appear in the regular expression. So you can use ‘\1’ through ‘\9’ to refer to the text matched by the corresponding ‘\( … \)’ constructs.

For example, ‘\(.*\)\1’ matches any newline-free string that is composed of two identical halves. The ‘\(.*\)’ matches the first half, which may be anything, but the ‘\1’ that follows must match the same exact text.

If a particular ‘\( … \)’ construct matches more than once (which can easily happen if it is followed by ‘*’), only the last match is recorded.

\`

matches the empty string, but only at the beginning of the string or buffer (or its accessible portion) being matched against.

\'

matches the empty string, but only at the end of the string or buffer (or its accessible portion) being matched against.

\=

matches the empty string, but only at point.

\b

matches the empty string, but only at the beginning or end of a word. Thus, ‘\bfoo\b’ matches any occurrence of ‘foo’ as a separate word. ‘\bballs?\b’ matches ‘ball’ or ‘balls’ as a separate word.

\b’ matches at the beginning or end of the buffer regardless of what text appears next to it.

\B

matches the empty string, but not at the beginning or end of a word.

\<

matches the empty string, but only at the beginning of a word. ‘\<’ matches at the beginning of the buffer only if a word-constituent character follows.

\>

matches the empty string, but only at the end of a word. ‘\>’ matches at the end of the buffer only if the contents end with a word-constituent character.

\w

matches any word-constituent character. The syntax table determines which characters these are. See Syntax Tables in The Emacs Lisp Reference Manual.

\W

matches any character that is not a word-constituent.

\_<

matches the empty string, but only at the beginning of a symbol. A symbol is a sequence of one or more symbol-constituent characters. A symbol-constituent character is a character whose syntax is either ‘w’ or ‘_’. ‘\_<’ matches at the beginning of the buffer only if a symbol-constituent character follows. As with words, the syntax table determines which characters are symbol-constituent.

\_>

matches the empty string, but only at the end of a symbol. ‘\_>’ matches at the end of the buffer only if the contents end with a symbol-constituent character.

\sc

matches any character whose syntax is c. Here c is a character that designates a particular syntax class: thus, ‘w’ for word constituent, ‘-’ or ‘ ’ for whitespace, ‘.’ for ordinary punctuation, etc. See Syntax Class Table in The Emacs Lisp Reference Manual.

\Sc

matches any character whose syntax is not c.

\cc

matches any character that belongs to the category c. For example, ‘\cc’ matches Chinese characters, ‘\cg’ matches Greek characters, etc. For the description of the known categories, type M-x describe-categories RET.

\Cc

matches any character that does not belong to category c.

The constructs that pertain to words and syntax are controlled by the setting of the syntax table. See Syntax Tables in The Emacs Lisp Reference Manual.

Next: , Previous: , Up: Search   [Contents][Index]

15.8Regular Expression Example

Here is an example of a regexp—similar to the regexp that Emacs uses, by default, to recognize the end of a sentence, not including the following space (i.e., the variable sentence-end-base):

[.?!][]\"')}]*

This contains two parts in succession: a character set matching period, ‘?’, or ‘!’, and a character set matching close-brackets, quotes, or parentheses, repeated zero or more times.

Next: , Previous: , Up: Search   [Contents][Index]

15.9Lax Matching During Searching

Normally, you’d want search commands to disregard certain minor differences between the search string you type and the text being searched. For example, sequences of whitespace characters of different length are usually perceived as equivalent; letter-case differences usually don’t matter; etc. This is known as character equivalence.

This section describes the Emacs lax search features, and how to tailor them to your needs.

By default, search commands perform lax space matching: each space, or sequence of spaces, matches any sequence of one or more whitespace characters in the text. (Incremental regexp search has a separate default; see Regexp Search.) Hence, ‘foo bar matches ‘foo bar, ‘foo  bar, ‘foo   bar, and so on (but not ‘foobar’). More precisely, Emacs matches each sequence of space characters in the search string to a regular expression specified by the variable search-whitespace-regexp. For example, to make spaces match sequences of newlines as well as spaces, set it to ‘"[[:space:]\n]+"’. The default value of this variable depends on the buffer’s major mode; most major modes classify spaces, tabs, and formfeed characters as whitespace.

If you want whitespace characters to match exactly, you can turn lax space matching off by typing M-s SPC (isearch-toggle-lax-whitespace) within an incremental search. Another M-s SPC turns lax space matching back on. To disable lax whitespace matching for all searches, change search-whitespace-regexp to nil; then each space in the search string matches exactly one space.

Searches in Emacs by default ignore the case of the text they are searching through, if you specify the search string in lower case. Thus, if you specify searching for ‘foo’, then ‘Foo’ and ‘fOO’ also match. Regexps, and in particular character sets, behave likewise: ‘[ab]’ matches ‘a’ or ‘A’ or ‘b’ or ‘B’. This feature is known as case folding, and it is supported in both incremental and non-incremental search modes.

An upper-case letter anywhere in the search string makes the search case-sensitive. Thus, searching for ‘Foo’ does not find ‘foo’ or ‘FOO’. This applies to regular expression search as well as to literal string search. The effect ceases if you delete the upper-case letter from the search string. The variable search-upper-case controls this: if it is non-nil, an upper-case character in the search string makes the search case-sensitive; setting it to nil disables this effect of upper-case characters. The default value of this variable is not-yanks, which makes search case-sensitive if there are upper-case letters in the search string, and also causes text yanked into the search string (see Isearch Yank) to be down-cased, so that such searches are case-insensitive by default.

If you set the variable case-fold-search to nil, then all letters must match exactly, including case. This is a per-buffer variable; altering the variable normally affects only the current buffer, unless you change its default value. See Locals. This variable applies to nonincremental searches also, including those performed by the replace commands (see Replace) and the minibuffer history matching commands (see Minibuffer History).

Typing M-c or M-s c (isearch-toggle-case-fold) within an incremental search toggles the case sensitivity of that search. The effect does not extend beyond the current incremental search, but it does override the effect of adding or removing an upper-case letter in the current search.

Several related variables control case-sensitivity of searching and matching for specific commands or activities. For instance, tags-case-fold-search controls case sensitivity for find-tag. To find these variables, do M-x apropos-variable RET case-fold-search RET.

Case folding disregards case distinctions among characters, making upper-case characters match lower-case variants, and vice versa. A generalization of case folding is character folding, which disregards wider classes of distinctions among similar characters. For instance, under character folding the letter a matches all of its accented cousins like ä and á, i.e., the match disregards the diacritics that distinguish these variants. In addition, a matches other characters that resemble it, or have it as part of their graphical representation, such as U+249C PARENTHESIZED LATIN SMALL LETTER A and U+2100 ACCOUNT OF (which looks like a small a over c). Similarly, the ASCII double-quote character " matches all the other variants of double quotes defined by the Unicode standard. Finally, character folding can make a sequence of one or more characters match another sequence of a different length: for example, the sequence of two characters ff matches U+FB00 LATIN SMALL LIGATURE FF. Character sequences that are not identical, but match under character folding are known as equivalent character sequences.

Generally, search commands in Emacs do not by default perform character folding in order to match equivalent character sequences. You can enable this behavior by customizing the variable search-default-mode to char-fold-to-regexp. See Search Customizations. Within an incremental search, typing M-s ' (isearch-toggle-char-fold) toggles character folding, but only for that search. (Replace commands have a different default, controlled by a separate option; see Replacement and Lax Matches.)

By default, typing an explicit variant of a character, such as ä, as part of the search string doesn’t match its base character, such as a. But if you customize the variable char-fold-symmetric to t, then search commands treat equivalent characters the same and use of any of a set of equivalent characters in a search string finds any of them in the text being searched, so typing an accented character ä matches the letter a as well as all the other variants like á.

You can add new foldings using the customizable variable char-fold-include, or remove the existing ones using the customizable variable char-fold-exclude.

Next: , Previous: , Up: Search   [Contents][Index]

15.10Replacement Commands

Emacs provides several commands for performing search-and-replace operations. In addition to the simple M-x replace-string command, there is M-% (query-replace), which presents each occurrence of the search pattern and asks you whether to replace it.

The replace commands normally operate on the text from point to the end of the buffer. When the region is active, they operate on it instead (see Mark). The basic replace commands replace one search string (or regexp) with one replacement string. It is possible to perform several replacements in parallel, using the command expand-region-abbrevs (see Expanding Abbrevs).

15.10.1 Unconditional Replacement

M-x replace-string RET string RET newstring RET

Replace every occurrence of string with newstring.

To replace every instance of ‘foo’ after point with ‘bar’, use the command M-x replace-string with the two arguments ‘foo’ and ‘bar’. Replacement happens only in the text after point, so if you want to cover the whole buffer you must go to the beginning first. All occurrences up to the end of the buffer are replaced; to limit replacement to part of the buffer, activate the region around that part. When the region is active, replacement is limited to the region (see Mark).

When replace-string exits, it leaves point at the last occurrence replaced. It adds the prior position of point (where the replace-string command was issued) to the mark ring, without activating the mark; use C-u C-SPC to move back there. See Mark Ring.

A prefix argument restricts replacement to matches that are surrounded by word boundaries.

See Replacement and Lax Matches, for details about case-sensitivity and character folding in replace commands.

15.10.2 Regexp Replacement

The M-x replace-string command replaces exact matches for a single string. The similar command M-x replace-regexp replaces any match for a specified regular expression pattern (see Regexps).

M-x replace-regexp RET regexp RET newstring RET

Replace every match for regexp with newstring.

In replace-regexp, the newstring need not be constant: it can refer to all or part of what is matched by the regexp. ‘\&’ in newstring stands for the entire match being replaced. ‘\d’ in newstring, where d is a digit starting from 1, stands for whatever matched the dth parenthesized grouping in regexp. (This is called a “back reference”.) ‘\#’ refers to the count of replacements already made in this command, as a decimal number. In the first replacement, ‘\#’ stands for ‘0’; in the second, for ‘1’; and so on. 例如,

M-x replace-regexp RET c[ad]+r RET \&-safe RET

replaces (for example) ‘cadr’ with ‘cadr-safe’ and ‘cddr’ with ‘cddr-safe’.

M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET

performs the inverse transformation. To include a ‘\’ in the text to replace with, you must enter ‘\\’.

If you want to enter part of the replacement string by hand each time, use ‘\?’ in the replacement string. Each replacement will ask you to edit the replacement string in the minibuffer, putting point where the ‘\?’ was.

The remainder of this subsection is intended for specialized tasks and requires knowledge of Lisp. Most readers can skip it.

You can use Lisp expressions to calculate parts of the replacement string. To do this, write ‘\,’ followed by the expression in the replacement string. Each replacement calculates the value of the expression and converts it to text without quoting (if it’s a string, this means using the string’s contents), and uses it in the replacement string in place of the expression itself. If the expression is a symbol, one space in the replacement string after the symbol name goes with the symbol name, so the value replaces them both.

Inside such an expression, you can use some special sequences. ‘\&’ and ‘\d’ refer here, as usual, to the entire match as a string, and to a submatch as a string. d may be multiple digits, and the value of ‘\d’ is nil if the d’th parenthesized grouping did not match. You can also use ‘\#&’ and ‘\#d’ to refer to those matches as numbers (this is valid when the match or submatch has the form of a numeral). ‘\#’ here too stands for the number of already-completed replacements.

For example, we can exchange ‘x’ and ‘y’ this way:

M-x replace-regexp RET \(x\)\|y RET
\,(if \1 "y" "x") RET

For computing replacement strings for ‘\,’, the format function is often useful (see Formatting Strings in The Emacs Lisp Reference Manual). For example, to add consecutively numbered strings like ‘ABC00042’ to columns 73 to 80 (unless they are already occupied), you can use

M-x replace-regexp RET ^.\{0,72\}$ RET
\,(format "%-72sABC%05d" \& \#) RET

Next: , Previous: , Up: Replace   [Contents][Index]

15.10.3 Replace Commands and Lax Matches

This subsection describes the behavior of replace commands with respect to lax matches (see Lax Search) and how to customize it. In general, replace commands mostly default to stricter matching than their search counterparts.

Unlike incremental search, the replacement commands do not use lax space matching (see lax space matching) by default. To enable lax space matching for replacement, change the variable replace-lax-whitespace to non-nil. (This only affects how Emacs finds the text to replace, not the replacement text.)

A companion variable replace-regexp-lax-whitespace controls whether query-replace-regexp uses lax whitespace matching when searching for patterns.

If the first argument of a replace command is all lower case, the command ignores case while searching for occurrences to replace—provided case-fold-search is non-nil and search-upper-case is also non-nil. If search-upper-case (see search-upper-case) is nil, whether searching ignores case is determined by case-fold-search alone, regardless of letter-case of the command’s first argument. If case-fold-search is set to nil, case is always significant in all searches.

In addition, when the newstring argument is all or partly lower case, replacement commands try to preserve the case pattern of each occurrence. Thus, the command

M-x replace-string RET foo RET bar RET

replaces a lower case ‘foo’ with a lower case ‘bar’, an all-caps ‘FOO’ with ‘BAR’, and a capitalized ‘Foo’ with ‘Bar’. (These three alternatives—lower case, all caps, and capitalized, are the only ones that replace-string can distinguish.)

If upper-case letters are used in the replacement string, they remain upper case every time that text is inserted. If upper-case letters are used in the first argument, the second argument is always substituted exactly as given, with no case conversion. Likewise, if either case-replace or case-fold-search is set to nil, replacement is done without case conversion.

The replacement commands by default do not use character folding (see character folding) when looking for the text to replace. To enable character folding for matching in query-replace and replace-string, set the variable replace-char-fold to a non-nil value. (This setting does not affect the replacement text, only how Emacs finds the text to replace. It also doesn’t affect replace-regexp.)

15.10.4 Query Replace

M-% string RET newstring RET

Replace some occurrences of string with newstring.

C-M-% regexp RET newstring RET

Replace some matches for regexp with newstring.

If you want to change only some of the occurrences of ‘foo’ to ‘bar’, not all of them, use M-% (query-replace). This command finds occurrences of ‘foo’ one by one, displays each occurrence and asks you whether to replace it. Aside from querying, query-replace works just like replace-string (see Unconditional Replace). In particular, it preserves case provided case-replace is non-nil, as it normally is (see Replacement and Lax Matches). A numeric argument means to consider only occurrences that are bounded by word-delimiter characters. A negative prefix argument replaces backward.

C-M-% performs regexp search and replace (query-replace-regexp). It works like replace-regexp except that it queries like query-replace.

You can reuse earlier replacements with these commands. When query-replace or query-replace-regexp prompts for the search string, use M-p and M-n to show previous replacements in the form ‘from -> to’, where from is the search pattern, to is its replacement, and the separator between them is determined by the value of the variable query-replace-from-to-separator. Type RET to select the desired replacement. If the value of this variable is nil, replacements are not added to the command history, and cannot be reused.

These commands highlight the current match using the face query-replace. You can disable this highlight by setting the variable query-replace-highlight to nil. They highlight other matches using lazy-highlight just like incremental search (see Incremental Search); this can be disabled by setting query-replace-lazy-highlight to nil. By default, query-replace-regexp will show the substituted replacement string for the current match in the minibuffer. If you want to keep special sequences ‘\&’ and ‘\n’ unexpanded, customize query-replace-show-replacement variable.

The variable query-replace-skip-read-only, if set non-nil, will cause replacement commands to ignore matches in read-only text. The default is not to ignore them.

The characters you can type when you are shown a match for the string or regexp are:

SPC
y

to replace the occurrence with newstring.

DEL
Delete
BACKSPACE
n

to skip to the next occurrence without replacing this one.

, (Comma)

to replace this occurrence and display the result. You are then asked for another input character to say what to do next. Since the replacement has already been made, DEL and SPC are equivalent in this situation; both move to the next occurrence.

You can type C-r at this point (see below) to alter the replaced text. You can also undo the replacement with the undo command (e.g., type C-x u; see Undo); this exits the query-replace, so if you want to do further replacement you must use C-x ESC ESC RET to restart (see Repetition).

RET
q

to exit without doing any more replacements.

. (Period)

to replace this occurrence and then exit without searching for more occurrences.

!

to replace all remaining occurrences without asking again.

^

to go back to the position of the previous occurrence (or what used to be an occurrence), in case you changed it by mistake or want to reexamine it.

u

to undo the last replacement and go back to where that replacement was made.

U

to undo all the replacements and go back to where the first replacement was made.

C-r

to enter a recursive editing level, in case the occurrence needs to be edited rather than just replaced with newstring. When you are done, exit the recursive editing level with C-M-c to proceed to the next occurrence. See Recursive Edit.

C-w

to delete the occurrence, and then enter a recursive editing level as in C-r. Use the recursive edit to insert text to replace the deleted occurrence of string. When done, exit the recursive editing level with C-M-c to proceed to the next occurrence.

e

to edit the replacement string in the minibuffer. When you exit the minibuffer by typing RET, the minibuffer contents replace the current occurrence of the pattern. They also become the new replacement string for any further occurrences.

C-l

to redisplay the screen. Then you must type another character to specify what to do with this occurrence.

Y (Upper-case)

to replace all remaining occurrences in all remaining buffers in multi-buffer replacements (like the Dired Q command that performs query replace on selected files). It answers this question and all subsequent questions in the series with “yes”, without further user interaction.

N (Upper-case)

to skip to the next buffer in multi-buffer replacements without replacing remaining occurrences in the current buffer. It answers this question “no”, gives up on the questions for the current buffer, and continues to the next buffer in the sequence.

C-h
?
F1

to display a message summarizing these options. Then you must type another character to specify what to do with this occurrence.

Aside from this, any other character exits the query-replace, and is then reread as part of a key sequence. Thus, if you type C-k, it exits the query-replace and then kills to end of line. In particular, C-g simply exits the query-replace.

To restart a query-replace once it is exited, use C-x ESC ESC, which repeats the query-replace because it used the minibuffer to read its arguments. See C-x ESC ESC.

The option search-invisible determines how query-replace treats invisible text. See Outline Search.

See Operating on Files, for the Dired Q command which performs query replace on selected files. See also Transforming File Names, for Dired commands to rename, copy, or link files by replacing regexp matches in file names.

Next: , Previous: , Up: Search   [Contents][Index]

15.11Other Search-and-Loop Commands

Here are some other commands that find matches for a regular expression. They all ignore case in matching, if the pattern contains no upper-case letters and case-fold-search is non-nil. Aside from multi-occur and multi-occur-in-matching-buffers, which always search the whole buffer, all operate on the text from point to the end of the buffer, or on the region if it is active.

M-x multi-isearch-buffers

Prompt for one or more buffer names, ending with RET; then, begin a multi-buffer incremental search in those buffers. (If the search fails in one buffer, the next C-s tries searching the next specified buffer, and so forth.) With a prefix argument, prompt for a regexp and begin a multi-buffer incremental search in buffers matching that regexp.

M-x multi-isearch-buffers-regexp

This command is just like multi-isearch-buffers, except it performs an incremental regexp search.

M-x multi-isearch-files

Prompt for one or more file names, ending with RET; then, begin a multi-file incremental search in those files. (If the search fails in one file, the next C-s tries searching the next specified file, and so forth.) With a prefix argument, prompt for a regexp and begin a multi-file incremental search in files matching that regexp.

M-x multi-isearch-files-regexp

This command is just like multi-isearch-files, except it performs an incremental regexp search.

In some modes that set the buffer-local variable multi-isearch-next-buffer-function (e.g., in Change Log mode) a multi-file incremental search is activated automatically.

M-x occur
M-s o

Prompt for a regexp, and display a list showing each line in the buffer that contains a match for it. If you type M-n at the prompt, you can reuse search strings from previous incremental searches. The text that matched is highlighted using the match face. A numeric argument n specifies that n lines of context are to be displayed before and after each matching line.

The default number of context lines is specified by the variable list-matching-lines-default-context-lines. When list-matching-lines-jump-to-current-line is non-nil the current line is shown highlighted with face list-matching-lines-current-line-face and the point is set at the first match after such line.

You can also run M-s o when an incremental search is active; this uses the current search string.

Note that matches for the regexp you type are extended to include complete lines, and a match that starts before the previous match ends is not considered a match.

In the *Occur* buffer, you can click on each entry, or move point there and type RET, to visit the corresponding position in the buffer that was searched. o and C-o display the match in another window; C-o does not select it. Alternatively, you can use the M-g M-n (next-error) command to visit the occurrences one by one (see Compilation Mode).

Typing e in the *Occur* buffer switches to Occur Edit mode, in which edits made to the entries are also applied to the text in the originating buffer. Type C-c C-c to return to Occur mode.

The command M-x list-matching-lines is a synonym for M-x occur.

M-x multi-occur

This command is just like occur, except it is able to search through multiple buffers. It asks you to specify the buffer names one by one.

M-x multi-occur-in-matching-buffers

This command is similar to multi-occur, except the buffers to search are specified by a regular expression that matches visited file names. With a prefix argument, it uses the regular expression to match buffer names instead.

M-x how-many

Prompt for a regexp, and print the number of matches for it in the buffer after point. If the region is active, this operates on the region instead.

M-x flush-lines

Prompt for a regexp, and delete each line that contains a match for it, operating on the text after point. When the command finishes, it prints the number of deleted matching lines.

This command deletes the current line if it contains a match starting after point. If the region is active, it operates on the region instead; if a line partially contained in the region contains a match entirely contained in the region, it is deleted.

If a match is split across lines, flush-lines deletes all those lines. It deletes the lines before starting to look for the next match; hence, it ignores a match starting on the same line at which another match ended.

M-x keep-lines

Prompt for a regexp, and delete each line that does not contain a match for it, operating on the text after point. If point is not at the beginning of a line, this command always keeps the current line. If the region is active, the command operates on the region instead; it never deletes lines that are only partially contained in the region (a newline that ends a line counts as part of that line).

If a match is split across lines, this command keeps all those lines.

15.12Tailoring Search to Your Needs

This section describes miscellaneous search-related customizations not described elsewhere.

The default search mode for the incremental search is specified by the variable search-default-mode. It can be nil, t, or a function. If it is nil, the default mode is to do literal searches without character folding, but with case folding and lax-whitespace matches as determined by case-fold-search and search-whitespace-regexp, respectively (see Lax Search). If the value is t, incremental search defaults to regexp searches. The default value specifies a function that only performs case folding and lax-whitespace matching.

The current match of an on-going incremental search is highlighted using the isearch face. This highlighting can be disabled by setting the variable search-highlight to nil.

The other matches for the search string that are visible on display are highlighted using the lazy-highlight face. Setting the variable isearch-lazy-highlight to nil disables this highlighting. Here are some other variables that customize the lazy highlighting:

lazy-highlight-initial-delay

Time in seconds to wait before highlighting visible matches.

lazy-highlight-interval

Time in seconds between highlighting successive matches.

lazy-highlight-max-at-a-time

The maximum number of matches to highlight before checking for input. A large number can take some time to highlight, so if you want to continue searching and type C-s or C-r during that time, Emacs will not respond until it finishes highlighting all those matches. Thus, smaller values make Emacs more responsive.

isearch-lazy-count

Show the current match number and the total number of matches in the search prompt.

lazy-count-prefix-format
lazy-count-suffix-format

These two variables determine the format of showing the current and the total number of matches for isearch-lazy-count.

Normally, entering RET within incremental search when the search string is empty launches a nonincremental search. (Actually, it lets you edit the search string, and the next RET does the search.) However, if you customize the variable search-nonincremental-instead to nil, typing RET will always exit the incremental search, even if the search string is empty.

By default, incremental search and query-replace commands match invisible text, but hide any such matches as soon as the current match moves off the invisible text. If you customize the variable isearch-hide-immediately to nil, any invisible text where matches were found stays on display until the search or the replace command exits.

Searching incrementally on slow terminals, such as displays connected to remote machines over slow connection, could be annoying due to the need to redraw large portions of the display as the search proceeds. Emacs provides a special display mode for slow terminals, whereby search pops up a separate small window and displays the text surrounding the match in that window. Small windows display faster, so the annoying effect of slow speed is alleviated. The variable search-slow-speed determines the baud rate threshold below which Emacs will use this display mode. The variable search-slow-window-lines controls the number of lines in the window Emacs pops up for displaying the search results; the default is 1 line. Normally, this window will pop up at the bottom of the window that displays the buffer where you start searching, but if the value of search-slow-window-lines is negative, that means to put the window at the top and give it the number of lines that is the absolute value of search-slow-window-lines.


Next: , Previous: , Up: Top   [Contents][Index]

16Commands for Fixing Typos

In this chapter we describe commands that are useful when you catch a mistake while editing. The most fundamental of these commands is the undo command C-/ (also bound to C-x u and C-_). This undoes a single command, or a part of a command (as in the case of query-replace), or several consecutive character insertions. Consecutive repetitions of C-/ undo earlier and earlier changes, back to the limit of the undo information available.

Aside from the commands described here, you can erase text using deletion commands such as DEL (delete-backward-char). These were described earlier in this manual. See Erasing.

Next: , Up: Fixit   [Contents][Index]

16.1Undo

The undo command reverses recent changes in the buffer’s text. Each buffer records changes individually, and the undo command always applies to the current buffer. You can undo all the changes in a buffer for as far back as the buffer’s records go. Usually, each editing command makes a separate entry in the undo records, but some commands such as query-replace divide their changes into multiple entries for flexibility in undoing. Consecutive character insertion commands are usually grouped together into a single undo record, to make undoing less tedious.

C-/
C-x u
C-_

Undo one entry in the current buffer’s undo records (undo).

To begin to undo, type C-/ (or its aliases, C-_ or C-x u)6. This undoes the most recent change in the buffer, and moves point back to where it was before that change. Consecutive repetitions of C-/ (or its aliases) undo earlier and earlier changes in the current buffer. If all the recorded changes have already been undone, the undo command signals an error.

Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the entire sequence of undo commands that you have just performed are themselves placed into the undo record. Therefore, to re-apply changes you have undone, type C-f or any other command that harmlessly breaks the sequence of undoing; then type C-/ one or more times to undo some of the undo commands.

Alternatively, if you want to resume undoing, without redoing previous undo commands, use M-x undo-only. This is like undo, but will not redo changes you have just undone.

If you notice that a buffer has been modified accidentally, the easiest way to recover is to type C-/ repeatedly until the stars disappear from the front of the mode line (see Mode Line). Whenever an undo command makes the stars disappear from the mode line, it means that the buffer contents are the same as they were when the file was last read in or saved. If you do not remember whether you changed the buffer deliberately, type C-/ once. When you see the last change you made undone, you will see whether it was an intentional change. If it was an accident, leave it undone. If it was deliberate, redo the change as described above.

Alternatively, you can discard all the changes since the buffer was last visited or saved with M-x revert-buffer (see Reverting).

When there is an active region, any use of undo performs selective undo: it undoes the most recent change within the region, instead of the entire buffer. However, when Transient Mark mode is off (see Disabled Transient Mark), C-/ always operates on the entire buffer, ignoring the region. In this case, you can perform selective undo by supplying a prefix argument to the undo command: C-u C-/. To undo further changes in the same region, repeat the undo command (no prefix argument is needed).

Some specialized buffers do not make undo records. Buffers whose names start with spaces never do; these buffers are used internally by Emacs to hold text that users don’t normally look at or edit.

When the undo information for a buffer becomes too large, Emacs discards the oldest records from time to time (during garbage collection). You can specify how much undo information to keep by setting the variables undo-limit, undo-strong-limit, and undo-outer-limit. Their values are expressed in bytes.

The variable undo-limit sets a soft limit: Emacs keeps undo data for enough commands to reach this size, and perhaps exceed it, but does not keep data for any earlier commands beyond that. Its default value is 160000. The variable undo-strong-limit sets a stricter limit: any previous command (though not the most recent one) that pushes the size past this amount is forgotten. The default value of undo-strong-limit is 240000.

Regardless of the values of those variables, the most recent change is never discarded unless it gets bigger than undo-outer-limit (normally 24,000,000). At that point, Emacs discards the undo data and warns you about it. This is the only situation in which you cannot undo the last command. If this happens, you can increase the value of undo-outer-limit to make it even less likely to happen in the future. But if you didn’t expect the command to create such large undo data, then it is probably a bug and you should report it. See Reporting Bugs.

Next: , Previous: , Up: Fixit   [Contents][Index]

16.2Transposing Text

C-t

Transpose two characters (transpose-chars).

M-t

Transpose two words (transpose-words).

C-M-t

Transpose two balanced expressions (transpose-sexps).

C-x C-t

Transpose two lines (transpose-lines).

M-x transpose-sentences

Transpose two sentences (transpose-sentences).

M-x transpose-paragraphs

Transpose two paragraphs (transpose-paragraphs).

M-x transpose-regions

Transpose two regions.

The common error of transposing two characters can be fixed, when they are adjacent, with the C-t command (transpose-chars). Normally, C-t transposes the two characters on either side of point. When given at the end of a line, rather than transposing the last character of the line with the newline, which would be useless, C-t transposes the last two characters on the line. So, if you catch your transposition error right away, you can fix it with just a C-t. If you don’t catch it so fast, you must move the cursor back between the two transposed characters before you type C-t. If you transposed a space with the last character of the word before it, the word motion commands (M-f, M-b, etc.) are a good way of getting there. Otherwise, a reverse search (C-r) is often the best way. See Search.

M-t transposes the word before point with the word after point (transpose-words). It moves point forward over a word, dragging the word preceding or containing point forward as well. The punctuation characters between the words do not move. For example, ‘FOO, BAR transposes into ‘BAR, FOO rather than ‘BAR FOO,. When point is at the end of the line, it will transpose the word before point with the first word on the next line.

C-M-t (transpose-sexps) is a similar command for transposing two expressions (see Expressions), and C-x C-t (transpose-lines) exchanges lines. M-x transpose-sentences and M-x transpose-paragraphs transpose sentences and paragraphs, respectively. These commands work like M-t except as regards the units of text they transpose.

A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (or word or expression or line) before or containing point across several other characters (or words or expressions or lines). For example, C-u 3 C-t moves the character before point forward across three other characters. It would change ‘f∗oobar’ into ‘oobf∗ar’. This is equivalent to repeating C-t three times. C-u - 4 M-t moves the word before point backward across four words. C-u - C-M-t would cancel the effect of plain C-M-t.

A numeric argument of zero is assigned a special meaning (because otherwise a command with a repeat count of zero would do nothing): to transpose the character (or word or expression or line) ending after point with the one ending after the mark.

M-x transpose-regions transposes the text between point and mark with the text between the last two marks pushed to the mark ring (see Setting Mark). With a numeric prefix argument, it transposes the text between point and mark with the text between two successive marks that many entries back in the mark ring. This command is best used for transposing multiple characters (or words or sentences or paragraphs) in one go.

Next: , Previous: , Up: Fixit   [Contents][Index]

16.3Case Conversion

M-- M-l

Convert last word to lower case. Note Meta-- is Meta-minus.

M-- M-u

Convert last word to all upper case.

M-- M-c

Convert last word to lower case with capital initial.

A very common error is to type words in the wrong case. Because of this, the word case-conversion commands M-l, M-u, and M-c have a special feature when used with a negative argument: they do not move the cursor. As soon as you see you have mistyped the last word, you can simply case-convert it and go on typing. See Case.

Previous: , Up: Fixit   [Contents][Index]

16.4Checking and Correcting Spelling

This section describes the commands to check the spelling of a single word or of a portion of a buffer. These commands only work if a spelling checker program, one of Hunspell, Aspell, Ispell or Enchant, is installed. These programs are not part of Emacs, but one of them is usually installed on GNU/Linux and other free operating systems. See Aspell in The Aspell Manual.

M-$

Check and correct spelling of the word at point (ispell-word). If the region is active, do it for all words in the region instead.

M-x ispell

Check and correct spelling of all words in the buffer. If the region is active, do it for all words in the region instead.

M-x ispell-buffer

Check and correct spelling in the buffer.

M-x ispell-region

Check and correct spelling in the region.

M-x ispell-message

Check and correct spelling in a draft mail message, excluding cited material.

M-x ispell-change-dictionary RET dict RET

Restart the spell-checker process, using dict as the dictionary.

M-x ispell-kill-ispell

Kill the spell-checker subprocess.

M-TAB
ESC TAB
C-M-i

Complete the word before point based on the spelling dictionary (ispell-complete-word).

M-x flyspell-mode

Enable Flyspell mode, which highlights all misspelled words.

M-x flyspell-prog-mode

Enable Flyspell mode for comments and strings only.

To check the spelling of the word around or before point, and optionally correct it as well, type M-$ (ispell-word). If a region is active, M-$ checks the spelling of all words within the region. See Mark. (When Transient Mark mode is off, M-$ always acts on the word around or before point, ignoring the region; see Disabled Transient Mark.)

Similarly, the command M-x ispell performs spell-checking in the region if one is active, or in the entire buffer otherwise. The commands M-x ispell-buffer and M-x ispell-region explicitly perform spell-checking on the entire buffer or the region respectively. To check spelling in an email message you are writing, use M-x ispell-message; that command checks the whole buffer, except for material that is indented or appears to be cited from other messages. See Sending Mail.

When one of these commands encounters what appears to be an incorrect word, it asks you what to do. It usually displays a list of numbered near-misses—words that are close to the incorrect word. Then you must type a single-character response. Here are the valid responses:

digit

Replace the word, just this time, with one of the displayed near-misses. Each near-miss is listed with a digit; type that digit to select it.

SPC

Skip this word—continue to consider it incorrect, but don’t change it here.

r new RET

Replace the word, just this time, with new. (The replacement string will be rescanned for more spelling errors.)

R new RET

Replace the word with new, and do a query-replace so you can replace it elsewhere in the buffer if you wish. (The replacements will be rescanned for more spelling errors.)

a

Accept the incorrect word—treat it as correct, but only in this editing session.

A

Accept the incorrect word—treat it as correct, but only in this editing session and for this buffer.

i

Insert this word in your private dictionary file so that it will be considered correct from now on, even in future sessions.

m

Like i, but you can also specify dictionary completion information.

u

Insert the lower-case version of this word in your private dictionary file.

l word RET

Look in the dictionary for words that match word. These words become the new list of near-misses; you can select one of them as the replacement by typing a digit. You can use ‘*’ in word as a wildcard.

C-g
X

Quit interactive spell-checking, leaving point at the word that was being checked. You can restart checking again afterward with C-u M-$.

x

Quit interactive spell-checking and move point back to where it was when you started spell-checking.

q

Quit interactive spell-checking and kill the spell-checker subprocess.

?

Show the list of options.

In Text mode and related modes, M-TAB (ispell-complete-word) performs in-buffer completion based on spelling correction. Insert the beginning of a word, and then type M-TAB; this shows a list of completions. (If your window manager intercepts M-TAB, type ESC TAB or C-M-i.) Each completion is listed with a digit or character; type that digit or character to choose it.

Once started, the spell-checker subprocess continues to run, waiting for something to do, so that subsequent spell-checking commands complete more quickly. If you want to get rid of the process, use M-x ispell-kill-ispell. This is not usually necessary, since the process uses no processor time except when you do spelling correction.

Spell-checkers look up spelling in two dictionaries: the standard dictionary and your personal dictionary. The standard dictionary is specified by the variable ispell-local-dictionary or, if that is nil, by the variable ispell-dictionary. If both are nil, the spelling program’s default dictionary is used. The command M-x ispell-change-dictionary sets the standard dictionary for the buffer and then restarts the subprocess, so that it will use a different standard dictionary. Your personal dictionary is specified by the variable ispell-personal-dictionary. If that is nil, the spelling program looks for a personal dictionary in a default location, which is specific to each spell-checker.

A separate dictionary is used for word completion. The variable ispell-complete-word-dict specifies the file name of this dictionary. The completion dictionary must be different because it cannot use the information about roots and affixes of the words, which spell-checking uses to detect variations of words. For some languages, there is a spell-checking dictionary but no word completion dictionary.

Flyspell mode is a minor mode that performs automatic spell-checking of the text you type as you type it. When it finds a word that it does not recognize, it highlights that word. Type M-x flyspell-mode to toggle Flyspell mode in the current buffer. To enable Flyspell mode in all text mode buffers, add flyspell-mode to text-mode-hook. See Hooks. Note that, as Flyspell mode needs to check each word across which you move, it will slow down cursor motion and scrolling commands. It also doesn’t automatically check the text you didn’t type or move across; use flyspell-region or flyspell-buffer for that.

When Flyspell mode highlights a word as misspelled, you can click on it with mouse-2 (flyspell-correct-word) to display a menu of possible corrections and actions. In addition, C-. or ESC-TAB (flyspell-auto-correct-word) will propose various successive corrections for the word at point, and C-c $ (flyspell-correct-word-before-point) will pop up a menu of possible corrections. Of course, you can always correct the misspelled word by editing it manually in any way you like.

Flyspell Prog mode works just like ordinary Flyspell mode, except that it only checks words in comments and string constants. This feature is useful for editing programs. Type M-x flyspell-prog-mode to enable or disable this mode in the current buffer. To enable this mode in all programming mode buffers, add flyspell-prog-mode to prog-mode-hook (see Hooks).


Next: , Previous: , Up: Top   [Contents][Index]

17 Keyboard Macros

In this chapter we describe how to record a sequence of editing commands so you can repeat it conveniently later.

A keyboard macro is a command defined by an Emacs user to stand for another sequence of keys. For example, if you discover that you are about to type C-n M-d C-d forty times, you can speed your work by defining a keyboard macro to do C-n M-d C-d, and then executing it 39 more times.

You define a keyboard macro by executing and recording the commands which are its definition. Put differently, as you define a keyboard macro, the definition is being executed for the first time. This way, you can see the effects of your commands, so that you don’t have to figure them out in your head. When you close the definition, the keyboard macro is defined and also has been, in effect, executed once. You can then do the whole thing over again by invoking the macro.

Keyboard macros differ from ordinary Emacs commands in that they are written in the Emacs command language rather than in Lisp. This makes it easier for the novice to write them, and makes them more convenient as temporary hacks. However, the Emacs command language is not powerful enough as a programming language to be useful for writing anything intelligent or general. For such things, Lisp must be used.

17.1 Basic Use

F3

Start defining a keyboard macro (kmacro-start-macro-or-insert-counter).

F4

If a keyboard macro is being defined, end the definition; otherwise, execute the most recent keyboard macro (kmacro-end-or-call-macro).

C-u F3

Re-execute last keyboard macro, then append keys to its definition.

C-u C-u F3

Append keys to the last keyboard macro without re-executing it.

C-x C-k r

Run the last keyboard macro on each line that begins in the region (apply-macro-to-region-lines).

C-x (

Start defining a keyboard macro (old style) (kmacro-start-macro); with a prefix argument, append keys to the last macro.

C-x )

End a macro definition (old style) (kmacro-end-macro); prefix argument serves as the repeat count for executing the macro.

C-x e

Execute the most recently defined keyboard macro (kmacro-end-and-call-macro); prefix argument serves as repeat count.

To start defining a keyboard macro, type F3. From then on, your keys continue to be executed, but also become part of the definition of the macro. ‘Def’ appears in the mode line to remind you of what is going on. When you are finished, type F4 (kmacro-end-or-call-macro) to terminate the definition. 例如,

F3 M-f foo F4

defines a macro to move forward a word and then insert ‘foo’. Note that F3 and F4 do not become part of the macro.

After defining the macro, you can call it with F4. For the above example, this has the same effect as typing M-f foo again. (Note the two roles of the F4 command: it ends the macro if you are in the process of defining one, or calls the last macro otherwise.) You can also supply F4 with a numeric prefix argument ‘n’, which means to invoke the macro ‘n’ times. An argument of zero repeats the macro indefinitely, until it gets an error or you type C-g (or, on MS-DOS, C-BREAK).

The above example demonstrates a handy trick that you can employ with keyboard macros: if you wish to repeat an operation at regularly spaced places in the text, include a motion command as part of the macro. In this case, repeating the macro inserts the string ‘foo’ after each successive word.

After terminating the definition of a keyboard macro, you can append more keystrokes to its definition by typing C-u F3. This is equivalent to plain F3 followed by retyping the whole definition so far. As a consequence, it re-executes the macro as previously defined. If you change the variable kmacro-execute-before-append to nil, the existing macro will not be re-executed before appending to it (the default is t). You can also add to the end of the definition of the last keyboard macro without re-executing it by typing C-u C-u F3.

When a command reads an argument with the minibuffer, your minibuffer input becomes part of the macro along with the command. So when you replay the macro, the command gets the same argument as when you entered the macro. 例如,

F3 C-a C-k C-x b foo RET C-y C-x b RET F4

defines a macro that kills the current line, yanks it into the buffer ‘foo’, then returns to the original buffer.

Most keyboard commands work as usual in a keyboard macro definition, with some exceptions. Typing C-g (keyboard-quit) quits the keyboard macro definition. Typing C-M-c (exit-recursive-edit) can be unreliable: it works as you’d expect if exiting a recursive edit that started within the macro, but if it exits a recursive edit that started before you invoked the keyboard macro, it also necessarily exits the keyboard macro too. Mouse events are also unreliable, even though you can use them in a keyboard macro: when the macro replays the mouse event, it uses the original mouse position of that event, the position that the mouse had while you were defining the macro. The effect of this may be hard to predict.

The command C-x C-k r (apply-macro-to-region-lines) repeats the last defined keyboard macro on each line that begins in the region. It does this line by line, by moving point to the beginning of the line and then executing the macro.

In addition to the F3 and F4 commands described above, Emacs also supports an older set of key bindings for defining and executing keyboard macros. To begin a macro definition, type C-x ( (kmacro-start-macro); as with F3, a prefix argument appends this definition to the last keyboard macro. To end a macro definition, type C-x ) (kmacro-end-macro). To execute the most recent macro, type C-x e (kmacro-end-and-call-macro). If you enter C-x e while defining a macro, the macro is terminated and executed immediately. Immediately after typing C-x e, you can type e repeatedly to immediately repeat the macro one or more times. You can also give C-x e a repeat argument, just like F4 (when it is used to execute a macro).

C-x ) can be given a repeat count as an argument. This means to repeat the macro right after defining it. The macro definition itself counts as the first repetition, since it is executed as you define it, so C-u 4 C-x ) executes the macro immediately 3 additional times.

17.2 The Keyboard Macro Ring

All defined keyboard macros are recorded in the keyboard macro ring. There is only one keyboard macro ring, shared by all buffers.

C-x C-k C-k

Execute the keyboard macro at the head of the ring (kmacro-end-or-call-macro-repeat).

C-x C-k C-n

Rotate the keyboard macro ring to the next macro (defined earlier) (kmacro-cycle-ring-next).

C-x C-k C-p

Rotate the keyboard macro ring to the previous macro (defined later) (kmacro-cycle-ring-previous).

All commands which operate on the keyboard macro ring use the same C-x C-k prefix. Most of these commands can be executed and repeated immediately after each other without repeating the C-x C-k prefix. 例如,

C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d

will rotate the keyboard macro ring to the second-previous macro, execute the resulting head macro three times, rotate back to the original head macro, execute that once, rotate to the previous macro, execute that, and finally delete it from the macro ring.

The command C-x C-k C-k (kmacro-end-or-call-macro-repeat) executes the keyboard macro at the head of the macro ring. You can repeat the macro immediately by typing another C-k, or you can rotate the macro ring immediately by typing C-n or C-p.

When a keyboard macro is being defined, C-x C-k C-k behaves like F4 except that, immediately afterward, you can use most key bindings of this section without the C-x C-k prefix. For instance, another C-k will re-execute the macro.

The commands C-x C-k C-n (kmacro-cycle-ring-next) and C-x C-k C-p (kmacro-cycle-ring-previous) rotate the macro ring, bringing the next or previous keyboard macro to the head of the macro ring. The definition of the new head macro is displayed in the echo area. You can continue to rotate the macro ring immediately by repeating just C-n and C-p until the desired macro is at the head of the ring. To execute the new macro ring head immediately, just type C-k.

Note that Emacs treats the head of the macro ring as the last defined keyboard macro. For instance, F4 will execute that macro, and C-x C-k n will give it a name.

The maximum number of macros stored in the keyboard macro ring is determined by the customizable variable kmacro-ring-max.

17.3 The Keyboard Macro Counter

Each keyboard macro has an associated counter, which is initialized to 0 when you start defining the macro. This current counter allows you to insert a number into the buffer that depends on the number of times the macro has been called. The counter is normally incremented each time its value is inserted into the buffer.

In addition to the current counter, keyboard macros also maintain the previous counter, which records the value the current counter had last time it was incremented or set. Note that incrementing the current counter by zero, e.g., with C-u 0 C-x C-k C-i, also records the value of the current counter as the previous counter value.

F3

In a keyboard macro definition, insert the keyboard macro counter value in the buffer (kmacro-start-macro-or-insert-counter).

C-x C-k C-i

Insert the keyboard macro counter value in the buffer (kmacro-insert-counter).

C-x C-k C-c

Set the keyboard macro counter (kmacro-set-counter).

C-x C-k C-a

Add the prefix arg to the keyboard macro counter (kmacro-add-counter).

C-x C-k C-f

Specify the format for inserting the keyboard macro counter (kmacro-set-format).

When you are defining a keyboard macro, the command F3 (kmacro-start-macro-or-insert-counter) inserts the current value of the keyboard macro’s counter into the buffer, and increments the counter by 1. (If you are not defining a macro, F3 begins a macro definition instead. See Basic Keyboard Macro.) You can use a numeric prefix argument to specify a different increment. If you just specify a C-u prefix, that inserts the previous counter value, and doesn’t change the current value.

As an example, let us show how the keyboard macro counter can be used to build a numbered list. Consider the following key sequence:

F3 C-a F3 . SPC F4

As part of this keyboard macro definition, the string ‘0. ’ was inserted into the beginning of the current line. If you now move somewhere else in the buffer and type F4 to invoke the macro, the string ‘1. ’ is inserted at the beginning of that line. Subsequent invocations insert ‘2. ’, ‘3. ’, and so forth.

The command C-x C-k C-i (kmacro-insert-counter) does the same thing as F3, but it can be used outside a keyboard macro definition. When no keyboard macro is being defined or executed, it inserts and increments the counter of the macro at the head of the keyboard macro ring.

The command C-x C-k C-c (kmacro-set-counter) sets the current macro counter to the value of the numeric argument. If you use it inside the macro, it operates on each repetition of the macro. If you specify just C-u as the prefix, while executing the macro, that resets the counter to the value it had at the beginning of the current repetition of the macro (undoing any increments so far in this repetition).

The command C-x C-k C-a (kmacro-add-counter) adds the prefix argument to the current macro counter. With just C-u as argument, it resets the counter to the last value inserted by any keyboard macro. (Normally, when you use this, the last insertion will be in the same macro and it will be the same counter.)

The command C-x C-k C-f (kmacro-set-format) prompts for the format to use when inserting the macro counter. The default format is ‘%d’, which means to insert the number in decimal without any padding. You can exit with empty minibuffer to reset the format to this default. You can specify any format string that the format function accepts and that makes sense with a single integer extra argument (see Formatting Strings in The Emacs Lisp Reference Manual). Do not put the format string inside double quotes when you insert it in the minibuffer.

If you use this command while no keyboard macro is being defined or executed, the new format affects all subsequent macro definitions. Existing macros continue to use the format in effect when they were defined. If you set the format while defining a keyboard macro, this affects the macro being defined from that point on, but it does not affect subsequent macros. Execution of the macro will, at each step, use the format in effect at that step during its definition. Changes to the macro format during execution of a macro, like the corresponding changes during its definition, have no effect on subsequent macros.

The format set by C-x C-k C-f does not affect insertion of numbers stored in registers.

If you use a register as a counter, incrementing it on each repetition of the macro, that accomplishes the same thing as a keyboard macro counter. See Number Registers. For most purposes, it is simpler to use a keyboard macro counter.

17.4 Executing Macros with Variations

In a keyboard macro, you can create an effect similar to that of query-replace, in that the macro asks you each time around whether to make a change.

C-x q

When this point is reached during macro execution, ask for confirmation (kbd-macro-query).

While defining the macro, type C-x q at the point where you want the query to occur. During macro definition, the C-x q does nothing, but when you run the macro later, C-x q asks you interactively whether to continue.

The valid responses when C-x q asks are:

SPC (or y)

Continue executing the keyboard macro.

DEL (or n)

Skip the remainder of this repetition of the macro, and start right away with the next repetition.

RET (or q)

Skip the remainder of this repetition and cancel further repetitions.

C-r

Enter a recursive editing level, in which you can perform editing which is not part of the macro. When you exit the recursive edit using C-M-c, you are asked again how to continue with the keyboard macro. If you type a SPC at this time, the rest of the macro definition is executed. It is up to you to leave point and the text in a state such that the rest of the macro will do what you want.

C-u C-x q, which is C-x q with a prefix argument, performs a completely different function. It enters a recursive edit reading input from the keyboard, both when you type it during the definition of the macro, and when it is executed from the macro. During definition, the editing you do inside the recursive edit does not become part of the macro. During macro execution, the recursive edit gives you a chance to do some particularized editing on each repetition. See Recursive Edit.

17.5 Naming and Saving Keyboard Macros

C-x C-k n

Give a command name (for the duration of the Emacs session) to the most recently defined keyboard macro (kmacro-name-last-macro).

C-x C-k b

Bind the most recently defined keyboard macro to a key sequence (for the duration of the session) (kmacro-bind-to-key).

M-x insert-kbd-macro

Insert in the buffer a keyboard macro’s definition, as Lisp code.

If you wish to save a keyboard macro for later use, you can give it a name using C-x C-k n (kmacro-name-last-macro). This reads a name as an argument using the minibuffer and defines that name to execute the last keyboard macro, in its current form. (If you later add to the definition of this macro, that does not alter the name’s definition as a macro.) The macro name is a Lisp symbol, and defining it in this way makes it a valid command name for calling with M-x or for binding a key to with global-set-key (see Keymaps). If you specify a name that has a prior definition other than a keyboard macro, an error message is shown and nothing is changed.

You can also bind the last keyboard macro (in its current form) to a key, using C-x C-k b (kmacro-bind-to-key) followed by the key sequence you want to bind. You can bind to any key sequence in the global keymap, but since most key sequences already have other bindings, you should select the key sequence carefully. If you try to bind to a key sequence with an existing binding (in any keymap), this command asks you for confirmation before replacing the existing binding.

To avoid problems caused by overriding existing bindings, the key sequences C-x C-k 0 through C-x C-k 9 and C-x C-k A through C-x C-k Z are reserved for your own keyboard macro bindings. In fact, to bind to one of these key sequences, you only need to type the digit or letter rather than the whole key sequences. 例如,

C-x C-k b 4

will bind the last keyboard macro to the key sequence C-x C-k 4.

Once a macro has a command name, you can save its definition in a file. Then it can be used in another editing session. First, visit the file you want to save the definition in. Then use this command:

M-x insert-kbd-macro RET macroname RET

This inserts some Lisp code that, when executed later, will define the same macro with the same definition it has now. (You don’t need to understand Lisp code to do this, because insert-kbd-macro writes the Lisp code for you.) Then save the file. You can load the file later with load-file (see Lisp Libraries). If the file you save in is your init file ~/.emacs (see Init File) then the macro will be defined each time you run Emacs.

If you give insert-kbd-macro a prefix argument, it makes additional Lisp code to record the keys (if any) that you have bound to macroname, so that the macro will be reassigned the same keys when you load the file.

17.6 Editing a Keyboard Macro

C-x C-k C-e

Edit the last defined keyboard macro (kmacro-edit-macro).

C-x C-k e name RET

Edit a previously defined keyboard macro name (edit-kbd-macro).

C-x C-k l

Edit the last 300 keystrokes as a keyboard macro (kmacro-edit-lossage).

You can edit the last keyboard macro by typing C-x C-k C-e or C-x C-k RET (kmacro-edit-macro). This formats the macro definition in a buffer and enters a specialized major mode for editing it. Type C-h m once in that buffer to display details of how to edit the macro. When you are finished editing, type C-c C-c.

You can edit a named keyboard macro or a macro bound to a key by typing C-x C-k e (edit-kbd-macro). Follow that with the keyboard input that you would use to invoke the macro—C-x e or M-x name or some other key sequence.

You can edit the last 300 keystrokes as a macro by typing C-x C-k l (kmacro-edit-lossage).

17.7 Stepwise Editing a Keyboard Macro

You can interactively replay and edit the last keyboard macro, one command at a time, by typing C-x C-k SPC (kmacro-step-edit-macro). Unless you quit the macro using q or C-g, the edited macro replaces the last macro on the macro ring.

This macro editing feature shows the last macro in the minibuffer together with the first (or next) command to be executed, and prompts you for an action. You can enter ? to get a summary of your options. These actions are available:

Next: , Previous: , Up: Top   [Contents][Index]

18 File Handling

The operating system stores data permanently in named files, so most of the text you edit with Emacs comes from a file and is ultimately stored in a file.

To edit a file, you must tell Emacs to read the file and prepare a buffer containing a copy of the file’s text. This is called visiting the file. Editing commands apply directly to text in the buffer; that is, to the copy inside Emacs. Your changes appear in the file itself only when you save the buffer back into the file.

In addition to visiting and saving files, Emacs can delete, copy, rename, and append to files, keep multiple versions of them, and operate on file directories.

Next: , Up: Files   [Contents][Index]

18.1 File Names

Many Emacs commands that operate on a file require you to specify the file name, using the minibuffer (see Minibuffer File).

While in the minibuffer, you can use the usual completion and history commands (see Minibuffer). Note that file name completion ignores file names whose extensions appear in the variable completion-ignored-extensions (see Completion Options). Note also that most commands use permissive completion with confirmation for reading file names: you are allowed to submit a nonexistent file name, but if you type RET immediately after completing up to a nonexistent file name, Emacs prints ‘[Confirm]’ and you must type a second RET to confirm. See Completion Exit, for details.

Minibuffer history commands offer some special features for reading file names, see Minibuffer History.

Each buffer has a default directory, stored in the buffer-local variable default-directory. Whenever Emacs reads a file name using the minibuffer, it usually inserts the default directory into the minibuffer as the initial contents. You can inhibit this insertion by changing the variable insert-default-directory to nil (see Minibuffer File). Regardless, Emacs always assumes that any relative file name is relative to the default directory, e.g., entering a file name without a directory specifies a file in the default directory.

When you visit a file, Emacs sets default-directory in the visiting buffer to the directory of its file. When you create a new buffer that is not visiting a file, via a command like C-x b, its default directory is usually copied from the buffer that was current at the time (see Select Buffer). You can use the command M-x pwd to see the value of default-directory in the current buffer. The command M-x cd prompts for a directory’s name, and sets the buffer’s default-directory to that directory (doing this does not change the buffer’s file name, if any).

As an example, when you visit the file /u/rms/gnu/gnu.tasks, the default directory is set to /u/rms/gnu/. If you invoke a command that reads a file name, entering just ‘foo’ in the minibuffer, with a directory omitted, specifies the file /u/rms/gnu/foo; entering ‘../.login’ specifies /u/rms/.login; and entering ‘new/foo’ specifies /u/rms/gnu/new/foo.

When typing a file name into the minibuffer, you can make use of a couple of shortcuts: a double slash ignores everything before the second slash in the pair, and ‘~/’ is your home directory. See Minibuffer File.

The character ‘$’ is used to substitute an environment variable into a file name. The name of the environment variable consists of all the alphanumeric characters after the ‘$’; alternatively, it can be enclosed in braces after the ‘$’. For example, if you have used the shell command export FOO=rms/hacks to set up an environment variable named FOO, then both /u/$FOO/test.c and /u/${FOO}/test.c are abbreviations for /u/rms/hacks/test.c. If the environment variable is not defined, no substitution occurs, so that the character ‘$’ stands for itself. Note that environment variables set outside Emacs affect Emacs only if they are applied before Emacs is started.

To access a file with ‘$’ in its name, if the ‘$’ causes expansion, type ‘$$’. This pair is converted to a single ‘$’ at the same time that variable substitution is performed for a single ‘$’. Alternatively, quote the whole file name with ‘/:’ (see Quoted File Names). File names which begin with a literal ‘~’ should also be quoted with ‘/:’.

You can include non-ASCII characters in file names. See File Name Coding.

Next: , Previous: , Up: Files   [Contents][Index]

18.2 Visiting Files

C-x C-f

Visit a file (find-file).

C-x C-r

Visit a file for viewing, without allowing changes to it (find-file-read-only).

C-x C-v

Visit a different file instead of the one visited last (find-alternate-file).

C-x 4 f

Visit a file, in another window (find-file-other-window). Don’t alter what is displayed in the selected window.

C-x 5 f

Visit a file, in a new frame (find-file-other-frame). Don’t alter what is displayed in the selected frame.

M-x find-file-literally

Visit a file with no conversion of the contents.

Visiting a file means reading its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit.

To visit a file, type C-x C-f (find-file) and use the minibuffer to enter the name of the desired file. While in the minibuffer, you can abort the command by typing C-g. See File Names, for details about entering file names into minibuffers.

If the specified file exists but the system does not allow you to read it, an error message is displayed in the echo area (on GNU and Unix systems you might be able to visit such a file using the ‘su’ or ‘sudo’ methods; see Remote Files). Otherwise, you can tell that C-x C-f has completed successfully by the appearance of new text on the screen, and by the buffer name shown in the mode line (see Mode Line). Emacs normally constructs the buffer name from the file name, omitting the directory name. For example, a file named /usr/rms/emacs.tex is visited in a buffer named ‘emacs.tex’. If there is already a buffer with that name, Emacs constructs a unique name; the normal method is to add a suffix based on the directory name (e.g., ‘<rms>’, ‘<tmp>’, and so on), but you can select other methods. See Uniquify.

To create a new file, just visit it using the same command, C-x C-f. Emacs displays ‘(New file)’ in the echo area, but in other respects behaves as if you had visited an existing empty file.

After visiting a file, the changes you make with editing commands are made in the Emacs buffer. They do not take effect in the visited file, until you save the buffer (see Saving). If a buffer contains changes that have not been saved, we say the buffer is modified. This implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.

If you visit a file that is already in Emacs, C-x C-f switches to the existing buffer instead of making another copy. Before doing so, it checks whether the file has changed since you last visited or saved it. If the file has changed, Emacs offers to reread it.

If you try to visit a file larger than large-file-warning-threshold (the default is 10000000, which is about 10 megabytes), Emacs asks you for confirmation first. You can answer y to proceed with visiting the file or l to visit the file literally (see below). Visiting large files literally speeds up navigation and editing of such files, because various potentially-expensive features are turned off. Note, however, that Emacs cannot visit files that are larger than the maximum Emacs buffer size, which is limited by the amount of memory Emacs can allocate and by the integers that Emacs can represent (see Buffers). If you try, Emacs displays an error message saying that the maximum buffer size has been exceeded.

If the file name you specify contains shell-style wildcard characters, Emacs visits all the files that match it. (On case-insensitive filesystems, Emacs matches the wildcards disregarding the letter case.) Wildcards include ‘?’, ‘*’, and ‘[…]’ sequences. To enter the wild card ‘?’ in a file name in the minibuffer, you need to type C-q ?. See Quoted File Names, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing find-file-wildcards.

If you visit the wrong file unintentionally by typing its name incorrectly, type C-x C-v (find-alternate-file) to visit the file you really wanted. C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified). When C-x C-v reads the file name to visit, it inserts the entire default file name in the buffer, with point just after the directory part; this is convenient if you made a slight error in typing the name.

If you visit a file that is actually a directory, Emacs invokes Dired, the Emacs directory browser. See Dired. You can disable this behavior by setting the variable find-file-run-dired to nil; in that case, it is an error to try to visit a directory.

Files which are actually collections of other files, or file archives, are visited in special modes which invoke a Dired-like environment to allow operations on archive members. See File Archives, for more about these features.

If you visit a file that the operating system won’t let you modify, or that is marked read-only, Emacs makes the buffer read-only too, so that you won’t go ahead and make changes that you’ll have trouble saving afterward. You can make the buffer writable with C-x C-q (read-only-mode). See Misc Buffer.

If you want to visit a file as read-only in order to protect yourself from entering changes accidentally, visit it with the command C-x C-r (find-file-read-only) instead of C-x C-f.

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window. The window that was selected before C-x 4 f continues to show the same buffer it was already showing. If this command is used when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file. See Windows.

C-x 5 f (find-file-other-frame) is similar, but opens a new frame, or selects any existing frame showing the specified file. See Frames.

On graphical displays, there are two additional methods for visiting files. Firstly, when Emacs is built with a suitable GUI toolkit, commands invoked with the mouse (by clicking on the menu bar or tool bar) use the toolkit’s standard file selection dialog instead of prompting for the file name in the minibuffer. On GNU/Linux and Unix platforms, Emacs does this when built with GTK+, LessTif, and Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. For information on how to customize this, see Dialog Boxes.

Secondly, Emacs supports drag and drop: dropping a file into an ordinary Emacs window visits the file using that window. As an exception, dropping a file into a window displaying a Dired buffer moves or copies the file into the displayed directory. For details, see Drag and Drop, and Misc Dired Features.

On text-mode terminals and on graphical displays when Emacs was built without a GUI toolkit, you can visit files via the menu-bar ‘File’ menu, which has the ‘Visit New File’ and the ‘Open File’ items.

Each time you visit a file, Emacs automatically scans its contents to detect what character encoding and end-of-line convention it uses, and converts these to Emacs’s internal encoding and end-of-line convention within the buffer. When you save the buffer, Emacs performs the inverse conversion, writing the file to disk with its original encoding and end-of-line convention. See Coding Systems.

If you wish to edit a file as a sequence of ASCII characters with no special encoding or conversion, use the M-x find-file-literally command. This visits a file, like C-x C-f, but does not do format conversion (see Format Conversion in the Emacs Lisp Reference Manual), character code conversion (see Coding Systems), or automatic uncompression (see Compressed Files), and does not add a final newline because of require-final-newline (see Customize Save). If you have already visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead.

Two special hook variables allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in find-file-not-found-functions; this variable holds a list of functions, which are called one by one (with no arguments) until one of them returns non-nil. This is not a normal hook, and the name ends in ‘-functions’ rather than ‘-hook’ to indicate that fact.

Successful visiting of any file, whether existing or not, calls the functions in find-file-hook, with no arguments. This variable is a normal hook. In the case of a nonexistent file, the find-file-not-found-functions are run first. See Hooks.

There are several ways to specify automatically the major mode for editing the file (see Choosing Modes), and to specify local variables defined for that file (see File Variables).

Next: , Previous: , Up: Files   [Contents][Index]

18.3 Saving Files

Saving a buffer in Emacs means writing its contents back into the file that was visited in the buffer.

Next: , Up: Saving   [Contents][Index]

18.3.1 Commands for Saving Files

These are the commands that relate to saving and writing files.

C-x C-s

Save the current buffer to its file (save-buffer).

C-x s

Save any or all buffers to their files (save-some-buffers).

M-~

Forget that the current buffer has been changed (not-modified). With prefix argument (C-u), mark the current buffer as changed.

C-x C-w

Save the current buffer with a specified file name (write-file).

M-x set-visited-file-name

Change the file name under which the current buffer will be saved.

When you wish to save the file and make your changes permanent, type C-x C-s (save-buffer). After saving is finished, C-x C-s displays a message like this:

Wrote /u/rms/gnu/gnu.tasks

If the current buffer is not modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect. Instead, C-x C-s displays a message like this in the echo area:

(No changes need to be saved)

With a prefix argument, C-u C-x C-s, Emacs also marks the buffer to be backed up when the next save is done. See Backup.

The command C-x s (save-some-buffers) offers to save any or all modified buffers. It asks you what to do with each buffer. The possible responses are analogous to those of query-replace:

y
SPC

Save this buffer and ask about the rest of the buffers.

n
DEL

Don’t save this buffer, but ask about the rest of the buffers.

!

Save this buffer and all the rest with no more questions.

q
RET

Terminate save-some-buffers without any more saving.

.

Save this buffer, then exit save-some-buffers without even asking about other buffers.

C-r

View the buffer that you are currently being asked about. When you exit View mode, you get back to save-some-buffers, which asks the question again.

C-f

Exit save-some-buffers and visit the buffer that you are currently being asked about.

d

Diff the buffer against its corresponding file, so you can see what changes you would be saving. This calls the command diff-buffer-with-file (see Comparing Files).

C-h

Display a help message about these options.

You can customize the value of save-some-buffers-default-predicate to control which buffers Emacs will ask about.

C-x C-c, the key sequence to exit Emacs, invokes save-some-buffers and therefore asks the same questions.

If you have changed a buffer but do not wish to save the changes, you should take some action to prevent it. Otherwise, each time you use C-x s or C-x C-c, you are liable to save this buffer by mistake. One thing you can do is type M-~ (not-modified), which clears out the indication that the buffer is modified. If you do this, none of the save commands will believe that the buffer needs to be saved. (‘~’ is often used as a mathematical symbol for “not”; thus M-~ is “not”, metafied.) Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again. This is called reverting. See Reverting. (You could also undo all the changes by repeating the undo command C-x u until you have undone all the changes; but reverting is easier.)

M-x set-visited-file-name alters the name of the file that the current buffer is visiting. It reads the new file name using the minibuffer. Then it marks the buffer as visiting that file name, and changes the buffer name correspondingly. set-visited-file-name does not save the buffer in the newly visited file; it just alters the records inside Emacs in case you do save later. It also marks the buffer as modified so that C-x C-s in that buffer will save.

If you wish to mark the buffer as visiting a different file and save it right away, use C-x C-w (write-file). This is equivalent to set-visited-file-name followed by C-x C-s, except that C-x C-w asks for confirmation if the file exists. C-x C-s used on a buffer that is not visiting a file has the same effect as C-x C-w; that is, it reads a file name, marks the buffer as visiting that file, and saves it there. The default file name in a buffer that is not visiting a file is made by combining the buffer name with the buffer’s default directory (see File Names).

If the new file name implies a major mode, then C-x C-w switches to that major mode, in most cases. The command set-visited-file-name also does this. See Choosing Modes.

If Emacs is about to save a file and sees that the date of the latest version on disk does not match what Emacs last read or wrote, Emacs notifies you of this fact, because it probably indicates a problem caused by simultaneous editing and requires your immediate attention. See Simultaneous Editing.

Next: , Previous: , Up: Saving   [Contents][Index]

18.3.2 Backup Files

On most operating systems, rewriting a file automatically destroys all record of what the file used to contain. Thus, saving a file from Emacs throws away the old contents of the file—or it would, except that Emacs carefully copies the old contents to another file, called the backup file, before actually saving.

Emacs makes a backup for a file only the first time the file is saved from a buffer. No matter how many times you subsequently save the file, its backup remains unchanged. However, if you kill the buffer and then visit the file again, a new backup file will be made.

For most files, the variable make-backup-files determines whether to make backup files. On most operating systems, its default value is t, so that Emacs does write backup files.

For files managed by a version control system (see Version Control), the variable vc-make-backup-files determines whether to make backup files. By default it is nil, since backup files are redundant when you store all the previous versions in a version control system. See General VC Options.

At your option, Emacs can keep either a single backup for each file, or make a series of numbered backup files for each file that you edit. See Backup Names.

The default value of the backup-enable-predicate variable prevents backup files being written for files in the directories used for temporary files, specified by temporary-file-directory or small-temporary-file-directory.

You can explicitly tell Emacs to make another backup file from a buffer, even though that buffer has been saved before. If you save the buffer with C-u C-x C-s, the version thus saved will be made into a backup file if you save the buffer again. C-u C-u C-x C-s saves the buffer, but first makes the previous file contents into a new backup file. C-u C-u C-u C-x C-s does both things: it makes a backup from the previous contents, and arranges to make another from the newly saved contents if you save again.

You can customize the variable backup-directory-alist to specify that files matching certain patterns should be backed up in specific directories. A typical use is to add an element ("." . dir) to make all backups in the directory with absolute name dir. Emacs modifies the backup file names to avoid clashes between files with the same names originating in different directories. Alternatively, adding, ("." . ".~") would make backups in the invisible subdirectory .~ of the original file’s directory. Emacs creates the directory, if necessary, to make the backup.

18.3.2.1 Single or Numbered Backups

When Emacs makes a backup file, its name is normally constructed by appending ‘~’ to the file name being edited; thus, the backup file for eval.c would be eval.c~.

If access control stops Emacs from writing backup files under the usual names, it writes the backup file as ~/.emacs.d/%backup%~. Only one such file can exist, so only the most recently made such backup is available.

Emacs can also make numbered backup files. Numbered backup file names contain ‘.~’, the number, and another ‘~’ after the original file name. Thus, the backup files of eval.c would be called eval.c.~1~, eval.c.~2~, and so on, all the way through names like eval.c.~259~ and beyond.

The variable version-control determines whether to make single backup files or multiple numbered backup files. Its possible values are:

nil

Make numbered backups for files that have numbered backups already. Otherwise, make single backups. This is the default.

t

Make numbered backups.

never

Never make numbered backups; always make single backups.

The usual way to set this variable is globally, through your init file or the customization buffer. However, you can set version-control locally in an individual buffer to control the making of backups for that buffer’s file (see Locals). You can have Emacs set version-control locally whenever you visit a given file (see File Variables). Some modes, such as Rmail mode, set this variable.

If you set the environment variable VERSION_CONTROL, to tell various GNU utilities what to do with backup files, Emacs also obeys the environment variable by setting the Lisp variable version-control accordingly at startup. If the environment variable’s value is ‘t’ or ‘numbered’, then version-control becomes t; if the value is ‘nil’ or ‘existing’, then version-control becomes nil; if it is ‘never’ or ‘simple’, then version-control becomes never.

If you set the variable make-backup-file-name-function to a suitable Lisp function, you can override the usual way Emacs constructs backup file names.

Next: , Previous: , Up: Backup   [Contents][Index]

18.3.2.2 Automatic Deletion of Backups

To prevent excessive consumption of disk space, Emacs can delete numbered backup versions automatically. Generally Emacs keeps the first few backups and the latest few backups, deleting any in between. This happens every time a new backup is made.

The two variables kept-old-versions and kept-new-versions control this deletion. Their values are, respectively, the number of oldest (lowest-numbered) backups to keep and the number of newest (highest-numbered) ones to keep, each time a new backup is made. The backups in the middle (excluding those oldest and newest) are the excess middle versions—those backups are deleted. These variables’ values are used when it is time to delete excess versions, just after a new backup version is made; the newly made backup is included in the count in kept-new-versions. By default, both variables are 2.

If delete-old-versions is t, Emacs deletes the excess backup files silently. If it is nil, the default, Emacs asks you whether it should delete the excess backup versions. If it has any other value, then Emacs never automatically deletes backups.

Dired’s . (Period) command can also be used to delete old versions. See Flagging Many Files.

Previous: , Up: Backup   [Contents][Index]

18.3.2.3 Copying vs. Renaming

Backup files can be made by copying the old file or by renaming it. This makes a difference when the old file has multiple names (hard links). If the old file is renamed into the backup file, then the alternate names become names for the backup file. If the old file is copied instead, then the alternate names remain names for the file that you are editing, and the contents accessed by those names will be the new contents.

The method of making a backup file may also affect the file’s owner and group. If copying is used, these do not change. If renaming is used, you become the file’s owner, and the file’s group becomes the default (different operating systems have different defaults for the group).

The choice of renaming or copying is made as follows:

When a file is managed with a version control system (see Version Control), Emacs does not normally make backups in the usual way for that file. But committing (a.k.a. checking in, see VCS Concepts) new versions of files is similar in some ways to making backups. One unfortunate similarity is that these operations typically break hard links, disconnecting the file name you visited from any alternate names for the same file. This has nothing to do with Emacs—the version control system does it.

Next: , Previous: , Up: Saving   [Contents][Index]

18.3.3 Customizing Saving of Files

If the value of the variable require-final-newline is t, saving or writing a file silently puts a newline at the end if there isn’t already one there. If the value is visit, Emacs adds a newline at the end of any file that doesn’t have one, just after it visits the file. (This marks the buffer as modified, and you can undo it.) If the value is visit-save, Emacs adds such newlines both on visiting and on saving. If the value is nil, Emacs leaves the end of the file unchanged; any other non-nil value means Emacs asks you whether to add a newline. The default is nil.

Some major modes are designed for specific kinds of files that are always supposed to end in newlines. Such major modes set the variable require-final-newline to the value of mode-require-final-newline, which defaults to t. By setting the latter variable, you can control how these modes handle final newlines.

Normally, when a program writes a file, the operating system briefly caches the file’s data in main memory before committing the data to disk. This can greatly improve performance; for example, when running on laptops, it can avoid a disk spin-up each time a file is written. However, it risks data loss if the operating system crashes before committing the cache to disk.

To lessen this risk, Emacs can invoke the fsync system call after saving a file. Using fsync does not eliminate the risk of data loss, partly because many systems do not implement fsync properly, and partly because Emacs’s file-saving procedure typically relies also on directory updates that might not survive a crash even if fsync works properly.

The write-region-inhibit-fsync variable controls whether Emacs invokes fsync after saving a file. The variable’s default value is nil when Emacs is interactive, and t when Emacs runs in batch mode (see Batch Mode).

Emacs never uses fsync when writing auto-save files, as these files might lose data anyway.

Next: , Previous: , Up: Saving   [Contents][Index]

18.3.4 Protection against Simultaneous Editing

Simultaneous editing occurs when two users visit the same file, both make changes, and then both save them. If nobody is informed that this is happening, whichever user saves first would later find that their changes were lost.

On some systems, Emacs notices immediately when the second user starts to change the file, and issues an immediate warning. On all systems, Emacs checks when you save the file, and warns if you are about to overwrite another user’s changes. You can prevent loss of the other user’s work by taking the proper corrective action instead of saving the file.

When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is locked by you. (It does this by creating a specially-named symbolic link7 with special contents in the same directory. See (elisp)File Locks, for more details.) Emacs removes the lock when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes.

You can prevent the creation of lock files by setting the variable create-lockfiles to nil. Caution: by doing so you will lose the benefits that this feature provides.

If you begin to modify the buffer while the visited file is locked by someone else, this constitutes a collision. When Emacs detects a collision, it asks you what to do, by calling the Lisp function ask-user-about-lock. You can redefine this function for the sake of customization. The standard definition of this function asks you a question and accepts three possible answers:

s

Steal the lock. Whoever was already changing the file loses the lock, and you gain the lock.

p

Proceed. Go ahead and edit the file despite its being locked by someone else.

q

退出。This causes an error (file-locked), and the buffer contents remain unchanged—the modification you were trying to make does not actually take place.

If Emacs or the operating system crashes, this may leave behind lock files which are stale, so you may occasionally get warnings about spurious collisions. When you determine that the collision is spurious, just use p to tell Emacs to go ahead anyway.

Note that locking works on the basis of a file name; if a file has multiple names, Emacs does not prevent two users from editing it simultaneously under different names.

A lock file cannot be written in some circumstances, e.g., if Emacs lacks the system permissions or cannot create lock files for some other reason. In these cases, Emacs can still detect the collision when you try to save a file, by checking the file’s last-modification date. If the file has changed since the last time Emacs visited or saved it, that implies that changes have been made in some other way, and will be lost if Emacs proceeds with saving. Emacs then displays a warning message and asks for confirmation before saving; answer yes to save, and no or C-g cancel the save.

If you are notified that simultaneous editing has already taken place, one way to compare the buffer to its file is the M-x diff-buffer-with-file command. See Comparing Files.

Next: , Previous: , Up: Saving   [Contents][Index]

18.3.5 Shadowing Files

You can arrange to keep identical shadow copies of certain files in more than one place—possibly on different machines. To do this, first you must set up a shadow file group, which is a set of identically-named files shared between a list of sites. The file group is permanent and applies to further Emacs sessions as well as the current one. Once the group is set up, every time you exit Emacs, it will copy the file you edited to the other files in its group. You can also do the copying without exiting Emacs, by typing M-x shadow-copy-files.

A shadow cluster is a group of hosts that share directories, so that copying to or from one of them is sufficient to update the file on all of them. Each shadow cluster has a name, and specifies the network address of a primary host (the one we copy files to), and a regular expression that matches the host names of all the other hosts in the cluster. You can define a shadow cluster with M-x shadow-define-cluster.

M-x shadow-initialize

Set up file shadowing.

M-x shadow-define-literal-group

Declare a single file to be shared between sites.

M-x shadow-define-regexp-group

Make all files that match each of a group of files be shared between hosts.

M-x shadow-define-cluster RET name RET

Define a shadow file cluster name.

M-x shadow-copy-files

Copy all pending shadow files.

M-x shadow-cancel

Cancel the instruction to shadow some files.

To set up a shadow file group, use M-x shadow-define-literal-group or M-x shadow-define-regexp-group. See their documentation strings for further information.

Before copying a file to its shadows, Emacs asks for confirmation. You can answer “no” to bypass copying of this file, this time. If you want to cancel the shadowing permanently for a certain file, use M-x shadow-cancel to eliminate or change the shadow file group.

File Shadowing is not available on MS Windows.

Previous: , Up: Saving   [Contents][Index]

18.3.6 Updating Time Stamps Automatically

You can arrange to put a time stamp in a file, so that it is updated automatically each time you edit and save the file. The time stamp must be in the first eight lines of the file, and you should insert it like this:

Time-stamp: <>

or like this:

Time-stamp: " "

Then add the function time-stamp to the hook before-save-hook (see Hooks). When you save the file, this function then automatically updates the time stamp with the current date and time. You can also use the command M-x time-stamp to update the time stamp manually. By default the time stamp is formatted according to your locale setting (see Environment) and time zone (see Time of Day in The Emacs Lisp Reference Manual). For customizations, see the Custom group time-stamp.

Next: , Previous: , Up: Files   [Contents][Index]

18.4 Reverting a Buffer

If you have made extensive changes to a file-visiting buffer and then change your mind, you can revert the changes and go back to the saved version of the file. To do this, type M-x revert-buffer. Since reverting unintentionally could lose a lot of work, Emacs asks for confirmation first.

The revert-buffer command tries to position point in such a way that, if the file was edited only slightly, you will be at approximately the same part of the text as before. But if you have made major changes, point may end up in a totally different location.

Reverting marks the buffer as not modified. However, it adds the reverted changes as a single modification to the buffer’s undo history (see Undo). Thus, after reverting, you can type C-/ or its aliases to bring the reverted changes back, if you happen to change your mind.

Some kinds of buffers that are not associated with files, such as Dired buffers, can also be reverted. For them, reverting means recalculating their contents. Buffers created explicitly with C-x b cannot be reverted; revert-buffer reports an error if you try.

When you edit a file that changes automatically and frequently—for example, a log of output from a process that continues to run—it may be useful for Emacs to revert the file without querying you. To request this behavior, set the variable revert-without-query to a list of regular expressions. When a file name matches one of these regular expressions, find-file and revert-buffer will revert it automatically if it has changed—provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.)

You can also tell Emacs to revert buffers automatically when their visited files change on disk; see Auto Revert.

Next: , Previous: , Up: Files   [Contents][Index]

18.5 Auto Revert: Keeping buffers automatically up-to-date

A buffer can get out of sync with respect to its visited file on disk if that file is changed by another program. To keep it up to date, you can enable Auto Revert mode by typing M-x auto-revert-mode. This automatically reverts the buffer when its visited file changes on disk. To do the same for all file buffers, type M-x global-auto-revert-mode to enable Global Auto Revert mode.

Auto Revert will not revert a buffer if it has unsaved changes, or if its file on disk is deleted or renamed.

One use of Auto Revert mode is to “tail” a file such as a system log, so that changes made to that file by other programs are continuously displayed. To do this, just move the point to the end of the buffer, and it will stay there as the file contents change. However, if you are sure that the file will only change by growing at the end, use Auto Revert Tail mode instead (auto-revert-tail-mode). It is more efficient for this. Auto Revert Tail mode also works for remote files.

When a buffer is auto-reverted, a message is generated. This can be suppressed by setting auto-revert-verbose to nil.

The Auto Revert modes do not check or revert remote files, because that is usually too slow. This behavior can be changed by setting the variable auto-revert-remote-files to non-nil.

By default, Auto Revert mode works using file notifications, whereby changes in the filesystem are reported to Emacs by the OS. You can disable use of file notifications by customizing the variable auto-revert-use-notify to a nil value, then Emacs will check for file changes by polling every five seconds. You can change the polling interval through the variable auto-revert-interval.

Not all systems support file notifications; where they are not supported, auto-revert-use-notify will be nil by default.

By default, Auto Revert mode will poll files for changes periodically even when file notifications are used. Polling is unnecessary in many cases, and turning it off may save power by relying on notifications only. To do so, set the variable auto-revert-avoid-polling to non-nil. However, notification is ineffective on certain file systems; mainly network file system on Unix-like machines, where files can be altered from other machines. For such file systems, polling may be necessary. To force polling when auto-revert-avoid-polling is non-nil, set auto-revert-notify-exclude-dir-regexp to match files that should be excluded from using notification.

In Dired buffers (see Dired), Auto Revert mode refreshes the buffer when a file is created or deleted in the buffer’s directory.

See VC Undo, for commands to revert to earlier versions of files under version control. See VC Mode Line, for Auto Revert peculiarities when visiting files under version control.

18.5.1 Auto Reverting Non-File Buffers

Global Auto Revert Mode normally only reverts file buffers. There are two ways to auto-revert certain non-file buffers: by enabling Auto Revert Mode in those buffers (using M-x auto-revert-mode); and by setting global-auto-revert-non-file-buffers to a non-nil value. The latter enables Auto Reverting for all types of buffers for which it is implemented (listed in the menu below).

Like file buffers, non-file buffers should normally not revert while you are working on them, or while they contain information that might get lost after reverting. Therefore, they do not revert if they are modified. This can get tricky, because deciding when a non-file buffer should be marked modified is usually more difficult than for file buffers.

Another tricky detail is that, for efficiency reasons, Auto Revert often does not try to detect all possible changes in the buffer, only changes that are major or easy to detect. Hence, enabling auto-reverting for a non-file buffer does not always guarantee that all information in the buffer is up-to-date, and does not necessarily make manual reverts useless.

At the other extreme, certain buffers automatically revert every auto-revert-interval seconds. (This currently only applies to the Buffer Menu.) In this case, Auto Revert does not print any messages while reverting, even when auto-revert-verbose is non-nil.

Some non-file buffers can be updated reliably by file notification on their default directory; Dired buffers is an example. The major mode can indicate this by setting buffer-auto-revert-by-notification to a non-nil value in that buffer, allowing Auto Revert to avoid periodic polling. Such notification does not include changes to files in that directory, only to the directory itself.

The details depend on the particular types of buffers and are explained in the corresponding sections.

18.5.1.1 Auto Reverting the Buffer Menu

If auto-reverting of non-file buffers is enabled, the Buffer Menu (see Several Buffers) automatically reverts every auto-revert-interval seconds, whether there is a need for it or not. (It would probably take longer to check whether there is a need than to actually revert.)

If the Buffer Menu inappropriately gets marked modified, just revert it manually using g and auto-reverting will resume. However, if you marked certain buffers to get deleted or to be displayed, you have to be careful, because reverting erases all marks. The fact that adding marks sets the buffer’s modified flag prevents Auto Revert from automatically erasing the marks.

18.5.1.2 Auto Reverting Dired buffers

Dired buffers only auto-revert when the file list of the buffer’s main directory changes (e.g., when a new file is added or deleted). They do not auto-revert when information about a particular file changes (e.g., when the size changes) or when inserted subdirectories change. To be sure that all listed information is up to date, you have to manually revert using g, even if auto-reverting is enabled in the Dired buffer. Sometimes, you might get the impression that modifying or saving files listed in the main directory actually does cause auto-reverting. This is because making changes to a file, or saving it, very often causes changes in the directory itself; for instance, through backup files or auto-save files. However, this is not guaranteed.

If the Dired buffer is marked modified and there are no changes you want to protect, then most of the time you can make auto-reverting resume by manually reverting the buffer using g. There is one exception. If you flag or mark files, you can safely revert the buffer. This will not erase the flags or marks (unless the marked file has been deleted, of course). However, the buffer will stay modified, even after reverting, and auto-reverting will not resume. This is because, if you flag or mark files, you may be working on the buffer and you might not want the buffer to change without warning. If you want auto-reverting to resume in the presence of marks and flags, mark the buffer non-modified using M-~. However, adding, deleting or changing marks or flags will mark it modified again.

Remote Dired buffers are currently not auto-reverted. Neither are Dired buffers for which you used shell wildcards or file arguments to list only some of the files. *Find* and *Locate* buffers do not auto-revert either.

Note that auto-reverting Dired buffers may not work satisfactorily on some systems.

Next: , Previous: , Up: Files   [Contents][Index]

18.6 Auto-Saving: Protection Against Disasters

From time to time, Emacs automatically saves each visited file in a separate file, without altering the file you actually use. This is called auto-saving. It prevents you from losing more than a limited amount of work if the system crashes.

When Emacs determines that it is time for auto-saving, it considers each buffer, and each is auto-saved if auto-saving is enabled for it and it has been changed since the last time it was auto-saved. When the auto-save-no-message variable is set to nil (the default), the message ‘Auto-saving...’ is displayed in the echo area during auto-saving, if any files are actually auto-saved; to disable these messages, customize the variable to a non-nil value. Errors occurring during auto-saving are caught so that they do not interfere with the execution of commands you have been typing.

18.6.1 Auto-Save Files

Auto-saving does not normally save in the files that you visited, because it can be very undesirable to save a change that you did not want to make permanent. Instead, auto-saving is done in a different file called the auto-save file, and the visited file is changed only when you request saving explicitly (such as with C-x C-s).

Normally, the auto-save file name is made by appending ‘#’ to the front and rear of the visited file name. Thus, a buffer visiting file foo.c is auto-saved in a file #foo.c#. Most buffers that are not visiting files are auto-saved only if you request it explicitly; when they are auto-saved, the auto-save file name is made by appending ‘#’ to the front and rear of buffer name, then adding digits and letters at the end for uniqueness. For example, the *mail* buffer in which you compose messages to be sent might be auto-saved in a file named #*mail*#704juu. Auto-save file names are made this way unless you reprogram parts of Emacs to do something different (the functions make-auto-save-file-name and auto-save-file-name-p). The file name to be used for auto-saving in a buffer is calculated when auto-saving is turned on in that buffer.

The variable auto-save-file-name-transforms allows a degree of control over the auto-save file name. It lets you specify a series of regular expressions and replacements to transform the auto save file name. The default value puts the auto-save files for remote files (see Remote Files) into the temporary file directory on the local machine.

When you delete a substantial part of the text in a large buffer, auto save turns off temporarily in that buffer. This is because if you deleted the text unintentionally, you might find the auto-save file more useful if it contains the deleted text. To reenable auto-saving after this happens, save the buffer with C-x C-s, or use C-u 1 M-x auto-save-mode.

If you want auto-saving to be done in the visited file rather than in a separate auto-save file, enable the global minor mode auto-save-visited-mode. In this mode, auto-saving is identical to explicit saving. Note that this mode is orthogonal to the auto-save mode described above; you can enable both at the same time. However, if auto-save mode is active in some buffer and the obsolete auto-save-visited-file-name variable is set to a non-nil value, that buffer won’t be affected by auto-save-visited-mode.

You can use the variable auto-save-visited-interval to customize the interval between auto-save operations in auto-save-visited-mode; by default it’s five seconds. auto-save-interval and auto-save-timeout have no effect on auto-save-visited-mode. See Auto Save Control, for details on these variables.

A buffer’s auto-save file is deleted when you save the buffer in its visited file. (You can inhibit this by setting the variable delete-auto-save-files to nil.) Changing the visited file name with C-x C-w or set-visited-file-name renames any auto-save file to go with the new visited name.

Next: , Previous: , Up: Auto Save   [Contents][Index]

18.6.2 Controlling Auto-Saving

Each time you visit a file, auto-saving is turned on for that file’s buffer if the variable auto-save-default is non-nil (but not in batch mode; see Initial Options). The default for this variable is t, so auto-saving is the usual practice for file-visiting buffers. To toggle auto-saving in the current buffer, type M-x auto-save-mode. Auto Save mode acts as a buffer-local minor mode (see Minor Modes).

Emacs auto-saves periodically based on how many characters you have typed since the last auto-save. The variable auto-save-interval specifies how many characters there are between auto-saves. By default, it is 300. Emacs doesn’t accept values that are too small: if you customize auto-save-interval to a value less than 20, Emacs will behave as if the value is 20.

Auto-saving also takes place when you stop typing for a while. By default, it does this after 30 seconds of idleness (at this time, Emacs may also perform garbage collection; see Garbage Collection in The Emacs Lisp Reference Manual). To change this interval, customize the variable auto-save-timeout. The actual time period is longer if the current buffer is long; this is a heuristic which aims to keep out of your way when you are editing long buffers, in which auto-save takes an appreciable amount of time. Auto-saving during idle periods accomplishes two things: first, it makes sure all your work is saved if you go away from the terminal for a while; second, it may avoid some auto-saving while you are actually typing.

When auto-save-visited-mode is enabled, Emacs will auto-save file-visiting buffers after five seconds of idle time. You can customize the variable auto-save-visited-interval to change the idle time interval.

Emacs also does auto-saving whenever it gets a fatal error. This includes killing the Emacs job with a shell command such as ‘kill %emacs’, or disconnecting a phone line or network connection.

You can perform an auto-save explicitly with the command M-x do-auto-save.

Previous: , Up: Auto Save   [Contents][Index]

18.6.3 Recovering Data from Auto-Saves

You can use the contents of an auto-save file to recover from a loss of data with the command M-x recover-file RET file RET. This visits file and then (after your confirmation) restores the contents from its auto-save file #file#. You can then save with C-x C-s to put the recovered text into file itself. For example, to recover file foo.c from its auto-save file #foo.c#, do:

M-x recover-file RET foo.c RET
yes RET
C-x C-s

Before asking for confirmation, M-x recover-file displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, M-x recover-file does not offer to read it.

If Emacs or the computer crashes, you can recover all the files you were editing from their auto save files with the command M-x recover-session. This first shows you a list of recorded interrupted sessions. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that were being edited during that session, asking whether to recover that file. If you answer y, it calls recover-file, which works in its normal fashion. It shows the dates of the original file and its auto-save file, and asks once again whether to recover that file.

When recover-session is done, the files you’ve chosen to recover are present in Emacs buffers. You should then save them. Only this—saving them—updates the files themselves.

Emacs records information about interrupted sessions in files named .saves-pid-hostname~ in the directory ~/.emacs.d/auto-save-list/. This directory is determined by the variable auto-save-list-file-prefix. If you set auto-save-list-file-prefix to nil, sessions are not recorded for recovery.

Next: , Previous: , Up: Files   [Contents][Index]

18.7 File Name Aliases

Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when foo is a symbolic link to bar, you can use either name to refer to the file, but bar is the real name, while foo is just an alias. More complex cases occur when symbolic links point to directories.

Normally, if you visit a file which Emacs is already visiting under a different name, Emacs displays a message in the echo area and uses the existing buffer visiting that file. This can happen on systems that support hard or symbolic links, or if you use a long file name on a system that truncates long file names, or on a case-insensitive file system. You can suppress the message by setting the variable find-file-suppress-same-file-warnings to a non-nil value. You can disable this feature entirely by setting the variable find-file-existing-other-name to nil: then if you visit the same file under two different names, you get a separate buffer for each file name.

If the variable find-file-visit-truename is non-nil, then the file name recorded for a buffer is the file’s truename (made by replacing all symbolic links with their target names), rather than the name you specify. Setting find-file-visit-truename also implies the effect of find-file-existing-other-name.

Sometimes, a directory is ordinarily accessed through a symbolic link, and you may want Emacs to preferentially show its linked name. To do this, customize directory-abbrev-alist. Each element in this list should have the form (from . to), which means to replace from with to whenever from appears in a directory name. The from string is a regular expression (see Regexps). It is matched against directory names anchored at the first character, and should start with ‘\`’ (to support directory names with embedded newlines, which would defeat ‘^’). The to string should be an ordinary absolute directory name pointing to the same directory. Do not use ‘~’ to stand for a home directory in the to string; Emacs performs these substitutions separately. Here’s an example, from a system on which /home/fsf is normally accessed through a symbolic link named /fsf:

(("\\`/home/fsf" . "/fsf"))

Next: , Previous: , Up: Files   [Contents][Index]

18.8 File Directories

The file system groups files into directories. A directory listing is a list of all the files in a directory. Emacs provides commands to create and delete directories, and to make directory listings in brief format (file names only) and verbose format (sizes, dates, and other attributes included). Emacs also includes a directory browser feature called Dired, which you can invoke with C-x d; see Dired.

C-x C-d dir-or-pattern RET

Display a brief directory listing (list-directory).

C-u C-x C-d dir-or-pattern RET

Display a verbose directory listing.

M-x make-directory RET dirname RET

Create a new directory named dirname.

M-x delete-directory RET dirname RET

Delete the directory named dirname. If it isn’t empty, you will be asked whether you want to delete it recursively.

The command to display a directory listing is C-x C-d (list-directory). It reads using the minibuffer a file name which is either a directory to be listed or a wildcard-containing pattern for the files to be listed. 例如,

C-x C-d /u2/emacs/etc RET

lists all the files in directory /u2/emacs/etc. Here is an example of specifying a file name pattern:

C-x C-d /u2/emacs/src/*.c RET

Normally, C-x C-d displays a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to make a verbose listing including sizes, dates, and owners (like ‘ls -l’).

The text of a directory listing is mostly obtained by running ls in an inferior process. Two Emacs variables control the switches passed to ls: list-directory-brief-switches is a string giving the switches to use in brief listings ("-CF" by default), and list-directory-verbose-switches is a string giving the switches to use in a verbose listing ("-l" by default).

In verbose directory listings, Emacs adds information about the amount of free space on the disk that contains the directory.

The command M-x delete-directory prompts for a directory’s name using the minibuffer, and deletes the directory if it is empty. If the directory is not empty, you will be asked whether you want to delete it recursively. On systems that have a “Trash” (or “Recycle Bin”) feature, you can make this command move the specified directory to the Trash instead of deleting it outright, by changing the variable delete-by-moving-to-trash to t. See Misc File Ops, for more information about using the Trash.

Next: , Previous: , Up: Files   [Contents][Index]

18.9 Comparing Files

The command M-x diff prompts for two file names, using the minibuffer, and displays the differences between the two files in a buffer named *diff*. This works by running the diff program, using options taken from the variable diff-switches. The value of diff-switches should be a string; the default is "-u" to specify a unified context diff. See Diff in Comparing and Merging Files, for more information about the diff program.

The output of the diff command is shown using a major mode called Diff mode. See Diff Mode.

A (much more sophisticated) alternative is M-x ediff (see Ediff in The Ediff Manual).

The command M-x diff-backup compares a specified file with its most recent backup. If you specify the name of a backup file, diff-backup compares it with the source file that it is a backup of. In all other respects, this behaves like M-x diff.

The command M-x diff-buffer-with-file compares a specified buffer with its corresponding file. This shows you what changes you would make to the file if you save the buffer.

The command M-x diff-buffers compares the contents of two specified buffers.

The command M-x compare-windows compares the text in the current window with that in the window that was the selected window before you selected the current one. (For more information about windows in Emacs, Windows.) Comparison starts at point in each window, after pushing each initial point value on the mark ring (see Mark Ring) in its respective buffer. Then it moves point forward in each window, one character at a time, until it reaches characters that don’t match. Then the command exits.

If point in the two windows is followed by non-matching text when the command starts, M-x compare-windows tries heuristically to advance up to matching text in the two windows, and then exits. So if you use M-x compare-windows repeatedly, each time it either skips one matching range or finds the start of another.

With a numeric argument, compare-windows ignores changes in whitespace. If the variable compare-ignore-case is non-nil, the comparison ignores differences in case as well. If the variable compare-ignore-whitespace is non-nil, compare-windows by default ignores changes in whitespace, but a prefix argument turns that off for that single invocation of the command.

You can use M-x smerge-mode to turn on Smerge mode, a minor mode for editing output from the diff3 program. This is typically the result of a failed merge from a version control system update outside VC, due to conflicting changes to a file. Smerge mode provides commands to resolve conflicts by selecting specific changes.

See Emerge, for the Emerge facility, which provides a powerful interface for merging files.

Next: , Previous: , Up: Files   [Contents][Index]

18.10 Diff Mode

Diff mode is a major mode used for the output of M-x diff and other similar commands. This kind of output is called a patch, because it can be passed to the patch command to automatically apply the specified changes. To select Diff mode manually, type M-x diff-mode.

The changes specified in a patch are grouped into hunks, which are contiguous chunks of text that contain one or more changed lines. Hunks usually also include unchanged lines to provide context for the changes. Each hunk is preceded by a hunk header, which specifies the old and new line numbers where the hunk’s changes occur. Diff mode highlights each hunk header, to distinguish it from the actual contents of the hunk.

The first hunk in a patch is preceded by a file header, which shows the names of the new and the old versions of the file, and their time stamps. If a patch shows changes for more than one file, each file has such a header before the first hunk of that file’s changes.

You can edit a Diff mode buffer like any other buffer. (If it is read-only, you need to make it writable first; see Misc Buffer.) Whenever you edit a hunk, Diff mode attempts to automatically correct the line numbers in the hunk headers, to ensure that the patch remains correct, and could still be applied by patch. To disable automatic line number correction, change the variable diff-update-on-the-fly to nil.

Diff mode arranges for hunks to be treated as compiler error messages by M-g M-n and other commands that handle error messages (see Compilation Mode). Thus, you can use the compilation-mode commands to visit the corresponding source locations.

In addition, Diff mode provides the following commands to navigate, manipulate and apply parts of patches:

M-n

Move to the next hunk-start (diff-hunk-next). With prefix argument n, move forward to the nth next hunk.

By default, Diff mode refines hunks as Emacs displays them, highlighting their changes with better granularity. Alternatively, if you set diff-refine to the symbol navigation, Diff mode only refines the hunk you move to with this command or with diff-hunk-prev.

M-p

Move to the previous hunk-start (diff-hunk-prev). With prefix argument n, move back to the nth previous hunk. Like M-n, this command refines the hunk you move to if you set diff-refine to the symbol navigation.

M-}

Move to the next file-start, in a multi-file patch (diff-file-next). With prefix argument n, move forward to the start of the nth next file.

M-{

Move to the previous file-start, in a multi-file patch (diff-file-prev). With prefix argument n, move back to the start of the nth previous file.

M-k

Kill the hunk at point (diff-hunk-kill).

M-K

In a multi-file patch, kill the current file part. (diff-file-kill).

C-c C-a

Apply this hunk to its target file (diff-apply-hunk). With a prefix argument of C-u, revert this hunk, i.e. apply the reverse of the hunk, which changes the “new” version into the “old” version. If diff-jump-to-old-file is non-nil, apply the hunk to the “old” version of the file instead.

C-c C-b

Highlight the changes of the hunk at point with a finer granularity (diff-refine-hunk). This allows you to see exactly which parts of each changed line were actually changed.

By default, Diff mode refines hunks as Emacs displays them, so you may find this command useful if you customize diff-refine to a non-default value.

C-c C-c

Go to the source file and line corresponding to this hunk (diff-goto-source). By default, this jumps to the “new” version of the file, the one shown first on the file header. With a prefix argument, jump to the “old” version instead. If diff-jump-to-old-file is non-nil, this command by default jumps to the “old” file, and the meaning of the prefix argument is reversed. If the prefix argument is a number greater than 8 (e.g., if you type C-u C-u C-c C-c), then this command also sets diff-jump-to-old-file for the next invocation. If the source file is under version control (see Version Control), this jumps to the work file by default. With a prefix argument, jump to the “old” revision of the file (see Old Revisions), when point is on the old line, or otherwise jump to the “new” revision.

C-c C-e

Start an Ediff session with the patch (diff-ediff-patch). See Ediff in The Ediff Manual.

C-c C-n

Restrict the view to the current hunk (diff-restrict-view). See Narrowing. With a prefix argument, restrict the view to the current file of a multiple-file patch. To widen again, use C-x n w (widen).

C-c C-r

Reverse the direction of comparison for the entire buffer (diff-reverse-direction). With a prefix argument, reverse the direction only inside the current region (see Mark). Reversing the direction means changing the hunks and the file-start headers to produce a patch that would change the “new” version into the “old” one.

C-c C-s

Split the hunk at point (diff-split-hunk) into two separate hunks. This inserts a hunk header and modifies the header of the current hunk. This command is useful for manually editing patches, and only works with the unified diff format produced by the -u or --unified options to the diff program. If you need to split a hunk in the context diff format produced by the -c or --context options to diff, first convert the buffer to the unified diff format with C-c C-u.

C-c C-d

Convert the entire buffer to the context diff format (diff-unified->context). With a prefix argument, convert only the hunks within the region.

C-c C-u

Convert the entire buffer to unified diff format (diff-context->unified). With a prefix argument, convert unified format to context format. When the mark is active, convert only the hunks within the region.

C-c C-w

Re-generate the current hunk, disregarding changes in whitespace (diff-ignore-whitespace-hunk).

C-x 4 A

Generate a ChangeLog entry, like C-x 4 a does (see Change Log), for each one of the hunks (diff-add-change-log-entries-other-window). This creates a skeleton of the log of changes that you can later fill with the actual descriptions of the changes. C-x 4 a itself in Diff mode operates on behalf of the current hunk’s file, but gets the function name from the patch itself. This is useful for making log entries for functions that are deleted by the patch.

Patches sometimes include trailing whitespace on modified lines, as an unintentional and undesired change. There are two ways to deal with this problem. Firstly, if you enable Whitespace mode in a Diff buffer (see Useless Whitespace), it automatically highlights trailing whitespace in modified lines. Secondly, you can use the command M-x diff-delete-trailing-whitespace, which searches for trailing whitespace in the lines modified by the patch, and removes that whitespace in both the patch and the patched source file(s). This command does not save the modifications that it makes, so you can decide whether to save the changes (the list of modified files is displayed in the echo area). With a prefix argument, it tries to modify the original (“old”) source files rather than the patched (“new”) source files.

If non-nil, fragments of source in hunks are highlighted according to the appropriate major mode.

Next: , Previous: , Up: Files   [Contents][Index]

18.11 Copying, Naming and Renaming Files

Emacs has several commands for copying, naming, and renaming files. All of them read two file names, old (or target) and new, using the minibuffer, and then copy or adjust a file’s name accordingly; they do not accept wildcard file names.

In all these commands, if the argument new is just a directory name (see Directory Names in the Emacs Lisp Reference Manual), the real new name is in that directory, with the same non-directory component as old. For example, the command M-x rename-file RET ~/foo RET /tmp/ RET renames ~/foo to /tmp/foo. On GNU and other POSIX-like systems, directory names end in ‘/’.

All these commands ask for confirmation when the new file name already exists.

M-x copy-file copies the contents of the file old to the file new.

M-x copy-directory copies directories, similar to the cp -r shell command. If new is a directory name, it creates a copy of the old directory and puts it in new. Otherwise it copies all the contents of old into a new directory named new.

M-x rename-file renames file old as new. If the file name new already exists, you must confirm with yes or renaming is not done; this is because renaming causes the old meaning of the name new to be lost. If old and new are on different file systems, the file old is copied and deleted.

If a file is under version control (see Version Control), you should rename it using M-x vc-rename-file instead of M-x rename-file. See VC Delete/Rename.

M-x add-name-to-file adds an additional name to an existing file without removing the old name. The new name is created as a hard link to the existing file. The new name must belong on the same file system that the file is on. On MS-Windows, this command works only if the file resides in an NTFS file system. On MS-DOS, and some remote system types, it works by copying the file.

M-x make-symbolic-link creates a symbolic link named new, which points at target. The effect is that future attempts to open file new will refer to whatever file is named target at the time the opening is done, or will get an error if the name target is nonexistent at that time. This command does not expand the argument target, so that it allows you to specify a relative name as the target of the link. However, this command does expand leading ‘~’ in target so that you can easily specify home directories, and strips leading ‘/:’ so that you can specify relative names beginning with literal ‘~’ or ‘/:’. See Quoted File Names. On MS-Windows, this command works only on MS Windows Vista and later. When new is remote, it works depending on the system type.

18.12 Miscellaneous File Operations

Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wildcard file names.

M-x delete-file prompts for a file and deletes it. If you are deleting many files in one directory, it may be more convenient to use Dired rather than delete-file. See Dired Deletion.

M-x move-file-to-trash moves a file into the system Trash (or Recycle Bin). This is a facility available on most operating systems; files that are moved into the Trash can be brought back later if you change your mind. (The way to restore trashed files is system-dependent.)

By default, Emacs deletion commands do not use the Trash. To use the Trash (when it is available) for common deletion commands, change the variable delete-by-moving-to-trash to t. This affects the commands M-x delete-file and M-x delete-directory (see Directories), as well as the deletion commands in Dired (see Dired Deletion). Supplying a prefix argument to M-x delete-file or M-x delete-directory makes them delete outright, instead of using the Trash, regardless of delete-by-moving-to-trash.

If a file is under version control (see Version Control), you should delete it using M-x vc-delete-file instead of M-x delete-file. See VC Delete/Rename.

M-x insert-file (also C-x i) inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents. The position after the inserted contents is added to the mark ring, without activating the mark (see Mark Ring).

M-x insert-file-literally is like M-x insert-file, except the file is inserted literally: it is treated as a sequence of ASCII characters with no special encoding or conversion, similar to the M-x find-file-literally command (see Visiting).

M-x write-region is the inverse of M-x insert-file; it copies the contents of the region into the specified file. M-x append-to-file adds the text of the region to the end of the specified file. See Accumulating Text. The variable write-region-inhibit-fsync applies to these commands, as well as saving files; see Customize Save.

M-x set-file-modes reads a file name followed by a file mode, and applies that file mode to the specified file. File modes, also called file permissions, determine whether a file can be read, written to, or executed, and by whom. This command reads file modes using the same symbolic or octal format accepted by the chmod command; for instance, ‘u+x’ means to add execution permission for the user who owns the file. It has no effect on operating systems that do not support file modes. chmod is a convenience alias for this function.

Next: , Previous: , Up: Files   [Contents][Index]

18.13 Accessing Compressed Files

Emacs automatically uncompresses compressed files when you visit them, and automatically recompresses them if you alter them and save them. Emacs recognizes compressed files by their file names. File names ending in ‘.gz’ indicate a file compressed with gzip. Other endings indicate other compression programs.

Automatic uncompression and compression apply to all the operations in which Emacs uses the contents of a file. This includes visiting it, saving it, inserting its contents into a buffer, loading it, and byte compiling it.

To disable this feature, type the command M-x auto-compression-mode. You can disable it permanently by customizing the variable auto-compression-mode.

Next: , Previous: , Up: Files   [Contents][Index]

18.14 File Archives

A file whose name ends in ‘.tar’ is normally an archive made by the tar program. Emacs views these files in a special mode called Tar mode which provides a Dired-like list of the contents (see Dired). You can move around through the list just as you would in Dired, and visit the subfiles contained in the archive. However, not all Dired commands are available in Tar mode.

If Auto Compression mode is enabled (see Compressed Files), then Tar mode is used also for compressed archives—files with extensions ‘.tgz’, .tar.Z and .tar.gz.

The keys e, f and RET all extract a component file into its own buffer. You can edit it there, and if you save the buffer, the edited version will replace the version in the Tar buffer. Clicking with the mouse on the file name in the Tar buffer does likewise. v extracts a file into a buffer in View mode (see View Mode). o extracts the file and displays it in another window, so you could edit the file and operate on the archive simultaneously.

The I key adds a new (regular) file to the archive. The file is initially empty, but can readily be edited using the commands above. The command inserts the new file before the current one, so that using it on the topmost line of the Tar buffer makes the new file the first one in the archive, and using it at the end of the buffer makes it the last one.

d marks a file for deletion when you later use x, and u unmarks a file, as in Dired. C copies a file from the archive to disk and R renames a file within the archive. g reverts the buffer from the archive on disk. The keys M, G, and O change the file’s permission bits, group, and owner, respectively.

Saving the Tar buffer writes a new version of the archive to disk with the changes you made to the components.

You don’t need the tar program to use Tar mode—Emacs reads the archives directly. However, accessing compressed archives requires the appropriate uncompression program.

A separate but similar Archive mode is used for arc, jar, lzh, zip, rar, 7z, and zoo archives, as well as exe files that are self-extracting executables.

The key bindings of Archive mode are similar to those in Tar mode, with the addition of the m key which marks a file for subsequent operations, and M-DEL which unmarks all the marked files. Also, the a key toggles the display of detailed file information, for those archive types where it won’t fit in a single line. Operations such as renaming a subfile, or changing its mode or owner, are supported only for some of the archive formats.

Unlike Tar mode, Archive mode runs the archiving programs to unpack and repack archives. However, you don’t need these programs to look at the archive table of contents, only to extract or manipulate the subfiles in the archive. Details of the program names and their options can be set in the ‘Archive’ Customize group (see Customization Groups).

Next: , Previous: , Up: Files   [Contents][Index]

18.15 Remote Files

You can refer to files on other machines using a special file name syntax:

/method:host:filename
/method:user@host:filename
/method:user@host#port:filename

To carry out this request, Emacs uses a remote-login program such as ssh. You must always specify in the file name which method to use—for example, /ssh:user@host:filename uses ssh. When you specify the pseudo method ‘-’ in the file name, Emacs chooses the method as follows:

  1. If the host name starts with ‘ftp.’ (with dot), Emacs uses FTP.
  2. If the user name is ‘ftp’ or ‘anonymous’, Emacs uses FTP.
  3. If the variable tramp-default-method is set to ‘ftp’, Emacs uses FTP.
  4. If ssh-agent is running, Emacs uses scp.
  5. Otherwise, Emacs uses ssh.

You can entirely turn off the remote file name feature by setting the variable tramp-mode to nil. You can turn off the feature in individual cases by quoting the file name with ‘/:’ (see Quoted File Names).

Remote file access through FTP is handled by the Ange-FTP package, which is documented in the following. Remote file access through the other methods is handled by the Tramp package, which has its own manual. See The Tramp Manual in The Tramp Manual.

When the Ange-FTP package is used, Emacs logs in through FTP using the name user, if that is specified in the remote file name. If user is unspecified, Emacs logs in using your user name on the local system; but if you set the variable ange-ftp-default-user to a string, that string is used instead. When logging in, Emacs may also ask for a password.

For performance reasons, Emacs does not make backup files for files accessed via FTP by default. To make it do so, change the variable ange-ftp-make-backup-files to a non-nil value.

By default, auto-save files for remote files are made in the temporary file directory on the local machine, as specified by the variable auto-save-file-name-transforms. See Auto Save Files.

To visit files accessible by anonymous FTP, you use special user names ‘anonymous’ or ‘ftp’. Passwords for these user names are handled specially. The variable ange-ftp-generate-anonymous-password controls what happens: if the value of this variable is a string, then that string is used as the password; if non-nil (the default), then the value of user-mail-address is used; if nil, then Emacs prompts you for a password as usual (see Passwords).

Sometimes you may be unable to access files on a remote machine because a firewall in between blocks the connection for security reasons. If you can log in on a gateway machine from which the target files are accessible, and whose FTP server supports gatewaying features, you can still use remote file names; all you have to do is specify the name of the gateway machine by setting the variable ange-ftp-gateway-host, and set ange-ftp-smart-gateway to t. Otherwise you may be able to make remote file names work, but the procedure is complex. You can read the instructions by typing M-x finder-commentary RET ange-ftp RET.

Next: , Previous: , Up: Files   [Contents][Index]

18.16 Quoted File Names

You can quote an absolute file name to prevent special characters and syntax in it from having their special effects. The way to do this is to add ‘/:’ at the beginning.

For example, you can quote a local file name which appears remote, to prevent it from being treated as a remote file name. Thus, if you have a directory named /foo: and a file named bar in it, you can refer to that file in Emacs as ‘/:/foo:/bar’.

If you want to quote only special characters in the local part of a remote file name, you can quote just the local part. ‘/ssh:baz:/:/foo:/bar’ refers to the file bar of directory /foo: on the host baz.

/:’ can also prevent ‘~’ from being treated as a special character for a user’s home directory. For example, /:/tmp/~hack refers to a file whose name is ~hack in directory /tmp.

Quoting with ‘/:’ is also a way to enter in the minibuffer a file name that contains ‘$’. In order for this to work, the ‘/:’ must be at the beginning of the minibuffer contents. (You can also double each ‘$’; see File Names with $.)

You can also quote wildcard characters with ‘/:’, for visiting. For example, /:/tmp/foo*bar visits the file /tmp/foo*bar.

Another method of getting the same result is to enter /tmp/foo[*]bar, which is a wildcard specification that matches only /tmp/foo*bar. However, in many cases there is no need to quote the wildcard characters because even unquoted they give the right result. For example, if the only file name in /tmp that starts with ‘foo’ and ends with ‘bar’ is foo*bar, then specifying /tmp/foo*bar will visit only /tmp/foo*bar.

18.17 File Name Cache

You can use the file name cache to make it easy to locate a file by name, without having to remember exactly where it is located. When typing a file name in the minibuffer, C-TAB (file-cache-minibuffer-complete) completes it using the file name cache. If you repeat C-TAB, that cycles through the possible completions of what you had originally typed. (However, note that the C-TAB character cannot be typed on most text terminals.)

The file name cache does not fill up automatically. Instead, you load file names into the cache using these commands:

M-x file-cache-add-directory RET directory RET

Add each file name in directory to the file name cache.

M-x file-cache-add-directory-using-find RET directory RET

Add each file name in directory and all of its nested subdirectories to the file name cache.

M-x file-cache-add-directory-using-locate RET directory RET

Add each file name in directory and all of its nested subdirectories to the file name cache, using locate to find them all.

M-x file-cache-add-directory-list RET variable RET

Add each file name in each directory listed in variable to the file name cache. variable should be a Lisp variable whose value is a list of directories, like load-path.

M-x file-cache-clear-cache RET

Clear the cache; that is, remove all file names from it.

The file name cache is not persistent: it is kept and maintained only for the duration of the Emacs session. You can view the contents of the cache with the file-cache-display command.

Next: , Previous: , Up: Files   [Contents][Index]

18.18 Convenience Features for Finding Files

In this section, we introduce some convenient facilities for finding recently-opened files, reading file names from a buffer.

If you enable Recentf mode, with M-x recentf-mode, the ‘File’ menu includes a submenu containing a list of recently opened files. M-x recentf-save-list saves the current recentf-list to a file, and M-x recentf-edit-list edits it.

The M-x ffap command generalizes find-file with more powerful heuristic defaults (see FFAP), often based on the text at point. Partial Completion mode offers other features extending find-file, which can be used with ffap. See Completion Options.

Next: , Previous: , Up: Files   [Contents][Index]

18.19 Viewing Image Files

Visiting image files automatically selects Image mode. In this major mode, you can type C-c C-c (image-toggle-display) to toggle between displaying the file as an image in the Emacs buffer, and displaying its underlying text (or raw byte) representation. Additionally you can type C-c C-x (image-toggle-hex-display) to toggle between displaying the file as an image in the Emacs buffer, and displaying it in hex representation. Displaying the file as an image works only if Emacs is compiled with support for displaying such images.

If the displayed image is wider or taller than the window in which it is displayed, the usual point motion keys (C-f, C-p, and so forth) cause different parts of the image to be displayed. However, by default images are resized automatically to fit the window, so this is only necessary if you customize the default behavior by using the options image-auto-resize and image-auto-resize-on-window-resize.

To resize the image manually you can use the command image-transform-fit-both bound to s b that fits the image to both the window height and width. To scale the image specifying a scale factor, use the command image-transform-set-scale bound to s s. To reset all transformations to the initial state, use image-transform-reset bound to s 0.

You can press n (image-next-file) and p (image-previous-file) to visit the next image file and the previous image file in the same directory, respectively.

When looking through images, it’s sometimes convenient to be able to mark the files for later processing (for instance, if you want to select a group of images to copy somewhere else). The m (image-mode-mark-file) command will mark the current file in any Dired buffer(s) that display the current file’s directory. If no such buffer is open, the directory is opened in a new buffer. To unmark files, use the u (image-mode-mark-file) command. Finally, if you just want to copy the current buffers file name to the kill ring, you can use the w (image-mode-copy-file-name-as-kill) command.

If the image can be animated, the command RET (image-toggle-animation) starts or stops the animation. Animation plays once, unless the option image-animate-loop is non-nil. With f (image-next-frame) and b (image-previous-frame) you can step through the individual frames. Both commands accept a numeric prefix to step through several frames at once. You can go to a specific frame with F (image-goto-frame). Frames are indexed from 1. Typing a + (image-increase-speed) increases the speed of the animation, a - (image-decrease-speed) decreases it, and a r (image-reverse-speed) reverses it. The command a 0 (image-reset-speed) resets the speed to the original value.

If Emacs was compiled with support for the ImageMagick library, it can use ImageMagick to render a wide variety of images. The variable imagemagick-enabled-types lists the image types that Emacs may render using ImageMagick; each element in the list should be an internal ImageMagick name for an image type, as a symbol or an equivalent string (e.g., BMP for .bmp images). To enable ImageMagick for all possible image types, change imagemagick-enabled-types to t. The variable imagemagick-types-inhibit lists the image types which should never be rendered using ImageMagick, regardless of the value of imagemagick-enabled-types (the default list includes types like C and HTML, which ImageMagick can render as an image but Emacs should not). To disable ImageMagick entirely, change imagemagick-types-inhibit to t.

If Emacs doesn’t have native support for the image format in question, and image-use-external-converter is non-nil, Emacs will try to determine whether there are external utilities that can be used to transform the image in question to PNG before displaying. GraphicsMagick, ImageMagick and ffmpeg are currently supported for image conversions.

The Image-Dired package can also be used to view images as thumbnails. See Image-Dired.

Previous: , Up: Files   [Contents][Index]

18.20 Filesets

If you regularly edit a certain group of files, you can define them as a fileset. This lets you perform certain operations, such as visiting, query-replace, and shell commands on all the files at once. To make use of filesets, you must first add the expression (filesets-init) to your init file (see Init File). This adds a ‘Filesets’ sub-menu to the menu bar’s ‘File’ menu.

The simplest way to define a fileset is by adding files to it one at a time. To add a file to fileset name, visit the file and type M-x filesets-add-buffer RET name RET. If there is no fileset name, this creates a new one, which initially contains only the current file. The command M-x filesets-remove-buffer removes the current file from a fileset.

You can also edit the list of filesets directly, with M-x filesets-edit (or by choosing ‘Edit Filesets’ from the ‘Filesets’ menu). The editing is performed in a Customize buffer (see Easy Customization). Normally, a fileset is a simple list of files, but you can also define a fileset as a regular expression matching file names. Some examples of these more complicated filesets are shown in the Customize buffer. Remember to select ‘Save for future sessions’ if you want to use the same filesets in future Emacs sessions.

You can use the command M-x filesets-open to visit all the files in a fileset, and M-x filesets-close to close them. Use M-x filesets-run-cmd to run a shell command on all the files in a fileset. These commands are also available from the ‘Filesets’ menu, where each existing fileset is represented by a submenu.

See Version Control, for a different concept of filesets: groups of files bundled together for version control operations. Filesets of that type are unnamed, and do not persist across Emacs sessions.


Next: , Previous: , Up: Top   [Contents][Index]

19 Using Multiple Buffers

The text you are editing in Emacs resides in an object called a buffer. Each time you visit a file, a buffer is used to hold the file’s text. Each time you invoke Dired, a buffer is used to hold the directory listing. If you send a message with C-x m, a buffer is used to hold the text of the message. When you ask for a command’s documentation, that appears in a buffer named *Help*.

Buffers exist as long as they are in use, and are deleted (“killed”) when no longer needed, either by you (see Kill Buffer) or by Emacs (e.g., when you exit Emacs, see Exiting).

Each buffer has a unique name, which can be of any length. When a buffer is displayed in a window, its name is shown in the mode line (see Mode Line). The distinction between upper and lower case matters in buffer names. Most buffers are made by visiting files, and their names are derived from the files’ names; however, you can also create an empty buffer with any name you want. A newly started Emacs has several buffers, including one named *scratch*, which can be used for evaluating Lisp expressions and is not associated with any file (see Lisp Interaction).

At any time, one and only one buffer is selected; we call it the current buffer. We sometimes say that a command operates on “the buffer”; this really means that it operates on the current buffer. When there is only one Emacs window, the buffer displayed in that window is current. When there are multiple windows, the buffer displayed in the selected window is current. See Windows.

A buffer’s contents consist of a series of characters, each of which optionally carries a set of text properties (see Text properties) that can specify more information about that character.

Aside from its textual contents, each buffer records several pieces of information, such as what file it is visiting (if any), whether it is modified, and what major mode and minor modes are in effect (see Modes). These are stored in buffer-local variables—variables that can have a different value in each buffer. See Locals.

A buffer’s size cannot be larger than some maximum, which is defined by the largest buffer position representable by Emacs integers. This is because Emacs tracks buffer positions using that data type. For typical 64-bit machines, this maximum buffer size is 2^{61} - 2 bytes, or about 2 EiB. For typical 32-bit machines, the maximum is usually 2^{29} - 2 bytes, or about 512 MiB. Buffer sizes are also limited by the amount of memory in the system.

Next: , Up: Buffers   [Contents][Index]

19.1 Creating and Selecting Buffers

C-x b buffer RET

Select or create a buffer named buffer (switch-to-buffer).

C-x 4 b buffer RET

Similar, but select buffer in another window (switch-to-buffer-other-window).

C-x 5 b buffer RET

Similar, but select buffer in a separate frame (switch-to-buffer-other-frame).

C-x LEFT

Select the previous buffer in the buffer list (previous-buffer).

C-x RIGHT

Select the next buffer in the buffer list (next-buffer).

C-u M-g M-g
C-u M-g g

Read a number n and move to line n in the most recently selected buffer other than the current buffer, in another window.

The C-x b (switch-to-buffer) command reads a buffer name using the minibuffer. Then it makes that buffer current, and displays it in the currently-selected window. An empty input specifies the buffer that was current most recently among those not now displayed in any window.

While entering the buffer name, you can use the usual completion and history commands (see Minibuffer). Note that C-x b, and related commands, use permissive completion with confirmation for minibuffer completion: if you type RET when the minibuffer text names a nonexistent buffer, Emacs prints ‘[Confirm]’ and you must type a second RET to submit that buffer name. See Completion Exit, for details. For other completion options and features, see Completion Options.

If you specify a buffer that does not exist, C-x b creates a new, empty buffer that is not visiting any file, and selects it for editing. The default value of the variable major-mode determines the new buffer’s major mode; the default value is Fundamental mode. 请参阅主模式。One reason to create a new buffer is to use it for making temporary notes. If you try to save it, Emacs asks for the file name to use, and the buffer’s major mode is re-established taking that file name into account (see Choosing Modes).

For conveniently switching between a few buffers, use the commands C-x LEFT and C-x RIGHT. C-x LEFT (previous-buffer) selects the previous buffer (following the order of most recent selection in the current frame), while C-x RIGHT (next-buffer) moves through buffers in the reverse direction. Both commands support a numeric prefix argument that serves as a repeat count.

To select a buffer in a window other than the current one (see Windows), type C-x 4 b (switch-to-buffer-other-window). This prompts for a buffer name using the minibuffer, displays that buffer in another window, and selects that window.

Similarly, C-x 5 b (switch-to-buffer-other-frame) prompts for a buffer name, displays that buffer in another frame (see Frames), and selects that frame. If the buffer is already being shown in a window on another frame, Emacs selects that window and frame instead of creating a new frame.

See Displaying Buffers, for how the C-x 4 b and C-x 5 b commands get the window and/or frame to display in.

In addition, C-x C-f, and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. See Visiting.

C-u M-g M-g, that is goto-line with a plain prefix argument, reads a number n using the minibuffer, selects the most recently selected buffer other than the current buffer in another window, and then moves point to the beginning of line number n in that buffer. This is mainly useful in a buffer that refers to line numbers in another buffer: if point is on or just after a number, goto-line uses that number as the default for n. Note that prefix arguments other than just C-u behave differently. C-u 4 M-g M-g goes to line 4 in the current buffer, without reading a number from the minibuffer. (Remember that M-g M-g without prefix argument reads a number n and then moves to line number n in the current buffer. See Moving Point.)

Emacs uses buffer names that start with a space for internal purposes. It treats these buffers specially in minor ways—for example, by default they do not record undo information. It is best to avoid using such buffer names yourself.

Next: , Previous: , Up: Buffers   [Contents][Index]

19.2 Listing Existing Buffers

C-x C-b

List the existing buffers (list-buffers).

To display a list of existing buffers, type C-x C-b. This pops up a buffer menu in a buffer named *Buffer List*. Each line in the list shows one buffer’s name, size, major mode and visited file. The buffers are listed in the order that they were current; the buffers that were current most recently come first. This section describes how the list of buffers is displayed and how to interpret the various indications in the list; see Several Buffers, for description of the special mode in the *Buffer List* buffer and the commands available there.

.’ in the first field of a line indicates that the buffer is current. ‘%’ indicates a read-only buffer. ‘*’ indicates that the buffer is modified. If several buffers are modified, it may be time to save some with C-x s (see Save Commands). Here is an example of a buffer list:

CRM Buffer                Size  Mode              File
. * .emacs                3294  Emacs-Lisp        ~/.emacs
 %  *Help*                 101  Help
    search.c             86055  C                 ~/cvs/emacs/src/search.c
 %  src                  20959  Dired by name     ~/cvs/emacs/src/
  * *mail*                  42  Mail
 %  HELLO                 1607  Fundamental       ~/cvs/emacs/etc/HELLO
 %  NEWS                481184  Outline           ~/cvs/emacs/etc/NEWS
    *scratch*              191  Lisp Interaction
  * *Messages*            1554  Messages

The buffer *Help* was made by a help request (see Help); it is not visiting any file. The buffer src was made by Dired on the directory ~/cvs/emacs/src/. You can list only buffers that are visiting files by giving the command a prefix argument, as in C-u C-x C-b.

list-buffers omits buffers whose names begin with a space, unless they visit files: such buffers are used internally by Emacs.

Next: , Previous: , Up: Buffers   [Contents][Index]

19.3 Miscellaneous Buffer Operations

C-x C-q

Toggle read-only status of buffer (read-only-mode).

M-x rename-buffer RET buffer RET

Change the name of the current buffer.

M-x rename-uniquely

Rename the current buffer by adding ‘<number>’ to the end.

M-x view-buffer RET buffer RET

Scroll through buffer buffer. See View Mode.

A buffer can be read-only, which means that commands to insert or delete its text are not allowed. (However, other commands, like C-x RET f, can still mark it as modified, see Text Coding). The mode line indicates read-only buffers with ‘%%’ or ‘%*’ near the left margin. See Mode Line. Read-only buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text. Visiting a file whose access control says you cannot write it also makes the buffer read-only.

The command C-x C-q (read-only-mode) makes a read-only buffer writable, and makes a writable buffer read-only. This works by setting the variable buffer-read-only, which has a local value in each buffer and makes the buffer read-only if its value is non-nil. If you change the option view-read-only to a non-nil value, making the buffer read-only with C-x C-q also enables View mode in the buffer (see View Mode).

M-x rename-buffer changes the name of the current buffer. You specify the new name as a minibuffer argument; there is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done.

M-x rename-uniquely renames the current buffer to a similar name with a numeric suffix added to make it both different and unique. This command does not need an argument. It is useful for creating multiple shell buffers: if you rename the *shell* buffer, then do M-x shell again, it makes a new shell buffer named *shell*; meanwhile, the old shell buffer continues to exist under its new name. This method is also good for mail buffers, compilation buffers, and most Emacs features that create special buffers with particular names. (With some of these features, such as M-x compile, M-x grep, you need to switch to some other buffer before using the command again, otherwise it will reuse the current buffer despite the name change.)

The commands M-x append-to-buffer and M-x insert-buffer can also be used to copy text from one buffer to another. See Accumulating Text.

Next: , Previous: , Up: Buffers   [Contents][Index]

19.4 Killing Buffers

If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to kill the buffers you no longer need. (Some other editors call this operation close, and talk about “closing the buffer” or “closing the file” visited in the buffer.) On most operating systems, killing a buffer releases the memory Emacs used for the buffer back to the operating system so that other programs can use it. Here are some commands for killing buffers:

C-x k buffer RET

Kill buffer buffer (kill-buffer).

M-x kill-some-buffers

Offer to kill each buffer, one by one.

M-x kill-matching-buffers

Offer to kill all buffers matching a regular expression.

C-x k (kill-buffer) kills one buffer, whose name you specify in the minibuffer. The default, used if you type just RET in the minibuffer, is to kill the current buffer. If you kill the current buffer, another buffer becomes current: one that was current in the recent past but is not displayed in any window now. If you ask to kill a file-visiting buffer that is modified, then you must confirm with yes before the buffer is killed.

The command M-x kill-some-buffers asks about each buffer, one by one. An answer of yes means to kill the buffer, just like kill-buffer. This command ignores buffers whose names begin with a space, which are used internally by Emacs.

The command M-x kill-matching-buffers prompts for a regular expression and kills all buffers whose names match that expression. See Regexps. Like kill-some-buffers, it asks for confirmation before each kill. This command normally ignores buffers whose names begin with a space, which are used internally by Emacs. To kill internal buffers as well, call kill-matching-buffers with a prefix argument.

The Buffer Menu feature is also convenient for killing various buffers. See Several Buffers.

If you want to do something special every time a buffer is killed, you can add hook functions to the hook kill-buffer-hook (see Hooks).

If you run one Emacs session for a period of days, as many people do, it can fill up with buffers that you used several days ago. The command M-x clean-buffer-list is a convenient way to purge them; it kills all the unmodified buffers that you have not used for a long time. An ordinary buffer is killed if it has not been displayed for three days; however, you can specify certain buffers that should never be killed automatically, and others that should be killed if they have been unused for a mere hour. These defaults, and other aspects of this command’s behavior, can be controlled by customizing several options described in the doc string of clean-buffer-list.

You can also have this buffer purging done for you, once a day, by enabling Midnight mode. Midnight mode operates each day at midnight; at that time, it runs clean-buffer-list, or whichever functions you have placed in the normal hook midnight-hook (see Hooks). To enable Midnight mode, use the Customization buffer to set the variable midnight-mode to t. See Easy Customization.

Next: , Previous: , Up: Buffers   [Contents][Index]

19.5 Operating on Several Buffers

M-x buffer-menu

Begin editing a buffer listing all Emacs buffers.

M-x buffer-menu-other-window

Similar, but do it in another window.

The Buffer Menu opened by C-x C-b (see List Buffers) does not merely list buffers. It also allows you to perform various operations on buffers, through an interface similar to Dired (see Dired). You can save buffers, kill them (here called deleting them, for consistency with Dired), or display them.

To use the Buffer Menu, type C-x C-b and switch to the window displaying the *Buffer List* buffer. You can also type M-x buffer-menu to open the Buffer Menu in the selected window. Alternatively, the command M-x buffer-menu-other-window opens the Buffer Menu in another window, and selects that window.

The Buffer Menu is a read-only buffer, and can be changed only through the special commands described in this section. The usual cursor motion commands can be used in this buffer. The following commands apply to the buffer described on the current line:

d

Flag the buffer for deletion (killing), then move point to the next line (Buffer-menu-delete). The deletion flag is indicated by the character ‘D’ on the line, before the buffer name. The deletion occurs only when you type the x command (see below).

C-d

Like d, but move point up instead of down (Buffer-menu-delete-backwards).

s

Flag the buffer for saving (Buffer-menu-save). The save flag is indicated by the character ‘S’ on the line, before the buffer name. The saving occurs only when you type x. You may request both saving and deletion for the same buffer.

x

Perform all flagged deletions and saves (Buffer-menu-execute).

u

Remove all flags from the current line, and move down (Buffer-menu-unmark). With a prefix argument, moves up after removing the flags.

DEL

Move to the previous line and remove all flags on that line (Buffer-menu-backup-unmark).

M-DEL

Remove a particular flag from all lines (Buffer-menu-unmark-all-buffers). This asks for a single character, and unmarks buffers marked with that character; typing RET removes all marks.

U

Remove all flags from all the lines (Buffer-menu-unmark-all).

The commands for removing flags, d and C-d, accept a numeric argument as a repeat count.

The following commands operate immediately on the buffer listed on the current line. They also accept a numeric argument as a repeat count.

~

Mark the buffer as unmodified (Buffer-menu-not-modified). See Save Commands.

%

Toggle the buffer’s read-only status (Buffer-menu-toggle-read-only). See Misc Buffer.

t

Visit the buffer as a tags table (Buffer-menu-visit-tags-table). See Select Tags Table.

The following commands are used to select another buffer or buffers:

q

Quit the Buffer Menu (quit-window). The most recent formerly visible buffer is displayed in its place.

RET
f

Select this line’s buffer, replacing the *Buffer List* buffer in its window (Buffer-menu-this-window).

o

Select this line’s buffer in another window, as if by C-x 4 b, leaving *Buffer List* visible (Buffer-menu-other-window).

C-o

Display this line’s buffer in another window, without selecting it (Buffer-menu-switch-other-window).

1

Select this line’s buffer in a full-frame window (Buffer-menu-1-window).

2

Set up two windows on the current frame, with this line’s buffer selected in one, and a previously current buffer (aside from *Buffer List*) in the other (Buffer-menu-2-window).

b

Bury this line’s buffer (Buffer-menu-bury) (i.e., move it to the end of the buffer list).

m

Mark this line’s buffer to be displayed in another window if you exit with the v command (Buffer-menu-mark). The display flag is indicated by the character ‘>’ at the beginning of the line. (A single buffer may not have both deletion and display flags.)

v

Select this line’s buffer, and also display in other windows any buffers flagged with the m command (Buffer-menu-select). If you have not flagged any buffers, this command is equivalent to 1.

The following commands affect the entire buffer list:

S

Sort the Buffer Menu entries according to their values in the column at point. With a numeric prefix argument n, sort according to the n-th column (tabulated-list-sort).

}

Widen the current column width by n (the prefix numeric argument) characters.

{

Narrow the current column width by n (the prefix numeric argument) characters.

T

Delete, or reinsert, lines for non-file buffers (Buffer-menu-toggle-files-only). This command toggles the inclusion of such buffers in the buffer list.

Normally, the buffer *Buffer List* is not updated automatically when buffers are created and killed; its contents are just text. If you have created, deleted or renamed buffers, the way to update *Buffer List* to show what you have done is to type g (revert-buffer). You can make this happen regularly every auto-revert-interval seconds if you enable Auto Revert mode in this buffer, as long as it is not marked modified. Global Auto Revert mode applies to the *Buffer List* buffer only if global-auto-revert-non-file-buffers is non-nil. See global-auto-revert-non-file-buffers, for details.

19.6 Indirect Buffers

An indirect buffer shares the text of some other buffer, which is called the base buffer of the indirect buffer. In some ways it is a buffer analogue of a symbolic link between files.

M-x make-indirect-buffer RET base-buffer RET indirect-name RET

Create an indirect buffer named indirect-name with base buffer base-buffer.

M-x clone-indirect-buffer RET

Create an indirect buffer that is a twin copy of the current buffer.

C-x 4 c

Create an indirect buffer that is a twin copy of the current buffer, and select it in another window (clone-indirect-buffer-other-window).

The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. But in all other respects, the indirect buffer and its base buffer are completely separate. They can have different names, different values of point, different narrowing, different markers, different major modes, and different local variables.

An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually works by saving the base buffer. Killing the base buffer effectively kills the indirect buffer, but killing an indirect buffer has no effect on its base buffer.

One way to use indirect buffers is to display multiple views of an outline. See Outline Views.

A quick and handy way to make an indirect buffer is with the command M-x clone-indirect-buffer. It creates and selects an indirect buffer whose base buffer is the current buffer. With a numeric argument, it prompts for the name of the indirect buffer; otherwise it uses the name of the current buffer, with a ‘<n>’ suffix added. C-x 4 c (clone-indirect-buffer-other-window) works like M-x clone-indirect-buffer, but it selects the new buffer in another window. These functions run the hook clone-indirect-buffer-hook after creating the indirect buffer.

The more general way to make an indirect buffer is with the command M-x make-indirect-buffer. It creates an indirect buffer named indirect-name from a buffer base-buffer, prompting for both using the minibuffer.

Previous: , Up: Buffers   [Contents][Index]

19.7 Convenience Features and Customization of Buffer Handling

This section describes several modes and features that make it more convenient to switch between buffers.

19.7.1 Making Buffer Names Unique

When several buffers visit identically-named files, Emacs must give the buffers distinct names. The default method adds a suffix based on the names of the directories that contain the files. For example, if you visit files /foo/bar/mumble/name and /baz/quux/mumble/name at the same time, their buffers will be named ‘name<bar/mumble>’ and ‘name<quux/mumble>’, respectively. Emacs adds as many directory parts as are needed to make a unique name.

You can choose from several different styles for constructing unique buffer names, by customizing the option uniquify-buffer-name-style.

The forward naming method includes part of the file’s directory name at the beginning of the buffer name; using this method, buffers visiting the files /u/rms/tmp/Makefile and /usr/projects/zaphod/Makefile would be named ‘tmp/Makefile’ and ‘zaphod/Makefile’.

In contrast, the post-forward naming method would call the buffers ‘Makefile|tmp’ and ‘Makefile|zaphod’. The default method post-forward-angle-brackets is like post-forward, except that it encloses the unique path in angle brackets. The reverse naming method would call them ‘Makefile\tmp’ and ‘Makefile\zaphod’. The nontrivial difference between post-forward and reverse occurs when just one directory name is not enough to distinguish two files; then reverse puts the directory names in reverse order, so that /top/middle/file becomes ‘file\middle\top’, while post-forward puts them in forward order after the file name, as in ‘file|top/middle’. If uniquify-buffer-name-style is set to nil, the buffer names simply get ‘<2>’, ‘<3>’, etc. appended.

Which rule to follow for putting the directory names in the buffer name is not very important if you are going to look at the buffer names before you type one. But as an experienced user, if you know the rule, you won’t have to look. And then you may find that one rule or another is easier for you to remember and apply quickly.

Next: , Previous: , Up: Buffer Convenience   [Contents][Index]

19.7.2 Fast minibuffer selection

Icomplete global minor mode provides a convenient way to quickly select an element among the possible completions in a minibuffer. When enabled, typing in the minibuffer continuously displays a list of possible completions that match the string you have typed.

At any time, you can type C-j to select the first completion in the list. So the way to select a particular completion is to make it the first in the list. There are two ways to do this. You can type more of the completion name and thus narrow down the list, excluding unwanted completions above the desired one. Alternatively, you can use C-. and C-, to rotate the list until the desired buffer is first.

M-TAB will select the first completion in the list, like C-j but without exiting the minibuffer, so you can edit it further. This is typically used when entering a file name, where M-TAB can be used a few times to descend in the hierarchy of directories.

To enable Icomplete mode, type M-x icomplete-mode, or customize the variable icomplete-mode to t (see Easy Customization).

An alternative to Icomplete mode is Fido mode. This is very similar to Icomplete mode, but retains some functionality from a popular extension called Ido mode (in fact the name is derived from “Fake Ido”). Among other things, in Fido mode, C-s and C-r are also used to rotate the completions list, C-k can be used to delete files and kill buffers in-list. Another noteworthy aspect is that flex is used as the default completion style (see Completion Styles). To change this, add the following to your initialization file (see Init File):

(defun my-icomplete-styles ()
  (setq-local completion-styles '(initials flex)))
(add-hook 'icomplete-minibuffer-setup-hook 'my-icomplete-styles)

To enable Fido mode, type M-x fido-mode, or customize the variable fido-mode to t (see Easy Customization).

19.7.3 Customizing Buffer Menus

M-x bs-show

Make a list of buffers similarly to M-x list-buffers but customizable.

M-x ibuffer

Make a list of buffers and operate on them in Dired-like fashion.

M-x bs-show pops up a buffer list similar to the one normally displayed by C-x C-b, but whose display you can customize in a more flexible fashion. For example, you can specify the list of buffer attributes to show, the minimum and maximum width of buffer name column, a regexp for names of buffers that will never be shown and those which will always be shown, etc. If you prefer this to the usual buffer list, you can bind this command to C-x C-b. To customize this buffer list, use the bs Custom group (see Easy Customization), or invoke bs-customize.

MSB global minor mode (“MSB” stands for “mouse select buffer”) provides a different and customizable mouse buffer menu which you may prefer. It replaces the mouse-buffer-menu commands, normally bound to C-Down-mouse-1 and C-F10, with its own commands, and also modifies the menu-bar buffer menu. You can customize the menu in the msb Custom group.

IBuffer is a major mode for viewing a list of buffers and operating on them in a way analogous to that of Dired (see Dired), including filtering, marking, sorting in various ways, and acting on buffers.


Next: , Previous: , Up: Top   [Contents][Index]

20 Multiple Windows

Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame.

Next: , Up: Windows   [Contents][Index]

20.1 Concepts of Emacs Windows

Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But these windows can show different parts of the buffer, because each window has its own value of point.

At any time, one Emacs window is the selected window; the buffer this window is displaying is the current buffer. On graphical displays, the point is indicated by a solid blinking cursor in the selected window, and by a hollow box in non-selected windows. On text terminals, the cursor is drawn only in the selected window. See Cursor Display.

Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in other Emacs windows, even those showing the same buffer. The same is true for buffer-switching commands such as C-x b; they do not affect other windows at all. However, there are other commands such as C-x 4 b that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) C-h f (describe-function) and C-x C-b (list-buffers), usually work by displaying buffers in a nonselected window without affecting the selected window.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, they all have the same value for the mark, because each buffer has only one mark position.

Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. The selected window’s mode line appears in a different color. See Mode Line, for details.

Next: , Previous: , Up: Windows   [Contents][Index]

20.2 Splitting Windows

C-x 2

Split the selected window into two windows, one above the other (split-window-below).

C-x 3

Split the selected window into two windows, positioned side by side (split-window-right).

C-mouse-2

In the mode line of a window, split that window.

C-x 2 (split-window-below) splits the selected window into two windows, one above the other. After splitting, the selected window is the upper one, and the newly split-off window is below. Both windows have the same value of point as before, and display the same portion of the buffer (or as close to it as possible). If necessary, the windows are scrolled to keep point on-screen. By default, the two windows each get half the height of the original window. A positive numeric argument specifies how many lines to give to the top window; a negative numeric argument specifies how many lines to give to the bottom window.

If you change the variable split-window-keep-point to nil, C-x 2 instead adjusts the portion of the buffer displayed by the two windows, as well as the value of point in each window, in order to keep the text on the screen as close as possible to what it was before; furthermore, if point was in the lower half of the original window, the bottom window is selected instead of the upper one.

C-x 3 (split-window-right) splits the selected window into two side-by-side windows. The left window is the selected one; the right window displays the same portion of the same buffer, and has the same value of point. A positive numeric argument specifies how many columns to give the left window; a negative numeric argument specifies how many columns to give the right window.

When you split a window with C-x 3, each resulting window occupies less than the full width of the frame. If it becomes too narrow, the buffer may be difficult to read if continuation lines are in use (see Continuation Lines). Therefore, Emacs automatically switches to line truncation if the window width becomes narrower than 50 columns. This truncation occurs regardless of the value of the variable truncate-lines (see Line Truncation); it is instead controlled by the variable truncate-partial-width-windows. If the value of this variable is a positive integer (the default is 50), that specifies the minimum total width for a partial-width window before automatic line truncation occurs; if the value is nil, automatic line truncation is disabled; and for any other non-nil value, Emacs truncates lines in every partial-width window regardless of its width. The total width of a window is in column units as reported by window-total-width (see Window Sizes in The Emacs Lisp Reference Manual), it includes the fringes, the continuation and truncation glyphs, the margins, and the scroll bar.

On text terminals, side-by-side windows are separated by a vertical divider which is drawn using the vertical-border face.

If you click C-mouse-2 in the mode line of a window, that splits the window, putting a vertical divider where you click. Depending on how Emacs is compiled, you can also split a window by clicking C-mouse-2 in the scroll bar, which puts a horizontal divider where you click (this feature does not work when Emacs uses GTK+ scroll bars).

By default, when you split a window, Emacs gives each of the resulting windows dimensions that are an integral multiple of the default font size of the frame. That might subdivide the screen estate unevenly between the resulting windows. If you set the variable window-resize-pixelwise to a non-nil value, Emacs will give each window the same number of pixels (give or take one pixel if the initial dimension was an odd number of pixels). Note that when a frame’s pixel size is not a multiple of the frame’s character size, at least one window may get resized pixelwise even if this option is nil.

Next: , Previous: , Up: Windows   [Contents][Index]

20.3 Using Other Windows

C-x o

Select another window (other-window).

C-M-v

Scroll the next window upward (scroll-other-window).

C-M-S-v

Scroll the next window downward (scroll-other-window-down).

鼠标左键

mouse-1, in the text area of a window, selects the window and moves point to the position clicked. Clicking in the mode line selects the window without moving point in it.

With the keyboard, you can switch windows by typing C-x o (other-window). That is an o, for “other”, not a zero. When there are more than two windows, this command moves through all the windows in a cyclic order, generally top to bottom and left to right. After the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument means to move several steps in the cyclic order of windows. A negative argument moves around the cycle in the opposite order. When the minibuffer is active, the minibuffer window is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. See Minibuffer Edit.

The other-window command will normally only switch to the next window in the current frame (unless otherwise configured). If you work in a multi-frame environment and you want windows in all frames to be part of the cycle, you can rebind C-x o to the next-window-any-frame command. (See Rebinding, for how to rebind a command.)

The usual scrolling commands (see Display) apply to the selected window only, but there are also commands to scroll the next window. C-M-v (scroll-other-window) scrolls the window that C-x o would select. In other respects, the command behaves like C-v; both move the buffer text upward relative to the window, and take positive and negative arguments. (In the minibuffer, C-M-v scrolls the help window associated with the minibuffer, if any, rather than the next window in the standard cyclic order; see Minibuffer Edit.) C-M-S-v (scroll-other-window-down) scrolls the next window downward in a similar way.

If you set mouse-autoselect-window to a non-nil value, moving the mouse over a different window selects that window. This feature is off by default.

Next: , Previous: , Up: Windows   [Contents][Index]

20.4 Displaying in Another Window

C-x 4 is a prefix key for a variety of commands that switch to a buffer in a different window—either another existing window, or a new window created by splitting the selected window. See Window Choice, for how Emacs picks or creates the window to use.

C-x 4 b bufname RET

Select buffer bufname in another window (switch-to-buffer-other-window). See Select Buffer.

C-x 4 C-o bufname RET

Display buffer bufname in some window, without trying to select it (display-buffer). See Displaying Buffers, for details about how the window is chosen.

C-x 4 f filename RET

Visit file filename and select its buffer in another window (find-file-other-window). See Visiting.

C-x 4 d directory RET

Select a Dired buffer for directory directory in another window (dired-other-window). See Dired.

C-x 4 m

Start composing a mail message, similar to C-x m (see Sending Mail), but in another window (compose-mail-other-window).

C-x 4 .

Find the definition of an identifier, similar to M-. (see Xref), but in another window (xref-find-definitions-other-window).

C-x 4 r filename RET

Visit file filename read-only, and select its buffer in another window (find-file-read-only-other-window). See Visiting.

Next: , Previous: , Up: Windows   [Contents][Index]

20.5 Deleting and Resizing Windows

C-x 0

Delete the selected window (delete-window).

C-x 1

Delete all windows in the selected frame except the selected window (delete-other-windows).

C-x 4 0

Delete the selected window and kill the buffer that was showing in it (kill-buffer-and-window). The last character in this key sequence is a zero.

M-x delete-windows-on RET buffer RET

Delete windows showing the specified buffer.

C-x ^

Make selected window taller (enlarge-window).

C-x }

Make selected window wider (enlarge-window-horizontally).

C-x {

Make selected window narrower (shrink-window-horizontally).

C-x -

Shrink this window if its buffer doesn’t need so many lines (shrink-window-if-larger-than-buffer).

C-x +

Make all windows the same height (balance-windows).

To delete the selected window, type C-x 0 (delete-window). (That is a zero.) Once a window is deleted, the space that it occupied is given to an adjacent window (but not the minibuffer window, even if that is active at the time). Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can still switch to it with C-x b.

C-x 4 0 (kill-buffer-and-window) is a stronger command than C-x 0; it kills the current buffer and then deletes the selected window.

C-x 1 (delete-other-windows) deletes all the windows, except the selected one; the selected window expands to use the whole frame. (This command cannot be used while the minibuffer window is active; attempting to do so signals an error.)

M-x delete-windows-on deletes windows that show a specific buffer. It prompts for the buffer, defaulting to the current buffer. With prefix argument of zero, C-u 0, this command deletes windows only on the current display’s frames.

The command C-x ^ (enlarge-window) makes the selected window one line taller, taking space from a vertically adjacent window without changing the height of the frame. With a positive numeric argument, this command increases the window height by that many lines; with a negative argument, it reduces the height by that many lines. If there are no vertically adjacent windows (i.e., the window is at the full frame height), that signals an error. The command also signals an error if you attempt to reduce the height of any window below a certain minimum number of lines, specified by the variable window-min-height (the default is 4).

Similarly, C-x } (enlarge-window-horizontally) makes the selected window wider, and C-x { (shrink-window-horizontally) makes it narrower. These commands signal an error if you attempt to reduce the width of any window below a certain minimum number of columns, specified by the variable window-min-width (the default is 10).

Mouse clicks on the mode line (see Mode Line Mouse) or on window dividers (see Window Dividers) provide another way to change window heights and to split or delete windows.

C-x - (shrink-window-if-larger-than-buffer) reduces the height of the selected window, if it is taller than necessary to show the whole text of the buffer it is displaying. It gives the extra lines to other windows in the frame.

You can also use C-x + (balance-windows) to even out the heights of all the windows in the selected frame.

Next: , Previous: , Up: Windows   [Contents][Index]

20.6 Displaying a Buffer in a Window

It is a common Emacs operation to display or pop up some buffer in response to a user command. There are several different ways in which commands do this.

Many commands, like C-x C-f (find-file), by default display the buffer by “taking over” the selected window, expecting that the user’s attention will be diverted to that buffer.

Some commands try to display intelligently, trying not to take over the selected window, e.g., by splitting off a new window and displaying the desired buffer there. Such commands, which include the various help commands (see Help), work by calling display-buffer internally. See Window Choice, for details.

Other commands do the same as display-buffer, and additionally select the displaying window so that you can begin editing its buffer. The command M-g M-n (next-error) is one example (see Compilation Mode). Such commands work by calling the function pop-to-buffer internally. See Switching to a Buffer in a Window in The Emacs Lisp Reference Manual.

Commands with names ending in -other-window behave like display-buffer, except that they never display in the selected window. Several of these commands are bound in the C-x 4 prefix key (see Pop Up Window).

Commands with names ending in -other-frame behave like display-buffer, except that they (i) never display in the selected window and (ii) prefer to either create a new frame or use a window on some other frame to display the desired buffer. Several of these commands are bound in the C-x 5 prefix key.

20.6.1 How display-buffer works

The display-buffer command (as well as commands that call it internally) chooses a window to display by following the steps given below. See Choosing a Window for Displaying a Buffer in The Emacs Lisp Reference Manual, for details about how to alter this sequence of steps.

20.6.2 Displaying non-editable buffers.

Some buffers are shown in windows for perusal rather than for editing. Help commands (see Help) typically use a buffer called *Help* for that purpose, minibuffer completion (see Completion) uses a buffer called *Completions*, etc. Such buffers are usually displayed only for a short period of time.

Normally, Emacs chooses the window for such temporary displays via display-buffer, as described in the previous subsection. The *Completions* buffer, on the other hand, is normally displayed in a window at the bottom of the selected frame, regardless of the number of windows already shown on that frame.

If you prefer Emacs to display a temporary buffer in a different fashion, customize the variable display-buffer-alist (see Choosing a Window for Displaying a Buffer in The Emacs Lisp Reference Manual) appropriately. For example, to display *Completions* always below the selected window, use the following form in your initialization file (see Init File):

(customize-set-variable
 'display-buffer-alist
 '(("\\*Completions\\*" display-buffer-below-selected)))

The *Completions* buffer is also special in the sense that Emacs usually tries to make its window just as large as necessary to display all of its contents. To resize windows showing other temporary displays, like, for example, the *Help* buffer, turn on the minor mode (see Minor Modes) temp-buffer-resize-mode (see Temporary Displays in The Emacs Lisp Reference Manual).

The maximum size of windows resized by temp-buffer-resize-mode can be controlled by customizing the options temp-buffer-max-height and temp-buffer-max-width (see Temporary Displays in The Emacs Lisp Reference Manual), and cannot exceed the size of the containing frame.

Next: , Previous: , Up: Windows   [Contents][Index]

20.7 Convenience Features for Window Handling

Winner mode is a global minor mode that records the changes in the window configuration (i.e., how the frames are partitioned into windows), so that you can undo them. You can toggle Winner mode with M-x winner-mode, or by customizing the variable winner-mode. When the mode is enabled, C-c left (winner-undo) undoes the last window configuration change. If you change your mind while undoing, you can redo the changes you had undone using C-c right (M-x winner-redo). To prevent Winner mode from binding C-c left and C-c right, you can customize the variable winner-dont-bind-my-keys to a non-nil value. By default, Winner mode stores a maximum of 200 window configurations per frame, but you can change that by modifying the variable winner-ring-size. If there are some buffers whose windows you wouldn’t want Winner mode to restore, add their names to the list variable winner-boring-buffers or to the regexp winner-boring-buffers-regexp.

Follow mode (M-x follow-mode) synchronizes several windows on the same buffer so that they always display adjacent sections of that buffer. See Follow Mode.

The Windmove package defines commands for moving directionally between neighboring windows in a frame. M-x windmove-right selects the window immediately to the right of the currently selected one, and similarly for the left, up, and down counterparts. M-x windmove-default-keybindings binds these commands to S-right etc.; doing so disables shift selection for those keys (see Shift Selection). In the same way as keybindings can be defined for commands that select windows directionally, you can use M-x windmove-display-default-keybindings to define keybindings for commands that specify in what direction to display the window for the buffer that the next command is going to display. Also there is M-x windmove-delete-default-keybindings to define keybindings for commands that delete windows directionally, and M-x windmove-swap-states-in-direction that define keybindings for commands that swap the window contents of the selected window with the window in the specified direction.

The command M-x compare-windows lets you compare the text shown in different windows. See Comparing Files.

Scroll All mode (M-x scroll-all-mode) is a global minor mode that causes scrolling commands and point motion commands to apply to every single window.

Previous: , Up: Windows   [Contents][Index]

20.8 Window Tab Line

The command global-tab-line-mode toggles the display of a tab line on the top screen line of each window. The Tab Line shows special buttons (“tabs”) for each buffer that was displayed in a window, and allows switching to any of these buffers by clicking the corresponding button. Clicking on the + icon adds a new buffer to the window-local tab line of buffers, and clicking on the x icon of a tab deletes it. The mouse wheel on the tab line scrolls the tabs horizontally.

Selecting the previous window-local tab is the same as typing C-x LEFT (previous-buffer), selecting the next tab is the same as C-x RIGHT (next-buffer). Both commands support a numeric prefix argument as a repeat count.

You can customize the variable tab-line-tabs-function to define the preferred contents of the tab line. By default, it displays all buffers previously visited in the window, as described above. But you can also set it to display a list of buffers with the same major mode as the current buffer, or to display buffers grouped by their major mode, where clicking on the mode name in the first tab displays a list of all major modes where you can select another group of buffers.

Note that the Tab Line is different from the Tab Bar (see Tab Bars). Whereas tabs on the Tab Bar at the top of each frame are used to switch between window configurations containing several windows with buffers, tabs on the Tab Line at the top of each window are used to switch between buffers in the window.


Next: , Previous: , Up: Top   [Contents][Index]

21 Frames and Graphical Displays

When Emacs is started on a graphical display, e.g., on the X Window System, it occupies a graphical system-level display region. In this manual, we call this a frame, reserving the word “window” for the part of the frame used for displaying a buffer. A frame initially contains one window, but it can be subdivided into multiple windows (see Windows). A frame normally also contains a menu bar, tool bar, and echo area.

You can also create additional frames (see Creating Frames). All frames created in the same Emacs session have access to the same underlying buffers and other data. For instance, if a buffer is being shown in more than one frame, any changes made to it in one frame show up immediately in the other frames too.

Typing C-x C-c closes all the frames on the current display, and ends the Emacs session if it has no frames open on any other displays (see Exiting). To close just the selected frame, type C-x 5 0 (that is zero, not o).

This chapter describes Emacs features specific to graphical displays (particularly mouse commands), and features for managing multiple frames. On text terminals, many of these features are unavailable. However, it is still possible to create multiple frames on text terminals; such frames are displayed one at a time, filling the entire terminal screen (see Non-Window Terminals). It is also possible to use the mouse on some text terminals (see Text-Only Mouse, for doing so on GNU and Unix systems; and see MS-DOS Mouse, for doing so on MS-DOS). Menus are supported on all text terminals.

21.1 Mouse Commands for Editing

鼠标左键

Move point to where you click (mouse-set-point).

鼠标左键拖拽

Activate the region around the text selected by dragging, and put the text in the primary selection (mouse-set-region).

鼠标中键

Move point to where you click, and insert the contents of the primary selection there (mouse-yank-primary).

鼠标右键

If the region is active, move the nearer end of the region to the click position; otherwise, set mark at the current value of point and point at the click position. Save the resulting region in the kill ring; on a second click, kill it (mouse-save-then-kill).

C-M-mouse-1

Activate a rectangular region around the text selected by dragging. 请参见矩形

The most basic mouse command is mouse-set-point, which is invoked by clicking with the left mouse button, mouse-1, in the text area of a window. This moves point to the position where you clicked. If that window was not the selected window, it becomes the selected window. You can also activate a region by double-clicking mouse-1 (see Word and Line Mouse).

Normally, if the frame you clicked in was not the selected frame, it is made the selected frame, in addition to selecting the window and setting the cursor. On the X Window System, you can change this by setting the variable x-mouse-click-focus-ignore-position to t. In that case, the initial click on an unselected frame just selects the frame, without doing anything else; clicking again selects the window and sets the cursor position.

Holding down mouse-1 and dragging the mouse over a stretch of text activates the region around that text (mouse-set-region), placing the mark where you started holding down the mouse button, and point where you release it (see Mark). In addition, the text in the region becomes the primary selection (see Primary Selection).

If you change the variable mouse-drag-copy-region to a non-nil value, dragging the mouse over a stretch of text also adds the text to the kill ring. 默认值为nil

If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can select regions that don’t fit entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable mouse-scroll-min-lines specifies a minimum step size.

Clicking with the middle mouse button, mouse-2, moves point to the position where you clicked and inserts the contents of the primary selection (mouse-yank-primary). 请参阅主选择。This behavior is consistent with other X applications. Alternatively, you can rebind mouse-2 to mouse-yank-at-click, which performs a yank at the position you click.

If you change the variable mouse-yank-at-point to a non-nil value, mouse-2 does not move point; it inserts the text at point, regardless of where you clicked or even which of the frame’s windows you clicked on. This variable affects both mouse-yank-primary and mouse-yank-at-click.

Clicking with the right mouse button, mouse-3, runs the command mouse-save-then-kill. This performs several actions depending on where you click and the status of the region:

The mouse-save-then-kill command also obeys the variable mouse-drag-copy-region (described above). If the value is non-nil, then whenever the command sets or adjusts the active region, the text in the region is also added to the kill ring. If the latest kill ring entry had been added the same way, that entry is replaced rather than making a new entry.

Whenever you set the region using any of the mouse commands described above, the mark will be deactivated by any subsequent unshifted cursor motion command, in addition to the usual ways of deactivating the mark. 请参见Shift选择

Some mice have a “wheel” which can be used for scrolling. Emacs supports scrolling windows with the mouse wheel, by default, on most graphical displays. To toggle this feature, use M-x mouse-wheel-mode. The variables mouse-wheel-follow-mouse and mouse-wheel-scroll-amount determine where and by how much buffers are scrolled. The variable mouse-wheel-progressive-speed determines whether the scroll speed is linked to how fast you move the wheel. This mode also supports increasing or decreasing the height of the default face, by default bound to scrolling with the Ctrl modifier.

Emacs can also support horizontal scrolling if your mouse’s wheel can be tilted, or if your touchpad supports it. This feature is off by default; the variable mouse-wheel-tilt-scroll turns it on, if you customize it to a non-nil value. By default, tilting the mouse wheel scrolls the window’s view horizontally in the direction of the tilt: e.g., tilting to the right scrolls the window to the right, so that the text displayed in the window moves horizontally to the left. If you’d like to reverse the direction of horizontal scrolling, customize the variable mouse-wheel-flip-direction to a non-nil value.

When the mouse pointer is over an image in Image mode, see Image Mode, scrolling the mouse wheel with the Ctrl modifier scales the image under the mouse pointer.

Next: , Previous: , Up: Frames   [Contents][Index]

21.2 Mouse Commands for Words and Lines

These variants of mouse-1 select entire words or lines at a time. Emacs activates the region around the selected text, which is also copied to the kill ring.

Double-mouse-1

Select the text around the word or character which you click on.

Double-clicking on a character with symbol syntax (such as underscore, in C mode) selects the symbol surrounding that character. Double-clicking on a character with open- or close-parenthesis syntax selects the parenthetical grouping which that character starts or ends. Double-clicking on a character with string-delimiter syntax (such as a single-quote or double-quote in C) selects the string constant (Emacs uses heuristics to figure out whether that character is the beginning or the end of it).

Double-clicking on the beginning of a parenthetical grouping or beginning string-delimiter moves point to the end of the region, scrolling the buffer display forward if necessary to show the new location of point. Double-clicking on the end of a parenthetical grouping or end string-delimiter keeps point at the end of the region by default, so the beginning of the region will not be visible if it is above the top of the window; setting the user option mouse-select-region-move-to-beginning to non-nil changes this to move point to the beginning of the region, scrolling the display backward if necessary.

Double-Drag-mouse-1

Select the text you drag across, in units of whole words.

Triple-mouse-1

Select the line you click on.

Triple-Drag-mouse-1

Select the text you drag across, in units of whole lines.

21.3 Following References with the Mouse

Some Emacs buffers include buttons, or hyperlinks: pieces of text that perform some action (e.g., following a reference) when activated (e.g., by clicking on them). Usually, a button’s text is visually highlighted: it is underlined, or a box is drawn around it. If you move the mouse over a button, the shape of the mouse cursor changes and the button lights up. If you change the variable mouse-highlight to nil, Emacs disables this highlighting.

You can activate a button by moving point to it and typing RET, or by clicking either mouse-1 or mouse-2 on the button. For example, in a Dired buffer, each file name is a button; activating it causes Emacs to visit that file (see Dired). In a *Compilation* buffer, each error message is a button, and activating it visits the source code for that error (see Compilation).

Although clicking mouse-1 on a button usually activates the button, if you hold the mouse button down for a period of time before releasing it (specifically, for more than 450 milliseconds), then Emacs moves point where you clicked, without activating the button. In this way, you can use the mouse to move point over a button without activating it. Dragging the mouse over or onto a button has its usual behavior of setting the region, and does not activate the button.

You can change how mouse-1 applies to buttons by customizing the variable mouse-1-click-follows-link. If the value is a positive integer, that determines how long you need to hold the mouse button down for, in milliseconds, to cancel button activation; the default is 450, as described in the previous paragraph. If the value is nil, mouse-1 just sets point where you clicked, and does not activate buttons. If the value is double, double clicks activate buttons but single clicks just set point.

Normally, mouse-1 on a button activates the button even if it is in a non-selected window. If you change the variable mouse-1-click-in-non-selected-windows to nil, mouse-1 on a button in an unselected window moves point to the clicked position and selects that window, without activating the button.

Next: , Previous: , Up: Frames   [Contents][Index]

21.4 Mouse Clicks for Menus

Several mouse clicks with the Ctrl and SHIFT modifiers bring up menus.

C-mouse-1

This menu is for selecting a buffer.

The MSB (“mouse select buffer”) global minor mode makes this menu smarter and more customizable. See Buffer Menus.

C-mouse-2

This menu contains entries for examining faces and other text properties, and well as for setting them (the latter is mainly useful when editing enriched text; see Enriched Text).

C-mouse-3

This menu is mode-specific. For most modes if Menu-bar mode is on, this menu has the same items as all the mode-specific menu-bar menus put together. Some modes may specify a different menu for this button. If Menu Bar mode is off, this menu contains all the items which would be present in the menu bar—not just the mode-specific ones—so that you can access them without having to display the menu bar.

S-mouse-1

This menu is for changing the default face within the window’s buffer. See Text Scale.

Some graphical applications use mouse-3 for a mode-specific menu. If you prefer mouse-3 in Emacs to bring up such a menu instead of running the mouse-save-then-kill command, rebind mouse-3 by adding the following line to your init file (see Init Rebinding):

(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)

Next: , Previous: , Up: Frames   [Contents][Index]

21.5 Mode Line Mouse Commands

You can use mouse clicks on window mode lines to select and manipulate windows.

Some areas of the mode line, such as the buffer name, and major and minor mode names, have their own special mouse bindings. These areas are highlighted when you hold the mouse over them, and information about the special bindings will be displayed (see Tooltips). This section’s commands do not apply in those areas.

鼠标左键

mouse-1 on a mode line selects the window it belongs to. By dragging mouse-1 on the mode line, you can move it, thus changing the height of the windows above and below. Changing heights with the mouse in this way never deletes windows, it just refuses to make any window smaller than the minimum height.

鼠标中键

mouse-2 on a mode line expands that window to fill its frame.

鼠标右键

mouse-3 on a mode line deletes the window it belongs to. If the frame has only one window, it does nothing.

C-mouse-2

C-mouse-2 on a mode line splits that window, producing two side-by-side windows with the boundary running through the click position (see Split Window).

Furthermore, by clicking and dragging mouse-1 on the divider between two side-by-side mode lines, you can move the vertical boundary to the left or right.

Note that resizing windows is affected by the value of window-resize-pixelwise, see Split Window.

Next: , Previous: , Up: Frames   [Contents][Index]

21.6 Creating Frames

The prefix key C-x 5 is analogous to C-x 4. Whereas each C-x 4 command pops up a buffer in a different window in the selected frame (see Pop Up Window), the C-x 5 commands use a different frame. If an existing visible or iconified (a.k.a. “minimized”, see Visibility of Frames in The Emacs Lisp Reference Manual) frame already displays the requested buffer, that frame is raised and deiconified (“un-minimized”); otherwise, a new frame is created on the current display terminal.

The various C-x 5 commands differ in how they find or create the buffer to select:

C-x 5 2

Create a new frame (make-frame-command).

C-x 5 b bufname RET

Select buffer bufname in another frame. This runs switch-to-buffer-other-frame.

C-x 5 f filename RET

Visit file filename and select its buffer in another frame. This runs find-file-other-frame. See Visiting.

C-x 5 d directory RET

Select a Dired buffer for directory directory in another frame. This runs dired-other-frame. See Dired.

C-x 5 m

Start composing a mail message in another frame. This runs compose-mail-other-frame. It is the other-frame variant of C-x m. See Sending Mail.

C-x 5 .

Find the definition of an identifier in another frame. This runs xref-find-definitions-other-frame, the multiple-frame variant of M-.. See Xref.

C-x 5 r filename RET

Visit file filename read-only, and select its buffer in another frame. This runs find-file-read-only-other-frame. See Visiting.

You can control the appearance and behavior of the newly-created frames by specifying frame parameters. See Frame Parameters.

Next: , Previous: , Up: Frames   [Contents][Index]

21.7 Frame Commands

The following commands are used to delete and operate on frames:

C-x 5 0

Delete the selected frame (delete-frame). This signals an error if there is only one frame.

C-z

Minimize (or iconify) the selected Emacs frame (suspend-frame). See Exiting.

C-x 5 o

Select another frame, and raise it. If you repeat this command, it cycles through all the frames on your terminal.

C-x 5 1

Delete all frames on the current terminal, except the selected one.

M-F10

Toggle the maximization state of the current frame. When a frame is maximized, it fills the screen.

F11

Toggle full-screen mode for the current frame. (The difference between full-screen and maximized is normally that the former hides window manager decorations, giving slightly more screen space to Emacs itself.)

Note that with some window managers you may have to customize the variable frame-resize-pixelwise to a non-nil value in order to make a frame truly maximized or full-screen. This variable, when set to a non-nil value, in general allows resizing frames at pixel resolution, rather than in integral multiples of lines and columns.

The C-x 5 0 (delete-frame) command deletes the selected frame. However, it will refuse to delete the last frame in an Emacs session, to prevent you from losing the ability to interact with the Emacs session. Note that when Emacs is run as a daemon (see Emacs Server), there is always a virtual frame that remains after all the ordinary, interactive frames are deleted. In this case, C-x 5 0 can delete the last interactive frame; you can use emacsclient to reconnect to the Emacs session.

The C-x 5 1 (delete-other-frames) command deletes all other frames on the current terminal (this terminal refers to either a graphical display, or a text terminal; see Non-Window Terminals). If the Emacs session has frames open on other graphical displays or text terminals, those are not deleted.

The C-x 5 o (other-frame) command selects the next frame on the current terminal. If you are using Emacs on the X Window System with a window manager that selects (or gives focus to) whatever frame the mouse cursor is over, you have to change the variable focus-follows-mouse to t in order for this command to work properly. Then invoking C-x 5 o will also warp the mouse cursor to the chosen frame.

Next: , Previous: , Up: Frames   [Contents][Index]

21.8 Fonts

By default, Emacs displays text on graphical displays using a 10-point monospace font, and the font size can be changed interactively (see Text Scale).

There are several different ways to specify a different font:

To check what font you’re currently using, the C-u C-x = command can be helpful. It describes the character at point, and names the font that it’s rendered in.

There are four different ways to express a font name. The first is to use a Fontconfig pattern. Fontconfig patterns have the following form:

fontname[-fontsize][:name1=values1][:name2=values2]...

Within this format, any of the elements in brackets may be omitted. Here, fontname is the family name of the font, such as ‘Monospace’ or ‘DejaVu Sans Mono’; fontsize is the point size of the font (one printer’s point is about 1/72 of an inch); and the ‘name=values’ entries specify settings such as the slant and weight of the font. Each values may be a single value, or a list of values separated by commas. In addition, some property values are valid with only one kind of property name, in which case the ‘name=’ part may be omitted.

Here is a list of common font properties:

slant

One of ‘italic’, ‘oblique’, or ‘roman’.

weight

One of ‘light’, ‘medium’, ‘demibold’, ‘bold’ or ‘black’.

style

Some fonts define special styles which are a combination of slant and weight. For instance, ‘Dejavu Sans’ defines the ‘book’ style, which overrides the slant and weight properties.

width

One of ‘condensed’, ‘normal’, or ‘expanded’.

spacing

One of ‘monospace’, ‘proportional’, ‘dual-width’, or ‘charcell’.

Here are some examples of Fontconfig patterns:

Monospace
Monospace-12
Monospace-12:bold
DejaVu Sans Mono:bold:italic
Monospace-12:weight=bold:slant=italic

For a more detailed description of Fontconfig patterns, see the Fontconfig manual, which is distributed with Fontconfig and available online at https://fontconfig.org/fontconfig-user.html.

On MS-Windows, only the subset of the form fontname[-fontsize] is supported for all fonts; the full Fontconfig pattern might not work for all of them.

The second way to specify a font is to use a GTK font pattern. These have the syntax

fontname [properties] [fontsize]

where fontname is the family name, properties is a list of property values separated by spaces, and fontsize is the point size. The properties that you may specify for GTK font patterns are as follows:

Here are some examples of GTK font patterns:

Monospace 12
Monospace Bold Italic 12

On MS-Windows, only the subset fontname is supported.

The third way to specify a font is to use an XLFD (X Logical Font Description). This is the traditional method for specifying fonts under X, and is also supported on MS-Windows. Each XLFD consists of fourteen words or numbers, separated by dashes, like this:

-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1

A wildcard character (‘*’) in an XLFD matches any sequence of characters (including none), and ‘?’ matches any single character. However, matching is implementation-dependent, and can be inaccurate when wildcards match dashes in a long name. For reliable results, supply all 14 dashes and use wildcards only within a field. Case is insignificant in an XLFD. The syntax for an XLFD is as follows:

-maker-family-weight-slant-widthtype-style…
…-pixels-height-horiz-vert-spacing-width-registry-encoding

The entries have the following meanings:

maker

The name of the font manufacturer.

family

The name of the font family (e.g., ‘courier’).

weight

The font weight—normally either ‘bold’, ‘medium’ or ‘light’. Some font names support other values.

slant

The font slant—normally ‘r’ (roman), ‘i’ (italic), ‘o’ (oblique), ‘ri’ (reverse italic), or ‘ot’ (other). Some font names support other values.

widthtype

The font width—normally ‘normal’, ‘condensed’, ‘semicondensed’, or ‘extended’. Some font names support other values.

style

An optional additional style name. Usually it is empty—most XLFDs have two hyphens in a row at this point. The style name can also specify a two-letter ISO-639 language name, like ‘ja’ or ‘ko’; some fonts that support CJK scripts have that spelled out in the style name part.

pixels

The font height, in pixels.

height

The font height on the screen, measured in tenths of a printer’s point. This is the point size of the font, times ten. For a given vertical resolution, height and pixels are proportional; therefore, it is common to specify just one of them and use ‘*’ for the other.

horiz

The horizontal resolution, in pixels per inch, of the screen for which the font is intended.

vert

The vertical resolution, in pixels per inch, of the screen for which the font is intended. Normally the resolution of the fonts on your system is the right value for your screen; therefore, you normally specify ‘*’ for this and horiz.

spacing

This is ‘m’ (monospace), ‘p’ (proportional) or ‘c’ (character cell).

width

The average character width, in pixels, multiplied by ten.

registry
encoding

The X font character set that the font depicts. (X font character sets are not the same as Emacs character sets, but they are similar.) You can use the xfontsel program to check which choices you have. Normally you should use ‘iso8859’ for registry and ‘1’ for encoding.

The fourth and final method of specifying a font is to use a font nickname. Certain fonts have shorter nicknames, which you can use instead of a normal font specification. For instance, ‘6x13’ is equivalent to

-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1

This form is not supported on MS-Windows.

On X, Emacs recognizes two types of fonts: client-side fonts, which are provided by the Xft and Fontconfig libraries, and server-side fonts, which are provided by the X server itself. Most client-side fonts support advanced font features such as antialiasing and subpixel hinting, while server-side fonts do not. Fontconfig and GTK patterns match only client-side fonts.

You will probably want to use a fixed-width default font—that is, a font in which all characters have the same width. For Xft and Fontconfig fonts, you can use the fc-list command to list the available fixed-width fonts, like this:

fc-list :spacing=mono
fc-list :spacing=charcell

For server-side X fonts, you can use the xlsfonts program to list the available fixed-width fonts, like this:

xlsfonts -fn '*x*' | grep -E '^[0-9]+x[0-9]+'
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'

Any font with ‘m’ or ‘c’ in the spacing field of the XLFD is a fixed-width font. To see what a particular font looks like, use the xfd command. 例如:

xfd -fn 6x13

displays the entire font ‘6x13’.

While running Emacs, you can also set the font of a specific kind of text (see Faces), or a particular frame (see Frame Parameters).

Next: , Previous: , Up: Frames   [Contents][Index]

21.9 Speedbar Frames

The speedbar is a special frame for conveniently navigating in or operating on another frame. The speedbar, when it exists, is always associated with a specific frame, called its attached frame; all speedbar operations act on that frame.

Type M-x speedbar to create the speedbar and associate it with the current frame. To dismiss the speedbar, type M-x speedbar again, or select the speedbar and type q. (You can also delete the speedbar frame like any other Emacs frame.) If you wish to associate the speedbar with a different frame, dismiss it and call M-x speedbar from that frame.

The speedbar can operate in various modes. Its default mode is File Display mode, which shows the files in the current directory of the selected window of the attached frame, one file per line. Clicking on a non-directory visits that file in the selected window of the attached frame, and clicking on a directory shows that directory in the speedbar (see Mouse References). Each line also has a box, ‘[+]’ or ‘<+>’, that you can click on to expand the contents of that item. Expanding a directory adds the contents of that directory to the speedbar display, underneath the directory’s own line. Expanding an ordinary file adds a list of the tags in that file to the speedbar display; you can click on a tag name to jump to that tag in the selected window of the attached frame. When a file or directory is expanded, the ‘[+]’ changes to ‘[-]’; you can click on that box to contract the item, hiding its contents.

You navigate through the speedbar using the keyboard, too. Typing RET while point is on a line in the speedbar is equivalent to clicking the item on the current line, and SPC expands or contracts the item. U displays the parent directory of the current directory. To copy, delete, or rename the file on the current line, type C, D, and R respectively. To create a new directory, type M.

Another general-purpose speedbar mode is Buffer Display mode; in this mode, the speedbar displays a list of Emacs buffers. To switch to this mode, type b in the speedbar. To return to File Display mode, type f. You can also change the display mode by clicking mouse-3 anywhere in the speedbar window (or mouse-1 on the mode-line) and selecting ‘Displays’ in the pop-up menu.

Some major modes, including Rmail mode, Info, and GUD, have specialized ways of putting useful items into the speedbar for you to select. For example, in Rmail mode, the speedbar shows a list of Rmail files, and lets you move the current message to another Rmail file by clicking on its ‘<M>’ box.

For more details on using and programming the speedbar, See Speedbar in Speedbar Manual.

Next: , Previous: , Up: Frames   [Contents][Index]

21.10 Multiple Displays

A single Emacs can talk to more than one X display. Initially, Emacs uses just one display—the one specified with the DISPLAY environment variable or with the ‘--display’ option (see Initial Options). To connect to another display, use the command make-frame-on-display:

M-x make-frame-on-display RET display RET

Create a new frame on display display.

A single X server can handle more than one screen. When you open frames on two screens belonging to one server, Emacs knows they share a single keyboard, and it treats all the commands arriving from these screens as a single stream of input.

When you open frames on different X servers, Emacs makes a separate input stream for each server. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server’s selected frame.

On multi-monitor displays it is possible to use the command make-frame-on-monitor:

M-x make-frame-on-monitor RET monitor RET

Create a new frame on monitor monitor whose screen area is a part of the current display.

Next: , Previous: , Up: Frames   [Contents][Index]

21.11 Frame Parameters

You can control the default appearance and behavior of all frames by specifying a default list of frame parameters in the variable default-frame-alist. Its value should be a list of entries, each specifying a parameter name and a value for that parameter. These entries take effect whenever Emacs creates a new frame, including the initial frame.

For example, you can add the following lines to your init file (see Init File) to set the default frame width to 90 character columns, the default frame height to 40 character rows, and the default font to ‘Monospace-10’:

(add-to-list 'default-frame-alist '(width  . 90))
(add-to-list 'default-frame-alist '(height . 40))
(add-to-list 'default-frame-alist '(font . "Monospace-10"))

For a list of frame parameters and their effects, see Frame Parameters in The Emacs Lisp Reference Manual.

You can also specify a list of frame parameters which apply to just the initial frame, by customizing the variable initial-frame-alist.

If Emacs is compiled to use an X toolkit, frame parameters that specify colors and fonts don’t affect menus and the menu bar, since those are drawn by the toolkit and not directly by Emacs.

Frame appearance and behavior can also be customized through X resources (see X Resources); these override the parameters of the initial frame specified in your init file.

Note that if you are using the desktop library to save and restore your sessions, the frames to be restored are recorded in the desktop file, together with their parameters. When these frames are restored, the recorded parameters take precedence over the frame parameters specified by default-frame-alist and initial-frame-alist in your init file. See Saving Emacs Sessions, for how to avoid that.

Next: , Previous: , Up: Frames   [Contents][Index]

21.12 Scroll Bars

On graphical displays, there is a vertical scroll bar on the side of each Emacs window. Clicking mouse-1 on the scroll bar’s up and down buttons scrolls the window by one line at a time (but some toolkits allow you to customize the scroll bars to not have those buttons). Clicking mouse-1 above or below the scroll bar’s inner box scrolls the window by nearly the entire height of the window, like M-v and C-v respectively (see Moving Point). (This, too, can behave differently with some toolkits.) Dragging the inner box scrolls continuously.

If Emacs is compiled on the X Window System without X toolkit support, the scroll bar behaves differently. Clicking mouse-1 anywhere on the scroll bar scrolls forward like C-v, while mouse-3 scrolls backward like M-v. Clicking mouse-2 in the scroll bar lets you drag the inner box up and down.

To toggle the use of vertical scroll bars, type M-x scroll-bar-mode. This command applies to all frames, including frames yet to be created. To toggle vertical scroll bars for just the selected frame, use the command M-x toggle-scroll-bar.

To control the use of vertical scroll bars at startup, customize the variable scroll-bar-mode (see Customization). Its value should be either right (put scroll bars on the right side of windows), left (put them on the left), or nil (disable vertical scroll bars). By default, Emacs puts scroll bars on the right if it was compiled with GTK+ support on the X Window System, and on MS-Windows or macOS; Emacs puts scroll bars on the left if compiled on the X Window System without GTK+ support (following the old convention for X applications).

You can also use the X resource ‘verticalScrollBars’ to enable or disable the scroll bars (see Resources). To control the scroll bar width, change the scroll-bar-width frame parameter (see Frame Parameters in The Emacs Lisp Reference Manual).

If you’re using Emacs on X (with GTK+ or Motif), you can customize the variable scroll-bar-adjust-thumb-portion to control overscrolling of the scroll bar, i.e., dragging the thumb down even when the end of the buffer is visible. If its value is non-nil, the scroll bar can be dragged downwards even if the end of the buffer is shown; if nil, the thumb will be at the bottom when the end of the buffer is shown. You cannot over-scroll when the entire buffer is visible.

The visual appearance of the scroll bars is controlled by the scroll-bar face. (Some toolkits, such as GTK+ and MS-Windows, ignore this face; the scroll-bar appearance there can only be customized system-wide, for GTK+ see GTK resources).

On graphical frames, vertical scroll bars implicitly serve to separate side-by-side windows visually. When vertical scroll bars are disabled, Emacs by default separates such windows with the help of a one-pixel wide vertical border. That border occupies the first pixel column of the window on the right and may thus overdraw the leftmost pixels of any glyph displayed there. If these pixels convey important information, you can make them visible by enabling window dividers, see Window Dividers. To replicate the look of vertical borders, set the right-divider-width parameter of frames to one and have the window-divider face inherit from that of vertical-border, Window Dividers in The Emacs Lisp Reference Manual.

On graphical displays with toolkit support, Emacs may also supply a horizontal scroll bar on the bottom of each window. Clicking mouse-1 on that scroll bar’s left and right buttons scrolls the window horizontally by one column at a time. (Note that some toolkits allow customizations of the scroll bar that cause these buttons not to be shown.) Clicking mouse-1 on the left or right of the scroll bar’s inner box scrolls the window by four columns. Dragging the inner box scrolls the window continuously.

Note that such horizontal scrolling can make the window’s position of point disappear on the left or the right. Typing a character to insert text or moving point with a keyboard command will usually bring it back into view.

To toggle the use of horizontal scroll bars, type M-x horizontal-scroll-bar-mode. This command applies to all frames, including frames yet to be created. To toggle horizontal scroll bars for just the selected frame, use the command M-x toggle-horizontal-scroll-bar.

To control the use of horizontal scroll bars at startup, customize the variable horizontal-scroll-bar-mode.

You can also use the X resource ‘horizontalScrollBars’ to enable or disable horizontal scroll bars (see Resources). To control the scroll bar height, change the scroll-bar-height frame parameter (see Frame Parameters in The Emacs Lisp Reference Manual).

Next: , Previous: , Up: Frames   [Contents][Index]

21.13 Window Dividers

On graphical displays, you can use window dividers in order to separate windows visually. Window dividers are bars that can be dragged with the mouse, thus allowing you to easily resize adjacent windows.

To toggle the display of window dividers, use the command M-x window-divider-mode.

To customize where dividers should appear, use the option window-divider-default-places. Its value should be either bottom-only (to show dividers only on the bottom of windows), right-only (to show dividers only on the right of windows), or t (to show them on the bottom and on the right).

To adjust the width of window dividers displayed by this mode customize the options window-divider-default-bottom-width and window-divider-default-right-width.

When vertical scroll bars are disabled, dividers can be also useful to make the first pixel column of a window visible, which would be otherwise covered by the vertical border used to separate side-by-side windows (see Scroll Bars).

For more details about window dividers see Window Dividers in The Emacs Lisp Reference Manual.

Next: , Previous: , Up: Frames   [Contents][Index]

21.14 Drag and Drop

In most graphical desktop environments, Emacs has basic support for drag and drop operations. For instance, dropping text onto an Emacs frame inserts the text where it is dropped. Dropping a file onto an Emacs frame visits that file. As a special case, dropping the file on a Dired buffer moves or copies the file (according to the conventions of the application it came from) into the directory displayed in that buffer.

Dropping a file normally visits it in the window you drop it on. If you prefer to visit the file in a new window in such cases, customize the variable dnd-open-file-other-window.

The XDND and Motif drag and drop protocols, and the old KDE 1.x protocol, are currently supported.

Emacs can also optionally drag the region with the mouse into another portion of this or another buffer. To enable that, customize the variable mouse-drag-and-drop-region to a non-nil value. Normally, the text is moved, i.e. cut and pasted, when the destination is the same buffer as the origin; dropping the region on another buffer copies the text instead. If the value of this variable names a modifier key, such as ‘shift’, ‘control’ or ‘alt’, then pressing that modifier key when dropping the text will copy it instead of cutting it, even if you drop on the same buffer as the one from which the text came.

In order to cut text even when source and destination buffers differ, set the option mouse-drag-and-drop-region-cut-when-buffers-differ to a non-nil value. By default, on a graphic display the selected text is shown in a tooltip and point moves together with the mouse cursor during dragging. To suppress such behavior, set the options mouse-drag-and-drop-region-show-tooltip and/or mouse-drag-and-drop-region-show-cursor to nil.

Next: , Previous: , Up: Frames   [Contents][Index]

21.15 Menu Bars

You can toggle the use of menu bars with M-x menu-bar-mode. With no argument, this command toggles Menu Bar mode, a global minor mode. With an argument, the command turns Menu Bar mode on if the argument is positive, off if the argument is not positive. To control the use of menu bars at startup, customize the variable menu-bar-mode.

Expert users often turn off the menu bar, especially on text terminals, where this makes one additional line available for text. If the menu bar is off, you can still pop up a menu of its contents with C-mouse-3 on a display which supports pop-up menus. See Menu Mouse Clicks.

See Menu Bar, for information on how to invoke commands with the menu bar. See X Resources, for how to customize the menu bar menus’ visual appearance.

Next: , Previous: , Up: Frames   [Contents][Index]

21.16 Tool Bars

On graphical displays, Emacs puts a tool bar at the top of each frame, just below the menu bar. This is a row of icons which you can click on with the mouse to invoke various commands.

The global (default) tool bar contains general commands. Some major modes define their own tool bars; whenever a buffer with such a major mode is current, the mode’s tool bar replaces the global tool bar.

To toggle the use of tool bars, type M-x tool-bar-mode. This command applies to all frames, including frames yet to be created. To control the use of tool bars at startup, customize the variable tool-bar-mode.

When Emacs is compiled with GTK+ support, each tool bar item can consist of an image, or a text label, or both. By default, Emacs follows the Gnome desktop’s tool bar style setting; if none is defined, it displays tool bar items as just images. To impose a specific tool bar style, customize the variable tool-bar-style.

You can also control the placement of the tool bar for the GTK+ tool bar with the frame parameter tool-bar-position. See Frame Parameters in The Emacs Lisp Reference Manual.

NS builds consider the tool bar to be a window decoration, and therefore do not display it when a window is undecorated. See Frame Parameters in The Emacs Lisp Reference Manual. On macOS the tool bar is hidden when the frame is put into fullscreen, but can be displayed by moving the mouse pointer to the top of the screen.

Next: , Previous: , Up: Frames   [Contents][Index]

21.17 Tab Bars

On graphical displays and on text terminals, Emacs can optionally display a Tab Bar at the top of each frame, just below the menu bar. The Tab Bar is a row of tabs—buttons that you can click to switch between window configurations on that frame.

Each tab on the Tab Bar represents a named persistent window configuration. Its name is composed from the list of names of buffers visible in windows of that window configuration. Clicking on the tab switches to the window configuration recorded by the tab; it is a configuration of windows and buffers which was previously used in the frame when that tab was the current tab.

If you are using the desktop library to save and restore your sessions (see Saving Emacs Sessions), the tabs from the Tab Bar are recorded in the desktop file, together with their associated window configurations, and will be available after restoring the session.

Note that the Tab Bar is different from the Tab Line (see Tab Line). Whereas tabs on the Tab Line at the top of each window are used to switch between buffers, tabs on the Tab Bar at the top of each frame are used to switch between window configurations containing several windows with buffers.

To toggle the use of tab bars, type M-x tab-bar-mode. This command applies to all frames, including frames yet to be created. To control the use of tab bars at startup, customize the variable tab-bar-mode.

The variable tab-bar-show controls whether the Tab Bar mode is turned on automatically. If the value is t, then tab-bar-mode is enabled when using the commands that create new tabs. The value 1 hides the tab bar when it has only one tab, and shows it again when more tabs are created. The value nil always keeps the tab bar hidden; in this case it’s still possible to switch between named window configurations without the tab bar by using M-x tab-next, M-x tab-switcher, and other commands that provide completion on tab names. Also it’s possible to create and close tabs without the tab bar by using commands M-x tab-new, M-x tab-close, etc.

The prefix key C-x t is analogous to C-x 5. Whereas each C-x 5 command pops up a buffer in a different frame (see Creating Frames), the C-x t commands use a different tab with a different window configuration in the selected frame.

The various C-x t commands differ in how they find or create the buffer to select. The following commands can be used to select a buffer in a new tab:

C-x t 2

Add a new tab (tab-new). You can control the choice of the buffer displayed in a new tab by customizing the variable tab-bar-new-tab-choice.

C-x t b bufname RET

Select buffer bufname in another tab. This runs switch-to-buffer-other-tab.

C-x t f filename RET

Visit file filename and select its buffer in another tab. This runs find-file-other-tab. See Visiting.

C-x t d directory RET

Select a Dired buffer for directory directory in another tab. This runs dired-other-tab. See Dired.

By default, a new tab starts with the buffer that was current before calling the command that adds a new tab. To start a new tab with other buffers, customize the variable tab-bar-new-tab-choice.

The variable tab-bar-new-tab-to defines where to place a new tab. By default, a new tab is added on the right side of the current tab.

The following commands can be used to delete tabs:

C-x t 0

Close the selected tab (tab-close). It has no effect if there is only one tab, unless the variable tab-bar-close-last-tab-choice is customized to a non-default value.

C-x t 1

Close all tabs on the selected frame, except the selected one.

The variable tab-bar-close-tab-select defines what tab to select after closing the current tab. By default, it selects a recently used tab.

The command tab-undo restores the last closed tab.

The following commands can be used to switch between tabs:

C-x t o
C-TAB

Switch to the next tab. If you repeat this command, it cycles through all the tabs on the selected frame. With a positive numeric argument n, it switches to the next nth tab; with a negative argument -n, it switches back to the previous nth tab.

S-C-TAB

Switch to the previous tab. With a positive numeric argument n, it switches to the previous nth tab; with a negative argument -n, it switches back to the next nth tab.

C-x t RET tabname RET

Switch to the tab by its name, with completion on all tab names. Default values are tab names sorted by recency, so you can use M-n (next-history-element) to get the name of the last visited tab, the second last, and so on.

modifier-tabnumber

Switch to the tab by its number. After customizing the variable tab-bar-select-tab-modifiers to specify a modifier key, you can select a tab by its ordinal number using the specified modifier in combination with the tab number to select. To display the tab number alongside the tab name, you can customize another variable tab-bar-tab-hints. This will help you to decide what key to press to select the tab by its number.

modifier-0

Switch to the recent tab. The key combination is the modifier key defined by tab-bar-select-tab-modifiers and the key 0. With a numeric argument n, switch to the nth recent tab.

The following commands can be used to operate on tabs:

C-x t r tabname RET

Rename the current tab to tabname. You can control the programmatic name given to a tab by default by customizing the variable tab-bar-tab-name-function.

C-x t m

Move the current tab n positions to the right with a positive numeric argument n. With a negative argument -n, move the current tab n positions to the left.

You can enable tab-bar-history-mode to remember window configurations used in every tab, and restore them.

tab-bar-history-back

Restore a previous window configuration used in the current tab. This navigates back in the history of window configurations.

tab-bar-history-forward

Cancel restoration of the previous window configuration. This navigates forward in the history of window configurations.

Next: , Previous: , Up: Frames   [Contents][Index]

21.18 Using Dialog Boxes

A dialog box is a special kind of menu for asking you a yes-or-no question or some other special question. Many Emacs commands use a dialog box to ask a yes-or-no question, if you used the mouse to invoke the command that led to the question.

To disable the use of dialog boxes, change the variable use-dialog-box to nil. In that case, Emacs always performs yes-or-no prompts using the echo area and keyboard input. This variable also controls whether to use file selection windows (but those are not supported on all platforms).

A file selection window is a special kind of dialog box for asking for file names. You can customize the variable use-file-dialog to suppress the use of file selection windows, even if you still want other kinds of dialogs. This variable has no effect if you have suppressed all dialog boxes with the variable use-dialog-box.

When Emacs is compiled with GTK+ support, it uses the GTK+ file chooser dialog. Emacs adds an additional toggle button to this dialog, which you can use to enable or disable the display of hidden files (files starting with a dot) in that dialog. If you want this toggle to be activated by default, change the variable x-gtk-show-hidden-files to t. In addition, Emacs adds help text to the GTK+ file chooser dialog; to disable this help text, change the variable x-gtk-file-dialog-help-text to nil.

Next: , Previous: , Up: Frames   [Contents][Index]

21.19 Tooltips

Tooltips are small special frames that display text information at the current mouse position. They activate when there is a pause in mouse movement over some significant piece of text in a window, or the mode line, or some other part of the Emacs frame such as a tool bar button or menu item.

You can toggle the use of tooltips with the command M-x tooltip-mode. When Tooltip mode is disabled, the help text is displayed in the echo area instead. To control the use of tooltips at startup, customize the variable tooltip-mode.

The following variables provide customization options for tooltip display:

tooltip-delay

This variable specifies how long Emacs should wait before displaying the first tooltip. The value is in seconds.

tooltip-short-delay

This variable specifies how long Emacs should wait before displaying subsequent tooltips on different items, having already displayed the first tooltip. The value is in seconds.

tooltip-hide-delay

The number of seconds since displaying a tooltip to hide it, if the mouse doesn’t move.

tooltip-x-offset
tooltip-y-offset

The X and Y offsets, in pixels, of the left top corner of the tooltip from the mouse pointer position. Note that these are ignored if tooltip-frame-parameters was customized to include, respectively, the left and top parameters. The values of the offsets should be chosen so that the tooltip doesn’t cover the mouse pointer’s hot spot, or it might interfere with clicking the mouse.

tooltip-frame-parameters

The frame parameters used for displaying tooltips. See Frame Parameters in The Emacs Lisp Reference Manual, and also Tooltips in The Emacs Lisp Reference Manual.

For additional customization options for displaying tooltips, use M-x customize-group RET tooltip RET.

If Emacs is built with GTK+ support, it displays tooltips via GTK+, using the default appearance of GTK+ tooltips. To disable this, change the variable x-gtk-use-system-tooltips to nil. If you do this, or if Emacs is built without GTK+ support, most attributes of the tooltip text are specified by the tooltip face, and by X resources (see X Resources).

GUD tooltips are special tooltips that show the values of variables when debugging a program with GUD. See Debugger Operation.

Next: , Previous: , Up: Frames   [Contents][Index]

21.20 Mouse Avoidance

On graphical terminals, the mouse pointer may obscure the text in the Emacs frame. Emacs provides two methods to avoid this problem.

Firstly, Emacs hides the mouse pointer each time you type a self-inserting character, if the pointer lies inside an Emacs frame; moving the mouse pointer makes it visible again. To disable this feature, set the variable make-pointer-invisible to nil. See Display Custom.

Secondly, you can use Mouse Avoidance mode, a minor mode, to keep the mouse pointer away from point. To use Mouse Avoidance mode, customize the variable mouse-avoidance-mode. You can set this to various values to move the mouse in several ways:

banish

Move the pointer to a corner of the frame on any key-press. You can customize the variable mouse-avoidance-banish-position to specify where the pointer goes when it is banished.

exile

Banish the pointer only if the cursor gets too close, and allow it to return once the cursor is out of the way.

jump

If the cursor gets too close to the pointer, displace the pointer by a random distance and direction.

animate

As jump, but shows steps along the way for illusion of motion.

cat-and-mouse

The same as animate.

proteus

As animate, but changes the shape of the mouse pointer too.

You can also use the command M-x mouse-avoidance-mode to enable the mode. Whenever Mouse Avoidance mode moves the mouse, it also raises the frame.

Next: , Previous: , Up: Frames   [Contents][Index]

21.21 Non-Window Terminals

On a text terminal, Emacs can display only one Emacs frame at a time. However, you can still create multiple Emacs frames, and switch between them. Switching frames on these terminals is much like switching between different window configurations.

Use C-x 5 2 to create a new frame and switch to it; use C-x 5 o to cycle through the existing frames; use C-x 5 0 to delete the current frame.

Each frame has a number to distinguish it. If your terminal can display only one frame at a time, the selected frame’s number n appears near the beginning of the mode line, in the form ‘Fn’.

Fn’ is in fact the frame’s initial name. You can give frames more meaningful names if you wish, and you can select a frame by its name. Use the command M-x set-frame-name RET name RET to specify a new name for the selected frame, and use M-x select-frame-by-name RET name RET to select a frame according to its name. The name you specify appears in the mode line when the frame is selected.

Previous: , Up: Frames   [Contents][Index]

21.22 Using a Mouse in Text Terminals

Some text terminals support mouse clicks in the terminal window.

In a terminal emulator which is compatible with xterm, you can use M-x xterm-mouse-mode to give Emacs control over simple uses of the mouse—basically, only non-modified single clicks are supported. Newer versions of xterm also support mouse-tracking. The normal xterm mouse functionality for such clicks is still available by holding down the SHIFT key when you press the mouse button. Xterm Mouse mode is a global minor mode (see Minor Modes). Repeating the command turns the mode off again.

In the console on GNU/Linux, you can use M-x gpm-mouse-mode to enable mouse support. You must have the gpm server installed and running on your system in order for this to work. Note that when this mode is enabled, you cannot use the mouse to transfer text between Emacs and other programs which use GPM. This is due to limitations in GPM and the Linux kernel.

See MS-DOS Mouse, for information about mouse support on MS-DOS.


Next: , Previous: , Up: Top   [Contents][Index]

22 International Character Set Support

Emacs supports a wide variety of international character sets, including European and Vietnamese variants of the Latin alphabet, as well as Arabic scripts, Brahmic scripts (for languages such as Bengali, Hindi, and Thai), Cyrillic, Ethiopic, Georgian, Greek, Han (for Chinese and Japanese), Hangul (for Korean), Hebrew and IPA. Emacs also supports various encodings of these characters that are used by other internationalized software, such as word processors and mailers.

Emacs allows editing text with international characters by supporting all the related activities:

The rest of this chapter describes these issues in detail.

22.1 Introduction to International Character Sets

The users of international character sets and scripts have established many more-or-less standard coding systems for storing files. These coding systems are typically multibyte, meaning that sequences of two or more bytes are used to represent individual non-ASCII characters.

Internally, Emacs uses its own multibyte character encoding, which is a superset of the Unicode standard. This internal encoding allows characters from almost every known script to be intermixed in a single buffer or string. Emacs translates between the multibyte character encoding and various other coding systems when reading and writing files, and when exchanging data with subprocesses.

The command C-h h (view-hello-file) displays the file etc/HELLO, which illustrates various scripts by showing how to say “hello” in many languages. If some characters can’t be displayed on your terminal, they appear as ‘?’ or as hollow boxes (see Undisplayable Characters).

Keyboards, even in the countries where these character sets are used, generally don’t have keys for all the characters in them. You can insert characters that your keyboard does not support, using C-x 8 RET (insert-char). See Inserting Text. Shorthands are available for some common characters; for example, you can insert a left single quotation mark by typing C-x 8 [, or in Electric Quote mode, usually by simply typing `. See Quotation Marks. Emacs also supports various input methods, typically one for each script or language, which make it easier to type characters in the script. See Input Methods.

The prefix key C-x RET is used for commands that pertain to multibyte characters, coding systems, and input methods.

The command C-x = (what-cursor-position) shows information about the character at point. In addition to the character position, which was described in Position Info, this command displays how the character is encoded. For instance, it displays the following line in the echo area for the character ‘c’:

Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53

The four values after ‘Char:’ describe the character that follows point, first by showing it and then by giving its character code in decimal, octal and hex. For a non-ASCII multibyte character, these are followed by ‘file’ and the character’s representation, in hex, in the buffer’s coding system, if that coding system encodes the character safely and with a single byte (see Coding Systems). If the character’s encoding is longer than one byte, Emacs shows ‘file ...’.

On rare occasions, Emacs encounters raw bytes: single bytes whose values are in the range 128 (0200 octal) through 255 (0377 octal), which Emacs cannot interpret as part of a known encoding of some non-ASCII character. Such raw bytes are treated as if they belonged to a special character set eight-bit; Emacs displays them as escaped octal codes (this can be customized; see Display Custom). In this case, C-x = shows ‘raw-byte’ instead of ‘file’. In addition, C-x = shows the character codes of raw bytes as if they were in the range #x3FFF80..#x3FFFFF, which is where Emacs maps them to distinguish them from Unicode characters in the range #x0080..#x00FF.

With a prefix argument (C-u C-x =), this command displays a detailed description of the character in a window:

Here’s an example, with some lines folded to fit into this manual:

             position: 1 of 1 (0%), column: 0
            character: ê (displayed as ê) (codepoint 234, #o352, #xea)
    preferred charset: unicode (Unicode (ISO10646))
code point in charset: 0xEA
               script: latin
               syntax: w        which means: word
             category: .:Base, L:Left-to-right (strong), c:Chinese,
                       j:Japanese, l:Latin, v:Viet
             to input: type "C-x 8 RET ea" or
                       "C-x 8 RET LATIN SMALL LETTER E WITH CIRCUMFLEX"
          buffer code: #xC3 #xAA
            file code: #xC3 #xAA (encoded by coding system utf-8-unix)
              display: by this font (glyph code)
    xft:-PfEd-DejaVu Sans Mono-normal-normal-
        normal-*-15-*-*-*-m-0-iso10646-1 (#xAC)

Character code properties: customize what to show
  name: LATIN SMALL LETTER E WITH CIRCUMFLEX
  old-name: LATIN SMALL LETTER E CIRCUMFLEX
  general-category: Ll (Letter, Lowercase)
  decomposition: (101 770) ('e' '^')

22.2 Language Environments

All supported character sets are supported in Emacs buffers whenever multibyte characters are enabled; there is no need to select a particular language in order to display its characters. However, it is important to select a language environment in order to set various defaults. Roughly speaking, the language environment represents a choice of preferred script rather than a choice of language.

The language environment controls which coding systems to recognize when reading text (see Recognize Coding). This applies to files, incoming mail, and any other text you read into Emacs. It may also specify the default coding system to use when you create a file. Each language environment also specifies a default input method.

To select a language environment, customize current-language-environment or use the command M-x set-language-environment. It makes no difference which buffer is current when you use this command, because the effects apply globally to the Emacs session. See the variable language-info-alist for the list of supported language environments, and use the command C-h L lang-env RET (describe-language-environment) for more information about the language environment lang-env. Supported language environments include:

ASCII, Arabic, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, Burmese, Cham, Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GB18030, Chinese-GBK, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French, Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese, Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-6, Latin-7, Latin-8, Latin-9, Latvian, Lithuanian, Malayalam, Oriya, Persian, Polish, Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish, Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8, Ukrainian, Vietnamese, Welsh, and Windows-1255.

To display the script(s) used by your language environment on a graphical display, you need to have suitable fonts. See Fontsets, for more details about setting up your fonts.

Some operating systems let you specify the character-set locale you are using by setting the locale environment variables LC_ALL, LC_CTYPE, or LANG. (If more than one of these is set, the first one that is nonempty specifies your locale for this purpose.) During startup, Emacs looks up your character-set locale’s name in the system locale alias table, matches its canonical name against entries in the value of the variables locale-charset-language-names and locale-language-names (the former overrides the latter), and selects the corresponding language environment if a match is found. It also adjusts the display table and terminal coding system, the locale coding system, the preferred coding system as needed for the locale, and—last but not least—the way Emacs decodes non-ASCII characters sent by your keyboard.

If you modify the LC_ALL, LC_CTYPE, or LANG environment variables while running Emacs (by using M-x setenv), you may want to invoke the set-locale-environment command afterwards to readjust the language environment from the new locale.

The set-locale-environment function normally uses the preferred coding system established by the language environment to decode system messages. But if your locale matches an entry in the variable locale-preferred-coding-systems, Emacs uses the corresponding coding system instead. For example, if the locale ‘ja_JP.PCK’ matches japanese-shift-jis in locale-preferred-coding-systems, Emacs uses that encoding even though it might normally use utf-8.

You can override the language environment chosen at startup with explicit use of the command set-language-environment, or with customization of current-language-environment in your init file.

To display information about the effects of a certain language environment lang-env, use the command C-h L lang-env RET (describe-language-environment). This tells you which languages this language environment is useful for, and lists the character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts used in this language environment. If you give an empty input for lang-env, this command describes the chosen language environment.

You can customize any language environment with the normal hook set-language-environment-hook. The command set-language-environment runs that hook after setting up the new language environment. The hook functions can test for a specific language environment by checking the variable current-language-environment. This hook is where you should put non-default settings for specific language environments, such as coding systems for keyboard input and terminal output, the default input method, etc.

Before it starts to set up the new language environment, set-language-environment first runs the hook exit-language-environment-hook. This hook is useful for undoing customizations that were made with set-language-environment-hook. For instance, if you set up a special key binding in a specific language environment using set-language-environment-hook, you should set up exit-language-environment-hook to restore the normal binding for that key.

22.3 Input Methods

An input method is a kind of character conversion designed specifically for interactive input. In Emacs, typically each language has its own input method; sometimes several languages that use the same characters can share one input method. A few languages support several input methods.

The simplest kind of input method works by mapping ASCII letters into another alphabet; this allows you to use one other alphabet instead of ASCII. The Greek and Russian input methods work this way.

A more powerful technique is composition: converting sequences of characters into one letter. Many European input methods use composition to produce a single non-ASCII letter from a sequence that consists of a letter followed by accent characters (or vice versa). For example, some methods convert the sequence o ^ into a single accented letter. These input methods have no special commands of their own; all they do is compose sequences of printing characters.

The input methods for syllabic scripts typically use mapping followed by composition. The input methods for Thai and Korean work this way. First, letters are mapped into symbols for particular sounds or tone marks; then, sequences of these that make up a whole syllable are mapped into one syllable sign.

Chinese and Japanese require more complex methods. In Chinese input methods, first you enter the phonetic spelling of a Chinese word (in input method chinese-py, among others), or a sequence of portions of the character (input methods chinese-4corner and chinese-sw, and others). One input sequence typically corresponds to many possible Chinese characters. You select the one you mean using keys such as C-f, C-b, C-n, C-p (or the arrow keys), and digits, which have special meanings in this situation.

The possible characters are conceptually arranged in several rows, with each row holding up to 10 alternatives. Normally, Emacs displays just one row at a time, in the echo area; (i/j) appears at the beginning, to indicate that this is the ith row out of a total of j rows. Type C-n or C-p to display the next row or the previous row.

Type C-f and C-b to move forward and backward among the alternatives in the current row. As you do this, Emacs highlights the current alternative with a special color; type C-SPC to select the current alternative and use it as input. The alternatives in the row are also numbered; the number appears before the alternative. Typing a number selects the associated alternative of the current row and uses it as input.

TAB in these Chinese input methods displays a buffer showing all the possible characters at once; then clicking mouse-2 on one of them selects that alternative. The keys C-f, C-b, C-n, C-p, and digits continue to work as usual, but they do the highlighting in the buffer showing the possible characters, rather than in the echo area.

To enter characters according to the pīnyīn transliteration method instead, use the chinese-sisheng input method. This is a composition based method, where e.g. pi1 results in ‘’.

In Japanese input methods, first you input a whole word using phonetic spelling; then, after the word is in the buffer, Emacs converts it into one or more characters using a large dictionary. One phonetic spelling corresponds to a number of different Japanese words; to select one of them, use C-n and C-p to cycle through the alternatives.

Sometimes it is useful to cut off input method processing so that the characters you have just entered will not combine with subsequent characters. For example, in input method latin-1-postfix, the sequence o ^ combines to form an ‘o’ with an accent. What if you want to enter them as separate characters?

One way is to type the accent twice; this is a special feature for entering the separate letter and accent. For example, o ^ ^ gives you the two characters ‘o^’. Another way is to type another letter after the o—something that won’t combine with that—and immediately delete it. For example, you could type o o DEL ^ to get separate ‘o’ and ‘^’. Another method, more general but not quite as easy to type, is to use C-\ C-\ between two characters to stop them from combining. This is the command C-\ (toggle-input-method) used twice. See Select Input Method.

C-\ C-\ is especially useful inside an incremental search, because it stops waiting for more characters to combine, and starts searching for what you have already entered.

To find out how to input the character after point using the current input method, type C-u C-x =. See Position Info.

The variables input-method-highlight-flag and input-method-verbose-flag control how input methods explain what is happening. If input-method-highlight-flag is non-nil, the partial sequence is highlighted in the buffer (for most input methods—some disable this feature). If input-method-verbose-flag is non-nil, the list of possible characters to type next is displayed in the echo area (but not when you are in the minibuffer).

You can modify how an input method works by making your changes in a function that you add to the hook variable quail-activate-hook. See Hooks. For example, you can redefine some of the input method’s keys by defining key bindings in the keymap returned by the function quail-translation-keymap, using define-key. See Init Rebinding.

Another facility for typing characters not on your keyboard is by using C-x 8 RET (insert-char) to insert a single character based on its Unicode name or code-point; see Inserting Text.

22.4 Selecting an Input Method

C-\

Enable or disable use of the selected input method (toggle-input-method).

C-x RET C-\ method RET

Select a new input method for the current buffer (set-input-method).

C-h I method RET
C-h C-\ method RET

描述输入法方法(describe-input-method)。By default, it describes the current input method (if any). This description should give you the full details of how to use any particular input method.

M-x list-input-methods

Display a list of all the supported input methods.

To choose an input method for the current buffer, use C-x RET C-\ (set-input-method). This command reads the input method name from the minibuffer; the name normally starts with the language environment that it is meant to be used with. The variable current-input-method records which input method is selected.

Input methods use various sequences of ASCII characters to stand for non-ASCII characters. Sometimes it is useful to turn off the input method temporarily. To do this, type C-\ (toggle-input-method). To reenable the input method, type C-\ again.

If you type C-\ and you have not yet selected an input method, it prompts you to specify one. This has the same effect as using C-x RET C-\ to specify an input method.

When invoked with a numeric argument, as in C-u C-\, toggle-input-method always prompts you for an input method, suggesting the most recently selected one as the default.

Selecting a language environment specifies a default input method for use in various buffers. When you have a default input method, you can select it in the current buffer by typing C-\. The variable default-input-method specifies the default input method (nil means there is none).

In some language environments, which support several different input methods, you might want to use an input method different from the default chosen by set-language-environment. You can instruct Emacs to select a different default input method for a certain language environment, if you wish, by using set-language-environment-hook (see set-language-environment-hook). 例如:

(defun my-chinese-setup ()
  "Set up my private Chinese environment."
  (if (equal current-language-environment "Chinese-GB")
      (setq default-input-method "chinese-tonepy")))
(add-hook 'set-language-environment-hook 'my-chinese-setup)

This sets the default input method to be chinese-tonepy whenever you choose a Chinese-GB language environment.

You can instruct Emacs to activate a certain input method automatically. 例如:

(add-hook 'text-mode-hook
  (lambda () (set-input-method "german-prefix")))

This automatically activates the input method german-prefix in Text mode.

Some input methods for alphabetic scripts work by (in effect) remapping the keyboard to emulate various keyboard layouts commonly used for those scripts. How to do this remapping properly depends on your actual keyboard layout. To specify which layout your keyboard has, use the command M-x quail-set-keyboard-layout.

You can use the command M-x quail-show-key to show what key (or key sequence) to type in order to input the character following point, using the selected keyboard layout. The command C-u C-x = also shows that information, in addition to other information about the character.

M-x list-input-methods displays a list of all the supported input methods. The list gives information about each input method, including the string that stands for it in the mode line.

22.5 Coding Systems

Users of various languages have established many more-or-less standard coding systems for representing them. Emacs does not use these coding systems internally; instead, it converts from various coding systems to its own system when reading data, and converts the internal coding system to other coding systems when writing data. Conversion is possible in reading or writing files, in sending or receiving from the terminal, and in exchanging data with subprocesses.

Emacs assigns a name to each coding system. Most coding systems are used for one language, and the name of the coding system starts with the language name. Some coding systems are used for several languages; their names usually start with ‘iso’. There are also special coding systems, such as no-conversion, raw-text, and emacs-internal.

A special class of coding systems, collectively known as codepages, is designed to support text encoded by MS-Windows and MS-DOS software. The names of these coding systems are cpnnnn, where nnnn is a 3- or 4-digit number of the codepage. You can use these encodings just like any other coding system; for example, to visit a file encoded in codepage 850, type C-x RET c cp850 RET C-x C-f filename RET.

In addition to converting various representations of non-ASCII characters, a coding system can perform end-of-line conversion. Emacs handles three different conventions for how to separate lines in a file: newline (Unix), carriage return followed by linefeed (DOS), and just carriage return (Mac).

C-h C coding RET

Describe coding system coding (describe-coding-system).

C-h C RET

Describe the coding systems currently in use (describe-coding-system).

M-x list-coding-systems

Display a list of all the supported coding systems.

The command C-h C (describe-coding-system) displays information about particular coding systems, including the end-of-line conversion specified by those coding systems. You can specify a coding system name as the argument; alternatively, with an empty argument, it describes the coding systems currently selected for various purposes, both in the current buffer and as the defaults, and the priority list for recognizing coding systems (see Recognize Coding).

To display a list of all the supported coding systems, type M-x list-coding-systems. The list gives information about each coding system, including the letter that stands for it in the mode line (see Mode Line).

Each of the coding systems that appear in this list—except for no-conversion, which means no conversion of any kind—specifies how and whether to convert printing characters, but leaves the choice of end-of-line conversion to be decided based on the contents of each file. For example, if the file appears to use the sequence carriage return and linefeed to separate lines, DOS end-of-line conversion will be used.

Each of the listed coding systems has three variants, which specify exactly what to do for end-of-line conversion:

…-unix

Don’t do any end-of-line conversion; assume the file uses newline to separate lines. (This is the convention normally used on Unix and GNU systems, and macOS.)

…-dos

Assume the file uses carriage return followed by linefeed to separate lines, and do the appropriate conversion. (This is the convention normally used on Microsoft systems.8)

…-mac

Assume the file uses carriage return to separate lines, and do the appropriate conversion. (This was the convention used in Classic Mac OS.)

These variant coding systems are omitted from the list-coding-systems display for brevity, since they are entirely predictable. For example, the coding system iso-latin-1 has variants iso-latin-1-unix, iso-latin-1-dos and iso-latin-1-mac.

The coding systems unix, dos, and mac are aliases for undecided-unix, undecided-dos, and undecided-mac, respectively. These coding systems specify only the end-of-line conversion, and leave the character code conversion to be deduced from the text itself.

The coding system raw-text is good for a file which is mainly ASCII text, but may contain byte values above 127 that are not meant to encode non-ASCII characters. With raw-text, Emacs copies those byte values unchanged, and sets enable-multibyte-characters to nil in the current buffer so that they will be interpreted properly. raw-text handles end-of-line conversion in the usual way, based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion to use.

In contrast, the coding system no-conversion specifies no character code conversion at all—none for non-ASCII byte values and none for end of line. This is useful for reading or writing binary files, tar files, and other files that must be examined verbatim. It, too, sets enable-multibyte-characters to nil.

The easiest way to edit a file with no conversion of any kind is with the M-x find-file-literally command. This uses no-conversion, and also suppresses other Emacs features that might convert the file contents before you see them. See Visiting.

The coding system emacs-internal (or utf-8-emacs, which is equivalent) means that the file contains non-ASCII characters stored with the internal Emacs encoding. This coding system handles end-of-line conversion based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion.

22.6 Recognizing Coding Systems

Whenever Emacs reads a given piece of text, it tries to recognize which coding system to use. This applies to files being read, output from subprocesses, text from X selections, etc. Emacs can select the right coding system automatically most of the time—once you have specified your preferences.

Some coding systems can be recognized or distinguished by which byte sequences appear in the data. However, there are coding systems that cannot be distinguished, not even potentially. For example, there is no way to distinguish between Latin-1 and Latin-2; they use the same byte values with different meanings.

Emacs handles this situation by means of a priority list of coding systems. Whenever Emacs reads a file, if you do not specify the coding system to use, Emacs checks the data against each coding system, starting with the first in priority and working down the list, until it finds a coding system that fits the data. Then it converts the file contents assuming that they are represented in this coding system.

The priority list of coding systems depends on the selected language environment (see Language Environments). For example, if you use French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use Czech, you probably want Latin-2 to be preferred. This is one of the reasons to specify a language environment.

However, you can alter the coding system priority list in detail with the command M-x prefer-coding-system. This command reads the name of a coding system from the minibuffer, and adds it to the front of the priority list, so that it is preferred to all others. If you use this command several times, each use adds one element to the front of the priority list.

If you use a coding system that specifies the end-of-line conversion type, such as iso-8859-1-dos, what this means is that Emacs should attempt to recognize iso-8859-1 with priority, and should use DOS end-of-line conversion when it does recognize iso-8859-1.

Sometimes a file name indicates which coding system to use for the file. The variable file-coding-system-alist specifies this correspondence. There is a special function modify-coding-system-alist for adding elements to this list. For example, to read and write all ‘.txt’ files using the coding system chinese-iso-8bit, you can execute this Lisp expression:

(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)

The first argument should be file, the second argument should be a regular expression that determines which files this applies to, and the third argument says which coding system to use for these files.

Emacs recognizes which kind of end-of-line conversion to use based on the contents of the file: if it sees only carriage returns, or only carriage return followed by linefeed sequences, then it chooses the end-of-line conversion accordingly. You can inhibit the automatic use of end-of-line conversion by setting the variable inhibit-eol-conversion to non-nil. If you do that, DOS-style files will be displayed with the ‘^M’ characters visible in the buffer; some people prefer this to the more subtle ‘(DOS)’ end-of-line type indication near the left edge of the mode line (see eol-mnemonic).

By default, the automatic detection of the coding system is sensitive to escape sequences. If Emacs sees a sequence of characters that begin with an escape character, and the sequence is valid as an ISO-2022 code, that tells Emacs to use one of the ISO-2022 encodings to decode the file.

However, there may be cases that you want to read escape sequences in a file as is. In such a case, you can set the variable inhibit-iso-escape-detection to non-nil. Then the code detection ignores any escape sequences, and never uses an ISO-2022 encoding. The result is that all escape sequences become visible in the buffer.

The default value of inhibit-iso-escape-detection is nil. We recommend that you not change it permanently, only for one specific operation. That’s because some Emacs Lisp source files in the Emacs distribution contain non-ASCII characters encoded in the coding system iso-2022-7bit, and they won’t be decoded correctly when you visit those files if you suppress the escape sequence detection.

The variables auto-coding-alist and auto-coding-regexp-alist are the strongest way to specify the coding system for certain patterns of file names, or for files containing certain patterns, respectively. These variables even override ‘-*-coding:-*-’ tags in the file itself (see Specify Coding). For example, Emacs uses auto-coding-alist for tar and archive files, to prevent it from being confused by a ‘-*-coding:-*-’ tag in a member of the archive and thinking it applies to the archive file as a whole.

Another way to specify a coding system is with the variable auto-coding-functions. For example, one of the builtin auto-coding-functions detects the encoding for XML files. Unlike the previous two, this variable does not override any ‘-*-coding:-*-’ tag.

22.7 Specifying a File’s Coding System

If Emacs recognizes the encoding of a file incorrectly, you can reread the file using the correct coding system with C-x RET r (revert-buffer-with-coding-system). This command prompts for the coding system to use. To see what coding system Emacs actually used to decode the file, look at the coding system mnemonic letter near the left edge of the mode line (see Mode Line), or type C-h C (describe-coding-system).

You can specify the coding system for a particular file in the file itself, using the ‘-*--*- construct at the beginning, or a local variables list at the end (see File Variables). You do this by defining a value for the “variable” named coding. Emacs does not really have a variable coding; instead of setting a variable, this uses the specified coding system for the file. For example, ‘-*-mode: C; coding: latin-1; -*- specifies use of the Latin-1 coding system, as well as C mode. When you specify the coding explicitly in the file, that overrides file-coding-system-alist.

Next: , Previous: , Up: International   [Contents][Index]

22.8 Choosing Coding Systems for Output

Once Emacs has chosen a coding system for a buffer, it stores that coding system in buffer-file-coding-system. That makes it the default for operations that write from this buffer into a file, such as save-buffer and write-region. You can specify a different coding system for further file output from the buffer using set-buffer-file-coding-system (see Text Coding).

You can insert any character Emacs supports into any Emacs buffer, but most coding systems can only handle a subset of these characters. Therefore, it’s possible that the characters you insert cannot be encoded with the coding system that will be used to save the buffer. For example, you could visit a text file in Polish, encoded in iso-8859-2, and add some Russian words to it. When you save that buffer, Emacs cannot use the current value of buffer-file-coding-system, because the characters you added cannot be encoded by that coding system.

When that happens, Emacs tries the most-preferred coding system (set by M-x prefer-coding-system or M-x set-language-environment). If that coding system can safely encode all of the characters in the buffer, Emacs uses it, and stores its value in buffer-file-coding-system. Otherwise, Emacs displays a list of coding systems suitable for encoding the buffer’s contents, and asks you to choose one of those coding systems.

If you insert the unsuitable characters in a mail message, Emacs behaves a bit differently. It additionally checks whether the most-preferred coding system is recommended for use in MIME messages; if not, it informs you of this fact and prompts you for another coding system. This is so you won’t inadvertently send a message encoded in a way that your recipient’s mail software will have difficulty decoding. (You can still use an unsuitable coding system if you enter its name at the prompt.)

When you send a mail message (see Sending Mail), Emacs has four different ways to determine the coding system to use for encoding the message text. It first tries the buffer’s own value of buffer-file-coding-system, if that is non-nil. Otherwise, it uses the value of sendmail-coding-system, if that is non-nil. Thirdly, it uses the value of default-sendmail-coding-system. If all of these three values are nil, Emacs encodes outgoing mail using the default coding system for new files (i.e., the default value of buffer-file-coding-system), which is controlled by your choice of language environment.

22.9 Specifying a Coding System for File Text

In cases where Emacs does not automatically choose the right coding system for a file’s contents, you can use these commands to specify one:

C-x RET f coding RET

Use coding system coding to save or revisit the file in the current buffer (set-buffer-file-coding-system).

C-x RET c coding RET

Specify coding system coding for the immediately following command (universal-coding-system-argument).

C-x RET r coding RET

Revisit the current file using the coding system coding (revert-buffer-with-coding-system).

M-x recode-region RET right RET wrong RET

Convert a region that was decoded using coding system wrong, decoding it using coding system right instead.

The command C-x RET f (set-buffer-file-coding-system) sets the file coding system for the current buffer (i.e., the coding system to use when saving or reverting the file). You specify which coding system using the minibuffer. You can also invoke this command by clicking with mouse-3 on the coding system indicator in the mode line (see Mode Line).

If you specify a coding system that cannot handle all the characters in the buffer, Emacs will warn you about the troublesome characters, and ask you to choose another coding system, when you try to save the buffer (see Output Coding).

You can also use this command to specify the end-of-line conversion (see end-of-line conversion) for encoding the current buffer. For example, C-x RET f dos RET will cause Emacs to save the current buffer’s text with DOS-style carriage return followed by linefeed line endings.

Another way to specify the coding system for a file is when you visit the file. First use the command C-x RET c (universal-coding-system-argument); this command uses the minibuffer to read a coding system name. After you exit the minibuffer, the specified coding system is used for the immediately following command.

So if the immediately following command is C-x C-f, for example, it reads the file using that coding system (and records the coding system for when you later save the file). Or if the immediately following command is C-x C-w, it writes the file using that coding system. When you specify the coding system for saving in this way, instead of with C-x RET f, there is no warning if the buffer contains characters that the coding system cannot handle.

Other file commands affected by a specified coding system include C-x i and C-x C-v, as well as the other-window variants of C-x C-f. C-x RET c also affects commands that start subprocesses, including M-x shell (see Shell). If the immediately following command does not use the coding system, then C-x RET c ultimately has no effect.

An easy way to visit a file with no conversion is with the M-x find-file-literally command. See Visiting.

The default value of the variable buffer-file-coding-system specifies the choice of coding system to use when you create a new file. It applies when you find a new file, and when you create a buffer and then save it in a file. Selecting a language environment typically sets this variable to a good choice of default coding system for that language environment.

If you visit a file with a wrong coding system, you can correct this with C-x RET r (revert-buffer-with-coding-system). This visits the current file again, using a coding system you specify.

If a piece of text has already been inserted into a buffer using the wrong coding system, you can redo the decoding of it using M-x recode-region. This prompts you for the proper coding system, then for the wrong coding system that was actually used, and does the conversion. It first encodes the region using the wrong coding system, then decodes it again using the proper coding system.

22.10 Coding Systems for Interprocess Communication

This section explains how to specify coding systems for use in communication with other processes.

C-x RET x coding RET

Use coding system coding for transferring selections to and from other graphical applications (set-selection-coding-system).

C-x RET X coding RET

Use coding system coding for transferring one selection—the next one—to or from another graphical application (set-next-selection-coding-system).

C-x RET p input-coding RET output-coding RET

Use coding systems input-coding and output-coding for subprocess input and output in the current buffer (set-buffer-process-coding-system).

The command C-x RET x (set-selection-coding-system) specifies the coding system for sending selected text to other windowing applications, and for receiving the text of selections made in other applications. This command applies to all subsequent selections, until you override it by using the command again. The command C-x RET X (set-next-selection-coding-system) specifies the coding system for the next selection made in Emacs or read by Emacs.

The variable x-select-request-type specifies the data type to request from the X Window System for receiving text selections from other applications. If the value is nil (the default), Emacs tries UTF8_STRING and COMPOUND_TEXT, in this order, and uses various heuristics to choose the more appropriate of the two results; if none of these succeed, Emacs falls back on STRING. If the value of x-select-request-type is one of the symbols COMPOUND_TEXT, UTF8_STRING, STRING, or TEXT, Emacs uses only that request type. If the value is a list of some of these symbols, Emacs tries only the request types in the list, in order, until one of them succeeds, or until the list is exhausted.

The command C-x RET p (set-buffer-process-coding-system) specifies the coding system for input and output to a subprocess. This command applies to the current buffer; normally, each subprocess has its own buffer, and thus you can use this command to specify translation to and from a particular subprocess by giving the command in the corresponding buffer.

You can also use C-x RET c (universal-coding-system-argument) just before the command that runs or starts a subprocess, to specify the coding system for communicating with that subprocess. See Text Coding.

The default for translation of process input and output depends on the current language environment.

The variable locale-coding-system specifies a coding system to use when encoding and decoding system strings such as system error messages and format-time-string formats and time stamps. That coding system is also used for decoding non-ASCII keyboard input on the X Window System and for encoding text sent to the standard output and error streams when in batch mode. You should choose a coding system that is compatible with the underlying system’s text representation, which is normally specified by one of the environment variables LC_ALL, LC_CTYPE, and LANG. (The first one, in the order specified above, whose value is nonempty is the one that determines the text representation.)

22.11 Coding Systems for File Names

C-x RET F coding RET

Use coding system coding for encoding and decoding file names (set-file-name-coding-system).

The command C-x RET F (set-file-name-coding-system) specifies a coding system to use for encoding file names. It has no effect on reading and writing the contents of files.

In fact, all this command does is set the value of the variable file-name-coding-system. If you set the variable to a coding system name (as a Lisp symbol or a string), Emacs encodes file names using that coding system for all file operations. This makes it possible to use non-ASCII characters in file names—or, at least, those non-ASCII characters that the specified coding system can encode.

If file-name-coding-system is nil, Emacs uses a default coding system determined by the selected language environment, and stored in the default-file-name-coding-system variable. In the default language environment, non-ASCII characters in file names are not encoded specially; they appear in the file system using the internal Emacs representation.

When Emacs runs on MS-Windows versions that are descendants of the NT family (Windows 2000, XP, and all the later versions), the value of file-name-coding-system is largely ignored, as Emacs by default uses APIs that allow passing Unicode file names directly. By contrast, on Windows 9X, file names are encoded using file-name-coding-system, which should be set to the codepage (see codepage) pertinent for the current system locale. The value of the variable w32-unicode-filenames controls whether Emacs uses the Unicode APIs when it calls OS functions that accept file names. This variable is set by the startup code to nil on Windows 9X, and to t on newer versions of MS-Windows.

Warning: if you change file-name-coding-system (or the language environment) in the middle of an Emacs session, problems can result if you have already visited files whose names were encoded using the earlier coding system and cannot be encoded (or are encoded differently) under the new coding system. If you try to save one of these buffers under the visited file name, saving may use the wrong file name, or it may encounter an error. If such a problem happens, use C-x C-w to specify a new file name for that buffer.

If a mistake occurs when encoding a file name, use the command M-x recode-file-name to change the file name’s coding system. This prompts for an existing file name, its old coding system, and the coding system to which you wish to convert.

Next: , Previous: , Up: International   [Contents][Index]

22.12 Coding Systems for Terminal I/O

C-x RET t coding RET

Use coding system coding for terminal output (set-terminal-coding-system).

C-x RET k coding RET

Use coding system coding for keyboard input (set-keyboard-coding-system).

The command C-x RET t (set-terminal-coding-system) specifies the coding system for terminal output. If you specify a character code for terminal output, all characters output to the terminal are translated into that coding system.

This feature is useful for certain character-only terminals built to support specific languages or character sets—for example, European terminals that support one of the ISO Latin character sets. You need to specify the terminal coding system when using multibyte text, so that Emacs knows which characters the terminal can actually handle.

By default, output to the terminal is not translated at all, unless Emacs can deduce the proper coding system from your terminal type or your locale specification (see Language Environments).

The command C-x RET k (set-keyboard-coding-system), or the variable keyboard-coding-system, specifies the coding system for keyboard input. Character-code translation of keyboard input is useful for terminals with keys that send non-ASCII graphic characters—for example, some terminals designed for ISO Latin-1 or subsets of it.

By default, keyboard input is translated based on your system locale setting. If your terminal does not really support the encoding implied by your locale (for example, if you find it inserts a non-ASCII character if you type M-i), you will need to set keyboard-coding-system to nil to turn off encoding. You can do this by putting

(set-keyboard-coding-system nil)

in your init file.

There is a similarity between using a coding system translation for keyboard input, and using an input method: both define sequences of keyboard input that translate into single characters. However, input methods are designed to be convenient for interactive use by humans, and the sequences that are translated are typically sequences of ASCII printing characters. Coding systems typically translate sequences of non-graphic characters.

22.13 Fontsets

A font typically defines shapes for a single alphabet or script. Therefore, displaying the entire range of scripts that Emacs supports requires a collection of many fonts. In Emacs, such a collection is called a fontset. A fontset is defined by a list of font specifications, each assigned to handle a range of character codes, and may fall back on another fontset for characters that are not covered by the fonts it specifies.

Each fontset has a name, like a font. However, while fonts are stored in the system and the available font names are defined by the system, fontsets are defined within Emacs itself. Once you have defined a fontset, you can use it within Emacs by specifying its name, anywhere that you could use a single font. Of course, Emacs fontsets can use only the fonts that your system supports. If some characters appear on the screen as empty boxes or hex codes, this means that the fontset in use for them has no font for those characters. In this case, or if the characters are shown, but not as well as you would like, you may need to install extra fonts or modify the fontset to use specific fonts already installed on your system (see below). Your operating system may have optional fonts that you can install; or you can install the GNU Intlfonts package, which includes fonts for most supported scripts.9

Emacs creates three fontsets automatically: the standard fontset, the startup fontset and the default fontset. The default fontset is most likely to have fonts for a wide variety of non-ASCII characters, and is the default fallback for the other two fontsets, and if you set a default font rather than fontset. However, it does not specify font family names, so results can be somewhat random if you use it directly. You can specify a particular fontset by starting Emacs with the ‘-fn’ option. 例如,

emacs -fn fontset-standard

You can also specify a fontset with the ‘Font’ resource (see X Resources).

If no fontset is specified for use, then Emacs uses an ASCII font, with ‘fontset-default’ as a fallback for characters the font does not cover. The standard fontset is only used if explicitly requested, despite its name.

To show the information about a specific fontset, use the M-x describe-fontset command. It prompts for a fontset name, defaulting to the one used by the current frame, and then displays all the subranges of characters and the fonts assigned to them in that fontset. To see which fonts Emacs is using in a session started without a specific fontset (which is what happens normally), type fontset-default RET at the prompt, or just RET to describe the fontset used by the current frame.

A fontset does not necessarily specify a font for every character code. If a fontset specifies no font for a certain character, or if it specifies a font that does not exist on your system, then it cannot display that character properly. It will display that character as a hex code or thin space or an empty box instead. (See glyphless characters, for details.) Or a fontset might specify a font for some range of characters, but you may not like their visual appearance. If this happens, you may wish to modify your fontset; see Modifying Fontsets, for how to do that.

22.14 Defining Fontsets

When running on X, Emacs creates a standard fontset automatically according to the value of standard-fontset-spec. This fontset’s name is

-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard

or just ‘fontset-standard’ for short.

On GNUstep and macOS, the standard fontset is created using the value of ns-standard-fontset-spec, and on MS Windows it is created using the value of w32-standard-fontset-spec.

Bold, italic, and bold-italic variants of the standard fontset are created automatically. Their names have ‘bold’ instead of ‘medium’, or ‘i’ instead of ‘r’, or both.

Emacs generates a fontset automatically, based on any default ASCII font that you specify with the ‘Font’ resource or the ‘-fn’ argument, or the default font that Emacs found when it started. This is the startup fontset and its name is fontset-startup. Emacs generates this fontset by replacing the charset_registry field with ‘fontset’, and replacing the charset_encoding field with ‘startup’, then using the resulting string to specify a fontset.

For instance, if you start Emacs with a font of this form,

emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"

Emacs generates the following fontset and uses it for the initial X window frame:

-*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup

The startup fontset will use the font that you specify, or a variant with a different registry and encoding, for all the characters that are supported by that font, and fallback on ‘fontset-default’ for other characters.

With the X resource ‘Emacs.Font’, you can specify a fontset name just like an actual font name. But be careful not to specify a fontset name in a wildcard resource like ‘Emacs*Font’—that wildcard specification matches various other resources, such as for menus, and menus cannot handle fontsets. See X Resources.

You can specify additional fontsets using X resources named ‘Fontset-n’, where n is an integer starting from 0. The resource value should have this form:

fontpattern, [charset:font]…

where fontpattern should have the form of a standard X font name (see the previous fontset-startup example), except for the last two fields. They should have the form ‘fontset-alias’.

Each fontset has two names, one long and one short. The long name is fontpattern. The short name is ‘fontset-alias’, the last 2 fields of the long name (e.g., ‘fontset-startup’ for the fontset automatically created at startup). You can refer to the fontset by either name.

The construct ‘charset:font’ specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in defining one fontset.

For the other character sets, Emacs chooses a font based on fontpattern. It replaces ‘fontset-alias’ with values that describe the character set. For the ASCII character font, ‘fontset-alias’ is replaced with ‘ISO8859-1’.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is also not useful, because it is better to use the smaller font in its own size, which is what Emacs does.

Thus if fontpattern is this,

-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

-*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

-*-fixed-medium-r-normal-*-24-*-gb2312*-*

You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have ‘song ti’ or ‘fangsong ti’ in the family field. In such a case, ‘Fontset-n’ can be specified as:

Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have ‘fixed’ in the family field, and the font specification for Chinese GB2312 characters has a wild card ‘*’ in the family field.

The function that processes the fontset resource value to create the fontset is called create-fontset-from-fontset-spec. You can also call this function explicitly to create a fontset.

See Fonts, for more information about font naming.

22.15 Modifying Fontsets

Fontsets do not always have to be created from scratch. If only minor changes are required it may be easier to modify an existing fontset, usually ‘fontset-default’. Modifying ‘fontset-default’ will also affect other fontsets that use it as a fallback, so can be an effective way of fixing problems with the fonts that Emacs chooses for a particular script.

Fontsets can be modified using the function set-fontset-font, specifying a character, a charset, a script, or a range of characters to modify the font for, and a font specification for the font to be used. Some examples are:

;; Prefer a big5 font for han characters.
(set-fontset-font "fontset-default"
                  'han (font-spec :registry "big5")
                  nil 'prepend)

;; Use MyPrivateFont for the Unicode private use area.
(set-fontset-font "fontset-default"  '(#xe000 . #xf8ff)
                  "MyPrivateFont")

;; Use Liberation Mono for latin-3 charset.
(set-fontset-font "fontset-default" 'iso-8859-3
                  "Liberation Mono")

;; Use DejaVu Sans Mono as a fallback in fontset-startup
;; before resorting to fontset-default.
(set-fontset-font "fontset-startup" nil "DejaVu Sans Mono"
                  nil 'append)

See Fontsets in GNU Emacs Lisp Reference Manual, for more details about using the set-fontset-font function.

If you don’t know the character’s codepoint or the script to which it belongs, you can ask Emacs. With point at the character, type C-u C-x = (what-cursor-position), and this information, together with much more, will be displayed in the *Help* buffer that Emacs pops up. See Position Info. For example, Japanese characters belong to the ‘kana’ script, but Japanese text also mixes them with Chinese characters so the following uses the ‘han’ script to set up Emacs to use the ‘Kochi Gothic’ font for Japanese text:

(set-fontset-font "fontset-default" 'han "Kochi Gothic")

(For convenience, the ‘han’ script in Emacs is set up to support all of the Chinese, Japanese, and Korean, a.k.a. CJK, characters, not just Chinese characters.)

For the list of known scripts, see the variable script-representative-chars.

Fontset settings like those above only affect characters that the default font doesn’t support, so if the ‘Kochi Gothic’ font covers Latin characters, it will not be used for displaying Latin scripts, since the default font used by Emacs usually covers Basic Latin.

Some fonts installed on your system might be broken, or produce unpleasant results for characters for which they are used, and you may wish to instruct Emacs to completely ignore them while searching for a suitable font required to display a character. You can do that by adding the offending fonts to the value of the variable face-ignored-fonts, which is a list. Here’s an example to put in your ~/.emacs:

(add-to-list 'face-ignored-fonts "Some Bad Font")

22.16 Undisplayable Characters

There may be some non-ASCII characters that your terminal cannot display. Most text terminals support just a single character set (use the variable default-terminal-coding-system to tell Emacs which one, Terminal Coding); characters that can’t be encoded in that coding system are displayed as ‘?’ by default.

Graphical displays can display a broader range of characters, but you may not have fonts installed for all of them; characters that have no font appear as a hollow box.

If you use Latin-1 characters but your terminal can’t display Latin-1, you can arrange to display mnemonic ASCII sequences instead, e.g., ‘"o’ for o-umlaut. Load the library iso-ascii to do this.

If your terminal can display Latin-1, you can display characters from other European character sets using a mixture of equivalent Latin-1 characters and ASCII mnemonics. Customize the variable latin1-display to enable this. The mnemonic ASCII sequences mostly correspond to those of the prefix input methods.

22.17 Unibyte Editing Mode

The ISO 8859 Latin-n character sets define character codes in the range 0240 to 0377 octal (160 to 255 decimal) to handle the accented letters and punctuation needed by various European languages (and some non-European ones). Note that Emacs considers bytes with codes in this range as raw bytes, not as characters, even in a unibyte buffer, i.e., if you disable multibyte characters. However, Emacs can still handle these character codes as if they belonged to one of the single-byte character sets at a time. To specify which of these codes to use, invoke M-x set-language-environment and specify a suitable language environment such as ‘Latin-n’. See Disabling Multibyte Characters in GNU Emacs Lisp Reference Manual.

Emacs can also display bytes in the range 160 to 255 as readable characters, provided the terminal or font in use supports them. This works automatically. On a graphical display, Emacs can also display single-byte characters through fontsets, in effect by displaying the equivalent multibyte characters according to the current language environment. To request this, set the variable unibyte-display-via-language-environment to a non-nil value. Note that setting this only affects how these bytes are displayed, but does not change the fundamental fact that Emacs treats them as raw bytes, not as characters.

If your terminal does not support display of the Latin-1 character set, Emacs can display these characters as ASCII sequences which at least give you a clear idea of what the characters are. To do this, load the library iso-ascii. Similar libraries for other Latin-n character sets could be implemented, but have not been so far.

Normally non-ISO-8859 characters (decimal codes between 128 and 159 inclusive) are displayed as octal escapes. You can change this for non-standard extended versions of ISO-8859 character sets by using the function standard-display-8bit in the disp-table library.

There are two ways to input single-byte non-ASCII characters:

22.18 Charsets

In Emacs, charset is short for “character set”. Emacs supports most popular charsets (such as ascii, iso-8859-1, cp1250, big5, and unicode), in addition to some charsets of its own (such as emacs, unicode-bmp, and eight-bit). All supported characters belong to one or more charsets.

Emacs normally does the right thing with respect to charsets, so that you don’t have to worry about them. However, it is sometimes helpful to know some of the underlying details about charsets.

One example is font selection (see Fonts). Each language environment (see Language Environments) defines a priority list for the various charsets. When searching for a font, Emacs initially attempts to find one that can display the highest-priority charsets. For instance, in the Japanese language environment, the charset japanese-jisx0208 has the highest priority, so Emacs tries to use a font whose registry property is ‘JISX0208.1983-0’.

There are two commands that can be used to obtain information about charsets. The command M-x list-charset-chars prompts for a charset name, and displays all the characters in that character set. The command M-x describe-character-set prompts for a charset name, and displays information about that charset, including its internal representation within Emacs.

M-x list-character-sets displays a list of all supported charsets. The list gives the names of charsets and additional information to identity each charset; for more details, see the ISO International Register of Coded Character Sets to be Used with Escape Sequences (ISO-IR) maintained by the Information Processing Society of Japan/Information Technology Standards Commission of Japan (IPSJ/ITSCJ). In this list, charsets are divided into two categories: normal charsets are listed first, followed by supplementary charsets. A supplementary charset is one that is used to define another charset (as a parent or a subset), or to provide backward-compatibility for older Emacs versions.

To find out which charset a character in the buffer belongs to, put point before it and type C-u C-x = (see International Chars).

Previous: , Up: International   [Contents][Index]

22.19 Bidirectional Editing

Emacs supports editing text written in scripts, such as Arabic, Farsi, and Hebrew, whose natural ordering of horizontal text for display is from right to left. However, digits and Latin text embedded in these scripts are still displayed left to right. It is also not uncommon to have small portions of text in Arabic or Hebrew embedded in an otherwise Latin document; e.g., as comments and strings in a program source file. For these reasons, text that uses these scripts is actually bidirectional: a mixture of runs of left-to-right and right-to-left characters.

This section describes the facilities and options provided by Emacs for editing bidirectional text.

Emacs stores right-to-left and bidirectional text in the so-called logical (or reading) order: the buffer or string position of the first character you read precedes that of the next character. Reordering of bidirectional text into the visual order happens at display time. As a result, character positions no longer increase monotonically with their positions on display. Emacs implements the Unicode Bidirectional Algorithm (UBA) described in the Unicode Standard Annex #9, for reordering of bidirectional text for display. It deviates from the UBA only in how continuation lines are displayed when text direction is opposite to the base paragraph direction, e.g., when a long line of English text appears in a right-to-left paragraph.

The buffer-local variable bidi-display-reordering controls whether text in the buffer is reordered for display. If its value is non-nil, Emacs reorders characters that have right-to-left directionality when they are displayed. The default value is t.

Each paragraph of bidirectional text can have its own base direction, either right-to-left or left-to-right. Text in left-to-right paragraphs begins on the screen at the left margin of the window and is truncated or continued when it reaches the right margin. By contrast, text in right-to-left paragraphs is displayed starting at the right margin and is continued or truncated at the left margin. By default, paragraph boundaries are empty lines, i.e., lines consisting entirely of whitespace characters. To change that, you can customize the two variables bidi-paragraph-start-re and bidi-paragraph-separate-re, whose values should be regular expressions (strings); e.g., to have a single newline start a new paragraph, set both of these variables to "^". These two variables are buffer-local (see Locals).

Emacs determines the base direction of each paragraph dynamically, based on the text at the beginning of the paragraph. However, sometimes a buffer may need to force a certain base direction for its paragraphs. The variable bidi-paragraph-direction, if non-nil, disables the dynamic determination of the base direction, and instead forces all paragraphs in the buffer to have the direction specified by its buffer-local value. The value can be either right-to-left or left-to-right. Any other value is interpreted as nil.

Alternatively, you can control the base direction of a paragraph by inserting special formatting characters in front of the paragraph. The special character RIGHT-TO-LEFT MARK, or RLM, forces the right-to-left direction on the following paragraph, while LEFT-TO-RIGHT MARK, or LRM forces the left-to-right direction. (You can use C-x 8 RET to insert these characters.) In a GUI session, the LRM and RLM characters display as very thin blank characters; on text terminals they display as blanks.

Because characters are reordered for display, Emacs commands that operate in the logical order or on stretches of buffer positions may produce unusual effects. For example, the commands C-f and C-b move point in the logical order, so the cursor will sometimes jump when point traverses reordered bidirectional text. Similarly, a highlighted region covering a contiguous range of character positions may look discontinuous if the region spans reordered text. This is normal and similar to the behavior of other programs that support bidirectional text.

Cursor motion commands bound to arrow keys, such as LEFT and C-RIGHT, are sensitive to the base direction of the current paragraph. In a left-to-right paragraph, commands bound to RIGHT with or without modifiers move forward through buffer text, but in a right-to-left paragraph they move backward instead. This reflects the fact that in a right-to-left paragraph buffer positions predominantly increase when moving to the left on display.

When you move out of a paragraph, the meaning of the arrow keys might change if the base direction of the preceding or the following paragraph is different from the paragraph out of which you moved. When that happens, you need to adjust the arrow key you press to the new base direction.

By default, LEFT and RIGHT move in the logical order, but if visual-order-cursor-movement is non-nil, these commands move to the character that is, correspondingly, to the left or right of the current screen position, moving to the next or previous screen line as appropriate. Note that this might potentially move point many buffer positions away, depending on the surrounding bidirectional context.


Next: , Previous: , Up: Top   [Contents][Index]

23 Major and Minor Modes

Emacs contains many editing modes that alter its basic behavior in useful ways. These are divided into major modes and minor modes.

Major modes provide specialized facilities for working on a particular file type, such as a C source file (see Programs), or a particular type of non-file buffer, such as a shell buffer (see Shell). Major modes are mutually exclusive; each buffer has one and only one major mode at any time.

Minor modes are optional features which you can turn on or off, not necessarily specific to a type of file or buffer. For example, Auto Fill mode is a minor mode in which SPC breaks lines between words as you type (see Auto Fill). Minor modes are independent of one another, and of the selected major mode.

Next: , Up: Modes   [Contents][Index]

23.1 Major Modes

Every buffer possesses a major mode, which determines the editing behavior of Emacs while that buffer is current. The mode line normally shows the name of the current major mode, in parentheses (see Mode Line).

The least specialized major mode is called Fundamental mode. This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each user option variable is in its default state.

For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you typically use a more specialized major mode, such as Lisp mode or Text mode. Most major modes fall into three major groups. The first group contains modes for normal text, either plain or with mark-up. It includes Text mode, HTML mode, SGML mode, TeX mode and Outline mode. The second group contains modes for specific programming languages. These include Lisp mode (which has several variants), C mode, Fortran mode, and others. The third group consists of major modes that are not associated directly with files; they are used in buffers created for specific purposes by Emacs. Examples include Dired mode for buffers made by Dired (see Dired), Message mode for buffers made by C-x m (see Sending Mail), and Shell mode for buffers used to communicate with an inferior shell process (see Interactive Shell).

Usually, the major mode is automatically set by Emacs, when you first visit a file or create a buffer (see Choosing Modes). You can explicitly select a new major mode by using an M-x command. Take the name of the mode and add -mode to get the name of the command to select that mode (e.g., M-x lisp-mode enters Lisp mode). Since every buffer has exactly one major mode, there is no way to “turn off” a major mode; instead you must switch to a different one.

The value of the buffer-local variable major-mode is a symbol with the same name as the major mode command (e.g., lisp-mode). This variable is set automatically; you should not change it yourself.

The default value of major-mode determines the major mode to use for files that do not specify a major mode, and for new buffers created with C-x b. Normally, this default value is the symbol fundamental-mode, which specifies Fundamental mode. You can change this default value via the Customization interface (see Easy Customization), or by adding a line like this to your init file (see Init File):

(setq-default major-mode 'text-mode)

If the default value of major-mode is nil, the major mode is taken from the previously current buffer.

Specialized major modes often change the meanings of certain keys to do something more suitable for the mode. For instance, programming language modes bind TAB to indent the current line according to the rules of the language (see Indentation). The keys that are commonly changed are TAB, DEL, and C-j. Many modes also define special commands of their own, usually bound to key sequences whose prefix key is C-c (see Keys). Major modes can also alter user options and variables; for instance, programming language modes typically set a buffer-local value for the variable comment-start, which determines how source code comments are delimited (see Comments).

To view the documentation for the current major mode, including a list of its key bindings, type C-h m (describe-mode). 请参阅其他帮助

Every major mode, apart from Fundamental mode, defines a mode hook, a customizable list of Lisp functions to run each time the mode is enabled in a buffer. See Hooks, for more information about hooks. Each mode hook is named after its major mode, e.g., Fortran mode has fortran-mode-hook. Furthermore, all text-based major modes run text-mode-hook, and many programming language modes 10 (including all those distributed with Emacs) run prog-mode-hook, prior to running their own mode hooks. Hook functions can look at the value of the variable major-mode to see which mode is actually being entered.

Mode hooks are commonly used to enable minor modes (see Minor Modes). For example, you can put the following lines in your init file to enable Flyspell minor mode in all text-based major modes (see Spelling), and ElDoc minor mode in Emacs Lisp mode (see Lisp Doc):

(add-hook 'text-mode-hook 'flyspell-mode)
(add-hook 'emacs-lisp-mode-hook 'eldoc-mode)

Next: , Previous: , Up: Modes   [Contents][Index]

23.2 Minor Modes

A minor mode is an optional editing mode that alters the behavior of Emacs in some well-defined way. Unlike major modes, any number of minor modes can be in effect at any time. Some minor modes are buffer-local, and can be turned on (enabled) in certain buffers and off (disabled) in others. Other minor modes are global: while enabled, they affect everything you do in the Emacs session, in all buffers. Most minor modes are disabled by default, but a few are enabled by default.

Most buffer-local minor modes say in the mode line when they are enabled, just after the major mode indicator. For example, ‘Fill’ in the mode line means that Auto Fill mode is enabled. See Mode Line.

Like major modes, each minor mode is associated with a mode command, whose name consists of the mode name followed by ‘-mode’. For instance, the mode command for Auto Fill mode is auto-fill-mode. But unlike a major mode command, which simply enables the mode, the mode command for a minor mode can either enable or disable it:

Most minor modes also have a mode variable, with the same name as the mode command. Its value is non-nil if the mode is enabled, and nil if it is disabled. In general, you should not try to enable or disable the mode by changing the value of the mode variable directly in Lisp; you should run the mode command instead. However, setting the mode variable through the Customize interface (see Easy Customization) will always properly enable or disable the mode, since Customize automatically runs the mode command for you.

The following is a list of some buffer-local minor modes:

And here are some useful global minor modes:

Previous: , Up: Modes   [Contents][Index]

23.3 Choosing File Modes

When you visit a file, Emacs chooses a major mode automatically. Normally, it makes the choice based on the file name—for example, files whose names end in ‘.c’ are normally edited in C mode—but sometimes it chooses the major mode based on special text in the file. This special text can also be used to enable buffer-local minor modes.

Here is the exact procedure:

First, Emacs checks whether the file contains file-local mode variables. See File Variables. If there is a file-local variable that specifies a major mode, then Emacs uses that major mode, ignoring all other criteria. There are several methods to specify a major mode using a file-local variable; the simplest is to put the mode name in the first nonblank line, preceded and followed by ‘-*-’. Other text may appear on the line as well. 例如,

; -*-Lisp-*-

tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp treat this line as a comment. You could equivalently write

; -*- mode: Lisp;-*-

You can also use file-local variables to specify buffer-local minor modes, by using eval specifications. For example, this first nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:

; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-

Note, however, that it is usually inappropriate to enable minor modes this way, since most minor modes represent individual user preferences. If you personally want to use a minor mode for a particular file type, it is better to enable the minor mode via a major mode hook (see Major Modes).

Second, if there is no file variable specifying a major mode, Emacs checks whether the file’s contents begin with ‘#!’. If so, that indicates that the file can serve as an executable shell command, which works by running an interpreter named on the file’s first line (the rest of the file is used as input to the interpreter). Therefore, Emacs tries to use the interpreter name to choose a mode. For instance, a file that begins with ‘#!/usr/bin/perl’ is opened in Perl mode. The variable interpreter-mode-alist specifies the correspondence between interpreter program names and major modes.

When the first line starts with ‘#!’, you usually cannot use the ‘-*-’ feature on the first line, because the system would get confused when running the interpreter. So Emacs looks for ‘-*-’ on the second line in such files as well as on the first line. The same is true for man pages which start with the magic string ‘'\"’ to specify a list of troff preprocessors.

Third, Emacs tries to determine the major mode by looking at the text at the start of the buffer, based on the variable magic-mode-alist. By default, this variable is nil (an empty list), so Emacs skips this step; however, you can customize it in your init file (see Init File). The value should be a list of elements of the form

(regexp . mode-function)

where regexp is a regular expression (see Regexps), and mode-function is a major mode command. If the text at the beginning of the file matches regexp, Emacs chooses the major mode specified by mode-function.

Alternatively, an element of magic-mode-alist may have the form

(match-function . mode-function)

where match-function is a Lisp function that is called at the beginning of the buffer; if the function returns non-nil, Emacs set the major mode with mode-function.

Fourth—if Emacs still hasn’t found a suitable major mode—it looks at the file’s name. The correspondence between file names and major modes is controlled by the variable auto-mode-alist. Its value is a list in which each element has this form,

(regexp . mode-function)

or this form,

(regexp mode-function flag)

For example, one element normally found in the list has the form ("\\.c\\'" . c-mode), and it is responsible for selecting C mode for files whose names end in .c. (Note that ‘\\’ is needed in Lisp syntax to include a ‘\’ in the string, which must be used to suppress the special meaning of ‘.’ in regexps.) If the element has the form (regexp mode-function flag) and flag is non-nil, then after calling mode-function, Emacs discards the suffix that matched regexp and searches the list again for another match.

On GNU/Linux and other systems with case-sensitive file names, Emacs performs a case-sensitive search through auto-mode-alist; if this search fails, it performs a second case-insensitive search through the alist. To suppress the second search, change the variable auto-mode-case-fold to nil. On systems with case-insensitive file names, such as Microsoft Windows, Emacs performs a single case-insensitive search through auto-mode-alist.

Finally, if Emacs still hasn’t found a major mode to use, it compares the text at the start of the buffer to the variable magic-fallback-mode-alist. This variable works like magic-mode-alist, described above, except that it is consulted only after auto-mode-alist. By default, magic-fallback-mode-alist contains forms that check for image files, HTML/XML/SGML files, PostScript files, and Unix style Conf files.

If you have changed the major mode of a buffer, you can return to the major mode Emacs would have chosen automatically, by typing M-x normal-mode. This is the same function that find-file calls to choose the major mode. It also processes the file’s ‘-*-’ line or local variables list (if any). See File Variables.

The commands C-x C-w and set-visited-file-name change to a new major mode if the new file name implies a mode (see Saving). (C-x C-s does this too, if the buffer wasn’t visiting a file.) However, this does not happen if the buffer contents specify a major mode, and certain special major modes do not allow the mode to change. You can turn off this mode-changing feature by setting change-major-mode-with-file-name to nil.


Next: , Previous: , Up: Top   [Contents][Index]

24 Indentation

Indentation refers to inserting or adjusting whitespace characters (space and/or tab characters) at the beginning of a line of text. This chapter documents indentation commands and options which are common to Text mode and related modes, as well as programming language modes. See Program Indent, for additional documentation about indenting in programming modes.

The simplest way to perform indentation is the TAB key. In most major modes, this runs the command indent-for-tab-command. (In C and related modes, TAB runs the command c-indent-line-or-region, which behaves similarly, see C Indent).

TAB

Insert whitespace, or indent the current line, in a mode-appropriate way (indent-for-tab-command). If the region is active, indent all the lines within it.

The exact behavior of TAB depends on the major mode. In Text mode and related major modes, TAB normally inserts some combination of space and tab characters to advance point to the next tab stop (see Tab Stops). For this purpose, the position of the first non-whitespace character on the preceding line is treated as an additional tab stop, so you can use TAB to align point with the preceding line. If the region is active (see Using Region), TAB acts specially: it indents each line in the region so that its first non-whitespace character is aligned with the preceding line.

In programming modes, TAB indents the current line of code in a way that makes sense given the code in the preceding lines. If the region is active, all the lines in the region are indented this way. If point was initially within the current line’s indentation, it is repositioned to the first non-whitespace character on the line.

If you just want to insert a tab character in the buffer, type C-q TAB (see Inserting Text).

Next: , Up: Indentation   [Contents][Index]

24.1 Indentation Commands

Apart from the TAB (indent-for-tab-command) command, Emacs provides a variety of commands to perform indentation in other ways.

C-M-o

Split the current line at point (split-line). The text on the line after point becomes a new line, indented to the same column where point is located. This command first moves point forward over any spaces and tabs. Afterward, point is positioned before the inserted newline.

M-m

Move (forward or back) to the first non-whitespace character on the current line (back-to-indentation). If there are no non-whitespace characters on the line, move to the end of the line.

M-i

Indent whitespace at point, up to the next tab stop (tab-to-tab-stop). See Tab Stops.

M-x indent-relative

Insert whitespace at point, until point is aligned with the first non-whitespace character on the previous line (actually, the last non-blank line). If point is already farther right than that, run tab-to-tab-stop instead—unless called with a numeric argument, in which case do nothing.

M-^

Merge the previous and the current line (delete-indentation). This joins the two lines cleanly, by replacing any indentation at the front of the current line, together with the line boundary, with a single space.

As a special case (useful for Lisp code), the single space is omitted if the characters to be joined are consecutive opening and closing parentheses, or if the junction follows another newline.

If there is a fill prefix, M-^ deletes the fill prefix if it appears after the newline that is deleted. See Fill Prefix.

With a prefix argument, join the current line to the following line. If the region is active, and no prefix argument is given, join all lines in the region instead.

C-M-\

Indent all the lines in the region, as though you had typed TAB at the beginning of each line (indent-region).

If a numeric argument is supplied, indent every line in the region to that column number.

C-x TAB

This command is used to change the indentation of all lines that begin in the region, moving the affected lines as a rigid unit.

If called with no argument, the command activates a transient mode for adjusting the indentation of the affected lines interactively. While this transient mode is active, typing LEFT or RIGHT indents leftward and rightward, respectively, by one space. You can also type S-LEFT or S-RIGHT to indent leftward or rightward to the next tab stop (see Tab Stops). Typing any other key disables the transient mode, and resumes normal editing.

If called with a prefix argument n, this command indents the lines forward by n spaces (without enabling the transient mode). Negative values of n indent backward, so you can remove all indentation from the lines in the region using a large negative argument, like this:

C-u -999 C-x TAB

24.2 Tab Stops

Emacs defines certain column numbers to be tab stops. These are used as stopping points by TAB when inserting whitespace in Text mode and related modes (see Indentation), and by commands like M-i (see Indentation Commands). The variable tab-stop-list controls these positions. The default value is nil, which means a tab stop every 8 columns. The value can also be a list of zero-based column numbers (in increasing order) at which to place tab stops. Emacs extends the list forever by repeating the difference between the last and next-to-last elements.

Instead of customizing the variable tab-stop-list directly, a convenient way to view and set tab stops is via the command M-x edit-tab-stops. This switches to a buffer containing a description of the tab stop settings, which looks like this:

        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c

The first line contains a colon at each tab stop. The numbers on the next two lines are present just to indicate where the colons are. If the value of tab-stop-list is nil, as it is by default, no colons are displayed initially.

You can edit this buffer to specify different tab stops by placing colons on the desired columns. The buffer uses Overwrite mode (see Minor Modes). Remember that Emacs will extend the list of tab stops forever by repeating the difference between the last two explicit stops that you place. When you are done, type C-c C-c to make the new tab stops take effect. Normally, the new tab stop settings apply to all buffers. However, if you have made the tab-stop-list variable local to the buffer where you called M-x edit-tab-stops (see Locals), then the new tab stop settings apply only to that buffer. To save the tab stop settings for future Emacs sessions, use the Customize interface to save the value of tab-stop-list (see Easy Customization).

Note that the tab stops discussed in this section have nothing to do with how tab characters are displayed in the buffer. Tab characters are always displayed as empty spaces extending to the next display tab stop. See Text Display.

Next: , Previous: , Up: Indentation   [Contents][Index]

24.3 Tabs vs. Spaces

Normally, indentation commands insert (or remove) the shortest possible series of tab and space characters so as to align to the desired column. Tab characters are displayed as a stretch of empty space extending to the next display tab stop. By default, there is one display tab stop every tab-width columns (the default is 8). See Text Display.

If you prefer, all indentation can be made from spaces only. To request this, set the buffer-local variable indent-tabs-mode to nil. See Locals, for information about setting buffer-local variables. Note, however, that C-q TAB always inserts a tab character, regardless of the value of indent-tabs-mode.

One reason to set indent-tabs-mode to nil is that not all editors display tab characters in the same way. Emacs users, too, may have different customized values of tab-width. By using spaces only, you can make sure that your file always looks the same. If you only care about how it looks within Emacs, another way to tackle this problem is to set the tab-width variable in a file-local variable (see File Variables).

There are also commands to convert tabs to spaces or vice versa, always preserving the columns of all non-whitespace text. M-x tabify scans the region for sequences of spaces, and converts sequences of at least two spaces to tabs if that can be done without changing indentation. M-x untabify changes all tabs in the region to appropriate numbers of spaces.

Previous: , Up: Indentation   [Contents][Index]

24.4 Convenience Features for Indentation

The variable tab-always-indent tweaks the behavior of the TAB (indent-for-tab-command) command. The default value, t, gives the behavior described in Indentation. If you change the value to the symbol complete, then TAB first tries to indent the current line, and if the line was already indented, it tries to complete the text at point (see Symbol Completion). If the value is nil, then TAB indents the current line only if point is at the left margin or in the line’s indentation; otherwise, it inserts a tab character.

Electric Indent mode is a global minor mode that automatically indents the line after every RET you type. This mode is enabled by default. To toggle this minor mode, type M-x electric-indent-mode. To toggle the mode in a single buffer, use M-x electric-indent-local-mode.


Next: , Previous: , Up: Top   [Contents][Index]

25 Commands for Human Languages

This chapter describes Emacs commands that act on text, by which we mean sequences of characters in a human language (as opposed to, say, a computer programming language). These commands act in ways that take into account the syntactic and stylistic conventions of human languages: conventions involving words, sentences, paragraphs, and capital letters. There are also commands for filling, which means rearranging the lines of a paragraph to be approximately equal in length. These commands, while intended primarily for editing text, are also often useful for editing programs.

Emacs has several major modes for editing human-language text. If the file contains ordinary text, use Text mode, which customizes Emacs in small ways for the syntactic conventions of text. Outline mode provides special commands for operating on text with an outline structure. See Outline Mode.

Org mode extends Outline mode and turns Emacs into a full-fledged organizer: you can manage TODO lists, store notes and publish them in many formats. See the Org Info manual, which is distributed with Emacs.

Emacs has other major modes for text which contains embedded commands, such as TeX and LaTeX (see TeX Mode); HTML and SGML (see HTML Mode); XML (see the nXML mode Info manual, which is distributed with Emacs); and Groff and Nroff (see Nroff Mode).

If you need to edit ASCII art pictures made out of text characters, use Picture mode, a special major mode for editing such pictures. See Picture Mode.

Next: , Up: Text   [Contents][Index]

25.1 Words

Emacs defines several commands for moving over or operating on words:

M-f

Move forward over a word (forward-word).

M-b

Move backward over a word (backward-word).

M-d

Kill up to the end of a word (kill-word).

M-DEL

Kill back to the beginning of a word (backward-kill-word).

M-@

在下一个单词的末尾设置标记(mark-word)。

M-t

Transpose two words or drag a word across others (transpose-words).

Notice how these keys form a series that parallels the character-based C-f, C-b, C-d, DEL and C-t. M-@ is cognate to C-@, which is an alias for C-SPC.

The commands M-f (forward-word) and M-b (backward-word) move forward and backward over words. These Meta-based key sequences are analogous to the key sequences C-f and C-b, which move over single characters. The analogy extends to numeric arguments, which serve as repeat counts. M-f with a negative argument moves backward, and M-b with a negative argument moves forward. Forward motion stops right after the last letter of the word, while backward motion stops right before the first letter.

M-d (kill-word) kills the word after point. To be precise, it kills everything from point to the place M-f would move to. Thus, if point is in the middle of a word, M-d kills just the part after point. If some punctuation comes between point and the next word, it is killed along with the word. (If you wish to kill only the next word but not the punctuation before it, simply do M-f to get the end, and kill the word backwards with M-DEL.) M-d takes arguments just like M-f.

M-DEL (backward-kill-word) kills the word before point. It kills everything from point back to where M-b would move to. For instance, if point is after the space in ‘FOO, BAR, it kills ‘FOO, . If you wish to kill just ‘FOO’, and not the comma and the space, use M-b M-d instead of M-DEL.

M-t (transpose-words) exchanges the word before or containing point with the following word. The delimiter characters between the words do not move. For example, ‘FOO, BAR transposes into ‘BAR, FOO rather than ‘BAR FOO,’. See Transpose, for more on transposition.

To operate on words with an operation which acts on the region, use the command M-@ (mark-word). This command sets the mark where M-f would move to. See Marking Objects, for more information about this command.

The word commands’ understanding of word boundaries is controlled by the syntax table. Any character can, for example, be declared to be a word delimiter. See Syntax Tables in The Emacs Lisp Reference Manual.

In addition, see Position Info for the M-= (count-words-region) and M-x count-words commands, which count and report the number of words in the region or buffer.

Next: , Previous: , Up: Text   [Contents][Index]

25.2 Sentences

The Emacs commands for manipulating sentences and paragraphs are mostly on Meta keys, like the word-handling commands.

M-a

Move back to the beginning of the sentence (backward-sentence).

M-e

Move forward to the end of the sentence (forward-sentence).

M-k

Kill forward to the end of the sentence (kill-sentence).

C-x DEL

Kill back to the beginning of the sentence (backward-kill-sentence).

The commands M-a (backward-sentence) and M-e (forward-sentence) move to the beginning and end of the current sentence, respectively. Their bindings were chosen to resemble C-a and C-e, which move to the beginning and end of a line. Unlike them, M-a and M-e move over successive sentences if repeated.

Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the punctuation that ends the sentence. Neither one moves over the whitespace at the sentence boundary.

Just as C-a and C-e have a kill command, C-k, to go with them, M-a and M-e have a corresponding kill command: M-k (kill-sentence) kills from point to the end of the sentence. With a positive numeric argument n, it kills the next n sentences; with a negative argument -n, it kills back to the beginning of the nth preceding sentence.

The C-x DEL (backward-kill-sentence) kills back to the beginning of a sentence.

The sentence commands assume that you follow the American typist’s convention of putting two spaces at the end of a sentence. That is, a sentence ends wherever there is a ‘.’, ‘?’ or ‘!’ followed by the end of a line or two spaces, with any number of ‘)’, ‘]’, ‘'’, or ‘"’ characters allowed in between. A sentence also begins or ends wherever a paragraph begins or ends. It is useful to follow this convention, because it allows the Emacs sentence commands to distinguish between periods that end a sentence and periods that indicate abbreviations.

If you want to use just one space between sentences, you can set the variable sentence-end-double-space to nil to make the sentence commands stop for single spaces. However, this has a drawback: there is no way to distinguish between periods that end sentences and those that indicate abbreviations. For convenient and reliable editing, we therefore recommend you follow the two-space convention. The variable sentence-end-double-space also affects filling (see Fill Commands).

The variable sentence-end controls how to recognize the end of a sentence. If non-nil, its value should be a regular expression, which is used to match the last few characters of a sentence, together with the whitespace following the sentence (see Regexps). If the value is nil, the default, then Emacs computes sentence ends according to various criteria such as the value of sentence-end-double-space.

Some languages, such as Thai, do not use periods to indicate the end of a sentence. Set the variable sentence-end-without-period to t in such cases.

Next: , Previous: , Up: Text   [Contents][Index]

25.3段落

The Emacs commands for manipulating paragraphs are also on Meta keys.

M-{

Move back to previous paragraph beginning (backward-paragraph).

M-}

Move forward to next paragraph end (forward-paragraph).

M-h

Put point and mark around this or next paragraph (mark-paragraph).

M-{ (backward-paragraph) moves to the beginning of the current or previous paragraph, depending on where point is when the command is invoked (see below for the definition of a paragraph). M-} (forward-paragraph) similarly moves to the end of the current or next paragraph. If there is a blank line before the paragraph, M-{ moves to the blank line.

When you wish to operate on a paragraph, type M-h (mark-paragraph) to set the region around it. For example, M-h C-w kills the paragraph around or after point. M-h puts point at the beginning and mark at the end of the paragraph point was in. If point is between paragraphs (in a run of blank lines, or at a boundary), M-h sets the region around the paragraph following point. If there are blank lines preceding the first line of the paragraph, one of these blank lines is included in the region. If the region is already active, the command sets the mark without changing point, and each subsequent M-h further advances the mark by one paragraph.

The definition of a paragraph depends on the major mode. In Fundamental mode, as well as Text mode and related modes, a paragraph is separated from neighboring paragraphs by one or more blank lines—lines that are either empty, or consist solely of space, tab and/or formfeed characters. In programming language modes, paragraphs are usually defined in a similar way, so that you can use the paragraph commands even though there are no paragraphs as such in a program.

Note that an indented line is not itself a paragraph break in Text mode. If you want indented lines to separate paragraphs, use Paragraph-Indent Text mode instead. See Text Mode.

If you set a fill prefix, then paragraphs are delimited by all lines which don’t start with the fill prefix. 请参阅填充

The precise definition of a paragraph boundary is controlled by the variables paragraph-separate and paragraph-start. The value of paragraph-start is a regular expression that should match lines that either start or separate paragraphs (see Regexps). The value of paragraph-separate is another regular expression that should match lines that separate paragraphs without being part of any paragraph (for example, blank lines). Lines that start a new paragraph and are contained in it must match only paragraph-start, not paragraph-separate. For example, in Fundamental mode, paragraph-start is "\f\\|[ \t]*$", and paragraph-separate is "[ \t\f]*$".

Note that paragraph-start and paragraph-separate are matched against the text at the left margin, which is not necessarily the beginning of the line, so these regexps should not use ‘^’ as an anchor, to ensure that the paragraph functions will work equally within a region of text indented by a margin setting.

Next: , Previous: , Up: Text   [Contents][Index]

25.4 Pages

Within some text files, text is divided into pages delimited by the formfeed character (ASCII code 12, also denoted as ‘control-L’), which is displayed in Emacs as the escape sequence ‘^L’ (see Text Display). Traditionally, when such text files are printed to hardcopy, each formfeed character forces a page break. Most Emacs commands treat it just like any other character, so you can insert it with C-q C-l, delete it with DEL, etc. In addition, Emacs provides commands to move over pages and operate on them.

M-x what-page

Display the page number of point, and the line number within that page.

C-x [

Move point to previous page boundary (backward-page).

C-x ]

Move point to next page boundary (forward-page).

C-x C-p

Put point and mark around this page (or another page) (mark-page).

C-x l

Count the lines in this page (count-lines-page).

M-x what-page counts pages from the beginning of the file, and counts lines within the page, showing both numbers in the echo area.

The C-x [ (backward-page) command moves point to immediately after the previous page delimiter. If point is already right after a page delimiter, it skips that one and stops at the previous one. A numeric argument serves as a repeat count. The C-x ] (forward-page) command moves forward past the next page delimiter.

The C-x C-p command (mark-page) puts point at the beginning of the current page (after that page delimiter at the front), and the mark at the end of the page (after the page delimiter at the end).

C-x C-p C-w is a handy way to kill a page to move it elsewhere. If you move to another page delimiter with C-x [ and C-x ], then yank the killed page, all the pages will be properly delimited once again. Making sure this works as expected is the reason C-x C-p includes only the following page delimiter in the region.

A numeric argument to C-x C-p specifies which page to go to, relative to the current one. Zero means the current page, one means the next page, and -1 means the previous one.

The C-x l command (count-lines-page) is good for deciding where to break a page in two. It displays in the echo area the total number of lines in the current page, and then divides it up into those preceding the current line and those following, as in

Page has 96 (72+25) lines

Notice that the sum is off by one; this is correct if point is not at the beginning of a line.

The variable page-delimiter controls where pages begin. Its value is a regular expression that matches the beginning of a line that separates pages (see Regexps). The normal value of this variable is "^\f", which matches a formfeed character at the beginning of a line.

Next: , Previous: , Up: Text   [Contents][Index]

25.5引号

一种常见的引用方式是打字机约定,它使用直撇号‘像这样’或双引号“像这样”引用。另一种常见的方法是弯曲引号约定,它使用左右单引号或双引号‘像这样’或“像这样11。在文本文件中,打字机引号简单且便携;弧形引号不那么模棱两可,通常看起来更美观。

Electric Quote mode makes it easier to type curved quotes. As you type characters it optionally converts ` to , ' to , `` to , and '' to . It’s possible to change the default quotes listed above, by customizing the variable electric-quote-chars, a list of four characters, where the items correspond to the left single quote, the right single quote, the left double quote and the right double quote, respectively, whose default value is '(? ? ? ?).

You can customize the behavior of Electric Quote mode by customizing variables that control where it is active. It is active in text paragraphs if electric-quote-paragraph is non-nil, in programming-language comments if electric-quote-comment is non-nil, and in programming-language strings if electric-quote-string is non-nil. The default is nil for electric-quote-string and t for the other variables.

You can also set the option electric-quote-replace-double to a non-nil value. Then, typing " insert an appropriate curved double quote depending on context: at the beginning of the buffer or after a line break, whitespace, opening parenthesis, or quote character, and otherwise.

Electric Quote mode is disabled by default. To toggle it in a single buffer, use M-x electric-quote-local-mode. To toggle it globally, type M-x electric-quote-mode. To suppress it for a single use, type C-q ` or C-q ' instead of ` or '. To insert a curved quote even when Electric Quote is disabled or inactive, you can type C-x 8 [ for , C-x 8 ] for , C-x 8 { for “, and C-x 8 } for ”. See Inserting Text. Note that the value of electric-quote-chars does not affect these keybindings, they are not keybindings of electric-quote-mode but bound in global-map.

Next: , Previous: , Up: Text   [Contents][Index]

25.6 Filling Text

Filling text means breaking it up into lines that fit a specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing text.

Next: , Up: Filling   [Contents][Index]

25.6.1 Auto Fill Mode

Auto Fill mode is a buffer-local minor mode (see Minor Modes) in which lines are broken automatically at spaces when the line becomes too wide.

M-x auto-fill-mode

Enable or disable Auto Fill mode.

SPC
RET

In Auto Fill mode, break lines when appropriate.

The mode command M-x auto-fill-mode toggles Auto Fill mode in the current buffer. Like any other minor mode, with a positive numeric argument, it enables Auto Fill mode, and with a negative argument it disables it. To enable Auto Fill mode automatically in certain major modes, add auto-fill-mode to the mode hooks (see Major Modes). When Auto Fill mode is enabled, the mode indicator ‘Fill’ appears in the mode line (see Mode Line).

Auto Fill mode breaks lines automatically at spaces whenever they get longer than the desired width. This line breaking occurs only when you type SPC or RET. If you wish to insert a space or newline without permitting line-breaking, type C-q SPC or C-q C-j respectively. Also, C-o inserts a newline without line breaking.

When Auto Fill mode breaks a line, it tries to obey the adaptive fill prefix: if a fill prefix can be deduced from the first and/or second line of the current paragraph, it is inserted into the new line (see Adaptive Fill). Otherwise the new line is indented, as though you had typed TAB on it (see Indentation). In a programming language mode, if a line is broken in the middle of a comment, the comment is split by inserting new comment delimiters as appropriate.

Auto Fill mode does not refill entire paragraphs; it breaks lines but does not merge lines. Therefore, editing in the middle of a paragraph can result in a paragraph that is not correctly filled. To fill it, call the explicit fill commands (see Fill Commands).

Next: , Previous: , Up: Filling   [Contents][Index]

25.6.2 Explicit Fill Commands

M-q

Fill current paragraph (fill-paragraph).

C-x f

Set the fill column (set-fill-column).

M-x fill-region

Fill each paragraph in the region (fill-region).

M-x fill-region-as-paragraph

Fill the region, considering it as one paragraph.

M-o M-s

Center a line.

The command M-q (fill-paragraph) fills the current paragraph. It redistributes the line breaks within the paragraph, and deletes any excess space and tab characters occurring within the paragraph, in such a way that the lines end up fitting within a certain maximum width.

Normally, M-q acts on the paragraph where point is, but if point is between paragraphs, it acts on the paragraph after point. If the region is active, it acts instead on the text in the region. You can also call M-x fill-region to specifically fill the text in the region.

M-q and fill-region use the usual Emacs criteria for finding paragraph boundaries (see Paragraphs). For more control, you can use M-x fill-region-as-paragraph, which refills everything between point and mark as a single paragraph. This command deletes any blank lines within the region, so separate blocks of text end up combined into one block.

A numeric argument to M-q tells it to justify the text as well as filling it. This means that extra spaces are inserted to make the right margin line up exactly at the fill column. To remove the extra spaces, use M-q with no argument. (Likewise for fill-region.)

The maximum line width for filling is specified by the buffer-local variable fill-column. The default value (see Locals) is 70. The easiest way to set fill-column in the current buffer is to use the command C-x f (set-fill-column). With a numeric argument, it uses that as the new fill column. With just C-u as argument, it sets fill-column to the current horizontal position of point.

The command M-o M-s (center-line) centers the current line within the current fill column. With an argument n, it centers n lines individually and moves past them. This binding is made by Text mode and is available only in that and related modes (see Text Mode).

By default, Emacs considers a period followed by two spaces or by a newline as the end of a sentence; a period followed by just one space indicates an abbreviation, not the end of a sentence. Accordingly, the fill commands will not break a line after a period followed by just one space. If you set the variable sentence-end-double-space to nil, the fill commands will break a line after a period followed by one space, and put just one space after each period. See Sentences, for other effects and possible drawbacks of this.

If the variable colon-double-space is non-nil, the fill commands put two spaces after a colon.

To specify additional conditions where line-breaking is not allowed, customize the abnormal hook variable fill-nobreak-predicate (see Hooks). Each function in this hook is called with no arguments, with point positioned where Emacs is considering breaking a line. If a function returns a non-nil value, Emacs will not break the line there. Functions you can use there include: fill-single-word-nobreak-p (don’t break after the first word of a sentence or before the last); fill-single-char-nobreak-p (don’t break after a one-letter word preceded by a whitespace character); fill-french-nobreak-p (don’t break after ‘(’ or before ‘)’, ‘:’ or ‘?’); and fill-polish-nobreak-p (don’t break after a one letter word, even if preceded by a non-whitespace character).

Emacs can display an indicator in the fill-column position using the Display fill column indicator mode (see display-fill-column-indicator).

Next: , Previous: , Up: Filling   [Contents][Index]

25.6.3 The Fill Prefix

The fill prefix feature allows paragraphs to be filled so that each line starts with a special string of characters (such as a sequence of spaces, giving an indented paragraph). You can specify a fill prefix explicitly; otherwise, Emacs tries to deduce one automatically (see Adaptive Fill).

C-x .

Set the fill prefix (set-fill-prefix).

M-q

Fill a paragraph using current fill prefix (fill-paragraph).

M-x fill-individual-paragraphs

Fill the region, considering each change of indentation as starting a new paragraph.

M-x fill-nonuniform-paragraphs

Fill the region, considering only paragraph-separator lines as starting a new paragraph.

To specify a fill prefix for the current buffer, move to a line that starts with the desired prefix, put point at the end of the prefix, and type C-x . (set-fill-prefix). (That’s a period after the C-x.) To turn off the fill prefix, specify an empty prefix: type C-x . with point at the beginning of a line.

When a fill prefix is in effect, the fill commands remove the fill prefix from each line of the paragraph before filling, and insert it on each line after filling. (The beginning of the first line of the paragraph is left unchanged, since often that is intentionally different.) Auto Fill mode also inserts the fill prefix automatically when it makes a new line (see Auto Fill). The C-o command inserts the fill prefix on new lines it creates, when you use it at the beginning of a line (see Blank Lines). Conversely, the command M-^ deletes the prefix (if it occurs) after the newline that it deletes (see Indentation).

For example, if fill-column is 40 and you set the fill prefix to ‘;; ’, then M-q in the following text

;; This is an
;; example of a paragraph
;; inside a Lisp-style comment.

produces this:

;; This is an example of a paragraph
;; inside a Lisp-style comment.

Lines that do not start with the fill prefix are considered to start paragraphs, both in M-q and the paragraph commands; this gives good results for paragraphs with hanging indentation (every line indented except the first one). Lines which are blank or indented once the prefix is removed also separate or start paragraphs; this is what you want if you are writing multi-paragraph comments with a comment delimiter on each line.

You can use M-x fill-individual-paragraphs to set the fill prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these paragraphs. Thus, all the lines in one paragraph have the same amount of indentation. That indentation serves as the fill prefix for that paragraph.

M-x fill-nonuniform-paragraphs is a similar command that divides the region into paragraphs in a different way. It considers only paragraph-separating lines (as defined by paragraph-separate) as starting a new paragraph. Since this means that the lines of one paragraph may have different amounts of indentation, the fill prefix used is the smallest amount of indentation of any of the lines of the paragraph. This gives good results with styles that indent a paragraph’s first line more or less that the rest of the paragraph.

The fill prefix is stored in the variable fill-prefix. Its value is a string, or nil when there is no fill prefix. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See Locals.

The indentation text property provides another way to control the amount of indentation paragraphs receive. See Enriched Indentation.

Previous: , Up: Filling   [Contents][Index]

25.6.4 Adaptive Filling

The fill commands can deduce the proper fill prefix for a paragraph automatically in certain cases: either whitespace or certain punctuation characters at the beginning of a line are propagated to all lines of the paragraph.

If the paragraph has two or more lines, the fill prefix is taken from the paragraph’s second line, but only if it appears on the first line as well.

If a paragraph has just one line, fill commands may take a prefix from that line. The decision is complicated because there are three reasonable things to do in such a case:

All three of these styles of formatting are commonly used. So the fill commands try to determine what you would like, based on the prefix that appears and on the major mode. Here is how.

If the prefix found on the first line matches adaptive-fill-first-line-regexp, or if it appears to be a comment-starting sequence (this depends on the major mode), then the prefix found is used for filling the paragraph, provided it would not act as a paragraph starter on subsequent lines.

Otherwise, the prefix found is converted to an equivalent number of spaces, and those spaces are used as the fill prefix for the rest of the lines, provided they would not act as a paragraph starter on subsequent lines.

In Text mode, and other modes where only blank lines and page delimiters separate paragraphs, the prefix chosen by adaptive filling never acts as a paragraph starter, so it can always be used for filling.

The variable adaptive-fill-regexp determines what kinds of line beginnings can serve as a fill prefix: any characters at the start of the line that match this regular expression are used. If you set the variable adaptive-fill-mode to nil, the fill prefix is never chosen automatically.

You can specify more complex ways of choosing a fill prefix automatically by setting the variable adaptive-fill-function to a function. This function is called with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns nil, adaptive-fill-regexp gets a chance to find a prefix.

Next: , Previous: , Up: Text   [Contents][Index]

25.7 Case Conversion Commands

Emacs has commands for converting either a single word or any arbitrary range of text to upper case or to lower case.

M-l

Convert following word to lower case (downcase-word).

M-u

Convert following word to upper case (upcase-word).

M-c

Capitalize the following word (capitalize-word).

C-x C-l

Convert region to lower case (downcase-region).

C-x C-u

Convert region to upper case (upcase-region).

M-l (downcase-word) converts the word after point to lower case, moving past it. Thus, repeating M-l converts successive words. M-u (upcase-word) converts to all capitals instead, while M-c (capitalize-word) puts the first letter of the word into upper case and the rest into lower case. All these commands convert several words at once if given an argument. They are especially convenient for converting a large amount of text from all upper case to mixed case, because you can move through the text using M-l, M-u or M-c on each word as appropriate, occasionally using M-f instead to skip a word.

When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. This is convenient when you have just typed a word in the wrong case: you can give the case conversion command and continue typing.

If a word case conversion command is given in the middle of a word, it applies only to the part of the word which follows point. (This is comparable to what M-d (kill-word) does.) With a negative argument, case conversion applies only to the part of the word before point.

The other case conversion commands are C-x C-u (upcase-region) and C-x C-l (downcase-region), which convert everything between point and mark to the specified case. Point and mark do not move.

The region case conversion commands upcase-region and downcase-region are normally disabled. This means that they ask for confirmation if you try to use them. When you confirm, you may enable the command, which means it will not ask for confirmation again. See Disabling.

Next: , Previous: , Up: Text   [Contents][Index]

25.8 Text Mode

Text mode is a major mode for editing files of text in a human language. Files which have names ending in the extension .txt are usually opened in Text mode (see Choosing Modes). To explicitly switch to Text mode, type M-x text-mode.

In Text mode, only blank lines and page delimiters separate paragraphs. As a result, paragraphs can be indented, and adaptive filling determines what indentation to use when filling a paragraph. See Adaptive Fill.

In Text mode, the TAB (indent-for-tab-command) command usually inserts whitespace up to the next tab stop, instead of indenting the current line. See Indentation, for details.

Text mode turns off the features concerned with comments except when you explicitly invoke them. It changes the syntax table so that apostrophes are considered part of words (e.g., ‘don't’ is considered one word). However, if a word starts with an apostrophe, it is treated as a prefix for the purposes of capitalization (e.g., M-c converts ‘'hello'’ into ‘'Hello'’, as expected).

If you indent the first lines of paragraphs, then you should use Paragraph-Indent Text mode (M-x paragraph-indent-text-mode) rather than Text mode. In that mode, you do not need to have blank lines between paragraphs, because the first-line indentation is sufficient to start a paragraph; however paragraphs in which every line is indented are not supported. Use M-x paragraph-indent-minor-mode to enable an equivalent minor mode for situations where you shouldn’t change the major mode—in mail composition, for instance.

Text mode binds M-TAB to ispell-complete-word. This command performs completion of the partial word in the buffer before point, using the spelling dictionary as the space of possible words. See Spelling. If your window manager defines M-TAB to switch windows, you can type ESC TAB or C-M-i instead.

Entering Text mode runs the mode hook text-mode-hook (see Major Modes).

The following sections describe several major modes that are derived from Text mode. These derivatives share most of the features of Text mode described above. In particular, derivatives of Text mode run text-mode-hook prior to running their own mode hooks.

Next: , Previous: , Up: Text   [Contents][Index]

25.9 Outline Mode

Outline mode is a major mode derived from Text mode, which is specialized for editing outlines. It provides commands to navigate between entries in the outline structure, and commands to make parts of a buffer temporarily invisible, so that the outline structure may be more easily viewed. Type M-x outline-mode to switch to Outline mode. Entering Outline mode runs the hook text-mode-hook followed by the hook outline-mode-hook (see Hooks).

When you use an Outline mode command to make a line invisible (see Outline Visibility), the line disappears from the screen. An ellipsis (three periods in a row) is displayed at the end of the previous visible line, to indicate the hidden text. Multiple consecutive invisible lines produce just one ellipsis.

Editing commands that operate on lines, such as C-n and C-p, treat the text of the invisible line as part of the previous visible line. Killing the ellipsis at the end of a visible line really kills all the following invisible text associated with the ellipsis.

Outline minor mode is a buffer-local minor mode which provides the same commands as the major mode, Outline mode, but can be used in conjunction with other major modes. You can type M-x outline-minor-mode to toggle Outline minor mode in the current buffer, or use a file-local variable setting to enable it in a specific file (see File Variables).

The major mode, Outline mode, provides special key bindings on the C-c prefix. Outline minor mode provides similar bindings with C-c @ as the prefix; this is to reduce the conflicts with the major mode’s special commands. (The variable outline-minor-mode-prefix controls the prefix used.)

25.9.1 Format of Outlines

Outline mode assumes that the lines in the buffer are of two types: heading lines and body lines. A heading line represents a topic in the outline. Heading lines start with one or more asterisk (‘*’) characters; the number of asterisks determines the depth of the heading in the outline structure. Thus, a heading line with one ‘*’ is a major topic; all the heading lines with two ‘*’s between it and the next one-‘*’ heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example:

* Food
This is the body,
which says something about the topic of food.

** Delicious Food
This is the body of the second-level header.

** Distasteful Food
This could have
a body too, with
several lines.

*** Dormitory Food

* Shelter
Another first-level topic with its header line.

A heading line together with all following body lines is called collectively an entry. A heading line together with all following deeper heading lines and their body lines is called a subtree.

You can customize the criterion for distinguishing heading lines by setting the variable outline-regexp. (The recommended ways to do this are in a major mode function or with a file local variable.) Any line whose beginning has a match for this regexp is considered a heading line. Matches that start within a line (not at the left margin) do not count.

The length of the matching text determines the level of the heading; longer matches make a more deeply nested level. Thus, for example, if a text formatter has commands ‘@chapter’, ‘@section’ and ‘@subsection’ to divide the document into chapters and sections, you could make those lines count as heading lines by setting outline-regexp to ‘"@chap\\|@\\(sub\\)*section"’. Note the trick: the two words ‘chapter’ and ‘section’ are equally long, but by defining the regexp to match only ‘chap’ we ensure that the length of the text matched on a chapter heading is shorter, so that Outline mode will know that sections are contained in chapters. This works as long as no other command starts with ‘@chap’.

You can explicitly specify a rule for calculating the level of a heading line by setting the variable outline-level. The value of outline-level should be a function that takes no arguments and returns the level of the current heading. The recommended ways to set this variable are in a major mode command or with a file local variable.

25.9.2 Outline Motion Commands

Outline mode provides special motion commands that move backward and forward to heading lines.

C-c C-n

Move point to the next visible heading line (outline-next-visible-heading).

C-c C-p

Move point to the previous visible heading line (outline-previous-visible-heading).

C-c C-f

Move point to the next visible heading line at the same level as the one point is on (outline-forward-same-level).

C-c C-b

Move point to the previous visible heading line at the same level (outline-backward-same-level).

C-c C-u

Move point up to a lower-level (more inclusive) visible heading line (outline-up-heading).

All of the above commands accept numeric arguments as repeat counts. For example, C-c C-f, when given an argument, moves forward that many visible heading lines on the same level, and C-c C-u with an argument moves out of that many nested levels.

25.9.3 Outline Visibility Commands

Outline mode provides several commands for temporarily hiding or revealing parts of the buffer, based on the outline structure. These commands are not undoable; their effects are simply not recorded by the undo mechanism, so you can undo right past them (see Undo).

Many of these commands act on the current heading line. If point is on a heading line, that is the current heading line; if point is on a body line, the current heading line is the nearest preceding header line.

C-c C-c

Make the current heading line’s body invisible (outline-hide-entry).

C-c C-e

Make the current heading line’s body visible (outline-show-entry).

C-c C-d

Make everything under the current heading invisible, not including the heading itself (outline-hide-subtree).

C-c C-s

Make everything under the current heading visible, including body, subheadings, and their bodies (outline-show-subtree).

C-c C-l

Make the body of the current heading line, and of all its subheadings, invisible (outline-hide-leaves).

C-c C-k

Make all subheadings of the current heading line, at all levels, visible (outline-show-branches).

C-c C-i

Make immediate subheadings (one level down) of the current heading line visible (outline-show-children).

C-c C-t

Make all body lines in the buffer invisible (outline-hide-body).

C-c C-a

Make all lines in the buffer visible (outline-show-all).

C-c C-q

Hide everything except the top n levels of heading lines (outline-hide-sublevels).

C-c C-o

Hide everything except for the heading or body that point is in, plus the headings leading up from there to the top level of the outline (outline-hide-other).

The simplest of these commands are C-c C-c (outline-hide-entry), which hides the body lines directly following the current heading line, and C-c C-e (outline-show-entry), which reveals them. Subheadings and their bodies are not affected.

The commands C-c C-d (outline-hide-subtree) and C-c C-s (outline-show-subtree) are more powerful. They apply to the current heading line’s subtree: its body, all of its subheadings, both direct and indirect, and all of their bodies.

The command C-c C-l (outline-hide-leaves) hides the body of the current heading line as well as all the bodies in its subtree; the subheadings themselves are left visible. The command C-c C-k (outline-show-branches) reveals the subheadings, if they had previously been hidden (e.g., by C-c C-d). The command C-c C-i (outline-show-children) is a weaker version of this; it reveals just the direct subheadings, i.e., those one level down.

The command C-c C-o (outline-hide-other) hides everything except the entry that point is in, plus its parents (the headers leading up from there to top level in the outline) and the top level headings. It also reveals body lines preceding the first heading in the buffer.

The remaining commands affect the whole buffer. C-c C-t (outline-hide-body) makes all body lines invisible, so that you see just the outline structure (as a special exception, it will not hide lines at the top of the file, preceding the first header line, even though these are technically body lines). C-c C-a (outline-show-all) makes all lines visible. C-c C-q (outline-hide-sublevels) hides all but the top level headings at and above the level of the current heading line (defaulting to 1 if point is not on a heading); with a numeric argument n, it hides everything except the top n levels of heading lines. Note that it completely reveals all the n top levels and the body lines before the first heading.

When incremental search finds text that is hidden by Outline mode, it makes that part of the buffer visible. If you exit the search at that position, the text remains visible. To toggle whether or not an active incremental search can match hidden text, type M-s i. To change the default for future searches, customize the option search-invisible. (This option also affects how query-replace and related functions treat hidden text, see Query Replace.) You can also automatically make text visible as you navigate in it by using Reveal mode (M-x reveal-mode), a buffer-local minor mode.

Next: , Previous: , Up: Outline Mode   [Contents][Index]

25.9.4 Viewing One Outline in Multiple Views

You can display two views of a single outline at the same time, in different windows. To do this, you must create an indirect buffer using M-x make-indirect-buffer. The first argument of this command is the existing outline buffer name, and its second argument is the name to use for the new indirect buffer. See Indirect Buffers.

Once the indirect buffer exists, you can display it in a window in the normal fashion, with C-x 4 b or other Emacs commands. The Outline mode commands to show and hide parts of the text operate on each buffer independently; as a result, each buffer can have its own view. If you want more than two views on the same outline, create additional indirect buffers.

Previous: , Up: Outline Mode   [Contents][Index]

25.9.5 Folding Editing

The Foldout package extends Outline mode and Outline minor mode with folding commands. The idea of folding is that you zoom in on a nested portion of the outline, while hiding its relatives at higher levels.

Consider an Outline mode buffer with all the text and subheadings under level-1 headings hidden. To look at what is hidden under one of these headings, you could use C-c C-e (M-x outline-show-entry) to expose the body, or C-c C-i to expose the child (level-2) headings.

With Foldout, you use C-c C-z (M-x foldout-zoom-subtree). This exposes the body and child subheadings, and narrows the buffer so that only the level-1 heading, the body and the level-2 headings are visible. Now to look under one of the level-2 headings, position the cursor on it and use C-c C-z again. This exposes the level-2 body and its level-3 child subheadings and narrows the buffer again. Zooming in on successive subheadings can be done as much as you like. A string in the mode line shows how deep you’ve gone.

When zooming in on a heading, to see only the child subheadings specify a numeric argument: C-u C-c C-z. The number of levels of children can be specified too (compare M-x outline-show-children), e.g., M-2 C-c C-z exposes two levels of child subheadings. Alternatively, the body can be specified with a negative argument: M-- C-c C-z. The whole subtree can be expanded, similarly to C-c C-s (M-x outline-show-subtree), by specifying a zero argument: M-0 C-c C-z.

While you’re zoomed in, you can still use Outline mode’s exposure and hiding functions without disturbing Foldout. Also, since the buffer is narrowed, global editing actions will only affect text under the zoomed-in heading. This is useful for restricting changes to a particular chapter or section of your document.

To unzoom (exit) a fold, use C-c C-x (M-x foldout-exit-fold). This hides all the text and subheadings under the top-level heading and returns you to the previous view of the buffer. Specifying a numeric argument exits that many levels of folds. Specifying a zero argument exits all folds.

To cancel the narrowing of a fold without hiding the text and subheadings, specify a negative argument. For example, M--2 C-c C-x exits two folds and leaves the text and subheadings exposed.

Foldout mode also provides mouse commands for entering and exiting folds, and for showing and hiding text:

C-M-mouse-1 zooms in on the heading clicked on
  • single click: expose body.
  • double click: expose subheadings.
  • triple click: expose body and subheadings.
  • quad click: expose entire subtree.
C-M-mouse-2 exposes text under the heading clicked on
  • single click: expose body.
  • double click: expose subheadings.
  • triple click: expose body and subheadings.
  • quad click: expose entire subtree.
C-M-mouse-3 hides text under the heading clicked on or exits fold
  • single click: hide subtree.
  • double click: exit fold and hide text.
  • triple click: exit fold without hiding text.
  • quad click: exit all folds and hide text.

You can specify different modifier keys (instead of Ctrl-Meta-) by setting foldout-mouse-modifiers; but if you have already loaded the foldout.el library, you must reload it in order for this to take effect.

To use the Foldout package, you can type M-x load-library RET foldout RET; or you can arrange for to do that automatically by putting the following in your init file:

(with-eval-after-load "outline"
  (require 'foldout))

Next: , Previous: , Up: Text   [Contents][Index]

25.10 Org Mode

Org mode is a variant of Outline mode for using Emacs as an organizer and/or authoring system. Files with names ending in the extension .org are opened in Org mode (see Choosing Modes). To explicitly switch to Org mode, type M-x org-mode.

In Org mode, as in Outline mode, each entry has a heading line that starts with one or more ‘*’ characters. See Outline Format. In addition, any line that begins with the ‘#’ character is treated as a comment.

Org mode provides commands for easily viewing and manipulating the outline structure. The simplest of these commands is TAB (org-cycle). If invoked on a heading line, it cycles through the different visibility states of the subtree: (i) showing only that heading line, (ii) showing only the heading line and the heading lines of its direct children, if any, and (iii) showing the entire subtree. If invoked in a body line, the global binding for TAB is executed.

Typing S-TAB (org-shifttab) anywhere in an Org mode buffer cycles the visibility of the entire outline structure, between (i) showing only top-level heading lines, (ii) showing all heading lines but no body lines, and (iii) showing everything.

You can move an entire entry up or down in the buffer, including its body lines and subtree (if any), by typing M-UP (org-metaup) or M-DOWN (org-metadown) on the heading line. Similarly, you can promote or demote a heading line with M-LEFT (org-metaleft) and M-RIGHT (org-metaright). These commands execute their global bindings if invoked on a body line.

The following subsections give basic instructions for using Org mode as an organizer and as an authoring system. For details, see Introduction in The Org Manual.

25.10.1 Org as an organizer

You can tag an Org entry as a TODO item by typing C-c C-t (org-todo) anywhere in the entry. This adds the keyword ‘TODO’ to the heading line. Typing C-c C-t again switches the keyword to ‘DONE’; another C-c C-t removes the keyword entirely, and so forth. You can customize the keywords used by C-c C-t via the variable org-todo-keywords.

Apart from marking an entry as TODO, you can attach a date to it, by typing C-c C-s (org-schedule) in the entry. This prompts for a date by popping up the Emacs Calendar (see Calendar/Diary), and then adds the tag ‘SCHEDULED’, together with the selected date, beneath the heading line. The command C-c C-d (org-deadline) has the same effect, except that it uses the tag DEADLINE.

Once you have some TODO items planned in an Org file, you can add that file to the list of agenda files by typing C-c [ (org-agenda-file-to-front). Org mode is designed to let you easily maintain multiple agenda files, e.g., for organizing different aspects of your life. The list of agenda files is stored in the variable org-agenda-files.

To view items coming from your agenda files, type M-x org-agenda. This command prompts for what you want to see: a list of things to do this week, a list of TODO items with specific keywords, etc. See Agenda Views in The Org Manual, for details.

Previous: , Up: Org Mode   [Contents][Index]

25.10.2 Org as an authoring system

You may want to format your Org notes nicely and to prepare them for export and publication. To export the current buffer, type C-c C-e (org-export) anywhere in an Org buffer. This command prompts for an export format; currently supported formats include HTML, LaTeX, Texinfo, OpenDocument (.odt), iCalendar, Markdown, man-page, and PDF. Some formats, such as PDF, require certain system tools to be installed.

To export several files at once to a specific directory, either locally or over the network, you must define a list of projects through the variable org-publish-project-alist. See its documentation for details.

Org supports a simple markup scheme for applying text formatting to exported documents:

- This text is /emphasized/
- This text is *in bold*
- This text is _underlined_
- This text uses =a teletype font=

#+begin_quote
``This is a quote.''
#+end_quote

#+begin_example
This is an example.
#+end_example

For further details, Exporting in The Org Manual, and Publishing in The Org Manual.

Next: , Previous: , Up: Text   [Contents][Index]

25.11 TeX Mode

TeX is a powerful text formatter written by Donald Knuth; like GNU Emacs, it is free software. The TeX format has several variants, including LaTeX, a simplified input format for TeX; DocTeX, a special file format in which the LaTeX sources are written, combining sources with documentation; and SliTeX, an obsolete special form of LaTeX12.

Emacs provides a TeX major mode for each of these variants: Plain TeX mode, LaTeX mode, DocTeX mode, and SliTeX mode. Emacs selects the appropriate mode by looking at the contents of the buffer. (This is done by invoking the tex-mode command, which is normally called automatically when you visit a TeX-like file. See Choosing Modes.) If the contents are insufficient to determine this, Emacs chooses the mode specified by the variable tex-default-mode; its default value is latex-mode. If Emacs does not guess right, you can select the correct variant of TeX mode using the commands plain-tex-mode, latex-mode, slitex-mode, or doctex-mode.

The following sections document the features of TeX mode and its variants. There are several other TeX-related Emacs packages, which are not documented in this manual:

25.11.1 TeX Editing Commands

"

Insert, according to context, either ‘``’ or ‘"’ or ‘''’ (tex-insert-quote).

C-j

Insert a paragraph break (two newlines) and check the previous paragraph for unbalanced braces or dollar signs (tex-terminate-paragraph).

M-x tex-validate-region

Check each paragraph in the region for unbalanced braces or dollar signs.

C-c {

Insert ‘{}’ and position point between them (tex-insert-braces).

C-c }

Move forward past the next unmatched close brace (up-list).

In TeX, the character ‘"’ is not normally used; instead, quotations begin with ‘``’ and end with ‘''’. TeX mode therefore binds the " key to the tex-insert-quote command. This inserts ‘``’ after whitespace or an open brace, ‘"’ after a backslash, and ‘''’ after any other character.

As a special exception, if you type " when the text before point is either ‘``’ or ‘''’, Emacs replaces that preceding text with a single ‘"’ character. You can therefore type "" to insert ‘"’, should you ever need to do so. (You can also use C-q " to insert this character.)

In TeX mode, ‘$’ has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a ‘$’ that is meant to exit math mode, the position of the matching ‘$’ that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a ‘$’ enters math mode or leaves it; so when you insert a ‘$’ that enters math mode, the previous ‘$’ position is shown as if it were a match, even though they are actually unrelated.

TeX uses braces as delimiters that must match. Some users prefer to keep braces balanced at all times, rather than inserting them singly. Use C-c { (tex-insert-braces) to insert a pair of braces. It leaves point between the two braces so you can insert the text that belongs inside. Afterward, use the command C-c } (up-list) to move forward past the close brace. You can also invoke C-c { after marking some text: then the command encloses the marked text in braces.

There are two commands for checking the matching of braces. C-j (tex-terminate-paragraph) checks the paragraph before point, and inserts two newlines to start a new paragraph. It outputs a message in the echo area if any mismatch is found. M-x tex-validate-region checks a region, paragraph by paragraph. The errors are listed in an *Occur* buffer; you can use the usual Occur mode commands in that buffer, such as C-c C-c, to visit a particular mismatch (see Other Repeating Search).

Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters, and it is useful for the various motion commands and automatic match display to work with them.

Next: , Previous: , Up: TeX Mode   [Contents][Index]

25.11.2 LaTeX Editing Commands

LaTeX mode provides a few extra features not applicable to plain TeX:

C-c C-o

Insert ‘\begin’ and ‘\end’ for LaTeX block and position point on a line between them (tex-latex-block).

C-c C-e

Close the innermost LaTeX block not yet closed (tex-close-latex-block).

In LaTeX input, ‘\begin’ and ‘\end’ tags are used to group blocks of text. To insert a block, type C-c C-o (tex-latex-block). This prompts for a block type, and inserts the appropriate matching ‘\begin’ and ‘\end’ tags, leaving a blank line between the two and moving point there.

When entering the block type argument to C-c C-o, you can use the usual completion commands (see Completion). The default completion list contains the standard LaTeX block types. If you want additional block types for completion, customize the list variable latex-block-names.

In LaTeX input, ‘\begin’ and ‘\end’ tags must balance. You can use C-c C-e (tex-close-latex-block) to insert an ‘\end’ tag which matches the last unmatched ‘\begin’. It also indents the ‘\end’ to match the corresponding ‘\begin’, and inserts a newline after the ‘\end’ tag if point is at the beginning of a line. The minor mode latex-electric-env-pair-mode automatically inserts an ‘\end’ or ‘\begin’ tag for you when you type the corresponding one.

Next: , Previous: , Up: TeX Mode   [Contents][Index]

25.11.3 TeX Printing Commands

You can invoke TeX as a subprocess of Emacs, supplying either the entire contents of the buffer or just part of it (e.g., one chapter of a larger document).

C-c C-b

Invoke TeX on the entire current buffer (tex-buffer).

C-c C-r

Invoke TeX on the current region, together with the buffer’s header (tex-region).

C-c C-f

Invoke TeX on the current file (tex-file).

C-c C-v

Preview the output from the last C-c C-b, C-c C-r, or C-c C-f command (tex-view).

C-c C-p

Print the output from the last C-c C-b, C-c C-r, or C-c C-f command (tex-print).

C-c TAB

Invoke BibTeX on the current file (tex-bibtex-file).

C-c C-l

Recenter the window showing output from TeX so that the last line can be seen (tex-recenter-output-buffer).

C-c C-k

Kill the TeX subprocess (tex-kill-job).

C-c C-c

Invoke some other compilation command on the entire current buffer (tex-compile).

To pass the current buffer through TeX, type C-c C-b (tex-buffer). The formatted output goes in a temporary file, normally a .dvi file. Afterwards, you can type C-c C-v (tex-view) to launch an external program, such as xdvi, to view this output file. You can also type C-c C-p (tex-print) to print a hardcopy of the output file.

By default, C-c C-b runs TeX in the current directory. The output of TeX is also created in this directory. To run TeX in a different directory, change the variable tex-directory to the desired directory. If your environment variable TEXINPUTS contains relative names, or if your files contain ‘\input’ commands with relative file names, then tex-directory must be "." or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as "/tmp".

The buffer’s TeX variant determines what shell command C-c C-b actually runs. In Plain TeX mode, it is specified by the variable tex-run-command, which defaults to "tex". In LaTeX mode, it is specified by latex-run-command, which defaults to "latex". The shell command that C-c C-v runs to view the .dvi output is determined by the variable tex-dvi-view-command, regardless of the TeX variant. The shell command that C-c C-p runs to print the output is determined by the variable tex-dvi-print-command. The variable tex-print-file-extension can be set to the required file extension for viewing and printing TeX-compiled files. For example, you can set it to .pdf, and update tex-dvi-view-command and tex-dvi-print-command accordingly, as well as latex-run-command or tex-run-command.

Normally, Emacs automatically appends the output file name to the shell command strings described in the preceding paragraph. For example, if tex-dvi-view-command is "xdvi", C-c C-v runs xdvi output-file-name. In some cases, however, the file name needs to be embedded in the command, e.g., if you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with ‘*’ in the command string. 例如,

(setq tex-dvi-print-command "dvips -f * | lpr")

The terminal output from TeX, including any error messages, appears in a buffer called *tex-shell*. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; see Interactive Shell). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.

Type C-c C-k (tex-kill-job) to kill the TeX process if you see that its output is no longer useful. Using C-c C-b or C-c C-r also kills any TeX process still running.

You can also pass an arbitrary region through TeX by typing C-c C-r (tex-region). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, C-c C-r allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the header.

To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert ‘%**start of header’ before the header, and ‘%**end of header’ after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If ‘%**start of header’ does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.

In LaTeX mode, the header begins with ‘\documentclass’ or ‘\documentstyle’ and ends with ‘\begin{document}’. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.

The commands (tex-buffer) and (tex-region) do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct.

When you want the auxiliary files for cross references, use C-c C-f (tex-file) which runs TeX on the current buffer’s file, in that file’s directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (tex-file) twice to get the cross-references right.

The value of the variable tex-start-options specifies options for the TeX run.

The value of the variable tex-start-commands specifies TeX commands for starting TeX. The default value causes TeX to run in nonstop mode. To run TeX interactively, set the variable to "".

Large TeX documents are often split into several files—one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make tex-file useful when you are editing a subfile, you can set the variable tex-main-file to the name of the main file. Then tex-file runs TeX on that file.

The most convenient way to use tex-main-file is to specify it in a local variable list in each of the subfiles. See File Variables.

For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer’s file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command C-c TAB (tex-bibtex-file) runs the shell command (tex-bibtex-command) to produce a ‘.bbl’ file for the current buffer’s file. Generally, you need to do C-c C-f (tex-file) once to generate the ‘.aux’ file, then do C-c TAB (tex-bibtex-file), and then repeat C-c C-f (tex-file) twice more to get the cross-references correct.

To invoke some other compilation program on the current TeX buffer, type C-c C-c (tex-compile). This command knows how to pass arguments to many common programs, including pdflatex, yap, xdvi, and dvips. You can select your desired compilation program using the standard completion keys (see Completion).

Previous: , Up: TeX Mode   [Contents][Index]

25.11.4 TeX Mode Miscellany

Entering any variant of TeX mode runs the hooks text-mode-hook and tex-mode-hook. Then it runs either plain-tex-mode-hook, doctex-mode-hook, latex-mode-hook, or slitex-mode-hook, whichever is appropriate. Starting the TeX shell runs the hook tex-shell-hook. See Hooks.

The commands M-x iso-iso2tex, M-x iso-tex2iso, M-x iso-iso2gtex and M-x iso-gtex2iso can be used to convert between Latin-1 encoded files and TeX-encoded equivalents.

Next: , Previous: , Up: Text   [Contents][Index]

25.12 SGML and HTML Modes

The major modes for SGML and HTML provide indentation support and commands for operating on tags.

HTML consists of two modes—one, a basic mode called html-mode is a slightly customized variant of SGML mode. The other, which is used by default for HTML files, is called mhtml-mode, and attempts to properly handle Javascript enclosed in a <script> element and CSS embedded in a <style> element.

C-c C-n

Interactively specify a special character and insert the SGML ‘&’-command for that character (sgml-name-char).

C-c C-t

Interactively specify a tag and its attributes (sgml-tag). This command asks you for a tag name and for the attribute values, then inserts both the opening tag and the closing tag, leaving point between them.

With a prefix argument n, the command puts the tag around the n words already present in the buffer after point. Whenever a region is active, it puts the tag around the region (when Transient Mark mode is off, it does this when a numeric argument of -1 is supplied.)

C-c C-a

Interactively insert attribute values for the current tag (sgml-attributes).

C-c C-f

Skip across a balanced tag group (which extends from an opening tag through its corresponding closing tag) (sgml-skip-tag-forward). A numeric argument acts as a repeat count.

C-c C-b

Skip backward across a balanced tag group (which extends from an opening tag through its corresponding closing tag) (sgml-skip-tag-backward). A numeric argument acts as a repeat count.

C-c C-d

Delete the tag at or after point, and delete the matching tag too (sgml-delete-tag). If the tag at or after point is an opening tag, delete the closing tag too; if it is a closing tag, delete the opening tag too.

C-c ? tag RET

Display a description of the meaning of tag tag (sgml-tag-help). If the argument tag is empty, describe the tag at point.

C-c /

Insert a close tag for the innermost unterminated tag (sgml-close-tag). If called within a tag or a comment, close it instead of inserting a close tag.

C-c 8

Toggle a minor mode in which Latin-1 characters insert the corresponding SGML commands that stand for them, instead of the characters themselves (sgml-name-8bit-mode).

C-c C-v

Run a shell command (which you must specify) to validate the current buffer as SGML (sgml-validate). (In HTML mode this key sequence runs a different command.)

C-c TAB

Toggle the visibility of existing tags in the buffer. This can be used as a cheap preview (sgml-tags-invisible).

The major mode for editing XML documents is called nXML mode. This is a powerful major mode that can recognize many existing XML schemas and use them to provide completion of XML elements via M-TAB, as well as on-the-fly XML validation with error highlighting. To enable nXML mode in an existing buffer, type M-x nxml-mode, or, equivalently, M-x xml-mode. Emacs uses nXML mode for files which have the extension .xml. For XHTML files, which have the extension .xhtml, Emacs uses HTML mode by default; you can make it use nXML mode by customizing the variable auto-mode-alist (see Choosing Modes). nXML mode is described in an Info manual, which is distributed with Emacs.

You may choose to use the less powerful SGML mode for editing XML, since XML is a strict subset of SGML. To enable SGML mode in an existing buffer, type M-x sgml-mode. On enabling SGML mode, Emacs examines the buffer to determine whether it is XML; if so, it sets the variable sgml-xml-mode to a non-nil value. This causes SGML mode’s tag insertion commands, described above, to always insert explicit closing tags as well.

Next: , Previous: , Up: Text   [Contents][Index]

25.13 Nroff Mode

Nroff mode, a major mode derived from Text mode, is specialized for editing nroff files (e.g., Unix man pages). Type M-x nroff-mode to enter this mode. Entering Nroff mode runs the hook text-mode-hook, then nroff-mode-hook (see Hooks).

In Nroff mode, nroff command lines are treated as paragraph separators, pages are separated by ‘.bp’ commands, and comments start with backslash-doublequote. It also defines these commands:

M-n

Move to the beginning of the next line that isn’t an nroff command (nroff-forward-text-line). An argument is a repeat count.

M-p

Like M-n but move up (nroff-backward-text-line).

M-?

Displays in the echo area the number of text lines (lines that are not nroff commands) in the region (nroff-count-text-lines).

Electric Nroff mode is a buffer-local minor mode that can be used with Nroff mode. To toggle this minor mode, type M-x nroff-electric-mode (see Minor Modes). When the mode is on, each time you type RET to end a line containing an nroff command that opens a kind of grouping, the nroff command to close that grouping is automatically inserted on the following line.

If you use Outline minor mode with Nroff mode (see Outline Mode), heading lines are lines of the form ‘.H’ followed by a number (the header level).

Next: , Previous: , Up: Text   [Contents][Index]

25.14 Enriched Text

Enriched mode is a minor mode for editing formatted text files in a WYSIWYG (What You See Is What You Get) fashion. When Enriched mode is enabled, you can apply various formatting properties to the text in the buffer, such as fonts and colors; upon saving the buffer, those properties are saved together with the text, using the MIME ‘text/enriched’ file format.

Enriched mode is typically used with Text mode (see Text Mode). It is not compatible with Font Lock mode, which is used by many major modes, including most programming language modes, for syntax highlighting (see Font Lock). Unlike Enriched mode, Font Lock mode assigns text properties automatically, based on the current buffer contents; those properties are not saved to disk.

The file enriched.txt in Emacs’s data-directory serves as an example of the features of Enriched mode.

25.14.1 Enriched Mode

Enriched mode is a buffer-local minor mode (see Minor Modes). When you visit a file that has been saved in the ‘text/enriched’ format, Emacs automatically enables Enriched mode, and applies the formatting information in the file to the buffer text. When you save a buffer with Enriched mode enabled, it is saved using the ‘text/enriched’ format, including the formatting information.

To create a new file of formatted text, visit the nonexistent file and type M-x enriched-mode. This command actually toggles Enriched mode. With a prefix argument, it enables Enriched mode if the argument is positive, and disables Enriched mode otherwise. If you disable Enriched mode, Emacs no longer saves the buffer using the ‘text/enriched’ format; any formatting properties that have been added to the buffer remain in the buffer, but they are not saved to disk.

Enriched mode does not save all Emacs text properties, only those specified in the variable enriched-translations. These include properties for fonts, colors, indentation, and justification.

If you visit a file and Emacs fails to recognize that it is in the ‘text/enriched’ format, type M-x format-decode-buffer. This command prompts for a file format, and re-reads the file in that format. Specifying the ‘text/enriched’ format automatically enables Enriched mode.

To view a ‘text/enriched’ file in raw form (as plain text with markup tags rather than formatted text), use M-x find-file-literally (see Visiting).

See Format Conversion in the Emacs Lisp Reference Manual, for details of how Emacs recognizes and converts file formats like ‘text/enriched’. See Text Properties in the Emacs Lisp Reference Manual, for more information about text properties.

25.14.2 Hard and Soft Newlines

In Enriched mode, Emacs distinguishes between two different kinds of newlines, hard newlines and soft newlines. You can also enable or disable this feature in other buffers, by typing M-x use-hard-newlines.

Hard newlines are used to separate paragraphs, or anywhere there needs to be a line break regardless of how the text is filled; soft newlines are used for filling. The RET (newline) and C-o (open-line) commands insert hard newlines. The fill commands, including Auto Fill (see Auto Fill), insert only soft newlines and delete only soft newlines, leaving hard newlines alone.

Thus, when editing with Enriched mode, you should not use RET or C-o to break lines in the middle of filled paragraphs. Use Auto Fill mode or explicit fill commands (see Fill Commands) instead. Use RET or C-o where line breaks should always remain, such as in tables and lists. For such lines, you may also want to set the justification style to unfilled (see Enriched Justification).

25.14.3 Editing Format Information

The easiest way to alter properties is with the ‘Text Properties’ menu. You can get to this menu from the ‘Edit’ menu in the menu bar (see Menu Bar), or with C-mouse-2 (see Menu Mouse Clicks). Some of the commands in the ‘Text Properties’ menu are listed below (you can also invoke them with M-x):

Remove Face Properties

Remove face properties from the region (facemenu-remove-face-props).

Remove Text Properties

Remove all text properties from the region, including face properties (facemenu-remove-all).

Describe Properties

List all text properties and other information about the character following point (describe-text-properties).

Display Faces

Display a list of defined faces (list-faces-display). See Faces.

Display Colors

Display a list of defined colors (list-colors-display). See Colors.

The other menu entries are described in the following sections.

25.14.4 Faces in Enriched Text

The following commands can be used to add or remove faces (see Faces). Each applies to the text in the region if the mark is active, and to the next self-inserting character if the mark is inactive. With a prefix argument, each command applies to the next self-inserting character even if the region is active.

M-o d

Remove all face properties (facemenu-set-default).

M-o b

Apply the bold face (facemenu-set-bold).

M-o i

Apply the italic face (facemenu-set-italic).

M-o l

Apply the bold-italic face (facemenu-set-bold-italic).

M-o u

Apply the underline face (facemenu-set-underline).

M-o o face RET

Apply the face face (facemenu-set-face).

M-x facemenu-set-foreground

Prompt for a color (see Colors), and apply it as a foreground color.

M-x facemenu-set-background

Prompt for a color, and apply it as a background color.

These commands are also available via the Text Properties menu.

A self-inserting character normally inherits the face properties (and most other text properties) from the preceding character in the buffer. If you use one of the above commands to specify the face for the next self-inserting character, that character will not inherit the faces properties from the preceding character, but it will still inherit other text properties.

Enriched mode defines two additional faces: excerpt and fixed. These correspond to codes used in the text/enriched file format. The excerpt face is intended for quotations; by default, it appears the same as italic. The fixed face specifies fixed-width text; by default, it appears the same as bold.

25.14.5 Indentation in Enriched Text

In Enriched mode, you can specify different amounts of indentation for the right or left margin of a paragraph or a part of a paragraph. These margins also affect fill commands such as M-q (see Filling).

The Indentation submenu of Text Properties offers commands for specifying indentation:

Indent More

Indent the region by 4 columns (increase-left-margin). In Enriched mode, this command is also available on C-x TAB; if you supply a numeric argument, that says how many columns to add to the margin (a negative argument reduces the number of columns).

Indent Less

Remove 4 columns of indentation from the region.

Indent Right More

Make the text narrower by indenting 4 columns at the right margin.

Indent Right Less

Remove 4 columns of indentation from the right margin.

The variable standard-indent specifies how many columns these commands should add to or subtract from the indentation. The default value is 4. The default right margin for Enriched mode is controlled by the variable fill-column, as usual.

You can also type C-c [ (set-left-margin) and C-c ] (set-right-margin) to set the left and right margins. You can specify the margin width with a numeric argument; otherwise these commands prompt for a value via the minibuffer.

The fill prefix, if any, works in addition to the specified paragraph indentation: C-x . does not include the specified indentation’s whitespace in the new value for the fill prefix, and the fill commands look for the fill prefix after the indentation on each line. See Fill Prefix.

25.14.6 Justification in Enriched Text

In Enriched mode, you can use the following commands to specify various justification styles for filling. These commands apply to the paragraph containing point, or, if the region is active, to all paragraphs overlapping the region.

M-j l

Align lines to the left margin (set-justification-left).

M-j r

Align lines to the right margin (set-justification-right).

M-j b

Align lines to both margins, inserting spaces in the middle of the line to achieve this (set-justification-full).

M-j c
M-S

Center lines between the margins (set-justification-center).

M-j u

Turn off filling entirely (set-justification-none). The fill commands do nothing on text with this setting. You can, however, still indent the left margin.

You can also specify justification styles using the Justification submenu in the Text Properties menu. The default justification style is specified by the per-buffer variable default-justification. Its value should be one of the symbols left, right, full, center, or none; their meanings correspond to the commands above.

25.14.7 Setting Other Text Properties

The Special Properties submenu of Text Properties has entries for adding or removing four other text properties: read-only, (which disallows alteration of the text), invisible (which hides text), intangible (which disallows moving point within the text), and charset (which is important for selecting a proper font to display a character). The ‘Remove Special’ menu item removes all of these special properties from the text in the region.

The invisible and intangible properties are not saved.

Enriched mode also supports saving and restoring display properties (see Display Property in the Emacs Lisp Reference Manual), which affect how text is displayed on the screen, and also allow displaying images and strings that come from sources other than buffer text. The display properties also support execution of arbitrary Lisp forms as part of processing the property for display, thus providing a means to dynamically tailor the display to some conditions that can only be known at display time. Since execution of arbitrary Lisp opens Emacs to potential attacks, especially when the source of enriched text is outside of Emacs or even outside of your system (e.g., if it was received in an email message), such execution is by default disabled in Enriched mode. You can enable it by customizing the variable enriched-allow-eval-in-display-props to a non-nil value.

Next: , Previous: , Up: Text   [Contents][Index]

25.15 Editing Text-based Tables

The table package provides commands to easily edit text-based tables. Here is an example of what such a table looks like:

+-----------------+--------------------------------+-----------------+
|     Command     |          Description           |   Key Binding   |
+-----------------+--------------------------------+-----------------+
|  forward-char   |Move point right N characters   |       C-f       |
|                 |(left if N is negative).        |                 |
|                 |                                |                 |
+-----------------+--------------------------------+-----------------+
|  backward-char  |Move point left N characters    |       C-b       |
|                 |(right if N is negative).       |                 |
|                 |                                |                 |
+-----------------+--------------------------------+-----------------+

When Emacs recognizes such a stretch of text as a table (see Table Recognition), editing the contents of each table cell will automatically resize the table, whenever the contents become too large to fit in the cell. You can use the commands defined in the following sections for navigating and editing the table layout.

Type M-x table-fixed-width-mode to toggle the automatic table resizing feature.

25.15.1 What is a Text-based Table?

A table consists of a rectangular text area which is divided into cells. Each cell must be at least one character wide and one character high, not counting its border lines. A cell can be subdivided into more cells, but they cannot overlap.

Cell border lines are drawn with three special characters, specified by the following variables:

table-cell-vertical-char

The character used for vertical lines. The default is ‘|’.

table-cell-horizontal-chars

The characters used for horizontal lines. The default is ‘"-="’.

table-cell-intersection-char

The character used for the intersection of horizontal and vertical lines. The default is ‘+’.

The following are examples of invalid tables:

   +-----+       +--+    +-++--+
   |     |       |  |    | ||  |
   |     |       |  |    | ||  |
   +--+  |    +--+--+    +-++--+
   |  |  |    |  |  |    +-++--+
   |  |  |    |  |  |    | ||  |
   +--+--+    +--+--+    +-++--+
      a          b          c

From left to right:

  1. Overlapped cells or non-rectangular cells are not allowed.
  2. The border must be rectangular.
  3. Cells must have a minimum width/height of one character.

25.15.2 Creating a Table

To create a text-based table from scratch, type M-x table-insert. This command prompts for the number of table columns, the number of table rows, cell width and cell height. The cell width and cell height do not include the cell borders; each can be specified as a single integer (which means each cell is given the same width/height), or as a sequence of integers separated by spaces or commas (which specify the width/height of the individual table columns/rows, counting from left to right for table columns and from top to bottom for table rows). The specified table is then inserted at point.

The table inserted by M-x table-insert contains special text properties, which tell Emacs to treat it specially as a text-based table. If you save the buffer to a file and visit it again later, those properties are lost, and the table appears to Emacs as an ordinary piece of text. See the next section, for how to convert it back into a table.

25.15.3 Table Recognition

Existing text-based tables in a buffer, which lack the special text properties applied by M-x table-insert, are not treated specially as tables. To apply those text properties, type M-x table-recognize. This command scans the current buffer, recognizes valid table cells, and applies the relevant text properties. Conversely, type M-x table-unrecognize to unrecognize all tables in the current buffer, removing the special text properties and converting tables back to plain text.

You can also use the following commands to selectively recognize or unrecognize tables:

M-x table-recognize-region

Recognize tables within the current region.

M-x table-unrecognize-region

Unrecognize tables within the current region.

M-x table-recognize-table

Recognize the table at point and activate it.

M-x table-unrecognize-table

Deactivate the table at point.

M-x table-recognize-cell

Recognize the cell at point and activate it.

M-x table-unrecognize-cell

Deactivate the cell at point.

See Table Conversion, for another way to recognize a table.

25.15.4 Commands for Table Cells

The commands M-x table-forward-cell and M-x table-backward-cell move point from the current cell to an adjacent cell. The order is cyclic: when point is in the last cell of a table, M-x table-forward-cell moves to the first cell. Likewise, when point is on the first cell, M-x table-backward-cell moves to the last cell.

M-x table-span-cell prompts for a direction—right, left, above, or below—and merges the current cell with the adjacent cell in that direction. This command signals an error if the merge would result in an illegitimate cell layout.

M-x table-split-cell splits the current cell vertically or horizontally, prompting for the direction with the minibuffer. To split in a specific direction, use M-x table-split-cell-vertically and M-x table-split-cell-horizontally. When splitting vertically, the old cell contents are automatically split between the two new cells. When splitting horizontally, you are prompted for how to divide the cell contents, if the cell is non-empty; the options are ‘split’ (divide the contents at point), ‘left’ (put all the contents in the left cell), and ‘right’ (put all the contents in the right cell).

The following commands enlarge or shrink a cell. By default, they resize by one row or column; if a numeric argument is supplied, that specifies the number of rows or columns to resize by.

M-x table-heighten-cell

Enlarge the current cell vertically.

M-x table-shorten-cell

Shrink the current cell vertically.

M-x table-widen-cell

Enlarge the current cell horizontally.

M-x table-narrow-cell

Shrink the current cell horizontally.

25.15.5 Cell Justification

The command M-x table-justify imposes justification on one or more cells in a text-based table. Justification determines how the text in the cell is aligned, relative to the edges of the cell. Each cell in a table can be separately justified.

M-x table-justify first prompts for what to justify; the options are ‘cell’ (just the current cell), ‘column’ (all cells in the current table column) and ‘row’ (all cells in the current table row). The command then prompts for the justification style; the options are left, center, right, top, middle, bottom, or none (meaning no vertical justification).

Horizontal and vertical justification styles are specified independently, and both types can be in effect simultaneously; for instance, you can call M-x table-justify twice, once to specify right justification and once to specify bottom justification, to align the contents of a cell to the bottom right.

The justification style is stored in the buffer as a text property, and is lost when you kill the buffer or exit Emacs. However, the table recognition commands, such as M-x table-recognize (see Table Recognition), attempt to determine and re-apply each cell’s justification style, by examining its contents. To disable this feature, change the variable table-detect-cell-alignment to nil.

25.15.6 Table Rows and Columns

M-x table-insert-row inserts a row of cells before the current table row. The current row, together with point, is pushed down past the new row. To insert a row after the last row at the bottom of a table, invoke this command with point below the table, just below the bottom edge. You can insert more than one row at a time by using a numeric prefix argument.

Similarly, M-x table-insert-column inserts a column of cells to the left of the current table column. To insert a column to the right side of the rightmost column, invoke this command with point to the right of the rightmost column, outside the table. A numeric prefix argument specifies the number of columns to insert.

M-x table-delete-column deletes the column of cells at point. Similarly, M-x table-delete-row deletes the row of cells at point. A numeric prefix argument to either command specifies the number of columns or rows to delete.

25.15.7 Converting Between Plain Text and Tables

The command M-x table-capture captures plain text in a region and turns it into a table. Unlike M-x table-recognize (see Table Recognition), the original text does not need to have a table appearance; it only needs to have a logical table-like structure.

For example, suppose we have the following numbers, which are divided into three lines and separated horizontally by commas:

1, 2, 3, 4
5, 6, 7, 8
, 9, 10

Invoking M-x table-capture on that text produces this table:

+-----+-----+-----+-----+
|1    |2    |3    |4    |
+-----+-----+-----+-----+
|5    |6    |7    |8    |
+-----+-----+-----+-----+
|     |9    |10   |     |
+-----+-----+-----+-----+

M-x table-release does the opposite: it converts a table back to plain text, removing its cell borders.

One application of this pair of commands is to edit a text in layout. Look at the following three paragraphs:

table-capture is a powerful command.
Here are some things it can do:

Parse Cell Items   Using row and column delimiter regexps,
                   it parses the specified text area and
                   extracts cell items into a table.

Applying table-capture to a region containing the above text, with empty strings for the column and row delimiter regexps, creates a table with a single cell like the following one.

+----------------------------------------------------------+
|table-capture is a powerful command.                      |
|Here are some things it can do:                           |
|                                                          |
|Parse Cell Items   Using row and column delimiter regexps,|
|                   it parses the specified text area and  |
|                   extracts cell items into a table.      |
+----------------------------------------------------------+

We can then use the cell splitting commands (see Cell Commands) to subdivide the table so that each paragraph occupies a cell:

+----------------------------------------------------------+
|table-capture is a powerful command.                      |
|Here are some things it can do:                           |
+-----------------+----------------------------------------+
|Parse Cell Items | Using row and column delimiter regexps,|
|                 | it parses the specified text area and  |
|                 | extracts cell items into a table.      |
+-----------------+----------------------------------------+

Each cell can now be edited independently without affecting the layout of other cells. When finished, we can invoke M-x table-release to convert the table back to plain text.

25.15.8 Table Miscellany

The command table-query-dimension reports the layout of the table and table cell at point. Here is an example of its output:

Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5

This indicates that the current cell is 21 characters wide and 6 lines high, the table is 67 characters wide and 16 lines high with 2 columns and 3 rows, and a total of 5 cells.

M-x table-insert-sequence traverses the cells of a table inserting a sequence of text strings into each cell as it goes. It asks for the base string of the sequence, and then produces the sequence by “incrementing” the base string, either numerically (if the base string ends in numerical characters) or in the ASCII order. In addition to the base string, the command prompts for the number of elements in the sequence, the increment, the cell interval, and the justification of the text in each cell.

M-x table-generate-source generates a table formatted for a specific markup language. It asks for a language (which must be one of html, latex, cals, wiki or mediawiki), a destination buffer in which to put the result, and a table caption, and then inserts the generated table into the specified buffer. The default destination buffer is table.lang, where lang is the language you specified.

Previous: , Up: Text   [Contents][Index]

25.16 Two-Column Editing

Two-column mode lets you conveniently edit two side-by-side columns of text. It uses two side-by-side windows, each showing its own buffer. There are three ways to enter two-column mode:

F2 2 or C-x 6 2

Enter two-column mode with the current buffer on the left, and on the right, a buffer whose name is based on the current buffer’s name (2C-two-columns). If the right-hand buffer doesn’t already exist, it starts out empty; the current buffer’s contents are not changed.

This command is appropriate when the current buffer is empty or contains just one column and you want to add another column.

F2 s or C-x 6 s

Split the current buffer, which contains two-column text, into two buffers, and display them side by side (2C-split). The current buffer becomes the left-hand buffer, but the text in the right-hand column is moved into the right-hand buffer. The current column specifies the split point. Splitting starts with the current line and continues to the end of the buffer.

This command is appropriate when you have a buffer that already contains two-column text, and you wish to separate the columns temporarily.

F2 b buffer RET
C-x 6 b buffer RET

Enter two-column mode using the current buffer as the left-hand buffer, and using buffer buffer as the right-hand buffer (2C-associate-buffer).

F2 s or C-x 6 s looks for a column separator, which is a string that appears on each line between the two columns. You can specify the width of the separator with a numeric argument to F2 s; that many characters, before point, constitute the separator string. By default, the width is 1, so the column separator is the character before point.

When a line has the separator at the proper place, F2 s puts the text after the separator into the right-hand buffer, and deletes the separator. Lines that don’t have the column separator at the proper place remain unsplit; they stay in the left-hand buffer, and the right-hand buffer gets an empty line to correspond. (This is the way to write a line that spans both columns while in two-column mode: write it in the left-hand buffer, and put an empty line in the right-hand buffer.)

The command F2 RET or C-x 6 RET (2C-newline) inserts a newline in each of the two buffers at corresponding positions. This is the easiest way to add a new line to the two-column text while editing it in split buffers.

When you have edited both buffers as you wish, merge them with F2 1 or C-x 6 1 (2C-merge). This copies the text from the right-hand buffer as a second column in the other buffer. To go back to two-column editing, use F2 s.

Use F2 d or C-x 6 d to dissociate the two buffers, leaving each as it stands (2C-dissociate). If the other buffer, the one not current when you type F2 d, is empty, F2 d kills it.


Next: , Previous: , Up: Top   [Contents][Index]

26 Editing Programs

This chapter describes Emacs features for facilitating editing programs. Some of the things these features can do are:

Next: , Up: Programs   [Contents][Index]

26.1 Major Modes for Programming Languages

Emacs has specialized major modes (see Major Modes) for many programming languages. A programming language mode typically specifies the syntax of expressions, the customary rules for indentation, how to do syntax highlighting for the language, and how to find the beginning or end of a function definition. It often has features for compiling and debugging programs as well. The major mode for each language is named after the language; for instance, the major mode for the C programming language is c-mode.

Emacs has programming language modes for Lisp, Scheme, the Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles, Metafont (TeX’s companion for font creation), Modula2, Object Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL. An alternative mode for Perl is called CPerl mode. Modes are also available for the scripting languages of the common GNU and Unix shells, and MS-DOS/MS-Windows ‘BAT’ files, and for makefiles, DNS master files, and various sorts of configuration files.

Ideally, Emacs should have a major mode for each programming language that you might want to edit. If it doesn’t have a mode for your favorite language, the mode might be implemented in a package not distributed with Emacs (see Packages); or you can contribute one.

In most programming languages, indentation should vary from line to line to illustrate the structure of the program. Therefore, in most programming language modes, typing TAB updates the indentation of the current line (see Program Indent). Furthermore, DEL is usually bound to backward-delete-char-untabify, which deletes backward treating each tab as if it were the equivalent number of spaces, so that you can delete one column of indentation without worrying whether the whitespace consists of spaces or tabs.

Entering a programming language mode runs the custom Lisp functions specified in the hook variable prog-mode-hook, followed by those specified in the mode’s own mode hook (see Major Modes). For instance, entering C mode runs the hooks prog-mode-hook and c-mode-hook. See Hooks, for information about hooks.

Separate manuals are available for the modes for Ada (see Ada Mode in Ada Mode), C/C++/Objective C/Java/Corba IDL/Pike/AWK (see CC Mode in CC Mode), Octave, VHDL, and IDLWAVE (see IDLWAVE in IDLWAVE User Manual).

Next: , Previous: , Up: Programs   [Contents][Index]

26.2 Top-Level Definitions, or Defuns

In Emacs, a major definition at the top level in the buffer, such as a function, is called a defun. The name comes from Lisp, but in Emacs we use it for all languages.

26.2.1 Left Margin Convention

Many programming-language modes have traditionally assumed that any opening parenthesis or brace found at the left margin is the start of a top-level definition, or defun. So, by default, commands which seek the beginning of a defun accept such a delimiter as signifying that position.

If you want to override this convention, you can do so by setting the user option open-paren-in-column-0-is-defun-start to nil. If this option is set to t (the default), commands seeking the start of a defun will stop at opening parentheses or braces at column zero which aren’t in a comment or string. When it is nil, defuns are found by searching for parens or braces at the outermost level. Since low-level Emacs routines no longer depend on this convention, you usually won’t need to change open-paren-in-column-0-is-defun-start from its default.

Next: , Previous: , Up: Defuns   [Contents][Index]

26.2.2 Moving by Defuns

These commands move point or set up the region based on top-level major definitions, also called defuns.

C-M-a

Move to beginning of current or preceding defun (beginning-of-defun).

C-M-e

Move to end of current or following defun (end-of-defun).

C-M-h

Put region around whole current or following defun (mark-defun).

The commands to move to the beginning and end of the current defun are C-M-a (beginning-of-defun) and C-M-e (end-of-defun). If you repeat one of these commands, or use a positive numeric argument, each repetition moves to the next defun in the direction of motion.

C-M-a with a negative argument -n moves forward n times to the next beginning of a defun. This is not exactly the same place that C-M-e with argument n would move to; the end of this defun is not usually exactly the same place as the beginning of the following defun. (Whitespace, comments, and perhaps declarations can separate them.) Likewise, C-M-e with a negative argument moves back to an end of a defun, which is not quite the same as C-M-a with a positive argument.

To operate on the current defun, use C-M-h (mark-defun), which sets the mark at the end of the current defun and puts point at its beginning. See Marking Objects. This is the easiest way to get ready to kill the defun in order to move it to a different place in the file. If the defun is directly preceded by comments (with no intervening blank lines), they are marked, too. If you use the command while point is between defuns, it uses the following defun. If you use the command while the mark is already active, it extends the end of the region to include one more defun. With a prefix argument, it marks that many defuns or extends the region by the appropriate number of defuns. With negative prefix argument it marks defuns in the opposite direction and also changes the direction of selecting for subsequent uses of mark-defun.

In C mode, C-M-h runs the function c-mark-function, which is almost the same as mark-defun; the difference is that it backs up over the argument declarations, function name and returned data type so that the entire C function is inside the region. This is an example of how major modes adjust the standard key bindings so that they do their standard jobs in a way better fitting a particular language. Other major modes may replace any or all of these key bindings for that purpose.

Next: , Previous: , Up: Defuns   [Contents][Index]

26.2.3 Imenu

The Imenu facility offers a way to find the major definitions in a file by name. It is also useful in text formatter major modes, where it treats each chapter, section, etc., as a definition. (See Xref, for a more powerful feature that handles multiple files together.)

If you type M-x imenu, it reads the name of a definition using the minibuffer, then moves point to that definition. You can use completion to specify the name; the command always displays the whole list of valid names.

Alternatively, you can bind the command imenu to a mouse click. Then it displays mouse menus for you to select a definition name. You can also add the buffer’s index to the menu bar by calling imenu-add-menubar-index. If you want to have this menu bar item available for all buffers in a certain major mode, you can do this by adding imenu-add-menubar-index to its mode hook. But if you have done that, you will have to wait a little while each time you visit a file in that mode, while Emacs finds all the definitions in that buffer.

When you change the contents of a buffer, if you add or delete definitions, you can update the buffer’s index based on the new contents by invoking the ‘*Rescan*’ item in the menu. Rescanning happens automatically if you set imenu-auto-rescan to a non-nil value. There is no need to rescan because of small changes in the text.

imenu-auto-rescan will be disabled in buffers that are larger than imenu-auto-rescan-maxout in bytes.

You can customize the way the menus are sorted by setting the variable imenu-sort-function. By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol imenu--sort-by-name as the value. You can also define your own comparison function by writing Lisp code.

Imenu provides the information to guide Which Function mode (see Which Function). The Speedbar can also use it (see Speedbar).

Previous: , Up: Defuns   [Contents][Index]

26.2.4 Which Function Mode

Which Function mode is a global minor mode (see Minor Modes) which displays the current function name in the mode line, updating it as you move around in a buffer.

To either enable or disable Which Function mode, use the command M-x which-function-mode. Which Function mode is a global minor mode. By default, it takes effect in all major modes that know how to support it (i.e., all the major modes that support Imenu). You can restrict it to a specific list of major modes by changing the value of the variable which-func-modes from t (which means to support all available major modes) to a list of major mode names.

Next: , Previous: , Up: Programs   [Contents][Index]

26.3 Indentation for Programs

The best way to keep a program properly indented is to use Emacs to reindent it as you change it. Emacs has commands to indent either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping.

See Indentation, for general information about indentation. This section describes indentation features specific to programming language modes.

Emacs also provides a Lisp pretty-printer in the pp package, which reformats Lisp objects with nice-looking indentation. See pp in The Emacs Lisp Reference Manual.

26.3.1 Basic Program Indentation Commands

TAB

Adjust indentation of current line (indent-for-tab-command).

RET

Insert a newline, then adjust indentation of following line (newline).

The basic indentation command is TAB (indent-for-tab-command), which was documented in Indentation. In programming language modes, TAB indents the current line, based on the indentation and syntactic content of the preceding lines; if the region is active, TAB indents each line within the region, not just the current line.

The command RET (newline), which was documented in Inserting Text, does the same as C-j followed by TAB: it inserts a new line, then adjusts the line’s indentation.

When indenting a line that starts within a parenthetical grouping, Emacs usually places the start of the line under the preceding line within the group, or under the text after the parenthesis. If you manually give one of these lines a nonstandard indentation (e.g., for aesthetic purposes), the lines below will follow it.

The indentation commands for most programming language modes assume that an open-parenthesis, open-brace or other opening delimiter at the left margin is the start of a function. If the code you are editing violates this assumption—even if the delimiters occur in strings or comments—you must set open-paren-in-column-0-is-defun-start to nil for indentation to work properly. See Left Margin Paren.

Next: , Previous: , Up: Program Indent   [Contents][Index]

26.3.2 Indenting Several Lines

Sometimes, you may want to reindent several lines of code at a time. One way to do this is to use the mark; when the mark is active and the region is non-empty, TAB indents every line in the region. Alternatively, the command C-M-\ (indent-region) indents every line in the region, whether or not the mark is active (see Indentation Commands).

In addition, Emacs provides the following commands for indenting large chunks of code:

C-M-q

Reindent all the lines within one parenthetical grouping.

C-u TAB

Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented.

M-x indent-code-rigidly

Shift all the lines in the region rigidly sideways, but do not alter lines that start inside comments and strings.

To reindent the contents of a single parenthetical grouping, position point before the beginning of the grouping and type C-M-q. This changes the relative indentation within the grouping, without affecting its overall indentation (i.e., the indentation of the line where the grouping starts). The function that C-M-q runs depends on the major mode; it is indent-pp-sexp in Lisp mode, c-indent-exp in C mode, etc. To correct the overall indentation as well, type TAB first.

If you like the relative indentation within a grouping but not the indentation of its first line, move point to that first line and type C-u TAB. In Lisp, C, and some other major modes, TAB with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the parenthetical grouping starting on the current line. It is clever, though, and does not alter lines that start inside strings. Neither does it alter C preprocessor lines when in C mode, but it does reindent any continuation lines that may be attached to them.

The command M-x indent-code-rigidly rigidly shifts all the lines in the region sideways, like indent-rigidly does (see Indentation Commands). It doesn’t alter the indentation of lines that start inside a string, unless the region also starts inside that string. The prefix arg specifies the number of columns to indent.

26.3.3 Customizing Lisp Indentation

The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program.

The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same.

If the variable lisp-indent-offset is non-nil, it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented lisp-indent-offset more columns than the containing list.

Certain functions override the standard pattern. Functions whose names start with def treat the second lines as the start of a body, by indenting the second line lisp-body-indent additional columns beyond the open-parenthesis that starts the expression.

You can override the standard pattern in various ways for individual functions, according to the lisp-indent-function property of the function name. This is normally done for macro definitions, using the declare construct. See Defining Macros in The Emacs Lisp Reference Manual.

26.3.4 Commands for C Indentation

Here are special features for indentation in C mode and related modes:

C-c C-q

Reindent the current top-level function definition or aggregate type declaration (c-indent-defun).

C-M-q

Reindent each line in the balanced expression that follows point (c-indent-exp). A prefix argument inhibits warning messages about invalid syntax.

TAB

Reindent the current line, and/or in some cases insert a tab character (c-indent-command).

If c-tab-always-indent is t, this command always reindents the current line and does nothing else. This is the default.

If that variable is nil, this command reindents the current line only if point is at the left margin or in the line’s indentation; otherwise, it inserts a tab (or the equivalent number of spaces, if indent-tabs-mode is nil).

Any other value (not nil or t) means always reindent the line, and also insert a tab if within a comment or a string.

To reindent the whole current buffer, type C-x h C-M-\. This first selects the whole buffer as the region, then reindents that region.

To reindent the current block, use C-M-u C-M-q. This moves to the front of the block and then reindents it all.

Previous: , Up: Program Indent   [Contents][Index]

26.3.5 Customizing C Indentation

C mode and related modes use a flexible mechanism for customizing indentation. C mode indents a source line in two steps: first it classifies the line syntactically according to its contents and context; second, it determines the indentation offset associated by your selected style with the syntactic construct and adds this onto the indentation of the anchor statement.

C-c . style RET

Select a predefined style style (c-set-style).

A style is a named collection of customizations that can be used in C mode and the related modes. Styles in The CC Mode Manual, for a complete description. Emacs comes with several predefined styles, including gnu, k&r, bsd, stroustrup, linux, python, java, whitesmith, ellemtel, and awk. Some of these styles are primarily intended for one language, but any of them can be used with any of the languages supported by these modes. To find out what a style looks like, select it and reindent some code, e.g., by typing C-M-q at the start of a function definition.

To choose a style for the current buffer, use the command C-c .. Specify a style name as an argument (case is not significant). This command affects the current buffer only, and it affects only future invocations of the indentation commands; it does not reindent the code already in the buffer. To reindent the whole buffer in the new style, you can type C-x h C-M-\.

You can also set the variable c-default-style to specify the default style for various major modes. Its value should be either the style’s name (a string) or an alist, in which each element specifies one major mode and which indentation style to use for it. 例如,

(setq c-default-style
      '((java-mode . "java")
        (awk-mode . "awk")
        (other . "gnu")))

specifies explicit choices for Java and AWK modes, and the default ‘gnu’ style for the other C-like modes. (These settings are actually the defaults.) This variable takes effect when you select one of the C-like major modes; thus, if you specify a new default style for Java mode, you can make it take effect in an existing Java mode buffer by typing M-x java-mode there.

The gnu style specifies the formatting recommended by the GNU Project for C; it is the default, so as to encourage use of our recommended style.

See Indentation Engine Basics in the CC Mode Manual, and Customizing Indentation in the CC Mode Manual, for more information on customizing indentation for C and related modes, including how to override parts of an existing style and how to define your own styles.

As an alternative to specifying a style, you can tell Emacs to guess a style by typing M-x c-guess in a sample code buffer. You can then apply the guessed style to other buffers with M-x c-guess-install. See Guessing the Style in the CC Mode Manual, for details.

Next: , Previous: , Up: Programs   [Contents][Index]

26.4 Commands for Editing with Parentheses

This section describes the commands and features that take advantage of the parenthesis structure in a program, or help you keep it balanced.

When talking about these facilities, the term “parenthesis” also includes braces, brackets, or whatever delimiters are defined to match in pairs. The major mode controls which delimiters are significant, through the syntax table (see Syntax Tables in The Emacs Lisp Reference Manual). In Lisp, only parentheses count; in C, these commands apply to braces and brackets too.

You can use M-x check-parens to find any unbalanced parentheses and unbalanced string quotes in the buffer.

26.4.1 Expressions with Balanced Parentheses

Each programming language mode has its own definition of a balanced expression. Balanced expressions typically include individual symbols, numbers, and string constants, as well as pieces of code enclosed in a matching pair of delimiters. The following commands deal with balanced expressions (in Emacs, such expressions are referred to internally as sexps13).

C-M-f

Move forward over a balanced expression (forward-sexp).

C-M-b

Move backward over a balanced expression (backward-sexp).

C-M-k

Kill balanced expression forward (kill-sexp).

C-M-t

Transpose expressions (transpose-sexps).

C-M-@
C-M-SPC

Put mark after following expression (mark-sexp).

To move forward over a balanced expression, use C-M-f (forward-sexp). If the first significant character after point is an opening delimiter (e.g., ‘(’, ‘[’ or ‘{’ in C), this command moves past the matching closing delimiter. If the character begins a symbol, string, or number, the command moves over that.

The command C-M-b (backward-sexp) moves backward over a balanced expression—like C-M-f, but in the reverse direction. If the expression is preceded by any prefix characters (single-quote, backquote and comma, in Lisp), the command moves back over them as well.

C-M-f or C-M-b with an argument repeats that operation the specified number of times; with a negative argument means to move in the opposite direction. In most modes, these two commands move across comments as if they were whitespace. Note that their keys, C-M-f and C-M-b, are analogous to C-f and C-b, which move by characters (see Moving Point), and M-f and M-b, which move by words (see Words).

To kill a whole balanced expression, type C-M-k (kill-sexp). This kills the text that C-M-f would move over.

C-M-t (transpose-sexps) switches the positions of the previous balanced expression and the next one. It is analogous to the C-t command, which transposes characters (see Transpose). An argument to C-M-t serves as a repeat count, moving the previous expression over that many following ones. A negative argument moves the previous balanced expression backwards across those before it. An argument of zero, rather than doing nothing, transposes the balanced expressions ending at or after point and the mark.

To operate on balanced expressions with a command which acts on the region, type C-M-SPC (mark-sexp). This sets the mark where C-M-f would move to. While the mark is active, each successive call to this command extends the region by shifting the mark by one expression. Positive or negative numeric arguments move the mark forward or backward by the specified number of expressions. The alias C-M-@ is equivalent to C-M-SPC. See Marking Objects, for more information about this and related commands.

In languages that use infix operators, such as C, it is not possible to recognize all balanced expressions because there can be multiple possibilities at a given position. For example, C mode does not treat ‘foo + bar’ as a single expression, even though it is one C expression; instead, it recognizes ‘foo’ as one expression and ‘bar’ as another, with the ‘+’ as punctuation between them. However, C mode recognizes ‘(foo + bar)’ as a single expression, because of the parentheses.

Next: , Previous: , Up: Parentheses   [Contents][Index]

26.4.2 Moving in the Parenthesis Structure

The following commands move over groupings delimited by parentheses (or whatever else serves as delimiters in the language you are working with). They ignore strings and comments, including any parentheses within them, and also ignore parentheses that are quoted with an escape character. These commands are mainly intended for editing programs, but can be useful for editing any text containing parentheses. They are referred to internally as “list commands” because in Lisp these groupings are lists.

These commands assume that the starting point is not inside a string or a comment. If you invoke them from inside a string or comment, the results are unreliable.

C-M-n

Move forward over a parenthetical group (forward-list).

C-M-p

Move backward over a parenthetical group (backward-list).

C-M-u

Move up in parenthesis structure (backward-up-list).

C-M-d

Move down in parenthesis structure (down-list).

The list commands C-M-n (forward-list) and C-M-p (backward-list) move forward or backward over one (or n) parenthetical groupings.

C-M-n and C-M-p try to stay at the same level in the parenthesis structure. To move up one (or n) levels, use C-M-u (backward-up-list). C-M-u moves backward up past one unmatched opening delimiter. A positive argument serves as a repeat count; a negative argument reverses the direction of motion, so that the command moves forward and up one or more levels.

To move down in the parenthesis structure, use C-M-d (down-list). In Lisp mode, where ‘(’ is the only opening delimiter, this is nearly the same as searching for a ‘(’. An argument specifies the number of levels to go down.

26.4.3 Matching Parentheses

Emacs has a number of parenthesis matching features, which make it easy to see how and whether parentheses (or other delimiters) match up.

Whenever you type a self-inserting character that is a closing delimiter, Emacs briefly indicates the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, Emacs displays some of the text near it in the echo area. Either way, you can tell which grouping you are closing off. If the opening delimiter and closing delimiter are mismatched—such as in ‘[x)’—a warning message is displayed in the echo area.

Three variables control the display of matching parentheses:

Show Paren mode, a global minor mode, provides a more powerful kind of automatic matching. Whenever point is before an opening delimiter or after a closing delimiter, the delimiter, its matching delimiter, and optionally the text between them are highlighted. To toggle Show Paren mode, type M-x show-paren-mode. To customize it, type M-x customize-group RET paren-showing. The customizable options which control the operation of this mode include:

Electric Pair mode, a global minor mode, provides a way to easily insert matching delimiters: parentheses, braces, brackets, etc. Whenever you insert an opening delimiter, the matching closing delimiter is automatically inserted as well, leaving point between the two. Conversely, when you insert a closing delimiter over an existing one, no insertion takes places, and that position is simply skipped over. If the region is active (see Mark), insertion of a delimiter operates on the region: the characters in the region are enclosed in a pair of matching delimiters, leaving point after the delimiter you typed.

These variables control additional features of Electric Pair mode:

To toggle Electric Pair mode, type M-x electric-pair-mode. To toggle the mode in a single buffer, use M-x electric-pair-local-mode.

Next: , Previous: , Up: Programs   [Contents][Index]

26.5 Manipulating Comments

Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments. It can also do spell checking on comments with Flyspell Prog mode (see Spelling).

Some major modes have special rules for indenting different kinds of comments. For example, in Lisp code, comments starting with two semicolons are indented as if they were lines of code, while those starting with three semicolons are supposed to be aligned to the left margin and are often used for sectioning purposes. Emacs understands these conventions; for instance, typing TAB on a comment line will indent the comment to the appropriate position.

;; This function is just an example.
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;;  And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.

26.5.1 Comment Commands

The following commands operate on comments:

M-;

Insert or realign comment on current line; if the region is active, comment or uncomment the region instead (comment-dwim).

C-x C-;

Comment or uncomment the current line (comment-line). If the region is active, comment or uncomment the lines in the region instead.

C-u M-;

Kill comment on current line (comment-kill).

C-x ;

Set comment column (comment-set-column).

C-M-j
M-j

Like RET followed by inserting and aligning a comment (comment-indent-new-line). See Multi-Line Comments.

M-x comment-region
C-c C-c (in C-like modes)

Add comment delimiters to all the lines in the region.

The command to create or align a comment is M-; (comment-dwim). The word “dwim” is an acronym for “Do What I Mean”; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it.

When a region is active (see Mark), M-; either adds comment delimiters to the region, or removes them. If every line in the region is already a comment, it uncomments each of those lines by removing their comment delimiters. Otherwise, it adds comment delimiters to enclose the text in the region.

If you supply a prefix argument to M-; when a region is active, that specifies the number of comment delimiters to add or delete. A positive argument n adds n delimiters, while a negative argument -n removes n delimiters.

If the region is not active, and there is no existing comment on the current line, M-; adds a new comment to the current line. If the line is blank (i.e., empty or containing only whitespace characters), the comment is indented to the same position where TAB would indent to (see Basic Indent). If the line is non-blank, the comment is placed after the last non-whitespace character on the line. Emacs tries to fit the comment between the columns specified by the variables comment-column and comment-fill-column (see Options for Comments), if possible. Otherwise, it will choose some other suitable position, usually separated from the non-comment text by at least one space. In each case, Emacs places point after the comment’s starting delimiter, so that you can start typing the comment text right away.

You can also use M-; to align an existing comment. If a line already contains the comment-start string, M-; realigns it to the conventional alignment and moves point after the comment’s starting delimiter. As an exception, comments starting in column 0 are not moved. Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment text.

C-x C-; (comment-line) comments or uncomments complete lines. When a region is active (see Mark), C-x C-; either comments or uncomments the lines in the region. If the region is not active, this command comments or uncomments the line point is on. With a positive prefix argument n, it operates on n lines starting with the current one; with a negative argument -n, it affects n preceding lines. After invoking this command with a negative argument, successive invocations with a positive argument will operate on preceding lines as if the argument were negated.

C-u M-; (comment-dwim with a prefix argument) kills any comment on the current line, along with the whitespace before it. Since the comment is saved to the kill ring, you can reinsert it on another line by moving to the end of that line, doing C-y, and then M-; to realign the comment. You can achieve the same effect as C-u M-; by typing M-x comment-kill (comment-dwim actually calls comment-kill as a subroutine when it is given a prefix argument).

The command M-x comment-region is equivalent to calling M-; on an active region, except that it always acts on the region, even if the mark is inactive. In C mode and related modes, this command is bound to C-c C-c. The command M-x uncomment-region uncomments each line in the region; a numeric prefix argument specifies the number of comment delimiters to remove (negative arguments specify the number of comment delimiters to add).

For C-like modes, you can configure the exact effect of M-; by setting the variables c-indent-comment-alist and c-indent-comments-syntactically-p. For example, on a line ending in a closing brace, M-; puts the comment one space after the brace rather than at comment-column. For full details see Comment Commands in The CC Mode Manual.

26.5.2 Multiple Lines of Comments

If you are typing a comment and wish to continue it to another line, type M-j or C-M-j (comment-indent-new-line). This breaks the current line, and inserts the necessary comment delimiters and indentation to continue the comment.

For languages with closing comment delimiters (e.g., ‘*/’ in C), the exact behavior of M-j depends on the value of the variable comment-multi-line. If the value is nil, the command closes the comment on the old line and starts a new comment on the new line. Otherwise, it opens a new line within the current comment delimiters.

When Auto Fill mode is on, going past the fill column while typing a comment also continues the comment, in the same way as an explicit invocation of M-j.

To turn existing lines into comment lines, use M-; with the region active, or use M-x comment-region as described in the preceding section.

You can configure C Mode such that when you type a ‘/’ at the start of a line in a multi-line block comment, this closes the comment. Enable the comment-close-slash clean-up for this. See Clean-ups in The CC Mode Manual.

26.5.3 Options Controlling Comments

As mentioned in Comment Commands, when the M-j command adds a comment to a line, it tries to place the comment between the columns specified by the buffer-local variables comment-column and comment-fill-column (or if that is nil, then the value of fill-column, see Fill Commands). You can set either the local value or the default value of these buffer-local variables in the usual way (see Locals). Alternatively, you can type C-x ; (comment-set-column) to set the value of comment-column in the current buffer to the column where point is currently located. C-u C-x ; sets the comment column to match the last comment before point in the buffer, and then does a M-; to align the current line’s comment under the previous one.

The comment commands recognize comments based on the regular expression that is the value of the variable comment-start-skip. Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is "\\(//+\\|/\\*+\\)\\s *", which matches extra stars and spaces after the ‘/*’ itself, and accepts C++ style comments also. (Note that ‘\\’ is needed in Lisp syntax to include a ‘\’ in the string, which is needed to deny the first star its special meaning in regexp syntax. See Regexp Backslash.)

When a comment command makes a new comment, it inserts the value of comment-start as an opening comment delimiter. It also inserts the value of comment-end after point, as a closing comment delimiter. For example, in Lisp mode, comment-start is ‘";"’ and comment-end is "" (the empty string). In C mode, comment-start is "/* " and comment-end is " */".

The variable comment-padding specifies a string that the commenting commands should insert between the comment delimiter(s) and the comment text. The default, ‘" "’, specifies a single space. Alternatively, the value can be a number, which specifies that number of spaces, or nil, which means no spaces at all.

The variable comment-multi-line controls how M-j and Auto Fill mode continue comments over multiple lines. See Multi-Line Comments.

The variable comment-indent-function should contain a function that will be called to compute the alignment for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the comment ought to start. For example, the default function bases its decision on how many comment characters begin an existing comment.

Emacs also tries to align comments on adjacent lines. To override this, the function may return a cons of two (possibly equal) integers to indicate an acceptable range of indentation.

Next: , Previous: , Up: Programs   [Contents][Index]

26.6 Documentation Lookup

Emacs provides several features you can use to look up the documentation of functions, variables and commands that you plan to use in your program.

26.6.1 Info Documentation Lookup

For major modes that apply to languages which have documentation in Info, you can use C-h S (info-lookup-symbol) to view the Info documentation for a symbol used in the program. You specify the symbol with the minibuffer; the default is the symbol appearing in the buffer at point. For example, in C mode this looks for the symbol in the C Library Manual. The command only works if the appropriate manual’s Info files are installed.

Emacs determines where to look for documentation for the symbol—which Info files to look in, and which indices to search—based on the major mode. You can also use M-x info-lookup-file to look for documentation for a file name.

If you use C-h S in a major mode that does not support it, it asks you to specify the symbol help mode. You should enter a command such as c-mode that would select a major mode which C-h S does support.

Next: , Previous: , Up: Documentation   [Contents][Index]

26.6.2 Man Page Lookup

On Unix, the main form of on-line documentation was the manual page or man page. In the GNU operating system, we aim to replace man pages with better-organized manuals that you can browse with Info (see Misc Help). This process is not finished, so it is still useful to read manual pages.

You can read the man page for an operating system command, library function, or system call, with the M-x man command. This prompts for a topic, with completion (see Completion), and runs the man program to format the corresponding man page. If the system permits, it runs man asynchronously, so that you can keep on editing while the page is being formatted. The result goes in a buffer named *Man topic*. These buffers use a special major mode, Man mode, that facilitates scrolling and jumping to other manual pages. For details, type C-h m while in a Man mode buffer.

Each man page belongs to one of ten or more sections, each named by a digit or by a digit and a letter. Sometimes there are man pages with the same name in different sections. To read a man page from a specific section, type ‘topic(section)’ or ‘section topic’ when M-x man prompts for the topic. For example, the man page for the C library function chmod is in section 2, but there is a shell command of the same name, whose man page is in section 1; to view the former, type M-x man RET chmod(2) RET.

If you do not specify a section, M-x man normally displays only the first man page found. On some systems, the man program accepts a ‘-a’ command-line option, which tells it to display all the man pages for the specified topic. To make use of this, change the value of the variable Man-switches to ‘"-a"’. Then, in the Man mode buffer, you can type M-n and M-p to switch between man pages in different sections. The mode line shows how many manual pages are available.

An alternative way of reading manual pages is the M-x woman command. Unlike M-x man, it does not run any external programs to format and display the man pages; the formatting is done by Emacs, so it works on systems such as MS-Windows where the man program may be unavailable. It prompts for a man page, and displays it in a buffer named *WoMan section topic.

M-x woman computes the completion list for manpages the first time you invoke the command. With a numeric argument, it recomputes this list; this is useful if you add or delete manual pages.

If you type a name of a manual page and M-x woman finds that several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them.

Note that M-x woman doesn’t yet support the latest features of modern man pages, so we recommend using M-x man if that is available on your system.

For more information about setting up and using M-x woman, see the WoMan Info manual, which is distributed with Emacs.

Previous: , Up: Documentation   [Contents][Index]

26.6.3 Emacs Lisp Documentation Lookup

When editing Emacs Lisp code, you can use the commands C-h f (describe-function) and C-h v (describe-variable) to view the built-in documentation for the Lisp functions and variables that you want to use. See Name Help.

ElDoc is a buffer-local minor mode that helps with looking up Lisp documentation. When it is enabled, the echo area displays some useful information whenever there is a Lisp function or variable at point; for a function, it shows the argument list, and for a variable it shows the first line of the variable’s documentation string. To toggle ElDoc mode, type M-x eldoc-mode. There’s also a Global ElDoc mode, which is turned on by default, and affects buffers, such as ‘*scratch*’, whose major mode is Emacs Lisp or Lisp Interaction (M-x global-eldoc-mode to turn it off globally).

Next: , Previous: , Up: Programs   [Contents][Index]

26.7 Hideshow minor mode

Hideshow mode is a buffer-local minor mode that allows you to selectively display portions of a program, which are referred to as blocks. Type M-x hs-minor-mode to toggle this minor mode (see Minor Modes).

When you use Hideshow mode to hide a block, the block disappears from the screen, to be replaced by an ellipsis (three periods in a row). Just what constitutes a block depends on the major mode. In C mode and related modes, blocks are delimited by braces, while in Lisp mode they are delimited by parentheses. Multi-line comments also count as blocks.

Hideshow mode provides the following commands:

C-c @ C-h
C-c @ C-d

Hide the current block (hs-hide-block).

C-c @ C-s

Show the current block (hs-show-block).

C-c @ C-c
C-c @ C-e

Either hide or show the current block (hs-toggle-hiding).

S-mouse-2

Toggle hiding for the block you click on (hs-mouse-toggle-hiding).

C-c @ C-M-h
C-c @ C-t

Hide all top-level blocks (hs-hide-all).

C-c @ C-M-s
C-c @ C-a

Show all blocks in the buffer (hs-show-all).

C-u n C-c @ C-l

Hide all blocks n levels below this block (hs-hide-level).

These variables can be used to customize Hideshow mode:

hs-hide-comments-when-hiding-all

If non-nil, C-c @ C-M-h (hs-hide-all) hides comments too.

hs-isearch-open

This variable specifies the conditions under which incremental search should unhide a hidden block when matching text occurs within the block. Its value should be either code (unhide only code blocks), comment (unhide only comments), t (unhide both code blocks and comments), or nil (unhide neither code blocks nor comments). The default value is code.

Next: , Previous: , Up: Programs   [Contents][Index]

26.8 Completion for Symbol Names

Completion is normally done in the minibuffer (see Completion), but you can also complete symbol names in ordinary Emacs buffers.

In programming language modes, type C-M-i or M-TAB to complete the partial symbol before point. On graphical displays, the M-TAB key is usually reserved by the window manager for switching graphical windows, so you should type C-M-i or ESC TAB instead.

In most programming language modes, C-M-i (or M-TAB) invokes the command completion-at-point, which generates its completion list in a flexible way. If Semantic mode is enabled, it tries to use the Semantic parser data for completion (see Semantic). If Semantic mode is not enabled or fails at performing completion, it tries to complete using the selected tags table (see Tags Tables). If in Emacs Lisp mode, it performs completion using the function, variable, or property names defined in the current Emacs session.

In all other respects, in-buffer symbol completion behaves like minibuffer completion. For instance, if Emacs cannot complete to a unique symbol, it displays a list of completion alternatives in another window. See Completion.

In Text mode and related modes, M-TAB completes words based on the spell-checker’s dictionary. See Spelling.

Next: , Previous: , Up: Programs   [Contents][Index]

26.9 MixedCase Words

Some programming styles make use of mixed-case (or “CamelCase”) symbols like ‘unReadableSymbol’. (In the GNU project, we recommend using underscores to separate words within an identifier, rather than using case distinctions.) Emacs has various features to make it easier to deal with such symbols.

Glasses mode is a buffer-local minor mode that makes it easier to read such symbols, by altering how they are displayed. By default, it displays extra underscores between each lower-case letter and the following capital letter. This does not alter the buffer text, only how it is displayed.

To toggle Glasses mode, type M-x glasses-mode (see Minor Modes). When Glasses mode is enabled, the minor mode indicator ‘o^o’ appears in the mode line. For more information about Glasses mode, type C-h P glasses RET.

Subword mode is another buffer-local minor mode. In subword mode, Emacs’s word commands recognize upper case letters in ‘StudlyCapsIdentifiers’ as word boundaries. When Subword mode is enabled, the minor mode indicator ‘,’ appears in the mode line. See also the similar superword-mode (see Misc for Programs).

26.10 Semantic

Semantic is a package that provides language-aware editing commands based on source code parsers. This section provides a brief description of Semantic; for full details, see Semantic in Semantic.

Most of the language-aware features in Emacs, such as Font Lock mode (see Font Lock), rely on rules of thumb14 that usually give good results but are never completely exact. In contrast, the parsers used by Semantic have an exact understanding of programming language syntax. This allows Semantic to provide search, navigation, and completion commands that are powerful and precise.

To begin using Semantic, type M-x semantic-mode or click on the menu item named ‘Source Code Parsers (Semantic)’ in the ‘Tools’ menu. This enables Semantic mode, a global minor mode.

When Semantic mode is enabled, Emacs automatically attempts to parse each file you visit. Currently, Semantic understands C, C++, HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo. Within each parsed buffer, the following commands are available:

C-c , j

Prompt for the name of a function defined in the current file, and move point there (semantic-complete-jump-local).

C-c , J

Prompt for the name of a function defined in any file Emacs has parsed, and move point there (semantic-complete-jump).

C-c , SPC

Display a list of possible completions for the symbol at point (semantic-complete-analyze-inline). This also activates a set of special key bindings for choosing a completion: RET accepts the current completion, M-n and M-p cycle through possible completions, TAB completes as far as possible and then cycles, and C-g or any other key aborts completion.

C-c , l

Display a list of the possible completions of the symbol at point, in another window (semantic-analyze-possible-completions).

In addition to the above commands, the Semantic package provides a variety of other ways to make use of parser information. For instance, you can use it to display a list of completions when Emacs is idle. See Semantic in Semantic, for details.

Next: , Previous: , Up: Programs   [Contents][Index]

26.11 Other Features Useful for Editing Programs

Some Emacs commands that aren’t designed specifically for editing programs are useful for that nonetheless.

The Emacs commands that operate on words, sentences and paragraphs are useful for editing code. Most symbol names contain words (see Words), while sentences can be found in strings and comments (see Sentences). As for paragraphs, they are defined in most programming language modes to begin and end at blank lines (see Paragraphs). Therefore, judicious use of blank lines to make the program clearer will also provide useful chunks of text for the paragraph commands to work on. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates.

Superword mode is a buffer-local minor mode that causes editing and motion commands to treat symbols (e.g., ‘this_is_a_symbol’) as words. When Superword mode is enabled, the minor mode indicator ‘²’ appears in the mode line. See also the similar subword-mode (see MixedCase Words).

Electric Layout mode (M-x electric-layout-mode) is a global minor mode that automatically inserts newlines when you type certain characters; for example, ‘{’, ‘}’ and ‘;’ in Javascript mode.

Apart from Hideshow mode (see Hideshow), another way to selectively display parts of a program is to use the selective display feature (see Selective Display). Programming modes often also support Outline minor mode (see Outline Mode), which can be used with the Foldout package (see Foldout).

Prettify Symbols mode is a buffer-local minor mode that replaces certain strings with more attractive versions for display purposes. For example, in Emacs Lisp mode, it replaces the string ‘lambda’ with the Greek lambda character ‘λ’. In a TeX buffer, it will replace ‘\alpha’ … ‘\omega’ and other math macros with their Unicode characters. You may wish to use this in non-programming modes as well. You can customize the mode by adding more entries to prettify-symbols-alist. More elaborate customization is available via customizing prettify-symbols-compose-predicate if its default value prettify-symbols-default-compose-p is not appropriate. There is also a global version, global-prettify-symbols-mode, which enables the mode in all buffers that support it.

The symbol at point can be shown in its original form. This is controlled by the variable prettify-symbols-unprettify-at-point: if non-nil, the original form of symbol at point will be restored for as long as point is at it.

Next: , Previous: , Up: Programs   [Contents][Index]

26.12 C and Related Modes

This section gives a brief description of the special features available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. (These are called “C mode and related modes”.) For more details, see the CC mode Info manual, which is distributed with Emacs.

Next: , Up: C Modes   [Contents][Index]

26.12.1 C Mode Motion Commands

This section describes commands for moving point, in C mode and related modes.

C-M-a
C-M-e

Move point to the beginning or end of the current function or top-level definition. In languages with enclosing scopes (such as C++’s classes) the current function is the immediate one, possibly inside a scope. Otherwise it is the one defined by the least enclosing braces. (By contrast, beginning-of-defun and end-of-defun search for braces in column zero.) See Moving by Defuns.

C-c C-u

Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional.

#elif’ is equivalent to ‘#else’ followed by ‘#if’, so the function will stop at a ‘#elif’ when going backward, but not when going forward.

C-c C-p

Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward.

C-c C-n

Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward.

M-a

Move point to the beginning of the innermost C statement (c-beginning-of-statement). If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument n, move back n - 1 statements.

In comments or in strings which span more than one line, this command moves by sentences instead of statements.

M-e

Move point to the end of the innermost C statement or sentence; like M-a except that it moves in the other direction (c-end-of-statement).

Next: , Previous: , Up: C Modes   [Contents][Index]

26.12.2 Electric C Characters

In C mode and related modes, certain printing characters are electric—in addition to inserting themselves, they also reindent the current line, and optionally also insert newlines. The electric characters are {, }, :, #, ;, ,, <, >, /, *, (, and ).

You might find electric indentation inconvenient if you are editing chaotically indented code. If you are new to CC Mode, you might find it disconcerting. You can toggle electric action with the command C-c C-l; when it is enabled, ‘/cl’ appears in the mode line after the mode name (where c, if present, is ‘*’ or ‘/’, depending on whether the comment style is block or line). See Minor Modes in The CC Mode Manual, for more about mode-line indicators in CC Mode.

C-c C-l

Toggle electric action (c-toggle-electric-state). With a positive prefix argument, this command enables electric action, with a negative one it disables it.

Electric characters insert newlines only when, in addition to the electric state, the auto-newline feature is enabled (indicated by ‘/cla’ in the mode line after the mode name). You can turn this feature on or off with the command C-c C-a:

C-c C-a

Toggle the auto-newline feature (c-toggle-auto-newline). With a prefix argument, this command turns the auto-newline feature on if the argument is positive, and off if it is negative.

Usually the CC Mode style configures the exact circumstances in which Emacs inserts auto-newlines. You can also configure this directly. See Custom Auto-newlines in The CC Mode Manual.

Next: , Previous: , Up: C Modes   [Contents][Index]

26.12.3 Hungry Delete Feature in C

If you want to delete an entire block of whitespace at point, you can use hungry deletion. This deletes all the contiguous whitespace either before point or after point in a single operation. Whitespace here includes tabs and newlines, but not comments or preprocessor commands.

C-c C-DEL
C-c DEL

Delete the entire block of whitespace preceding point (c-hungry-delete-backwards).

C-c C-d
C-c C-Delete
C-c Delete

Delete the entire block of whitespace after point (c-hungry-delete-forward).

As an alternative to the above commands, you can enable hungry delete mode. When this feature is enabled (indicated by ‘h’ after a ‘/’ in the mode line after the mode name), a single DEL deletes all preceding whitespace, not just one space, and a single C-d (but not plain Delete) deletes all following whitespace.

M-x c-toggle-hungry-state

Toggle the hungry-delete feature (c-toggle-hungry-state). With a prefix argument, this command turns the hungry-delete feature on if the argument is positive, and off if it is negative.

The variable c-hungry-delete-key controls whether the hungry-delete feature is enabled.

Previous: , Up: C Modes   [Contents][Index]

26.12.4 Other Commands for C Mode

M-x c-context-line-break

This command inserts a line break and indents the new line in a manner appropriate to the context. In normal code, it does the work of RET (newline), in a C preprocessor line it additionally inserts a ‘\’ at the line break, and within comments it’s like M-j (c-indent-new-comment-line).

c-context-line-break isn’t bound to a key by default, but it needs a binding to be useful. The following code will bind it to RET. We use c-initialization-hook here to make sure the keymap is loaded before we try to change it.

(defun my-bind-clb ()
  (define-key c-mode-base-map "\C-m"
              'c-context-line-break))
(add-hook 'c-initialization-hook 'my-bind-clb)
C-M-h

Put mark at the end of a function definition, and put point at the beginning (c-mark-function).

M-q

Fill a paragraph, handling C and C++ comments (c-fill-paragraph). If any part of the current line is a comment or within a comment, this command fills the comment or the paragraph of it that point is in, preserving the comment indentation and comment delimiters.

C-c C-e

Run the C preprocessor on the text in the region, and show the result, which includes the expansion of all the macro calls (c-macro-expand). The buffer text before the region is also included in preprocessing, for the sake of macros defined there, but the output from this part isn’t shown.

When you are debugging C code that uses macros, sometimes it is hard to figure out precisely how the macros expand. With this command, you don’t have to figure it out; you can see the expansions.

C-c C-\

Insert or align ‘\’ characters at the ends of the lines of the region (c-backslash-region). This is useful after writing or editing a C macro definition.

If a line already ends in ‘\’, this command adjusts the amount of whitespace before it. Otherwise, it inserts a new ‘\’. However, the last line in the region is treated specially; no ‘\’ is inserted on that line, and any ‘\’ there is deleted.

M-x cpp-highlight-buffer

Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named *CPP Edit*, which serves as a graphic menu for selecting how to display particular kinds of conditionals and their contents. After changing various settings, click on ‘[A]pply these settings’ (or go to that buffer and type a) to rehighlight the C mode buffer accordingly.

C-c C-s

Display the syntactic information about the current source line (c-show-syntactic-information). This information directs how the line is indented.

M-x cwarn-mode
M-x global-cwarn-mode

CWarn minor mode highlights certain suspicious C and C++ constructions:

  • Assignments inside expressions.
  • Semicolon following immediately after ‘if’, ‘for’, and ‘while’ (except after a ‘do … while’ statement);
  • C++ functions with reference parameters.

You can enable the mode for one buffer with the command M-x cwarn-mode, or for all suitable buffers with the command M-x global-cwarn-mode or by customizing the variable global-cwarn-mode. You must also enable Font Lock mode to make it work.

M-x hide-ifdef-mode

Hide-ifdef minor mode hides selected code within ‘#if’ and ‘#ifdef’ preprocessor blocks. If you change the variable hide-ifdef-shadow to t, Hide-ifdef minor mode shadows preprocessor blocks by displaying them with a less prominent face, instead of hiding them entirely. See the documentation string of hide-ifdef-mode for more information.

M-x ff-find-related-file

Find a file related in a special way to the file visited by the current buffer. Typically this will be the header file corresponding to a C/C++ source file, or vice versa. The variable ff-related-file-alist specifies how to compute related file names.

Next: , Previous: , Up: Programs   [Contents][Index]

26.13 Asm Mode

Asm mode is a major mode for editing files of assembler code. It defines these commands:

TAB

tab-to-tab-stop.

C-j

Insert a newline and then indent using tab-to-tab-stop.

:

Insert a colon and then remove the indentation from before the label preceding colon. Then do tab-to-tab-stop.

;

Insert or align a comment.

The variable asm-comment-char specifies which character starts comments in assembler syntax.

Previous: , Up: Programs   [Contents][Index]

26.14 Fortran Mode

Fortran mode is meant for editing fixed form (and also tab format) source code (normally Fortran 77). For editing more modern free-form source code (Fortran 90, 95, 2003, 2008), use F90 mode (f90-mode). Emacs normally uses Fortran mode for files with extension ‘.f’, ‘.F’ or ‘.for’, and F90 mode for the extensions ‘.f90’, ‘.f95’, ‘.f03’ and ‘.f08’. Customize auto-mode-alist to add more extensions. GNU Fortran supports both free and fixed form. This manual mainly documents Fortran mode, but the corresponding F90 mode features are mentioned when relevant.

Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran conventions of nesting, line numbers and continuation statements. Fortran mode has support for Auto Fill mode that breaks long lines into proper Fortran continuation lines. Fortran mode also supports Hideshow minor mode (see Hideshow), and Imenu (see Imenu).

Special commands for comments are provided because Fortran comments are unlike those of other languages. Built-in abbrevs optionally save typing when you insert Fortran keywords.

Use M-x fortran-mode to switch to this major mode. This command runs the hook fortran-mode-hook. See Hooks.

26.14.1 Motion Commands

In addition to the normal commands for moving by and operating on defuns (Fortran subprograms—functions and subroutines, as well as modules for F90 mode, using the commands fortran-end-of-subprogram and fortran-beginning-of-subprogram), Fortran mode provides special commands to move by statements and other program units.

C-c C-n

Move to the beginning of the next statement (fortran-next-statement/f90-next-statement).

C-c C-p

Move to the beginning of the previous statement (fortran-previous-statement/f90-previous-statement). If there is no previous statement (i.e., if called from the first statement in the buffer), move to the start of the buffer.

C-c C-e

Move point forward to the start of the next code block, or the end of the current one, whichever comes first (f90-next-block). A code block is a subroutine, ifendif statement, and so forth. This command exists for F90 mode only, not Fortran mode. With a numeric argument, it moves forward that many blocks.

C-c C-a

Move point backward to the previous block (f90-previous-block). This is like f90-next-block, but moves backwards.

C-M-n

Move to the end of the current code block (fortran-end-of-block/f90-end-of-block). With a numeric argument, move forward that number of blocks. The mark is set before moving point. The F90 mode version of this command checks for consistency of block types and labels (if present), but it does not check the outermost block since that may be incomplete.

C-M-p

Move to the start of the current code block (fortran-beginning-of-block/f90-beginning-of-block). This is like fortran-end-of-block, but moves backwards.

The commands fortran-beginning-of-subprogram and fortran-end-of-subprogram move to the start or end of the current subprogram, respectively. The commands fortran-mark-do and fortran-mark-if mark the end of the current do or if block, and move point to the start.

Next: , Previous: , Up: Fortran   [Contents][Index]

26.14.2 Fortran Indentation

Special commands and features are needed for indenting fixed (or tab) form Fortran code in order to make sure various syntactic entities (line numbers, comment line indicators and continuation line flags) appear in the required columns.

26.14.2.1 Fortran Indentation and Filling Commands

C-M-j

Break the current line at point and set up a continuation line (fortran-split-line).

M-^

Join this line to the previous line (fortran-join-line).

C-M-q

Indent all the lines of the subprogram that point is in (fortran-indent-subprogram).

M-q

Fill a comment block or statement (using fortran-fill-paragraph or fortran-fill-statement).

The key C-M-q runs fortran-indent-subprogram, a command to reindent all the lines of the Fortran subprogram (function or subroutine) containing point.

The key C-M-j runs fortran-split-line, which splits a line in the appropriate fashion for Fortran. In a non-comment line, the second half becomes a continuation line and is indented accordingly. In a comment line, both halves become separate comment lines.

M-^ or C-c C-d run the command fortran-join-line, which joins a continuation line back to the previous line, roughly as the inverse of fortran-split-line. The point must be on a continuation line when this command is invoked.

M-q in Fortran mode fills the comment block or statement that point is in. This removes any excess statement continuations.

26.14.2.2连续行

Most Fortran 77 compilers allow two ways of writing continuation lines. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this fixed form. (In GNU Emacs we always count columns from 0; but note that the Fortran standard counts from 1. You can customize the variable column-number-indicator-zero-based to make the column display Fortran-like; see Optional Mode Line.) The variable fortran-continuation-string specifies what character to put in column 5. A line that starts with a tab character followed by any digit except ‘0’ is also a continuation line. We call this style of continuation tab format. (Fortran 90 introduced free-form continuation lines.)

Fortran mode can use either style of continuation line. When you enter Fortran mode, it tries to deduce the proper continuation style automatically from the buffer contents. It does this by scanning up to fortran-analyze-depth (default 100) lines from the start of the buffer. The first line that begins with either a tab character or six spaces determines the choice. If the scan fails (for example, if the buffer is new and therefore empty), the value of fortran-tab-mode-default (nil for fixed form, and non-nil for tab format) is used. ‘/t’ (fortran-tab-mode-string) in the mode line indicates tab format is selected. Fortran mode sets the value of indent-tabs-mode accordingly.

If the text on a line starts with the Fortran continuation marker ‘$’, or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a continuation line with TAB, it converts the line to the current continuation style. When you split a Fortran statement with C-M-j, the continuation marker on the newline is created according to the continuation style.

The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed form mode, the minimum column number for the body of a statement is 6. Lines inside of Fortran blocks that are indented to larger column numbers must use only the space character for whitespace. In tab format mode, the minimum column number for the statement body is 8, and the whitespace before column 8 must consist of one tab character.

26.14.2.3 Line Numbers

If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 through 4. (Columns always count from 0 in Emacs, but setting column-number-indicator-zero-based to nil can change that, see Optional Mode Line.)

Line numbers of four digits or less are normally indented one space. The variable fortran-line-number-indent controls this; it specifies the maximum indentation a line number can have. The default value of the variable is 1. Fortran mode tries to prevent line number digits passing column 4, reducing the indentation below the specified maximum if necessary. If fortran-line-number-indent has the value 5, line numbers are right-justified to end in column 4.

Simply inserting a line number is enough to indent it according to these rules. As each digit is inserted, the indentation is recomputed. To turn off this feature, set the variable fortran-electric-line-number to nil.

26.14.2.4 Syntactic Conventions

Fortran mode assumes that you follow certain conventions that simplify the task of understanding a Fortran program well enough to indent it properly:

If you fail to follow these conventions, the indentation commands may indent some lines unaesthetically. However, a correct Fortran program retains its meaning when reindented even if the conventions are not followed.

26.14.2.5 Variables for Fortran Indentation

Several additional variables control how Fortran indentation works:

fortran-do-indent

Extra indentation within each level of ‘do’ statement (default 3).

fortran-if-indent

Extra indentation within each level of ‘if’, ‘select case’, or ‘where’ statements (default 3).

fortran-structure-indent

Extra indentation within each level of ‘structure’, ‘union’, ‘map’, or ‘interface’ statements (default 3).

fortran-continuation-indent

Extra indentation for bodies of continuation lines (default 5).

fortran-check-all-num-for-matching-do

In Fortran 77, a numbered ‘do’ statement is terminated by any statement with a matching line number. It is common (but not compulsory) to use a ‘continue’ statement for this purpose. If this variable has a non-nil value, indenting any numbered statement must check for a ‘do’ that ends there. If you always end ‘do’ statements with a ‘continue’ line (or if you use the more modern ‘enddo’), then you can speed up indentation by setting this variable to nil (the default).

fortran-blink-matching-if

If this is t, indenting an ‘endif’ (or ‘enddo’) statement moves the cursor momentarily to the matching ‘if’ (or ‘do’) statement to show where it is. The default is nil.

fortran-minimum-statement-indent-fixed

Minimum indentation for Fortran statements when using fixed form continuation line style. Statement bodies are never indented by less than this. The default is 6.

fortran-minimum-statement-indent-tab

Minimum indentation for Fortran statements for tab format continuation line style. Statement bodies are never indented by less than this. The default is 8.

The following section describes the variables controlling the indentation of comments.

Next: , Previous: , Up: Fortran   [Contents][Index]

26.14.3 Fortran Comments

The usual Emacs comment commands assume that a comment can follow a line of code. In Fortran 77, the standard comment syntax requires an entire line to be just a comment. Therefore, Fortran mode replaces the standard Emacs comment commands and defines some new variables.

Fortran mode can also handle the Fortran 90 comment syntax where comments start with ‘!’ and can follow other text. Because only some Fortran 77 compilers accept this syntax, Fortran mode will not insert such comments unless you have said in advance to do so. To do this, set the variable fortran-comment-line-start to ‘"!"’. If you use an unusual value, you may need to change fortran-comment-line-start-skip.

M-;

Align comment or insert new comment (comment-dwim).

C-x ;

Applies to nonstandard ‘!’ comments only (comment-set-column).

C-c ;

Turn all lines of the region into comments, or (with argument) turn them back into real code (fortran-comment-region).

M-; in Fortran mode runs the standard comment-dwim. This recognizes any kind of existing comment and aligns its text appropriately; if there is no existing comment, a comment is inserted and aligned. Inserting and aligning comments are not the same in Fortran mode as in other modes.

When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard ‘!’ comment is inserted if you have said you want to use them. Otherwise, a full-line comment is inserted on a new line before the current line.

Nonstandard ‘!’ comments are aligned like comments in other languages, but full-line comments are different. In a standard full-line comment, the comment delimiter itself must always appear in column zero. What can be aligned is the text within the comment. You can choose from three styles of alignment by setting the variable fortran-comment-indent-style to one of these values:

fixed

Align the text at a fixed column, which is the sum of fortran-comment-line-extra-indent and the minimum statement indentation. This is the default.

The minimum indentation is fortran-minimum-statement-indent-tab for tab format continuation line style and fortran-minimum-statement-indent-fixed for fixed form style.

relative

Align the text as if it were a line of code, but with an additional fortran-comment-line-extra-indent columns of indentation.

nil

Don’t move text in full-line comments automatically.

In addition, you can specify the character to be used to indent within full-line comments by setting the variable fortran-comment-indent-char to the single-character string you want to use.

Compiler directive lines, or preprocessor lines, have much the same appearance as comment lines. It is important, though, that such lines never be indented at all, no matter what the value of fortran-comment-indent-style. The variable fortran-directive-re is a regular expression that specifies which lines are directives. Matching lines are never indented, and receive distinctive font-locking.

The normal Emacs comment command C-x ; (comment-set-column) has not been redefined. If you use ‘!’ comments, this command can be used with them. Otherwise, it is useless in Fortran mode.

The command C-c ; (fortran-comment-region) turns all the lines of the region into comments by inserting the string ‘c$$$’ at the front of each one. With a numeric argument, it turns the region back into live code by deleting ‘c$$$’ from the front of each line in it. The string used for these comments can be controlled by setting the variable fortran-comment-region. Note that here we have an example of a command and a variable with the same name; these two uses of the name never conflict because in Lisp and in Emacs it is always clear from the context which one is meant.

Next: , Previous: , Up: Fortran   [Contents][Index]

26.14.4 Auto Fill in Fortran Mode

Fortran mode has specialized support for Auto Fill mode, which is a minor mode that automatically splits statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using fortran-continuation-string (see ForIndent Cont). This splitting happens when you type SPC, RET, or TAB, and also in the Fortran indentation commands. You activate Auto Fill in Fortran mode in the normal way. See Auto Fill.

Auto Fill breaks lines at spaces or delimiters when the lines get longer than the desired width (the value of fill-column). The delimiters (besides whitespace) that Auto Fill can break at are ‘+’, ‘-’, ‘/’, ‘*’, ‘=’, ‘<’, ‘>’, and ‘,’. The line break comes after the delimiter if the variable fortran-break-before-delimiters is nil. Otherwise (and by default), the break comes before the delimiter.

To enable Auto Fill in all Fortran buffers, add auto-fill-mode to fortran-mode-hook. See Hooks.

Next: , Previous: , Up: Fortran   [Contents][Index]

26.14.5 Checking Columns in Fortran

In standard Fortran 77, anything beyond column 72 is ignored. Most compilers provide an option to change this (for example, ‘-ffixed-line-length-N’ in gfortran). Customize the variable fortran-line-length to change the line length in Fortran mode. Anything beyond this point is font-locked as a comment. (Unless it is inside a string: strings that extend beyond fortran-line-length will confuse font-lock.)

C-c C-r

Display a column ruler momentarily above the current line (fortran-column-ruler).

C-c C-w

Split the current window horizontally temporarily so that it is fortran-line-length columns wide (fortran-window-create-momentarily). This may help you avoid making lines longer than the limit imposed by your Fortran compiler.

C-u C-c C-w

Split the current window horizontally so that it is fortran-line-length columns wide (fortran-window-create). You can then continue editing.

M-x fortran-strip-sequence-nos

Delete all text in column fortran-line-length and beyond.

The command C-c C-r (fortran-column-ruler) shows a column ruler momentarily above the current line. The comment ruler is two lines of text that show you the locations of columns with special significance in Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them.

Note that the column numbers count from zero, as always in GNU Emacs (but customizing column-number-indicator-zero-based can change column display to match that of Fortran; see Optional Mode Line.) As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran.

The text used to display the column ruler depends on the value of the variable indent-tabs-mode. If indent-tabs-mode is nil, then the value of the variable fortran-column-ruler-fixed is used as the column ruler. Otherwise, the value of the variable fortran-column-ruler-tab is displayed. By changing these variables, you can change the column ruler display.

C-c C-w (fortran-window-create-momentarily) temporarily splits the current window horizontally, making a window fortran-line-length columns wide, so you can see any lines that are too long. Type a space to restore the normal width.

You can also split the window horizontally and continue editing with the split in place. To do this, use C-u C-c C-w (M-x fortran-window-create). By editing in this window you can immediately see when you make a line too wide to be correct Fortran.

The command M-x fortran-strip-sequence-nos deletes all text in column fortran-line-length and beyond, on all lines in the current buffer. This is the easiest way to get rid of old sequence numbers.

Previous: , Up: Fortran   [Contents][Index]

26.14.6 Fortran Keyword Abbrevs

Fortran mode provides many built-in abbrevs for common keywords and declarations. These are the same sort of abbrev that you can define yourself. To use them, you must turn on Abbrev mode. See Abbrevs.

The built-in abbrevs are unusual in one way: they all start with a semicolon. For example, one built-in Fortran abbrev is ‘;c’ for ‘continue’. If you insert ‘;c’ and then insert a punctuation character such as a space or a newline, the ‘;c’ expands automatically to ‘continue’, provided Abbrev mode is enabled.

Type ‘;?’ or ‘;C-h’ to display a list of all the built-in Fortran abbrevs and what they stand for.


Next: , Previous: , Up: Top   [Contents][Index]

27 Compiling and Testing Programs

The previous chapter discusses the Emacs commands that are useful for making changes in programs. This chapter deals with commands that assist in the process of compiling and testing programs.

27.1 Running Compilations under Emacs

Emacs can run compilers for languages such as C and Fortran, feeding the compilation log into an Emacs buffer. It can also parse the error messages and show you where the errors occurred.

M-x compile

Run a compiler asynchronously under Emacs, with error messages going to the *compilation* buffer.

M-x recompile
g (Compilation mode)

Invoke a compiler with the same command as in the last invocation of M-x compile.

M-x kill-compilation

Kill the running compilation subprocess.

To run make or another compilation command, type M-x compile. This reads a shell command line using the minibuffer, and then executes the command by running a shell as a subprocess (or inferior process) of Emacs. The output is inserted in a buffer named *compilation*. The current buffer’s default directory is used as the working directory for the execution of the command, so by default compilation takes place in that directory.

The default compilation command is ‘make -k’, which is usually correct for programs compiled using the make utility (the ‘-k’ flag tells make to continue compiling as much as possible after an error). See Make in GNU Make Manual. If you have done M-x compile before, the command that you specified is automatically stored in the variable compile-command; this is used as the default the next time you type M-x compile. A file can also specify a file-local value for compile-command (see File Variables).

Starting a compilation displays the *compilation* buffer in another window but does not select it. While the compilation is running, the word ‘run’ is shown in the major mode indicator for the *compilation* buffer, and the word ‘Compiling’ appears in all mode lines. You do not have to keep the *compilation* buffer visible while compilation is running; it continues in any case. When the compilation ends, for whatever reason, the mode line of the *compilation* buffer changes to say ‘exit’ (followed by the exit code: ‘[0]’ for a normal exit), or ‘signal’ (if a signal terminated the process).

If you want to watch the compilation transcript as it appears, switch to the *compilation* buffer and move point to the end of the buffer. When point is at the end, new compilation output is inserted above point, which remains at the end. Otherwise, point remains fixed while compilation output is added at the end of the buffer.

While compilation proceeds, the mode line shows the number of errors, warnings, and informational messages emitted by the compiler so far.

If you change the variable compilation-scroll-output to a non-nil value, the *compilation* buffer scrolls automatically to follow the output. If the value is first-error, scrolling stops when the first error appears, leaving point at that error. For any other non-nil value, scrolling continues until there is no more output.

To rerun the last compilation with the same command, type M-x recompile. This reuses the compilation command from the last invocation of M-x compile. It also reuses the *compilation* buffer and starts the compilation in its default directory, which is the directory in which the previous compilation was started. In *compilation* buffers this command is bound to g.

Starting a new compilation also kills any compilation already running in *compilation*, as the buffer can only handle one compilation at any time. However, M-x compile and M-x recompile ask for confirmation before actually killing a compilation that is running; to always automatically kill the compilation without asking, change the variable compilation-always-kill to t. You can also kill a compilation process with the command M-x kill-compilation.

To run two compilations at once, start the first one, then rename the *compilation* buffer (perhaps using rename-uniquely; see Misc Buffer), then switch buffers and start the other compilation. This will create a new *compilation* buffer.

You can control the environment passed to the compilation command with the variable compilation-environment. Its value is a list of environment variable settings; each element should be a string of the form "envvarname=value". These environment variable settings override the usual ones.

Next: , Previous: , Up: Building   [Contents][Index]

27.2 Compilation Mode

The *compilation* buffer uses a major mode called Compilation mode. Compilation mode turns each error message in the buffer into a hyperlink; you can move point to it and type RET, or click on it with the mouse (see Mouse References), to visit the locus of the error message in a separate window. The locus is the specific position in a file where that error occurred.

The appearance of the *compilation* buffer can be controlled by customizing the faces which are used to highlight parts of the *compilation* buffer, e.g., compilation-error or compilation-warning, for error and warning messages respectively. Note that since those faces inherit from the error and warning faces, it is also possible to customize the parent face directly instead.

Use M-x customize-group RET compilation to see the entire list of customization variables and faces.

If you change the variable compilation-auto-jump-to-first-error to a non-nil value, Emacs automatically visits the locus of the first error message that appears in the *compilation* buffer.

Compilation mode provides the following additional commands. These commands can also be used in *grep* buffers, where the hyperlinks are search matches rather than error messages (see Grep Searching).

M-g M-n
M-g n
C-x `

Visit the locus of the next error message or match (next-error).

M-g M-p
M-g p

Visit the locus of the previous error message or match (previous-error).

M-n

Move point to the next error message or match, without visiting its locus (compilation-next-error).

M-p

Move point to the previous error message or match, without visiting its locus (compilation-previous-error).

M-}

Move point to the next error message or match occurring in a different file (compilation-next-file).

M-{

Move point to the previous error message or match occurring in a different file (compilation-previous-file).

C-c C-f

Toggle Next Error Follow minor mode, which makes cursor motion in the compilation buffer produce automatic source display.

g

Re-run the last command whose output is shown in the *compilation* buffer.

M-x next-error-select-buffer

Select a buffer to be used by next invocation of next-error and previous-error.

To visit errors sequentially, type C-x ` (next-error), or equivalently M-g M-n or M-g n. This command can be invoked from any buffer, not just a Compilation mode buffer. The first time you invoke it after a compilation, it visits the locus of the first error message. Each subsequent M-g M-n visits the next error, in a similar fashion. If you visit a specific error with RET or a mouse click in the *compilation* buffer, subsequent M-g M-n commands advance from there. When M-g M-n finds no more error messages to visit, it signals an error. C-u M-g M-n starts again from the beginning of the compilation buffer, and visits the first locus.

M-g M-p or M-g p (previous-error) iterates through errors in the opposite direction.

The next-error and previous-error commands don’t just act on the errors or matches listed in *compilation* and *grep* buffers; they also know how to iterate through error or match lists produced by other commands, such as M-x occur (see Other Repeating Search). If the current buffer contains error messages or matches, these commands will iterate through them; otherwise, Emacs looks for a buffer containing error messages or matches amongst the windows of the selected frame (if the variable next-error-find-buffer-function is customized to the value next-error-buffer-on-selected-frame), then for a buffer used previously by next-error or previous-error, and finally all other buffers. Any buffer these commands iterate through that is not currently displayed in a window will be displayed. You can use the next-error-select-buffer command to switch to a different buffer to be used by the subsequent invocation of next-error.

By default, the next-error and previous-error commands skip less important messages. The variable compilation-skip-threshold controls this. The default value, 1, means to skip anything less important than a warning. A value of 2 means to skip anything less important than an error, while 0 means not to skip any messages.

When Emacs visits the locus of an error message, it momentarily highlights the relevant source line. The duration of this highlight is determined by the variable next-error-highlight for the locus in the selected buffer, and next-error-highlight-no-select for the locus in non-selected buffers.

If the *compilation* buffer is shown in a window with a left fringe (see Fringes), the locus-visiting commands put an arrow in the fringe, pointing to the current error message. If the window has no left fringe, such as on a text terminal, these commands scroll the window so that the current message is at the top of the window. If you change the variable compilation-context-lines to t, a visible arrow is inserted before column zero instead. If you change the variable to an integer value n, these commands scroll the window so that the current error message is n lines from the top, whether or not there is a fringe; the default value, nil, gives the behavior described above.

To parse messages from the compiler, Compilation mode uses the variable compilation-error-regexp-alist which lists various error message formats and tells Emacs how to extract the locus from each. A similar variable, grep-regexp-alist, tells Emacs how to parse output from a grep command (see Grep Searching).

Compilation mode also defines the keys SPC and DEL to scroll by screenfuls; M-n (compilation-next-error) and M-p (compilation-previous-error) to move to the next or previous error message; and M-{ (compilation-next-file) and M-} (compilation-previous-file) to move to the next or previous error message for a different source file.

You can type C-c C-f to toggle Next Error Follow mode. In this minor mode, ordinary cursor motion in the compilation buffer automatically updates the source buffer, i.e., moving the cursor over an error message causes the locus of that error to be displayed.

The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in any buffer, not just a normal compilation output buffer. Type M-x compilation-minor-mode to enable the minor mode. For instance, in an Rlogin buffer (see Remote Host), Compilation minor mode automatically accesses remote source files by FTP (see File Names).

Next: , Previous: , Up: Building   [Contents][Index]

27.3 Subshells for Compilation

This section includes various techniques and advice for using a shell and its features in compilation buffers. This material is specific to local compilations, and will most probably not work in (or be irrelevant to) compilation buffers whose default directory is on remote hosts.

The M-x compile command uses a shell to run the compilation command, but specifies the option for a noninteractive shell. This means, in particular, that the shell should start with no prompt. If you find your usual shell prompt making an unsightly appearance in the *compilation* buffer, it means you have made a mistake in your shell’s init file by setting the prompt unconditionally. (This init file may be named .bashrc, .profile, .cshrc, .shrc, etc., depending on what shell you use.) The shell init file should set the prompt only if there already is a prompt. Here’s how to do it in bash:

if [ "${PS1+set}" = set ]
then PS1=…
fi

And here’s how to do it in csh:

if ($?prompt) set prompt = …

If you want to customize the value of the TERM environment variable passed to the compilation subshell, customize the variable comint-terminfo-terminal (see Shell Options).

Emacs does not expect a compiler process to launch asynchronous subprocesses; if it does, and they keep running after the main compiler process has terminated, Emacs may kill them or their output may not arrive in Emacs. To avoid this problem, make the main compilation process wait for its subprocesses to finish. In a shell script, you can do this using ‘$!’ and ‘wait’, like this:

(sleep 10; echo 2nd)& pid=$!  # Record pid of subprocess
echo first message
wait $pid                     # Wait for subprocess

If the background process does not output to the compilation buffer, so you only need to prevent it from being killed when the main compilation process terminates, this is sufficient:

nohup command; sleep 1

On MS-DOS, asynchronous subprocesses are not supported, so M-x compile runs the compilation command synchronously (i.e., you must wait until the command finishes before you can do anything else in Emacs). See MS-DOS.

Next: , Previous: , Up: Building   [Contents][Index]

27.4 Searching with Grep under Emacs

Just as you can run a compiler from Emacs and then visit the lines with compilation errors, you can also run grep and then visit the lines on which matches were found. This works by treating the matches reported by grep as if they were errors. The output buffer uses Grep mode, which is a variant of Compilation mode (see Compilation Mode).

M-x grep
M-x lgrep

Run grep asynchronously under Emacs, listing matching lines in the buffer named *grep*.

M-x grep-find
M-x find-grep
M-x rgrep

Run grep via find, and collect output in the *grep* buffer.

M-x zrgrep

Run zgrep and collect output in the *grep* buffer.

M-x kill-grep

Kill the running grep subprocess.

To run grep, type M-x grep, then enter a command line that specifies how to run grep. Use the same arguments you would give grep when running it normally: a grep-style regexp (usually in single-quotes to quote the shell’s special characters) followed by file names, which may use wildcards. If you specify a prefix argument for M-x grep, it finds the identifier (see Xref) in the buffer around point, and puts that into the default grep command.

Your command need not simply run grep; you can use any shell command that produces output in the same format. For instance, you can chain grep commands, like this:

grep -nH -e foo *.el | grep bar | grep toto

The output from grep goes in the *grep* buffer. You can find the corresponding lines in the original files using M-g M-n, RET, and so forth, just like compilation errors. See Compilation Mode, for detailed description of commands and key bindings available in the *grep* buffer.

Some grep programs accept a ‘--color’ option to output special markers around matches for the purpose of highlighting. You can make use of this feature by setting grep-highlight-matches to t. When displaying a match in the source buffer, the exact match will be highlighted, instead of the entire source line.

As with compilation commands (see Compilation), while the grep command runs, the mode line shows the running number of matches found and highlighted so far.

The grep commands will offer to save buffers before running. This is controlled by the grep-save-buffers variable. The possible values are either nil (don’t save), ask (ask before saving), or a function which will be used as a predicate (and is called with the file name as the parameter and should return non-nil if the buffer is to be saved). Any other non-nil value means that all buffers should be saved without asking. The default is ask.

The command M-x grep-find (also available as M-x find-grep) is similar to M-x grep, but it supplies a different initial default for the command—one that runs both find and grep, so as to search every file in a directory tree. See also the find-grep-dired command, in Dired and Find.

The commands M-x lgrep (local grep) and M-x rgrep (recursive grep) are more user-friendly versions of grep and grep-find, which prompt separately for the regular expression to match, the files to search, and the base directory for the search. Case sensitivity of the search is controlled by the current value of case-fold-search. The command M-x zrgrep is similar to M-x rgrep, but it calls zgrep instead of grep to search the contents of gzipped files.

These commands build the shell commands based on the variables grep-template (for lgrep) and grep-find-template (for rgrep). The files to search can use aliases defined in the variable grep-files-aliases.

Directories listed in the variable grep-find-ignored-directories are automatically skipped by M-x rgrep. The default value includes the data directories used by various version control systems.

By default, the shell commands constructed for lgrep, rgrep, and zgrep are abbreviated for display by concealing the part that contains a long list of files and directories to ignore. You can reveal the concealed part by clicking on the button with ellipsis, which represents them. You can also interactively toggle viewing the concealed part by typing M-x grep-find-toggle-abbreviation. To disable this abbreviation of the shell commands, customize the option grep-find-abbreviate to a nil value.

Next: , Previous: , Up: Building   [Contents][Index]

27.5 Finding Syntax Errors On The Fly

Flymake mode is a minor mode that performs on-the-fly syntax checking for many programming and markup languages, including C, C++, Perl, HTML, and TeX/LaTeX. It is somewhat analogous to Flyspell mode, which performs spell checking for ordinary human languages in a similar fashion (see Spelling). As you edit a file, Flymake mode runs an appropriate syntax checking tool in the background, using a temporary copy of the buffer. It then parses the error and warning messages, and highlights the erroneous lines in the buffer. The syntax checking tool used depends on the language; for example, for C/C++ files this is usually the C compiler. Flymake can also use build tools such as make for checking complicated projects.

To enable Flymake mode, type M-x flymake-mode. You can jump to the errors that it finds by using M-x flymake-goto-next-error and M-x flymake-goto-prev-error. To display any error messages associated with the current line, type M-x flymake-display-err-menu-for-current-line.

For more details about using Flymake, see Flymake in The Flymake Manual.

Next: , Previous: , Up: Building   [Contents][Index]

27.6 Running Debuggers Under Emacs

The GUD (Grand Unified Debugger) library provides an Emacs interface to a wide variety of symbolic debuggers. It can run the GNU Debugger (GDB), as well as DBX, SDB, XDB, Guile REPL debug commands, Perl’s debugging mode, the Python debugger PDB, and the Java Debugger JDB.

Emacs provides a special interface to GDB, which uses extra Emacs windows to display the state of the debugged program. See GDB Graphical Interface.

Emacs also has a built-in debugger for Emacs Lisp programs. See The Lisp Debugger in the Emacs Lisp Reference Manual.

27.6.1 Starting GUD

There are several commands for starting a debugger subprocess, each corresponding to a particular debugger program.

M-x gdb

Run GDB as a subprocess, and interact with it via an IDE-like Emacs interface. See GDB Graphical Interface, for more information about this command.

M-x gud-gdb

Run GDB, using a GUD interaction buffer for input and output to the GDB subprocess (see Debugger Operation). If such a buffer already exists, switch to it; otherwise, create the buffer and switch to it.

The other commands in this list do the same, for other debugger programs.

M-x perldb

Run the Perl interpreter in debug mode.

M-x jdb

Run the Java debugger.

M-x pdb

Run the Python debugger.

M-x guiler

Run Guile REPL for debugging Guile Scheme programs.

M-x dbx

Run the DBX debugger.

M-x xdb

Run the XDB debugger.

M-x sdb

Run the SDB debugger.

Each of these commands reads a command line to invoke the debugger, using the minibuffer. The minibuffer’s initial contents contain the standard executable name and options for the debugger, and sometimes also a guess for the name of the executable file you want to debug. Shell wildcards and variables are not allowed in this command line. Emacs assumes that the first command argument which does not start with a ‘-’ is the executable file name.

Tramp provides a facility for remote debugging, whereby both the debugger and the program being debugged are on the same remote host. See Running a debugger on a remote host in The Tramp Manual, for details. This is separate from GDB’s remote debugging feature, where the program and the debugger run on different machines (see Debugging Remote Programs in The GNU debugger).

Next: , Previous: , Up: Debuggers   [Contents][Index]

27.6.2 Debugger Operation

The GUD interaction buffer is an Emacs buffer which is used to send text commands to a debugger subprocess, and record its output. This is the basic interface for interacting with a debugger, used by M-x gud-gdb and other commands listed in Starting GUD. The M-x gdb command extends this interface with additional specialized buffers for controlling breakpoints, stack frames, and other aspects of the debugger state (see GDB Graphical Interface).

The GUD interaction buffer uses a variant of Shell mode, so the Emacs commands defined by Shell mode are available (see Shell Mode). Completion is available for most debugger commands (see Completion), and you can use the usual Shell mode history commands to repeat them. See Commands of GUD, for special commands that can be used in the GUD interaction buffer.

As you debug a program, Emacs displays the relevant source files by visiting them in Emacs buffers, with an arrow in the left fringe indicating the current execution line. (On a text terminal, the arrow appears as ‘=>’, overlaid on the first two text columns.) Moving point in such a buffer does not move the arrow. You are free to edit these source files, but note that inserting or deleting lines will throw off the arrow’s positioning, as Emacs has no way to figure out which edited source line corresponds to the line reported by the debugger subprocess. To update this information, you typically have to recompile and restart the program.

GUD Tooltip mode is a global minor mode that adds tooltip support to GUD. To toggle this mode, type M-x gud-tooltip-mode. It is disabled by default. If enabled, you can move the mouse pointer over a variable, a function, or a macro (collectively called identifiers) to show their values in tooltips (see Tooltips). If just placing the mouse pointer over an expression doesn’t show the value of the expression you had in mind, you can tell Emacs more explicitly what expression to evaluate by dragging the mouse over the expression, then leaving the mouse inside the marked area. The GUD Tooltip mode takes effect in the GUD interaction buffer, and in all source buffers with major modes listed in the variable gud-tooltip-modes. If the variable gud-tooltip-echo-area is non-nil, or if you turned off the tooltip mode, values are shown in the echo area instead of a tooltip.

When using GUD Tooltip mode with M-x gud-gdb, displaying an expression’s value in GDB can sometimes expand a macro, potentially causing side effects in the debugged program. For that reason, using tooltips in gud-gdb is disabled. If you use the M-x gdb interface, this problem does not occur, as there is special code to avoid side-effects; furthermore, you can display macro definitions associated with an identifier when the program is not executing.

27.6.3 Commands of GUD

GUD provides commands for setting and clearing breakpoints, selecting stack frames, and stepping through the program.

C-x C-a C-b

Set a breakpoint on the source line that point is on.

C-x C-a C-b (gud-break), when called in a source buffer, sets a debugger breakpoint on the current source line. This command is available only after starting GUD. If you call it in a buffer that is not associated with any debugger subprocess, it signals an error.

The following commands are available both in the GUD interaction buffer and globally, but with different key bindings. The keys starting with C-c are available only in the GUD interaction buffer, while those starting with C-x C-a are available globally. Some of these commands are also available via the tool bar; some are not supported by certain debuggers.

C-c C-l
C-x C-a C-l

Display, in another window, the last source line referred to in the GUD interaction buffer (gud-refresh).

C-c C-s
C-x C-a C-s

Execute the next single line of code (gud-step). If the line contains a function call, execution stops after entering the called function.

C-c C-n
C-x C-a C-n

Execute the next single line of code, stepping across function calls without stopping inside the functions (gud-next).

C-c C-i
C-x C-a C-i

Execute a single machine instruction (gud-stepi).

C-c C-p
C-x C-a C-p

Evaluate the expression at point (gud-print). If Emacs does not print the exact expression that you want, mark it as a region first.

C-c C-r
C-x C-a C-r

Continue execution without specifying any stopping point. The program will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (gud-cont).

C-c C-d
C-x C-a C-d

Delete the breakpoint(s) on the current source line, if any (gud-remove). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.

C-c C-t
C-x C-a C-t

Set a temporary breakpoint on the current source line, if any (gud-tbreak). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.

C-c <
C-x C-a <

Select the next enclosing stack frame (gud-up). This is equivalent to the GDB command ‘up’.

C-c >
C-x C-a >

Select the next inner stack frame (gud-down). This is equivalent to the GDB command ‘down’.

C-c C-u
C-x C-a C-u

Continue execution to the current line (gud-until). The program will run until it hits a breakpoint, terminates, gets a signal that the debugger is checking for, or reaches the line on which the cursor currently sits.

C-c C-f
C-x C-a C-f

Run the program until the selected stack frame returns or stops for some other reason (gud-finish).

If you are using GDB, these additional key bindings are available:

C-x C-a C-j

Only useful in a source buffer, gud-jump transfers the program’s execution point to the current line. In other words, the next line that the program executes will be the one where you gave the command. If the new execution line is in a different function from the previously one, GDB prompts for confirmation since the results may be bizarre. See the GDB manual entry regarding jump for details.

TAB

With GDB, complete a symbol name (gud-gdb-complete-command). This key is available only in the GUD interaction buffer.

These commands interpret a numeric argument as a repeat count, when that makes sense.

Because TAB serves as a completion command, you can’t use it to enter a tab as input to the program you are debugging with GDB. Instead, type C-q TAB to enter a tab.

27.6.4 GUD Customization

On startup, GUD runs one of the following hooks: gdb-mode-hook, if you are using GDB; dbx-mode-hook, if you are using DBX; sdb-mode-hook, if you are using SDB; xdb-mode-hook, if you are using XDB; guiler-mode-hook for Guile REPL debugging; perldb-mode-hook, for Perl debugging mode; pdb-mode-hook, for PDB; jdb-mode-hook, for JDB. See Hooks.

The gud-def Lisp macro (see Defining Macros in the Emacs Lisp Reference Manual) provides a convenient way to define an Emacs command that sends a particular command string to the debugger, and set up a key binding for in the GUD interaction buffer:

(gud-def function cmdstring binding docstring)

This defines a command named function which sends cmdstring to the debugger process, and gives it the documentation string docstring. You can then use the command function in any buffer. If binding is non-nil, gud-def also binds the command to C-c binding in the GUD buffer’s mode and to C-x C-a binding generally.

The command string cmdstring may contain certain ‘%’-sequences that stand for data to be filled in at the time function is called:

%f

The name of the current source file. If the current buffer is the GUD buffer, then the current source file is the file that the program stopped in.

%l

The number of the current source line. If the current buffer is the GUD buffer, then the current source line is the line that the program stopped in.

%e

In transient-mark-mode the text in the region, if it is active. Otherwise the text of the C lvalue or function-call expression at or adjacent to point.

%a

The text of the hexadecimal address at or adjacent to point.

%p

The numeric argument of the called function, as a decimal number. If the command is used without a numeric argument, ‘%p’ stands for the empty string.

If you don’t use ‘%p’ in the command string, the command you define ignores any numeric argument.

%d

The name of the directory of the current source file.

%c

Fully qualified class name derived from the expression surrounding point (jdb only).

Previous: , Up: Debuggers   [Contents][Index]

27.6.5 GDB Graphical Interface

The command M-x gdb starts GDB in an IDE-like interface, with specialized buffers for controlling breakpoints, stack frames, and other aspects of the debugger state. It also provides additional ways to control the debugging session with the mouse, such as clicking in the fringe of a source buffer to set a breakpoint there.

To run GDB using just the GUD interaction buffer interface, without these additional features, use M-x gud-gdb (see Starting GUD). You must use this if you want to debug multiple programs within one Emacs session, as that is currently unsupported by M-x gdb.

Internally, M-x gdb informs GDB that its screen size is unlimited; for correct operation, you must not change GDB’s screen height and width values during the debugging session.

27.6.5.1 GDB User Interface Layout

If the variable gdb-many-windows is nil (the default), M-x gdb normally displays only the GUD interaction buffer. However, if the variable gdb-show-main is also non-nil, it starts with two windows: one displaying the GUD interaction buffer, and the other showing the source for the main function of the program you are debugging.

If gdb-many-windows is non-nil, then M-x gdb displays the following frame layout:

+--------------------------------+--------------------------------+
|   GUD interaction buffer       |   Locals/Registers buffer      |
|--------------------------------+--------------------------------+
|   Primary Source buffer        |   I/O buffer for debugged pgm  |
|--------------------------------+--------------------------------+
|   Stack buffer                 |   Breakpoints/Threads buffer   |
+--------------------------------+--------------------------------+

If you ever change the window layout, you can restore the many-windows layout by typing M-x gdb-restore-windows. To toggle between the many windows layout and a simple layout with just the GUD interaction buffer and a source file, type M-x gdb-many-windows.

If you have an elaborate window setup, and don’t want gdb-many-windows to disrupt that, it is better to invoke M-x gdb in a separate frame to begin with, then the arrangement of windows on your original frame will not be affected. A separate frame for GDB sessions can come in especially handy if you work on a text-mode terminal, where the screen estate for windows could be at a premium.

You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you want by typing M-x gdb-display-buffertype-buffer or M-x gdb-frame-buffertype-buffer, where buffertype is the relevant buffer type, such as ‘breakpoints’. You can do the same with the menu bar, with the ‘GDB-Windows’ and ‘GDB-Frames’ sub-menus of the ‘GUD’ menu.

When you finish debugging, kill the GUD interaction buffer with C-x k, which will also kill all the buffers associated with the session. However you need not do this if, after editing and re-compiling your source code within Emacs, you wish to continue debugging. When you restart execution, GDB automatically finds the new executable. Keeping the GUD interaction buffer has the advantage of keeping the shell history as well as GDB’s breakpoints. You do need to check that the breakpoints in recently edited source files are still in the right places.

27.6.5.2 Source Buffers

mouse-1 (in fringe)

Set or clear a breakpoint on that line (gdb-mouse-set-clear-breakpoint).

C-mouse-1 (in fringe)

Enable or disable a breakpoint on that line (gdb-mouse-toggle-breakpoint-margin).

mouse-3 (in fringe)

Continue execution to that line (gdb-mouse-until).

C-mouse-3 (in fringe)

Jump to that line (gdb-mouse-jump).

On a graphical display, you can click mouse-1 in the fringe of a source buffer, to set a breakpoint on that line (see Fringes). A red dot appears in the fringe, where you clicked. If a breakpoint already exists there, the click removes it. A C-mouse-1 click enables or disables an existing breakpoint; a breakpoint that is disabled, but not unset, is indicated by a gray dot.

On a text terminal, or when fringes are disabled, enabled breakpoints are indicated with a ‘B’ character in the left margin of the window. Disabled breakpoints are indicated with ‘b’. (The margin is only displayed if a breakpoint is present.)

A solid arrow in the left fringe of a source buffer indicates the line of the innermost frame where the debugged program has stopped. A hollow arrow indicates the current execution line of a higher-level frame. If you drag the arrow in the fringe with mouse-1, that causes execution to advance to the line where you release the button. Alternatively, you can click mouse-3 in the fringe to advance to that line. You can click C-mouse-3 in the fringe to jump to that line without executing the intermediate lines. This command allows you to go backwards, which can be useful for running through code that has already executed, in order to examine its execution in more detail.

If the file names of the source files are shown with octal escapes, set the variable gdb-mi-decode-strings to the appropriate coding-system, most probably utf-8. (This is nil by default because GDB may emit octal escapes in situations where decoding is undesirable, and also because the program being debugged might use an encoding different from the one used to encode non-ASCII file names on your system.)

27.6.5.3 Breakpoints Buffer

The GDB Breakpoints buffer shows the breakpoints, watchpoints and catchpoints in the debugger session. See Breakpoints in The GNU debugger. It provides the following commands, which mostly apply to the current breakpoint (the breakpoint which point is on):

SPC

Enable/disable current breakpoint (gdb-toggle-breakpoint). On a graphical display, this changes the color of the dot in the fringe of the source buffer at that line. The dot is red when the breakpoint is enabled, and gray when it is disabled.

D

Delete the current breakpoint (gdb-delete-breakpoint).

RET

Visit the source line for the current breakpoint (gdb-goto-breakpoint).

鼠标中键

Visit the source line for the breakpoint you click on (gdb-goto-breakpoint).

When gdb-many-windows is non-nil, the GDB Breakpoints buffer shares its window with the GDB Threads buffer. To switch from one to the other click with mouse-1 on the relevant button in the header line. If gdb-show-threads-by-default is non-nil, the GDB Threads buffer is the one shown by default.

27.6.5.4 Threads Buffer

The GDB Threads buffer displays a summary of the threads in the debugged program. See Debugging programs with multiple threads in The GNU debugger. To select a thread, move point there and press RET (gdb-select-thread), or click on it with mouse-2. This also displays the associated source buffer, and updates the contents of the other GDB buffers.

You can customize variables in the gdb-buffers group to select fields included in GDB Threads buffer.

gdb-thread-buffer-verbose-names

Show long thread names like ‘Thread 0x4e2ab70 (LWP 1983)’.

gdb-thread-buffer-arguments

Show arguments of thread top frames.

gdb-thread-buffer-locations

Show file information or library names.

gdb-thread-buffer-addresses

Show addresses for thread frames in threads buffer.

To view information for several threads simultaneously, use the following commands from the GDB Threads buffer.

d

Display disassembly buffer for the thread at current line (gdb-display-disassembly-for-thread).

f

Display the GDB Stack buffer for the thread at current line (gdb-display-stack-for-thread).

l

Display the GDB Locals buffer for the thread at current line (gdb-display-locals-for-thread).

r

Display the GDB Registers buffer for the thread at current line (gdb-display-registers-for-thread).

Their upper-case counterparts, D, F ,L and R, display the corresponding buffer in a new frame.

When you create a buffer showing information about some specific thread, it becomes bound to that thread and keeps showing actual information while you debug your program. The mode indicator for each GDB buffer shows the number of the thread whose information that buffer displays. The thread number is also included in the name of each bound buffer.

Further commands are available in the GDB Threads buffer which depend on the mode of GDB that is used for controlling execution of your program. See Multithreaded Debugging.

27.6.5.5 Stack Buffer

The GDB Stack buffer displays a call stack, with one line for each of the nested subroutine calls (stack frames) in the debugger session. See Backtraces in The GNU debugger.

On graphical displays, the selected stack frame is indicated by an arrow in the fringe. On text terminals, or when fringes are disabled, the selected stack frame is displayed in reverse contrast. To select a stack frame, move point in its line and type RET (gdb-frames-select), or click mouse-2 on it. Doing so also updates the Locals buffer (see Other GDB Buffers).

If you want the frame address to be shown each stack frame, customize the variable gdb-stack-buffer-addresses to a non-nil value.

27.6.5.6 Other GDB Buffers

Locals Buffer

This buffer displays the values of local variables of the current frame for simple data types (see Information on a frame in The GNU debugger). Press RET or click mouse-2 on the value if you want to edit it.

Arrays and structures display their type only. With GDB 6.4 or later, you can examine the value of the local variable at point by typing RET, or with a mouse-2 click. With earlier versions of GDB, use RET or mouse-2 on the type description (‘[struct/union]’ or ‘[array]’). See Watch Expressions.

Registers Buffer

This buffer displays the values held by the registers (see Registers in The GNU debugger). Press RET or click mouse-2 on a register if you want to edit its value. With GDB 6.4 or later, recently changed register values display with font-lock-warning-face.

Assembler Buffer

The assembler buffer displays the current frame as machine code. An arrow points to the current instruction, and you can set and remove breakpoints as in a source buffer. Breakpoint icons also appear in the fringe or margin.

Memory Buffer

The memory buffer lets you examine sections of program memory (see Examining memory in The GNU debugger). Click mouse-1 on the appropriate part of the header line to change the starting address or number of data items that the buffer displays. Alternatively, use S or N respectively. Click mouse-3 on the header line to select the display format or unit size for these data items.

When gdb-many-windows is non-nil, the locals buffer shares its window with the registers buffer, just like breakpoints and threads buffers. To switch from one to the other, click with mouse-1 on the relevant button in the header line.

27.6.5.7 Watch Expressions

If you want to see how a variable changes each time your program stops, move point into the variable name and click on the watch icon in the tool bar (gud-watch) or type C-x C-a C-w. If you specify a prefix argument, you can enter the variable name in the minibuffer.

Each watch expression is displayed in the speedbar (see Speedbar). Complex data types, such as arrays, structures and unions are represented in a tree format. Leaves and simple data types show the name of the expression and its value and, when the speedbar frame is selected, display the type as a tooltip. Higher levels show the name, type and address value for pointers and just the name and type otherwise. Root expressions also display the frame address as a tooltip to help identify the frame in which they were defined.

To expand or contract a complex data type, click mouse-2 or press SPC on the tag to the left of the expression. Emacs asks for confirmation before expanding the expression if its number of immediate children exceeds the value of the variable gdb-max-children.

To delete a complex watch expression, move point to the root expression in the speedbar and type D (gdb-var-delete).

To edit a variable with a simple data type, or a simple element of a complex data type, move point there in the speedbar and type RET (gdb-edit-value). Or you can click mouse-2 on a value to edit it. Either way, this reads the new value using the minibuffer.

If you set the variable gdb-show-changed-values to non-nil (the default value), Emacs uses font-lock-warning-face to highlight values that have recently changed and shadow face to make variables which have gone out of scope less noticeable. When a variable goes out of scope you can’t edit its value.

If the variable gdb-delete-out-of-scope is non-nil (the default value), Emacs automatically deletes watch expressions which go out of scope. Sometimes, when your program re-enters the same function many times, it may be useful to set this value to nil so that you don’t need to recreate the watch expression.

If the variable gdb-use-colon-colon-notation is non-nil, Emacs uses the ‘function::variable’ format. This allows the user to display watch expressions which share the same variable name. The default value is nil.

To automatically raise the speedbar every time the display of watch expressions updates, set gdb-speedbar-auto-raise to non-nil. This can be useful if you are debugging with a full screen Emacs frame.

27.6.5.8 Multithreaded Debugging

In GDB’s all-stop mode, whenever your program stops, all execution threads stop. Likewise, whenever you restart the program, all threads start executing. See All-Stop Mode in The GNU debugger. For some multi-threaded targets, GDB supports a further mode of operation, called non-stop mode, in which you can examine stopped program threads in the debugger while other threads continue to execute freely. See Non-Stop Mode in The GNU debugger. Versions of GDB prior to 7.0 do not support non-stop mode, and it does not work on all targets.

The variable gdb-non-stop-setting determines whether Emacs runs GDB in all-stop mode or non-stop mode. The default is t, which means it tries to use non-stop mode if that is available. If you change the value to nil, or if non-stop mode is unavailable, Emacs runs GDB in all-stop mode. The variable takes effect when Emacs begins a debugging session; if you change its value, you should restart any active debugging session.

When a thread stops in non-stop mode, Emacs usually switches to that thread. If you don’t want Emacs to do this switch if another stopped thread is already selected, change the variable gdb-switch-when-another-stopped to nil.

Emacs can decide whether or not to switch to the stopped thread depending on the reason which caused the stop. Customize the variable gdb-switch-reasons to select the stop reasons which will cause a thread switch.

The variable gdb-stopped-functions allows you to execute your functions whenever some thread stops.

In non-stop mode, you can switch between different modes for GUD execution control commands.

Non-stop/A

When gdb-gud-control-all-threads is t (the default value), interruption and continuation commands apply to all threads, so you can halt or continue all your threads with one command using gud-stop-subjob and gud-cont, respectively. The ‘Go’ button is shown on the tool bar when at least one thread is stopped, whereas ‘Stop’ button is shown when at least one thread is running.

Non-stop/T

When gdb-gud-control-all-threads is nil, only the current thread is stopped/continued. ‘Go’ and ‘Stop’ buttons on the GUD tool bar are shown depending on the state of current thread.

You can change the current value of gdb-gud-control-all-threads from the tool bar or from ‘GUD->GDB-MI’ menu.

Stepping commands always apply to the current thread.

In non-stop mode, you can interrupt/continue your threads without selecting them. Hitting i in threads buffer interrupts thread under point, c continues it, s steps through. More such commands may be added in the future.

Note that when you interrupt a thread, it stops with the ‘signal received’ reason. If that reason is included in your gdb-switch-reasons (it is by default), Emacs will switch to that thread.

Next: , Previous: , Up: Building   [Contents][Index]

27.7 Executing Lisp Expressions

Emacs has major modes for several variants of Lisp. They use the same editing commands as other programming language modes (see Programs). In addition, they provide special commands for executing Lisp expressions.

Emacs Lisp mode

The mode for editing Emacs Lisp source files. It defines C-M-x to evaluate the current top-level Lisp expression. See Lisp Eval.

Lisp Interaction mode

The mode for an interactive Emacs Lisp session. It defines C-j to evaluate the expression before point and insert its value in the buffer. See Lisp Interaction.

Lisp mode

The mode for editing source files of programs that run in Lisps other than Emacs Lisp. It defines C-M-x to evaluate the current top-level expression in an external Lisp. See External Lisp.

Inferior Lisp mode

The mode for an interactive session with an external Lisp which is being run as a subprocess (or inferior process) of Emacs. See External Lisp.

Scheme mode

Like Lisp mode, but for Scheme programs.

Inferior Scheme mode

Like Inferior Lisp mode, but for Scheme.

Next: , Previous: , Up: Building   [Contents][Index]

27.8 Libraries of Lisp Code for Emacs

Emacs Lisp code is stored in files whose names conventionally end in .el. Such files are automatically visited in Emacs Lisp mode.

Emacs Lisp code can be compiled into byte-code, which loads faster, takes up less space, and executes faster. By convention, compiled Emacs Lisp code goes in a separate file whose name ends in ‘.elc’. For example, the compiled code for foo.el goes in foo.elc. See Byte Compilation in the Emacs Lisp Reference Manual.

To load an Emacs Lisp file, type M-x load-file. This command reads a file name using the minibuffer, and executes the contents of that file as Emacs Lisp code. It is not necessary to visit the file first; this command reads the file directly from disk, not from an existing Emacs buffer.

If an Emacs Lisp file is installed in the Emacs Lisp load path (defined below), you can load it by typing M-x load-library, instead of using M-x load-file. The M-x load-library command prompts for a library name rather than a file name; it searches through each directory in the Emacs Lisp load path, trying to find a file matching that library name. If the library name is ‘foo’, it tries looking for files named foo.elc, foo.el, and foo. The default behavior is to load the first file found. This command prefers .elc files over .el files because compiled files load and run faster. If it finds that lib.el is newer than lib.elc, it issues a warning, in case someone made changes to the .el file and forgot to recompile it, but loads the .elc file anyway. (Due to this behavior, you can save unfinished edits to Emacs Lisp source files, and not recompile until your changes are ready for use.) If you set the option load-prefer-newer to a non-nil value, however, then rather than the procedure described above, Emacs loads whichever version of the file is newest.

Emacs Lisp programs usually load Emacs Lisp files using the load function. This is similar to load-library, but is lower-level and accepts additional arguments. See How Programs Do Loading in the Emacs Lisp Reference Manual.

The Emacs Lisp load path is specified by the variable load-path. Its value should be a list of directories (strings). These directories are searched, in the specified order, by the M-x load-library command, the lower-level load function, and other Emacs functions that find Emacs Lisp libraries. An entry in load-path can also have the special value nil, which stands for the current default directory, but it is almost always a bad idea to use this, because its meaning will depend on the buffer that is current when load-path is used by Emacs. (If you find yourself wishing that nil were in the list, most likely what you really want is to use M-x load-file.)

The default value of load-path is a list of directories where the Lisp code for Emacs itself is stored. If you have libraries of your own in another directory, you can add that directory to the load path. Unlike most other variables described in this manual, load-path cannot be changed via the Customize interface (see Easy Customization), but you can add a directory to it by putting a line like this in your init file (see Init File):

(add-to-list 'load-path "/path/to/my/lisp/library")

It is customary to put locally installed libraries in the site-lisp directory that is already in the default value of load-path, or in some subdirectory of site-lisp. This way, you don’t need to modify the default value of load-path.

Some commands are autoloaded; when you run them, Emacs automatically loads the associated library first. For instance, the M-x compile command (see Compilation) is autoloaded; if you call it, Emacs automatically loads the compile library first. In contrast, the command M-x recompile is not autoloaded, so it is unavailable until you load the compile library.

Automatic loading can also occur when you look up the documentation of an autoloaded command (see Name Help), if the documentation refers to other functions and variables in its library (loading the library lets Emacs properly set up the hyperlinks in the *Help* buffer). To disable this feature, change the variable help-enable-autoload to nil.

Automatic loading also occurs when completing names for describe-variable and describe-function, based on the prefix being completed. To disable this feature, change the variable help-enable-completion-autoload to nil.

By default, Emacs refuses to load compiled Lisp files which were compiled with XEmacs, a modified version of Emacs—they can cause Emacs to crash. Set the variable load-dangerous-libraries to t if you want to try loading them.

Once you put your library in a directory where Emacs can find and load it, you may wish to make it available at startup. This is useful when the library defines features that should be available automatically on demand, and manually loading the library is thus inconvenient. In these cases, make sure the library will be loaded by adding suitable forms to your init file: either load or require (if you always need to load the library at startup), or autoload if you need Emacs to load the library when some command or function is invoked. 例如:

 ;; Loads my-shining-package.elc unconditionally.
 (require 'my-shining-package)
 ;; Will load my-shining-package.elc when my-func is invoked.
 (autoload 'my-func "my-shining-package")

Note that installing a package using package-install (see Package Installation) takes care of placing the package’s Lisp files in a directory where Emacs will find it, and also writes the necessary initialization code into your init files, making the above manual customizations unnecessary.

Next: , Previous: , Up: Building   [Contents][Index]

27.9 Evaluating Emacs Lisp Expressions

Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode command is M-x emacs-lisp-mode.

Emacs provides several commands for evaluating Emacs Lisp expressions. You can use these commands in Emacs Lisp mode, to test your Emacs Lisp code as it is being written. For example, after re-writing a function, you can evaluate the function definition to make it take effect for subsequent function calls. These commands are also available globally, and can be used outside Emacs Lisp mode.

M-:

Read a single Emacs Lisp expression in the minibuffer, evaluate it, and print the value in the echo area (eval-expression).

C-x C-e

Evaluate the Emacs Lisp expression before point, and print the value in the echo area (eval-last-sexp).

C-M-x (in Emacs Lisp mode)
M-x eval-defun

Evaluate the defun containing or after point, and print the value in the echo area (eval-defun).

M-x eval-region

Evaluate all the Emacs Lisp expressions in the region.

M-x eval-buffer

Evaluate all the Emacs Lisp expressions in the buffer.

M-: (eval-expression) reads an expression using the minibuffer, and evaluates it. (Before evaluating the expression, the current buffer switches back to the buffer that was current when you typed M-:, not the minibuffer into which you typed the expression.)

The command C-x C-e (eval-last-sexp) evaluates the Emacs Lisp expression preceding point in the buffer, and displays the value in the echo area. When the result of an evaluation is an integer, it is displayed together with the value in other formats (octal, hexadecimal, and character if eval-expression-print-maximum-character, described below, allows it).

If M-: or C-x C-e is given a prefix argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. If the prefix argument is zero, any integer output is inserted together with its value in other formats (octal, hexadecimal, and character). Such a prefix argument also prevents abbreviation of the output according to the variables eval-expression-print-level and eval-expression-print-length (see below). Similarly, a prefix argument of -1 overrides the effect of eval-expression-print-length.

The eval-defun command is bound to C-M-x in Emacs Lisp mode. It evaluates the top-level Lisp expression containing or following point, and prints the value in the echo area. In this context, a top-level expression is referred to as a “defun”, but it need not be an actual defun (function definition). In particular, this command treats defvar expressions specially. Normally, evaluating a defvar expression does nothing if the variable it defines already has a value. But this command unconditionally resets the variable to the initial value specified by the defvar; this is convenient for debugging Emacs Lisp programs. defcustom and defface expressions are treated similarly. Note that the other commands documented in this section do not have this special feature.

With a prefix argument, C-M-x instruments the function definition for Edebug, the Emacs Lisp Debugger. See Instrumenting for Edebug in the Emacs Lisp Reference Manual.

The command M-x eval-region parses the text of the region as one or more Lisp expressions, evaluating them one by one. M-x eval-buffer is similar but evaluates the entire buffer.

The options eval-expression-print-level and eval-expression-print-length control the maximum depth and length of lists to print in the result of the evaluation commands before abbreviating them. Supplying a zero prefix argument to eval-expression or eval-last-sexp causes lists to be printed in full. eval-expression-debug-on-error controls whether evaluation errors invoke the debugger when these commands are used; its default is t. eval-expression-print-maximum-character prevents integers which are larger than it from being displayed as characters.

Next: , Previous: , Up: Building   [Contents][Index]

27.10 Lisp Interaction Buffers

When Emacs starts up, it contains a buffer named *scratch*, which is provided for evaluating Emacs Lisp expressions interactively. Its major mode is Lisp Interaction mode. You can also enable Lisp Interaction mode by typing M-x lisp-interaction-mode.

In the *scratch* buffer, and other Lisp Interaction mode buffers, C-j (eval-print-last-sexp) evaluates the Lisp expression before point, and inserts the value at point. Thus, as you type expressions into the buffer followed by C-j after each expression, the buffer records a transcript of the evaluated expressions and their values. All other commands in Lisp Interaction mode are the same as in Emacs Lisp mode.

At startup, the *scratch* buffer contains a short message, in the form of a Lisp comment, that explains what it is for. This message is controlled by the variable initial-scratch-message, which should be either a documentation string, or nil (which means to suppress the message).

An alternative way of evaluating Emacs Lisp expressions interactively is to use Inferior Emacs Lisp mode, which provides an interface rather like Shell mode (see Shell Mode) for evaluating Emacs Lisp expressions. Type M-x ielm to create an *ielm* buffer which uses this mode. For more information, see that command’s documentation.

Previous: , Up: Building   [Contents][Index]

27.11 Running an External Lisp

Lisp mode is the major mode for editing programs written in general-purpose Lisp dialects, such as Common Lisp. Its mode command is M-x lisp-mode. Emacs uses Lisp mode automatically for files whose names end in .l, .lsp, or .lisp.

You can run an external Lisp session as a subprocess or inferior process of Emacs, and pass expressions to it to be evaluated. To begin an external Lisp session, type M-x run-lisp. This runs the program named lisp, and sets it up so that both input and output go through an Emacs buffer named *inferior-lisp*. To change the name of the Lisp program run by M-x run-lisp, change the variable inferior-lisp-program.

The major mode for the *lisp* buffer is Inferior Lisp mode, which combines the characteristics of Lisp mode and Shell mode (see Shell Mode). To send input to the Lisp session, go to the end of the *lisp* buffer and type the input, followed by RET. Terminal output from the Lisp session is automatically inserted in the buffer.

When you edit a Lisp program in Lisp mode, you can type C-M-x (lisp-eval-defun) to send an expression from the Lisp mode buffer to a Lisp session that you had started with M-x run-lisp. The expression sent is the top-level Lisp expression at or following point. The resulting value goes as usual into the *inferior-lisp* buffer. Note that the effect of C-M-x in Lisp mode is thus very similar to its effect in Emacs Lisp mode (see Lisp Eval), except that the expression is sent to a different Lisp environment instead of being evaluated in Emacs.

The facilities for editing Scheme code, and for sending expressions to a Scheme subprocess, are very similar. Scheme source files are edited in Scheme mode, which can be explicitly enabled with M-x scheme-mode. You can initiate a Scheme session by typing M-x run-scheme (the buffer for interacting with Scheme is named *scheme*), and send expressions to it by typing C-M-x.


Next: , Previous: , Up: Top   [Contents][Index]

28 Maintaining Large Programs

This chapter describes Emacs features for maintaining medium- to large-size programs and packages. These features include:

If you are maintaining a large Lisp program, then in addition to the features described here, you may find the Emacs Lisp Regression Testing (ERT) library useful (see ERT in Emacs Lisp Regression Testing).

Next: , Up: Maintaining   [Contents][Index]

28.1 Version Control

A version control system is a program that can record multiple versions of a source file, storing information such as the creation time of each version, who made it, and a description of what was changed.

The Emacs version control interface is called VC. VC commands work with several different version control systems; currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS, SRC, SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, RCS, and Bazaar.

VC is enabled automatically whenever you visit a file governed by a version control system. To disable VC entirely, set the customizable variable vc-handled-backends to nil (see Customizing VC).

To update the VC state information for the file visited in the current buffer, use the command vc-refresh-state. This command is useful when you perform version control commands outside Emacs (e.g., from the shell prompt), or if you put the buffer’s file under a different version control system, or remove it from version control entirely.

28.1.1 Introduction to Version Control

VC allows you to use a version control system from within Emacs, integrating the version control operations smoothly with editing. It provides a uniform interface for common operations in many version control operations.

Some uncommon or intricate version control operations, such as altering repository settings, are not supported in VC. You should perform such tasks outside VC, e.g., via the command line.

This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip this section if you are already familiar with the version control system you want to use.

28.1.1.1 Understanding the Problems it Addresses

Version control systems provide you with three important capabilities:

28.1.1.2 Supported Version Control Systems

VC currently works with many different version control systems, which it refers to as back ends:

28.1.1.3 Concepts of Version Control

When a file is under version control, we say that it is registered in the version control system. The system has a repository which stores both the file’s present state and its change history—enough to reconstruct the current version or any earlier version. The repository also contains other information, such as log entries that describe the changes made to each file.

The copy of a version-controlled file that you actually edit is called the work file. You can change each work file as you would an ordinary file. After you are done with a set of changes, you may commit (or check in) the changes; this records the changes in the repository, along with a descriptive log entry.

A directory tree of work files is called a working tree.

Each commit creates a new revision in the repository. The version control system keeps track of all past revisions and the changes that were made in each revision. Each revision is named by a revision ID, whose format depends on the version control system; in the simplest case, it is just an integer.

To go beyond these basic concepts, you will need to understand three aspects in which version control systems differ. As explained in the next three sections, they can be lock-based or merge-based; file-based or changeset-based; and centralized or decentralized. VC handles all these modes of operation, but it cannot hide the differences.

28.1.1.4 Merge-based vs Lock-based Version Control

A version control system typically has some mechanism to coordinate between users who want to change the same file. There are two ways to do this: merging and locking.

In a version control system that uses merging, each user may modify a work file at any time. The system lets you merge your work file, which may contain changes that have not been committed, with the latest changes that others have committed.

Older version control systems use a locking scheme instead. Here, work files are normally read-only. To edit a file, you ask the version control system to make it writable for you by locking it; only one user can lock a given file at any given time. This procedure is analogous to, but different from, the locking that Emacs uses to detect simultaneous editing of ordinary files (see Interlocking). When you commit your changes, that unlocks the file, and the work file becomes read-only again. Other users may then lock the file to make their own changes.

Both locking and merging systems can have problems when multiple users try to modify the same file at the same time. Locking systems have lock conflicts; a user may try to check a file out and be unable to because it is locked. In merging systems, merge conflicts happen when you commit a change to a file that conflicts with a change committed by someone else after your checkout. Both kinds of conflict have to be resolved by human judgment and communication. Experience has shown that merging is superior to locking, both in convenience to developers and in minimizing the number and severity of conflicts that actually occur.

SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. Decentralized version control systems, such as Git and Mercurial, are exclusively merging-based.

VC mode supports both locking and merging version control. The terms “commit” and “update” are used in newer version control systems; older lock-based systems use the terms “check in” and “check out”. VC hides the differences between them as much as possible.

28.1.1.5 Changeset-based vs File-based Version Control

On SCCS, RCS, CVS, and other early version control systems (and also in SRC), version control operations are file-based: each file has its own comment and revision history separate from that of all other files. Newer systems, beginning with Subversion, are changeset-based: a commit may include changes to several files, and the entire set of changes is handled as a unit. Any comment associated with the change does not belong to a single file, but to the changeset itself.

Changeset-based version control is more flexible and powerful than file-based version control; usually, when a change to multiple files has to be reversed, it’s good to be able to easily identify and remove all of it.

28.1.1.6 Decentralized vs Centralized Repositories

Early version control systems were designed around a centralized model in which each project has only one repository used by all developers. SCCS, RCS, CVS, Subversion, and SRC share this kind of model. One of its drawbacks is that the repository is a choke point for reliability and efficiency.

GNU Arch pioneered the concept of distributed or decentralized version control, later implemented in Git, Mercurial, and Bazaar. A project may have several different repositories, and these systems support a sort of super-merge between repositories that tries to reconcile their change histories. In effect, there is one repository for each developer, and repository merges take the place of commit operations.

VC helps you manage the traffic between your personal workfiles and a repository. Whether the repository is a single master, or one of a network of peer repositories, is not something VC has to care about.

28.1.1.7 Types of Log File

Projects that use a version control system can have two types of log for changes. One is the log maintained by the version control system: each time you commit a change, you fill out a log entry for the change (see Log Buffer). This is called the version control log.

The other kind of log is the file ChangeLog (see Change Log). It provides a chronological record of all changes to a large portion of a program—typically one directory and its subdirectories. A small program would use one ChangeLog file; a large program may have a ChangeLog file in each major directory. See Change Log. Programmers have used change logs since long before version control systems.

Changeset-based version systems typically maintain a changeset-based modification log for the entire system, which makes change log files somewhat redundant. One advantage that they retain is that it is sometimes useful to be able to view the transaction history of a single directory separately from those of other directories. Another advantage is that commit logs can’t be fixed in many version control systems.

A project maintained with version control can use just the version control log, or it can use both kinds of logs. It can handle some files one way and some files the other way. Each project has its policy, which you should follow.

When the policy is to use both, you typically want to write an entry for each change just once, then put it into both logs. You can write the entry in ChangeLog, then copy it to the log buffer with C-c C-a when committing the change (see Log Buffer). Or you can write the entry in the log buffer while committing the change (with the help of C-c C-w), and later use the C-x v a command to copy it to ChangeLog (see Change Logs and VC).

28.1.2 Version Control and the Mode Line

When you visit a file that is under version control, Emacs indicates this on the mode line. For example, ‘Bzr-1223’ says that Bazaar is used for that file, and the current revision ID is 1223.

The character between the back-end name and the revision ID indicates the version control status of the work file. In a merge-based version control system, a ‘-’ character indicates that the work file is unmodified, and ‘:’ indicates that it has been modified. ‘!’ indicates that the file contains conflicts as result of a recent merge operation (see Merging), or that the file was removed from the version control. Finally, ‘?’ means that the file is under version control, but is missing from the working tree.

In a lock-based system, ‘-’ indicates an unlocked file, and ‘:’ a locked file; if the file is locked by another user (for instance, ‘jim’), that is displayed as ‘RCS:jim:1.3’. ‘@’ means that the file was locally added, but not yet committed to the master repository.

On a graphical display, you can move the mouse over this mode line indicator to pop up a tool-tip, which displays a more verbose description of the version control status. Pressing mouse-1 over the indicator pops up a menu of VC commands, identical to ‘Tools / Version Control’ on the menu bar.

When Auto Revert mode (see Reverting) reverts a buffer that is under version control, it updates the version control information in the mode line. However, Auto Revert mode may not properly update this information if the version control status changes without changes to the work file, from outside the current Emacs session. If you set auto-revert-check-vc-info to t, Auto Revert mode updates the version control status information every auto-revert-interval seconds, even if the work file itself is unchanged. The resulting CPU usage depends on the version control system, but is usually not excessive.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.3 Basic Editing under Version Control

Most VC commands operate on VC filesets. A VC fileset is a collection of one or more files that a VC operation acts on. When you type VC commands in a buffer visiting a version-controlled file, the VC fileset is simply that one file. When you type them in a VC Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (see VC Directory Mode).

On modern changeset-based version control systems (see VCS Changesets), VC commands handle multi-file VC filesets as a group. For example, committing a multi-file VC fileset generates a single revision, containing the changes to all those files. On older file-based version control systems like CVS, each file in a multi-file VC fileset is handled individually; for example, a commit generates one revision for each changed file.

C-x v v

Perform the next appropriate version control operation on the current VC fileset.

The principal VC command is a multi-purpose command, C-x v v (vc-next-action), which performs the most appropriate action on the current VC fileset: either registering it with a version control system, or committing it, or unlocking it, or merging changes into it. The precise actions are described in detail in the following subsections. You can use C-x v v either in a file-visiting buffer or in a VC Directory buffer.

Note that VC filesets are distinct from the named filesets used for viewing and visiting files in functional groups (see Filesets). Unlike named filesets, VC filesets are not named and don’t persist across sessions.

28.1.3.1 Basic Version Control with Merging

On a merging-based version control system (i.e., most modern ones; see VCS Merging), C-x v v does the following:

These rules also apply when you use RCS in its non-locking mode, except that changes are not automatically merged from the repository. Nothing informs you if another user has committed changes in the same file since you began editing it; when you commit your revision, that other user’s changes are removed (however, they remain in the repository and are thus not irrevocably lost). Therefore, you must verify that the current revision is unchanged before committing your changes. In addition, locking is possible with RCS even in this mode: C-x v v with an unmodified file locks the file, just as it does with RCS in its normal locking mode (see VC With A Locking VCS).

28.1.3.2 Basic Version Control with Locking

On a locking-based version control system (such as SCCS, and RCS in its default mode), C-x v v does the following:

These rules also apply when you use CVS in locking mode, except that CVS does not support stealing locks.

28.1.3.3 Advanced Control in C-x v v

When you give a prefix argument to vc-next-action (C-u C-x v v), it still performs the next logical version control operation, but accepts additional arguments to specify precisely how to do the operation.

28.1.4 Features of the Log Entry Buffer

When you tell VC to commit a change, it pops up a buffer named *vc-log*. In this buffer, you should write a log entry describing the changes you have made (see Why Version Control?). After you are done, type C-c C-c (log-edit-done) to exit the buffer and commit the change, together with your log entry.

The major mode for the *vc-log* buffer is Log Edit mode, a variant of Text mode (see Text Mode). On entering Log Edit mode, Emacs runs the hooks text-mode-hook and vc-log-mode-hook (see Hooks).

In the *vc-log* buffer, you can write one or more header lines, specifying additional information to be supplied to the version control system. Each header line must occupy a single line at the top of the buffer; the first line that is not a header line is treated as the start of the log entry. For example, the following header line states that the present change was not written by you, but by another developer:

Author: J. R. Hacker <jrh@example.com>

Apart from the ‘Author’ header, Emacs recognizes the headers ‘Summary’ (a one-line summary of the changeset), ‘Date’ (a manually-specified commit time), and ‘Fixes’ (a reference to a bug fixed by the change). Not all version control systems recognize all headers. If you specify a header for a system that does not support it, the header is treated as part of the log entry.

While in the *vc-log* buffer, the current VC fileset is considered to be the fileset that will be committed if you type C-c C-c. To view a list of the files in the VC fileset, type C-c C-f (log-edit-show-files). To view a diff of changes between the VC fileset and the version from which you started editing (see Old Revisions), type C-c C-d (log-edit-show-diff).

To help generate ChangeLog entries, type C-c C-w (log-edit-generate-changelog-from-diff), to generate skeleton ChangeLog entries, listing all changed file and function names based on the diff of the VC fileset. Consecutive entries left empty will be combined by C-q (fill-paragraph).

If the VC fileset includes one or more ChangeLog files (see Change Log), type C-c C-a (log-edit-insert-changelog) to pull the relevant entries into the *vc-log* buffer. If the topmost item in each ChangeLog was made under your user name on the current date, this command searches that item for entries matching the file(s) to be committed, and inserts them. If you are using CVS or RCS, see Change Logs and VC, for the opposite way of working—generating ChangeLog entries from the Log Edit buffer.

To abort a commit, just don’t type C-c C-c in that buffer. You can switch buffers and do other editing. As long as you don’t try to make another commit, the entry you were editing remains in the *vc-log* buffer, and you can go back to that buffer at any time to complete the commit.

You can also browse the history of previous log entries to duplicate a commit comment. This can be useful when you want to make several commits with similar comments. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (see Minibuffer History), except that they are used outside the minibuffer.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.5 Registering a File for Version Control

C-x v i

Register the visited file for version control.

The command C-x v i (vc-register) registers each file in the current VC fileset, placing it under version control. This is essentially equivalent to the action of C-x v v on an unregistered VC fileset (see Basic VC Editing), except that if the VC fileset is already registered, C-x v i signals an error whereas C-x v v performs some other action.

To register a file, Emacs must choose a version control system. For a multi-file VC fileset, the VC Directory buffer specifies the system to use (see VC Directory Mode). For a single-file VC fileset, if the file’s directory already contains files registered in a version control system, or if the directory is part of a directory tree controlled by a version control system, Emacs chooses that system. In the event that more than one version control system is applicable, Emacs uses the one that appears first in the variable vc-handled-backends (see Customizing VC). If Emacs cannot find a version control system to register the file under, it prompts for a repository type, creates a new repository, and registers the file into that repository.

On most version control systems, registering a file with C-x v i or C-x v v adds it to the working tree but not to the repository. Such files are labeled as ‘added’ in the VC Directory buffer, and show a revision ID of ‘@@’ in the mode line. To make the registration take effect in the repository, you must perform a commit (see Basic VC Editing). Note that a single commit can include both file additions and edits to existing files.

On a locking-based version control system (see VCS Merging), registering a file leaves it unlocked and read-only. Type C-x v v to start editing it.

28.1.6 Examining And Comparing Old Revisions

C-x v =

Compare the work files in the current VC fileset with the versions you started from (vc-diff). With a prefix argument, prompt for two revisions of the current VC fileset and compare them. You can also call this command from a Dired buffer (see Dired).

M-x vc-ediff

Like C-x v =, but using Ediff. See Ediff in The Ediff Manual.

C-x v D

Compare the entire working tree to the revision you started from (vc-root-diff). With a prefix argument, prompt for two revisions and compare their trees.

C-x v ~

Prompt for a revision of the current file, and visit it in a separate buffer (vc-revision-other-window).

C-x v g

Display an annotated version of the current file: for each line, show the latest revision in which it was modified (vc-annotate).

C-x v = (vc-diff) displays a diff which compares each work file in the current VC fileset to the version(s) from which you started editing. The diff is displayed in another window, in a Diff mode buffer (see Diff Mode) named *vc-diff*. The usual Diff mode commands are available in this buffer. In particular, the g (revert-buffer) command performs the file comparison again, generating a new diff.

To compare two arbitrary revisions of the current VC fileset, call vc-diff with a prefix argument: C-u C-x v =. This prompts for two revision IDs (see VCS Concepts), and displays a diff between those versions of the fileset. This will not work reliably for multi-file VC filesets, if the version control system is file-based rather than changeset-based (e.g., CVS), since then revision IDs for different files would not be related in any meaningful way.

Instead of the revision ID, some version control systems let you specify revisions in other formats. For instance, under Bazaar you can enter ‘date:yesterday’ for the argument to C-u C-x v = (and related commands) to specify the first revision committed after yesterday. See the documentation of the version control system for details.

If you invoke C-x v = or C-u C-x v = from a Dired buffer (see Dired), the file listed on the current line is treated as the current VC fileset.

M-x vc-ediff works like C-x v =, except that it uses an Ediff session. See Ediff in The Ediff Manual.

C-x v D (vc-root-diff) is similar to C-x v =, but it displays the changes in the entire current working tree (i.e., the working tree containing the current VC fileset). If you invoke this command from a Dired buffer, it applies to the working tree containing the directory.

To compare two arbitrary revisions of the whole trees, call vc-root-diff with a prefix argument: C-u C-x v D. This prompts for two revision IDs (see VCS Concepts), and displays a diff between those versions of the entire version-controlled directory trees (RCS, SCCS, CVS, and SRC do not support this feature).

You can customize the diff options that C-x v = and C-x v D use for generating diffs. The options used are taken from the first non-nil value amongst the variables vc-backend-diff-switches, vc-diff-switches, and diff-switches (see Comparing Files), in that order. Here, backend stands for the relevant version control system, e.g., bzr for Bazaar. Since nil means to check the next variable in the sequence, either of the first two may use the value t to mean no switches at all. Most of the vc-backend-diff-switches variables default to nil, but some default to t; these are for version control systems whose diff implementations do not accept common diff options, such as Subversion.

To directly examine an older version of a file, visit the work file and type C-x v ~ revision RET (vc-revision-other-window). This retrieves the file version corresponding to revision, saves it to filename.~revision~, and visits it in a separate window.

Many version control systems allow you to view files annotated with per-line revision information, by typing C-x v g (vc-annotate). This creates a new “annotate” buffer displaying the file’s text, with each line colored to show how old it is. Red text is new, blue is old, and intermediate colors indicate intermediate ages. By default, the color is scaled over the full range of ages, such that the oldest changes are blue, and the newest changes are red. If the variable vc-annotate-background-mode is non-nil, the colors expressing the age of each line are applied to the background color, leaving the foreground at its default color.

When you give a prefix argument to this command, Emacs reads two arguments using the minibuffer: the revision to display and annotate (instead of the current file contents), and the time span in days the color range should cover.

From the “annotate” buffer, these and other color scaling options are available from the ‘VC-Annotate’ menu. In this buffer, you can also use the following keys to browse the annotations of past revisions, view diffs, or view log entries:

p

Annotate the previous revision, i.e., the revision before the one currently annotated. A numeric prefix argument is a repeat count, so C-u 10 p would take you back 10 revisions.

n

Annotate the next revision, i.e., the revision after the one currently annotated. A numeric prefix argument is a repeat count.

j

Annotate the revision indicated by the current line.

a

Annotate the revision before the one indicated by the current line. This is useful to see the state the file was in before the change on the current line was made.

f

Show in a buffer the file revision indicated by the current line.

d

Display the diff between the current line’s revision and the previous revision. This is useful to see what the current line’s revision actually changed in the file.

D

Display the diff between the current line’s revision and the previous revision for all files in the changeset (for VC systems that support changesets). This is useful to see what the current line’s revision actually changed in the tree.

l

Show the log of the current line’s revision. This is useful to see the author’s description of the changes in the revision on the current line.

w

Annotate the working revision–the one you are editing. If you used p and n to browse to other revisions, use this key to return to your working revision.

v

Toggle the annotation visibility. This is useful for looking just at the file contents without distraction from the annotations.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.7 VC Change Log

C-x v l

Display the change history for the current fileset (vc-print-log).

C-x v L

Display the change history for the current repository (vc-print-root-log).

C-x v I

Display the changes that a “pull” operation will retrieve (vc-log-incoming).

C-x v O

Display the changes that will be sent by the next “push” operation (vc-log-outgoing).

C-x v h

Display the history of changes made in the region of file visited by the current buffer (vc-region-history).

M-x vc-log-search RET

Search the change history for a specified pattern.

C-x v l (vc-print-log) displays a buffer named *vc-change-log*, showing the history of changes made to the current file, including who made the changes, the dates, and the log entry for each change (these are the same log entries you would enter via the *vc-log* buffer; see Log Buffer). Point is centered at the revision of the file currently being visited. With a prefix argument, the command prompts for the revision to center on, and the maximum number of revisions to display.

If you call C-x v l from a VC Directory buffer (see VC Directory Mode) or a Dired buffer (see Dired), it applies to the file listed on the current line.

C-x v L (vc-print-root-log) displays a *vc-change-log* buffer showing the history of the entire version-controlled directory tree (RCS, SCCS, CVS, and SRC do not support this feature). With a prefix argument, the command prompts for the maximum number of revisions to display. A numeric prefix argument specifies the maximum number of revisions without prompting. When the numeric prefix argument is 1, as in C-1 C-x v L or C-u 1 C-x v L, the command prompts for the revision ID, and displays the log entry of that revision together with the changes (diffs) it introduced. (Some less capable version control systems, such as RCS and CVS, don’t have commands to show a revision log with its diffs; for them the command displays only the log entry, and you can request to show the diffs by typing d or D, see below.)

The C-x v L history is shown in a compact form, usually showing only the first line of each log entry. However, you can type RET (log-view-toggle-entry-display) in the *vc-change-log* buffer to reveal the entire log entry for the revision at point. A second RET hides it again.

On a decentralized version control system, the C-x v I (vc-log-incoming) command displays a log buffer showing the changes that will be applied, the next time you run the version control system’s pull command to get new revisions from another repository (see Pulling / Pushing). This other repository is the default one from which changes are pulled, as defined by the version control system; with a prefix argument, vc-log-incoming prompts for a specific repository. Similarly, C-x v O (vc-log-outgoing) shows the changes that will be sent to another repository, the next time you run the push command; with a prefix argument, it prompts for a specific destination repository.

In the *vc-change-log* buffer, you can use the following keys to move between the logs of revisions and of files, and to examine and compare past revisions (see Old Revisions):

p

Move to the previous revision entry. (Revision entries in the log buffer are usually in reverse-chronological order, so the previous revision-item usually corresponds to a newer revision.) A numeric prefix argument is a repeat count.

n

Move to the next revision entry. A numeric prefix argument is a repeat count.

P

Move to the log of the previous file, if showing logs for a multi-file VC fileset. Otherwise, just move to the beginning of the log. A numeric prefix argument is a repeat count.

N

Move to the log of the next file, if showing logs for a multi-file VC fileset. A numeric prefix argument is a repeat count.

a

Annotate the revision on the current line (see Old Revisions).

e

Modify the change comment displayed at point. Note that not all VC systems support modifying change comments.

f

Visit the revision indicated at the current line.

d

Display a diff between the revision at point and the next earlier revision, for the specific file.

D

Display the changeset diff between the revision at point and the next earlier revision. This shows the changes to all files made in that revision.

RET

In a compact-style log buffer (e.g., the one created by C-x v L), toggle between showing and hiding the full log entry for the revision at point.

Because fetching many log entries can be slow, the *vc-change-log* buffer displays no more than 2000 revisions by default. The variable vc-log-show-limit specifies this limit; if you set the value to zero, that removes the limit. You can also increase the number of revisions shown in an existing *vc-change-log* buffer by clicking on the ‘Show 2X entries’ or ‘Show unlimited entries’ buttons at the end of the buffer. However, RCS, SCCS, CVS, and SRC do not support this feature.

A useful variant of examining history of changes is provided by the command vc-region-history (by default bound to C-x v h), which shows a *VC-history* buffer with the history of changes made in the region of the current buffer’s file between point and the mark (see Mark). The history of changes includes the commit log messages and also the changes themselves in the Diff format.

Invoke this command after marking in the current buffer the region in whose changes you are interested. In the *VC-history* buffer it pops up, you can use all of the commands available in the *vc-change-log* buffer described above, and also the commands defined by Diff mode (see Diff Mode).

This command is currently available only with Git and Mercurial (hg).

The command vc-log-search allows searching for a pattern in the log of changes. It prompts for a pattern (a regular expression), and displays all entries in the change history whose log messages match the pattern. When invoked with a prefix argument, the command will also prompt for a specific VCS shell command to run for this purpose.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.8 Undoing Version Control Actions

C-x v u

Revert the work file(s) in the current VC fileset to the last revision (vc-revert).

If you want to discard all the changes you have made to the current VC fileset, type C-x v u (vc-revert). This shows you a diff between the work file(s) and the revision from which you started editing, and asks for confirmation for discarding the changes. If you agree, the fileset is reverted. If you don’t want C-x v u to show a diff, set the variable vc-revert-show-diff to nil (you can still view the diff directly with C-x v =; see Old Revisions).

On locking-based version control systems, C-x v u leaves files unlocked; you must lock again to resume editing. You can also use C-x v u to unlock a file if you lock it and then decide not to change it.

28.1.9 Ignore Version Control Files

C-x v G

Ignore a file under current version control system. (vc-ignore).

Many source trees contain some files that do not need to be versioned, such as editor backups, object or bytecode files, and built programs. You can simply not add them, but then they’ll always crop up as unknown files. You can also tell the version control system to ignore these files by adding them to the ignore file at the top of the tree. C-x v G (vc-ignore) can help you do this. When called with a prefix argument, you can remove a file from the ignored file list.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.10 VC Directory Mode

The VC Directory buffer is a specialized buffer for viewing the version control statuses of the files in a directory tree, and performing version control operations on those files. In particular, it is used to specify multi-file VC filesets for commands like C-x v v to act on (see VC Directory Commands).

To use the VC Directory buffer, type C-x v d (vc-dir). This reads a directory’s name using the minibuffer, and switches to a VC Directory buffer for that directory. By default, the buffer is named *vc-dir*. Its contents are described in VC Directory Buffer.

The vc-dir command automatically detects the version control system to be used in the specified directory. In the event that more than one system is being used in the directory, you should invoke the command with a prefix argument, C-u C-x v d; this prompts for the version control system which the VC Directory buffer should use.

In addition to the VC Directory buffer, Emacs has a similar facility called PCL-CVS which is specialized for CVS. See About PCL-CVS in PCL-CVS—The Emacs Front-End to CVS.

28.1.10.1 The VC Directory Buffer

The VC Directory buffer contains a list of version-controlled files and their version control statuses. It lists files in the current directory (the one specified when you called C-x v d) and its subdirectories, but only those with a noteworthy status. Files that are up-to-date (i.e., the same as in the repository) are omitted. If all the files in a subdirectory are up-to-date, the subdirectory is not listed either. As an exception, if a file has become up-to-date as a direct result of a VC command, it is listed.

Here is an example of a VC Directory buffer listing:

                     ./
    edited           configure.ac
*   added            README
    unregistered     temp.txt
                     src/
*   edited           src/main.c

Two work files have been modified but not committed: configure.ac in the current directory, and main.c in the src/ subdirectory. The file named README has been added but is not yet committed, while temp.txt is not under version control (see Registering).

The ‘*’ characters next to the entries for README and src/main.c indicate that the user has marked these files as the current VC fileset (see VC Directory Commands).

The above example is typical for a decentralized version control system like Bazaar, Git, or Mercurial. Other systems can show other statuses. For instance, CVS shows the ‘needs-update’ status if the repository has changes that have not been applied to the work file. RCS and SCCS show the name of the user locking a file as its status.

On CVS, the vc-dir command normally contacts the repository, which may be on a remote machine, to check for updates. If you change the variable vc-cvs-stay-local to nil (see CVS Options), then Emacs avoids contacting a remote repository when generating the VC Directory buffer (it will still contact it when necessary, e.g., when doing a commit). This may be desirable if you are working offline or the network is slow.

The VC Directory buffer omits subdirectories listed in the variable vc-directory-exclusion-list. Its default value contains directories that are used internally by version control systems.

28.1.10.2 VC Directory Commands

Emacs provides several commands for navigating the VC Directory buffer, and for marking files as belonging to the current VC fileset.

n
SPC

Move point to the next entry (vc-dir-next-line).

p

Move point to the previous entry (vc-dir-previous-line).

TAB

Move to the next directory entry (vc-dir-next-directory).

S-TAB

Move to the previous directory entry (vc-dir-previous-directory).

RET
f

Visit the file or directory listed on the current line (vc-dir-find-file).

o

Visit the file or directory on the current line, in a separate window (vc-dir-find-file-other-window).

m

Mark the file or directory on the current line (vc-dir-mark), putting it in the current VC fileset. If the region is active, mark all files in the region.

A file cannot be marked with this command if it is already in a marked directory, or one of its subdirectories. Similarly, a directory cannot be marked with this command if any file in its tree is marked.

M

If point is on a file entry, mark all files with the same status; if point is on a directory entry, mark all files in that directory tree (vc-dir-mark-all-files). With a prefix argument, mark all listed files and directories.

G

Add the file under point to the list of files that the VC should ignore (vc-dir-ignore). For instance, if the VC is Git, it will append this file to the .gitignore file. If given a prefix, do this with all the marked files.

q

Quit the VC Directory buffer, and bury it (quit-window).

u

Unmark the file or directory on the current line. If the region is active, unmark all the files in the region (vc-dir-unmark).

U

If point is on a file entry, unmark all files with the same status; if point is on a directory entry, unmark all files in that directory tree (vc-dir-unmark-all-files). With a prefix argument, unmark all files and directories.

x

Hide files with ‘up-to-date’ or ‘ignored’ status (vc-dir-hide-up-to-date). With a prefix argument, hide items whose state is that of the item at point.

While in the VC Directory buffer, all the files that you mark with m (vc-dir-mark) or M (vc-dir-mark-all-files) are in the current VC fileset. If you mark a directory entry with m, all the listed files in that directory tree are in the current VC fileset. The files and directories that belong to the current VC fileset are indicated with a ‘*’ character in the VC Directory buffer, next to their VC status. In this way, you can set up a multi-file VC fileset to be acted on by VC commands like C-x v v (see Basic VC Editing), C-x v = (see Old Revisions), and C-x v u (see VC Undo).

The VC Directory buffer also defines some single-key shortcuts for VC commands with the C-x v prefix: =, +, l, i, D, L, G, I, O, and v.

For example, you can commit a set of edited files by opening a VC Directory buffer, where the files are listed with the ‘edited’ status; marking the files; and typing v or C-x v v (vc-next-action). If the version control system is changeset-based, Emacs will commit the files in a single revision.

While in the VC Directory buffer, you can also perform search and replace on the current VC fileset, with the following commands:

S

Search the fileset (vc-dir-search).

Q

Do a regular expression query replace on the fileset (vc-dir-query-replace-regexp).

M-s a C-s

Do an incremental search on the fileset (vc-dir-isearch).

M-s a C-M-s

Do an incremental regular expression search on the fileset (vc-dir-isearch-regexp).

Apart from acting on multiple files, these commands behave much like their single-buffer counterparts (see Search).

The VC Directory buffer additionally defines some branch-related commands starting with the prefix B:

B c

Create a new branch (vc-create-tag).

B l

Prompt for the name of a branch and display the change history of that branch (vc-print-branch-log).

B s

Switch to a branch (vc-retrieve-tag). See Switching Branches.

d

Delete the marked files, or the current file if no marks (vc-dir-clean-delete). The files will not be marked as deleted in the version control system, so this function is mostly useful for unregistered files.

The above commands are also available via the menu bar, and via a context menu invoked by mouse-2. Furthermore, some VC backends use the menu to provide extra backend-specific commands. For example, Git and Bazaar allow you to manipulate stashes and shelves (which are a way to temporarily put aside uncommitted changes, and bring them back at a later time).

28.1.11 Version Control Branches

One use of version control is to support multiple independent lines of development, which are called branches. Amongst other things, branches can be used for maintaining separate stable and development versions of a program, and for developing unrelated features in isolation from one another.

VC’s support for branch operations is currently fairly limited. For decentralized version control systems, it provides commands for updating one branch with the contents of another, and for merging the changes made to two different branches (see Merging). For centralized version control systems, it supports checking out different branches and committing into new or different branches.

28.1.11.1 Switching between Branches

The various version control systems differ in how branches are implemented, and these differences cannot be entirely concealed by VC.

On some decentralized version control systems, including Bazaar and Mercurial in its normal mode of operation, each branch has its own working directory tree, so switching between branches just involves switching directories. On Git, branches are normally co-located in the same directory, and switching between branches is done using the git checkout command, which changes the contents of the working tree to match the branch you switch to. Bazaar also supports co-located branches, in which case the bzr switch command will switch branches in the current directory. With Subversion, you switch to another branch using the svn switch command. With Mercurial, command hg update is used to swith to another branch.

The VC command to switch to another branch in the current directory is C-x v r branch-name RET (vc-retrieve-tag).

On centralized version control systems, you can also switch between branches by typing C-u C-x v v in an up-to-date work file (see Advanced C-x v v), and entering the revision ID for a revision on another branch. On CVS, for instance, revisions on the trunk (the main line of development) normally have IDs of the form 1.1, 1.2, 1.3, …, while the first branch created from (say) revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, …, the second branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, …, and so forth. You can also specify the branch ID, which is a branch revision ID omitting its final component (e.g., 1.2.1), to switch to the latest revision on that branch.

On a locking-based system, switching to a different branch also unlocks (write-protects) the working tree.

Once you have switched to a branch, VC commands will apply to that branch until you switch away; for instance, any VC filesets that you commit will be committed to that specific branch.

Next: , Previous: , Up: Branches   [Contents][Index]

28.1.11.2 Pulling/Pushing Changes into/from a Branch

C-x v P

On a decentralized version control system, update another location with changes from the current branch (a.k.a. “push” changes). This concept does not exist for centralized version control systems

C-x v +

On a decentralized version control system, update the current branch by “pulling in” changes from another location.

On a centralized version control system, update the current VC fileset.

On a decentralized version control system, the command C-x v P (vc-push) updates another location with changes from the current branch. With a prefix argument, it prompts for the exact version control command to run, which lets you specify where to push changes; the default is bzr push with Bazaar, git push with Git, and hg push with Mercurial. The default commands always push to a default location determined by the version control system from your branch configuration.

Prior to pushing, you can use C-x v O (vc-log-outgoing) to view a log buffer of the changes to be sent. See VC Change Log.

This command is currently supported only by Bazaar, Git, and Mercurial. The concept of “pushing” does not exist for centralized version control systems, where this operation is a part of committing a changeset, so invoking this command on a centralized VCS signals an error. This command also signals an error when attempted in a Bazaar bound branch, where committing a changeset automatically pushes the changes to the remote repository to which the local branch is bound.

On a decentralized version control system, the command C-x v + (vc-pull) updates the current branch and working tree. It is typically used to update a copy of a remote branch. If you supply a prefix argument, the command prompts for the exact version control command to use, which lets you specify where to pull changes from. Otherwise, it pulls from a default location determined by the version control system.

Amongst decentralized version control systems, C-x v + is currently supported only by Bazaar, Git, and Mercurial. With Bazaar, it calls bzr pull for ordinary branches (to pull from a master branch into a mirroring branch), and bzr update for a bound branch (to pull from a central repository). With Git, it calls git pull to fetch changes from a remote repository and merge it into the current branch. With Mercurial, it calls hg pull -u to fetch changesets from the default remote repository and update the working directory.

Prior to pulling, you can use C-x v I (vc-log-incoming) to view a log buffer of the changes to be applied. See VC Change Log.

On a centralized version control system like CVS, C-x v + updates the current VC fileset from the repository.

28.1.11.3 Merging Branches

C-x v m

On a decentralized version control system, merge changes from another branch into the current one.

On a centralized version control system, merge changes from another branch into the current VC fileset.

While developing a branch, you may sometimes need to merge in changes that have already been made in another branch. This is not a trivial operation, as overlapping changes may have been made to the two branches.

On a decentralized version control system, merging is done with the command C-x v m (vc-merge). On Bazaar, this prompts for the exact arguments to pass to bzr merge, offering a sensible default if possible. On Git, this prompts for the name of a branch to merge from, with completion (based on the branch names known to the current repository). With Mercurial, this prompts for argument to pass to hg merge. The output from running the merge command is shown in a separate buffer.

On a centralized version control system like CVS, C-x v m prompts for a branch ID, or a pair of revision IDs (see Switching Branches); then it finds the changes from that branch, or the changes between the two revisions you specified, and merges those changes into the current VC fileset. If you just type RET, Emacs simply merges any changes that were made on the same branch since you checked the file out.

Immediately after performing a merge, only the working tree is modified, and you can review the changes produced by the merge with C-x v D and related commands (see Old Revisions). If the two branches contained overlapping changes, merging produces a conflict; a warning appears in the output of the merge command, and conflict markers are inserted into each affected work file, surrounding the two sets of conflicting changes. You must then resolve the conflict by editing the conflicted files. Once you are done, the modified files must be committed in the usual way for the merge to take effect (see Basic VC Editing).

Previous: , Up: Branches   [Contents][Index]

28.1.11.4 Creating New Branches

On centralized version control systems like CVS, Emacs supports creating new branches as part of a commit operation. When committing a modified VC fileset, type C-u C-x v v (vc-next-action with a prefix argument; see Advanced C-x v v). Then Emacs prompts for a revision ID for the new revision. You should specify a suitable branch ID for a branch starting at the current revision. For example, if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point.

To create a new branch at an older revision (one that is no longer the head of a branch), first select that revision (see Switching Branches). Your procedure will then differ depending on whether you are using a locking or merging-based VCS.

On a locking VCS, you will need to lock the old revision branch with C-x v v. You’ll be asked to confirm, when you lock the old revision, that you really mean to create a new branch—if you say no, you’ll be offered a chance to lock the latest revision instead. On a merging-based VCS you will skip this step.

Then make your changes and type C-x v v again to commit a new revision. This creates a new branch starting from the selected revision.

After the branch is created, subsequent commits create new revisions on that branch. To leave the branch, you must explicitly select a different revision with C-u C-x v v.

Next: , Previous: , Up: Version Control   [Contents][Index]

28.1.12 Miscellaneous Commands and Features of VC

This section explains the less-frequently-used features of VC.

28.1.12.1 Change Logs and VC

If you use RCS or CVS for a program with a ChangeLog file (see Change Log), you can generate change log entries from the version control log entries of previous commits.

Note that this only works with RCS or CVS. This procedure would be particularly incorrect on a modern changeset-based version control system, where changes to the ChangeLog file would normally be committed as part of a changeset. In that case, you should write the change log entries first, then pull them into the ‘*vc-log*’ buffer when you commit (see Log Buffer).

C-x v a

Visit the current directory’s ChangeLog file and, for registered files in that directory, create new entries for versions committed since the most recent change log entry (vc-update-change-log).

C-u C-x v a

As above, but only find entries for the current buffer’s file.

For example, suppose the first line of ChangeLog is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to rcs2log on 1999-05-22 with log entry ‘Ignore log messages that start with '#'.’. Then C-x v a inserts this ChangeLog entry:

1999-05-22  Nathaniel Bowditch  <nat@apn.org>

        * rcs2log: Ignore log messages that start with '#'.

If the version control log entry specifies a function name (in parenthesis at the beginning of a line), that is reflected in the ChangeLog entry. For example, if a log entry for vc.el is ‘(vc-do-command): Check call-process status.’, the ChangeLog entry is:

1999-05-06  Nathaniel Bowditch  <nat@apn.org>

        * vc.el (vc-do-command): Check call-process status.

When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry.

28.1.12.2 Deleting and Renaming Version-Controlled Files

M-x vc-delete-file

Prompt for a file name, delete the file from the working tree, and schedule the deletion for committing.

M-x vc-rename-file

Prompt for two file names, old and new, rename them in the working tree, and schedule the renaming for committing. The old file defaults to the current buffer’s file name if it is under VC.

If you wish to delete a version-controlled file, use the command M-x vc-delete-file. This prompts for the file name, and deletes it via the version control system. The file is removed from the working tree, and in the VC Directory buffer (see VC Directory Mode), it is displayed with the ‘removed’ status. When you commit it, the deletion takes effect in the repository.

To rename a version-controlled file, type M-x vc-rename-file. This prompts for two arguments: the name of the file you wish to rename, and the new name; then it performs the renaming via the version control system. The renaming takes effect immediately in the working tree, and takes effect in the repository when you commit the renamed file.

On modern version control systems that have built-in support for renaming, the renamed file retains the full change history of the original file. On CVS and older version control systems, the vc-rename-file command actually works by creating a copy of the old file under the new name, registering it, and deleting the old file. In this case, the change history is not preserved.

28.1.12.3 Revision Tags

Most version control systems allow you to apply a revision tag to a specific version of a version-controlled tree. On modern changeset-based version control systems, a revision tag is simply a symbolic name for a particular revision. On older file-based systems like CVS, each tag is added to the entire set of version-controlled files, allowing them to be handled as a unit. Revision tags are commonly used to identify releases that are distributed to users.

There are two basic commands for tags; one makes a tag with a given name, the other retrieves a named tag.

C-x v s name RET

Define the working revision of every registered file in or under the current directory as a tag named name (vc-create-tag).

C-x v r name RET

For all registered files at or below the current directory level, retrieve the tagged revision name. This command will switch to a branch if name is a branch name and your VCS distinguishes branches from tags. (vc-retrieve-tag).

This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress.

You can give a tag or branch name as an argument to C-x v = or C-x v ~ (see Old Revisions). Thus, you can use it to compare a tagged version against the current files, or two tagged versions against each other.

On SCCS, VC implements tags itself; these tags are visible only through VC. Most later systems (including CVS, Subversion, bzr, git, and hg) have a native tag facility, and VC uses it where available; those tags will be visible even when you bypass VC.

In file-based version control systems, when you rename a registered file you need to rename its master along with it; the command vc-rename-file will do this automatically (see VC Delete/Rename). If you are using SCCS, you must also update the records of the tag, to mention the file by its new name (vc-rename-file does this, too). An old tag that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the tags by hand. Using vc-rename-file makes the tag remain valid for retrieval, but it does not solve all problems. For example, some of the files in your program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old tag, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won’t really work as retrieved.

28.1.12.4 Inserting Version Control Headers

On Subversion, CVS, RCS, and SCCS, you can put certain special strings called version headers into a work file. When the file is committed, the version control system automatically puts the revision number, the name of the user who made the commit, and other relevant information into the version header.

VC does not normally use the information in the version headers. As an exception, when using RCS, Emacs uses the version header, if there is one, to determine the file version, since it is often more reliable than the RCS master file. To inhibit using the version header this way, change the variable vc-consult-headers to nil. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

To insert a suitable header string into the current buffer, use the command M-x vc-insert-headers. This command works only on Subversion, CVS, RCS, and SCCS. The variable vc-backend-header contains the list of keywords to insert into the version header; for instance, CVS uses vc-cvs-header, whose default value is '("\$Id\$"). (The extra backslashes prevent the string constant from being interpreted as a header, if the Emacs Lisp file defining it is maintained with version control.) The vc-insert-headers command inserts each keyword in the list on a new line at point, surrounded by tabs, and inside comment delimiters if necessary.

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form (regexp . format). Whenever regexp matches the buffer name, format is also inserted as part of the version header. A ‘%s’ in format is replaced with the file’s version control type.

28.1.13 Customizing VC

The variable vc-handled-backends determines which version control systems VC should handle. The default value is (RCS CVS SVN SCCS SRC Bzr Git Hg Mtn), so it contains all the version systems that are currently supported. If you want VC to ignore one or more of these systems, exclude its name from the list. To disable VC entirely, set this variable to nil.

The order of systems in the list is significant: when you visit a file registered in more than one system, VC uses the system that comes first in vc-handled-backends by default. The order is also significant when you register a file for the first time (see Registering).

28.1.13.1 General Options

Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable vc-make-backup-files to a non-nil value.

Editing a version-controlled file through a symbolic link may cause unexpected results, if you are unaware that the underlying file is version-controlled. The variable vc-follow-symlinks controls what Emacs does if you try to visit a symbolic link pointing to a version-controlled file. If the value is ask (the default), Emacs asks for confirmation. If it is nil, Emacs just displays a warning message. If it is t, Emacs automatically follows the link and visits the real file instead.

If vc-suppress-confirm is non-nil, then C-x v v and C-x v i can save the current buffer without asking, and C-x v u also operates without asking for confirmation.

VC mode does much of its work by running the shell commands for the appropriate version control system. If vc-command-messages is non-nil, VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish.

28.1.13.2 Options for RCS and SCCS

By default, RCS uses locking to coordinate the activities of several users, but there is a mode called non-strict locking in which you can check-in changes without locking the file first. Use ‘rcs -U’ to switch to non-strict locking for a particular file, see the rcs manual page for details.

When deducing the version control state of an RCS file, VC first looks for an RCS version header string in the file (see Version Headers). If there is no header string, VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you if there’s any lock on the file, but not whether your work file really contains that locked version.

You can tell VC not to use version headers to determine the file status by setting vc-consult-headers to nil. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

VC determines the version control state of files under SCCS much as with RCS. It does not consider SCCS version headers, though. Thus, the variable vc-consult-headers does not affect SCCS use.

Previous: , Up: Customizing VC   [Contents][Index]

28.1.13.3 Options specific for CVS

You can specify additional command line options to pass to all CVS operations in the variable vc-cvs-global-switches. These switches are inserted immediately after the cvs command, before the name of the operation to invoke.

When using a CVS repository on a remote machine, VC can try keeping network interactions to a minimum. This is controlled by the variable vc-cvs-stay-local. If vc-cvs-stay-local is only-file (the default), VC determines the version control status of each file using only the entry in the local CVS subdirectory and the information returned by previous CVS commands. As a consequence, if you have modified a file and somebody else has checked in other changes, you will not be notified of the conflict until you try to commit.

If you change vc-cvs-stay-local to nil, VC queries the remote repository before it decides what to do in vc-next-action (C-x v v), just as it does for local repositories.

You can also set vc-cvs-stay-local to a regular expression that is matched against the repository host name; VC then stays local only for repositories from hosts that match the pattern.

When using a remote repository, Emacs normally makes automatic version backups of the original versions of each edited file. These local backups are made whenever you save the first changes to a file, and they are removed after you commit your changes to the repository. (Note that these are not the same as ordinary Emacs backup files; see Backup.) Commands like C-x v = and C-x v u make use of automatic version backups, if possible, to avoid having to access the network.

Setting vc-cvs-stay-local to nil disables the making of automatic version backups.

Automatic version backups have names of the form file.~version.~. This is similar to the name that C-x v ~ saves old versions to (see Old Revisions), except for the additional dot (‘.’) after the version. The relevant VC commands can use both kinds of version backups. The main difference is that the manual version backups made by C-x v ~ are not deleted automatically when you commit.

CVS does not use locking by default, but there are ways to enable locking-like behavior using its CVSREAD or watch feature; see the CVS documentation for details. If that case, you can use C-x v v in Emacs to toggle locking, as you would for a locking-based version control system (see VC With A Locking VCS).

Next: , Previous: , Up: Maintaining   [Contents][Index]

28.2 Working with Projects

A project is a collection of files used for producing one or more programs. Files that belong to a project are typically stored in a hierarchy of directories; the top-level directory of the hierarchy is known as the project root.

Whether a given directory is a root of some project is determined by the project-specific infrastructure, known as project back-end. Emacs currently supports two such back-ends: VC (see Version Control), whereby a VCS repository is considered a project; and EDE (see EDE). This is expected to be extended in the future to support additional types of projects.

Which files do or don’t belong to a project is also determined by the project back-end. For example, the VC back-end doesn’t consider “ignored” files (see VC Ignore) to be part of the project.

Emacs provides commands for handling project files conveniently. This section describes these commands.

All of the commands described here share the notion of the current project. The current project is determined by the default-directory (see File Names) of the buffer that is the current buffer when the command is invoked. If that directory doesn’t seem to belong to a recognizable project, these commands prompt you for the project directory.

The command project-find-file is a convenient way of visiting files (see Visiting) that belong to the current project. Unlike C-x C-f, this command doesn’t require to type the full file name of the file to visit, you can type only the file’s base name (i.e., omit the leading directories). In addition, the completion candidates considered by the command include only the files belonging to the current project, and nothing else. If there’s a file name at point, this command offers that file as the default to visit.

The command project-find-regexp is similar to rgrep (see Grep Searching), but it searches only the files that belong to the current project. The command prompts for the regular expression to search, and pops up an Xref mode buffer with the search results, where you can select a match using the Xref mode commands (see Xref Commands). When invoked with a prefix argument, this command additionally prompts for the base directory from which to start the search; this allows, for example, to limit the search only to project files under a certain subdirectory of the project root.

M-x project-search is an interactive variant of project-find-regexp. It prompts for a regular expression to search in the current project’s files, but instead of finding all the matches and displaying them, it stops when it finds a match and visits the matched file at the locus of the match, allowing you to edit the matched file. To find the rest of the matches, type M-x fileloop-continue RET.

M-x project-query-replace-regexp is similar to project-search, but it prompts you for whether to replace each match it finds, like query-replace does (see Query Replace), and continues to the next match after you respond. If your response causes Emacs to exit the query-replace loop, you can later continue with M-x fileloop-continue RET.

Next: , Previous: , Up: Maintaining   [Contents][Index]

28.3 Change Logs

Many software projects keep a change log. This is a file, normally named ChangeLog, containing a chronological record of when and how the program was changed. Sometimes, these files are automatically generated from the change log entries stored in version control systems, or are used to generate these change log entries. Sometimes, there are several change log files, each recording the changes in one directory or directory tree.

28.3.1 Change Log Commands

The Emacs command C-x 4 a adds a new entry to the change log file for the file you are editing (add-change-log-entry-other-window). If that file is actually a backup file, it makes an entry appropriate for the file’s parent—that is useful for making log entries for functions that have been deleted in the current version.

C-x 4 a visits the change log file and creates a new entry unless the most recent entry is for today’s date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed.

To find the change log file, Emacs searches up the directory tree from the file you are editing. By default, it stops if it finds a directory that seems to be the root of a version-control repository. To change this, customize change-log-directory-files.

When the variable add-log-keep-changes-together is non-nil, C-x 4 a adds to any existing item for the file, rather than starting a new item.

You can combine multiple changes of the same nature. If you don’t enter any text after the initial C-x 4 a, any subsequent C-x 4 a adds another symbol to the change log entry.

If add-log-always-start-new-record is non-nil, C-x 4 a always makes a new entry, even if the last entry was made by you and on the same date.

If the value of the variable change-log-version-info-enabled is non-nil, C-x 4 a adds the file’s version number to the change log entry. It finds the version number by searching the first ten percent of the file, using regular expressions from the variable change-log-version-number-regexp-list.

The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. C-j and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry.

You can use the command change-log-goto-source (by default bound to C-c C-c) to go to the source location of the change log entry near point, when Change Log mode is on. Then subsequent invocations of the next-error command (by default bound to M-g M-n and C-x `) will move between entries in the change log. You will jump to the actual site in the file that was changed, not just to the next change log entry. You can also use previous-error to move back through the change log entries.

You can use the command M-x change-log-merge to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries.

Version control systems are another way to keep track of changes in your program and keep a change log. Many projects that use a VCS don’t keep a separate versioned change log file nowadays, so you may wish to avoid having such a file in the repository. If the value of add-log-dont-create-changelog-file is non-nil, commands like C-x 4 a (add-change-log-entry-other-window) will record changes in a suitably named temporary buffer instead of a file, if such a file does not already exist.

Whether you have a change log file or use a temporary buffer for change logs, you can type C-c C-a (log-edit-insert-changelog) in the VC Log buffer to insert the relevant change log entries, if they exist. See Log Buffer.

28.3.2 Format of ChangeLog

A change log entry starts with a header line that contains the current date, your name (taken from the variable add-log-full-name), and your email address (taken from the variable add-log-mailing-address). Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of items, each of which starts with a line starting with whitespace and a star. Here are two entries, both dated in May 1993, with two items and one item respectively.

1993-05-25  Richard Stallman  <rms@gnu.org>

        * man.el: Rename symbols 'man-*' to 'Man-*'.
        (manual-entry): Make prompt string clearer.

        * simple.el (blink-matching-paren-distance):
        Change default to 12,000.

1993-05-24  Richard Stallman  <rms@gnu.org>

        * vc.el (minor-mode-map-alist): Don't use it if it's void.
        (vc-cancel-version): Doc fix.

One entry can describe several changes; each change should have its own item, or its own line in an item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them.

You should put a copyright notice and permission notice at the end of the change log file. Here is an example:

Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.

Of course, you should substitute the proper years and copyright holder.

Next: , Previous: , Up: Maintaining   [Contents][Index]

28.4 Find Identifier References

An identifier is a name of a syntactical subunit of the program: a function, a subroutine, a method, a class, a data type, a macro, etc. In a programming language, each identifier is a symbol in the language’s syntax. Program development and maintenance requires capabilities to quickly find where each identifier was defined and referenced, to rename identifiers across the entire project, etc.

These capabilities are also useful for finding references in major modes other than those defined to support programming languages. For example, chapters, sections, appendices, etc. of a text or a TeX document can be treated as subunits as well, and their names can be used as identifiers. In this chapter, we use the term “identifiers” to collectively refer to the names of any kind of subunits, in program source and in other kinds of text alike.

Emacs provides a unified interface to these capabilities, called ‘xref’.

To do its job, xref needs to make use of information and to employ methods specific to the major mode. What files to search for identifiers, how to find references to identifiers, how to complete on identifiers—all this and more is mode-specific knowledge. xref delegates the mode-specific parts of its job to a backend provided by the mode; it also includes defaults for some of its commands, for those modes that don’t provide their own.

A backend can implement its capabilities in a variety of ways. Here are a few examples:

  1. Some major modes provide built-in means for looking up the language symbols. For example, Emacs Lisp symbols can be identified by searching the package load history, maintained by the Emacs Lisp interpreter, and by consulting the built-in documentation strings; the Emacs Lisp mode uses these facilities in its backend to allow finding definitions of symbols. (One disadvantage of this kind of backend is that it only knows about subunits that were loaded into the interpreter.)
  2. An external program can extract references by scanning the relevant files, and build a database of these references. A backend can then access this database whenever it needs to list or look up references. The Emacs distribution includes etags, a command for tagging identifier definitions in programs, which supports many programming languages and other major modes, such as HTML, by extracting references into tags tables. See Create Tags Table. Major modes for languages supported by etags can use tags tables as basis for their backend. (One disadvantage of this kind of backend is that tags tables need to be kept reasonably up to date, by rebuilding them from time to time.)

Next: , Up: Xref   [Contents][Index]

28.4.1 Find Identifiers

This subsection describes the commands that find references to identifiers and perform various queries about identifiers. Each such reference could define an identifier, e.g., provide the implementation of a program subunit or the text of a document section; or it could use the identifier, e.g., call a function or a method, assign a value to a variable, mention a chapter in a cross-reference, etc.

28.4.1.1 Looking Up Identifiers

The most important thing that xref enables you to do is to find the definition of a specific identifier.

M-.

Find definitions of an identifier (xref-find-definitions).

C-M-. pattern RET

Find all identifiers whose name matches pattern (xref-find-apropos).

C-x 4 . RET

Find definitions of identifier, but display it in another window (xref-find-definitions-other-window).

C-x 5 . RET

Find definition of identifier, and display it in a new frame (xref-find-definitions-other-frame).

M-x xref-find-definitions-at-mouse

Find definition of identifier at mouse click.

M-,

Go back to where you previously invoked M-. and friends (xref-pop-marker-stack).

M-x xref-etags-mode

Switch xref to use the etags backend.

M-. (xref-find-definitions) shows the definitions of the identifier at point. With a prefix argument, or if there’s no identifier at point, it prompts for the identifier. (If you want it to always prompt, customize xref-prompt-for-identifier to t.)

If the specified identifier has only one definition, the command jumps to it. If the identifier has more than one possible definition (e.g., in an object-oriented language, or if there’s a function and a variable by the same name), the command shows the candidate definitions in the *xref* buffer, together with the files in which these definitions are found. Selecting one of these candidates by typing RET or clicking mouse-2 will pop a buffer showing the corresponding definition.

When entering the identifier argument to M-., the usual minibuffer completion commands can be used (see Completion), with the known identifier names as completion candidates.

Like most commands that can switch buffers, xref-find-definitions has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 . (xref-find-definitions-other-window), and the latter is C-x 5 . (xref-find-definitions-other-frame).

The command xref-find-definitions-at-mouse works like xref-find-definitions, but it looks for the identifier name at or around the place of a mouse event. This command is intended to be bound to a mouse event, such as C-M-mouse-1, for example.

The command C-M-. (xref-find-apropos) finds the definitions of one or more identifiers that match a specified regular expression. It is just like M-. except that it does regexp matching of identifiers instead of matching symbol names as fixed strings.

When any of the above commands finds more than one definition, it presents the *xref* buffer showing the definition candidates. In that buffer, you have several specialized commands, described in Xref Commands.

To go back to places from where you found the definition, use M-, (xref-pop-marker-stack). It jumps back to the point of the last invocation of M-.. Thus you can find and examine the definition of something with M-. and then return to where you were with M-,. M-, allows you to retrace your steps to a depth determined by the variable xref-marker-ring-length, which defaults to 16.

Some major modes install xref support facilities that might sometimes fail to find certain identifiers. For example, in Emacs Lisp mode (see Lisp Eval) M-. will by default find only functions and variables from Lisp packages which are loaded into the current Emacs session or are auto-loaded (see Autoload in The Emacs Lisp Reference Manual). If M-. fails to find some identifiers, you can try forcing xref to use the etags backend (see Xref). To this end, turn on the Xref Etags minor mode with M-x xref-etags-mode, then invoke M-. again. (For this to work, be sure to run etags to create the tags table in the directory tree of the source files, see Create Tags Table.)

28.4.1.2 Commands Available in the *xref* Buffer

The following commands are provided in the *xref* buffer by the special XREF mode:

RET
鼠标中键

Display the reference on the current line.

n
.

Move to the next reference and display it in the other window (xref-next-line).

p
,

Move to the previous reference and display it in the other window (xref-prev-line).

C-o

Display the reference on the current line in the other window (xref-show-location-at-point).

TAB

Display the reference on the current line and bury the *xref* buffer (xref-quit-and-goto-xref).

r pattern RET replacement RET

Perform interactive query-replace on references that match pattern (xref-query-replace-in-results), replacing the match with replacement. See Identifier Search.

g

Refresh the contents of the *xref* buffer (xref-revert-buffer.

q

Quit the window showing the *xref* buffer (xref-quit).

In addition, the usual navigation commands, such as the arrow keys, C-n, and C-p are available for moving around the buffer without displaying the references.

28.4.1.3 Searching and Replacing with Identifiers

The commands in this section perform various search and replace operations either on identifiers themselves or on files that reference them.

M-?

Find all the references for the identifier at point.

M-x xref-query-replace-in-results RET regexp RET replacement RET

Interactively replace regexp with replacement in the names of all the identifiers shown in the *xref* buffer.

M-x tags-search RET regexp RET

Search for regexp through the files in the selected tags table.

M-x tags-query-replace RET regexp RET replacement RET

Perform a query-replace-regexp on each file in the selected tags table.

M-x fileloop-continue

Restart one of the last 2 commands above, from the current location of point.

M-? finds all the references for the identifier at point, prompting for the identifier as needed, with completion. Depending on the current backend (see Xref), the command may prompt even if it finds a valid identifier at point. When invoked with a prefix argument, it always prompts for the identifier. (If you want it to prompt always, customize the value of the variable xref-prompt-for-identifier to t; or set it to nil to prompt only if there’s no usable identifier at point.) The command then presents the *xref* buffer with all the references to the identifier, showing the file name and the line where the identifier is referenced. The XREF mode commands are available in this buffer, see Xref Commands.

M-x xref-query-replace-in-results reads a regexp to match identifier names and a replacement string, just like ordinary M-x query-replace-regexp. It then performs the specified replacement in the names of the matching identifiers in all the places in all the files where these identifiers are referenced. This is useful when you rename your identifiers as part of refactoring. This command should be invoked in the *xref* buffer generated by M-?.

M-x tags-search reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, tags-search returns. This command requires tags tables to be available (see Tags Tables).

Having found one match with tags-search, you probably want to find all the rest. M-x fileloop-continue resumes the tags-search, finding one more match. This searches the rest of the current buffer, followed by the remaining files of the tags table.

M-x tags-query-replace performs a single query-replace-regexp through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary M-x query-replace-regexp. It searches much like M-x tags-search, but repeatedly, processing matches according to your input. See Query Replace, for more information on query replace.

You can control the case-sensitivity of tags search commands by customizing the value of the variable tags-case-fold-search. The default is to use the same setting as the value of case-fold-search (see Lax Search).

It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-x fileloop-continue; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type M-> M-x fileloop-continue.

Note that the commands described above carry out much broader searches than the xref-find-definitions family. The xref-find-definitions commands search only for definitions of identifiers that match your string or regexp. The commands xref-find-references, tags-search, and tags-query-replace find every occurrence of the identifier or regexp, as ordinary search commands and replace commands do in the current buffer.

As an alternative to xref-find-references and tags-search, you can run grep as a subprocess and have Emacs show you the matching lines one by one. See Grep Searching.

28.4.1.4 Identifier Inquiries

C-M-i
M-TAB

Perform completion on the text around point, possibly using the selected tags table if one is loaded (completion-at-point).

M-x xref-find-apropos RET regexp RET

Display a list of all known identifiers matching regexp.

M-x list-tags RET file RET

Display a list of the identifiers defined in the program file file.

M-x tags-next-file

Visit files recorded in the selected tags table.

In most programming language modes, you can type C-M-i or M-TAB (completion-at-point) to complete the symbol at point. Some modes provide specialized completion for this command tailored to the mode; for those that don’t, if there is a tags table loaded, this command can use it to generate completion candidates. See Symbol Completion.

M-x list-tags reads the name of one of the files covered by the selected tags table, and displays a list of tags defined in that file. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory. This command works only with the etags backend, and requires a tags table for the project to be available. See Tags Tables. If used interactively, the default tag is file name of the current buffer if used interactively.

M-x tags-next-file visits files covered by the selected tags table. The first time it is called, it visits the first file covered by the table. Each subsequent call visits the next covered file, unless a prefix argument is supplied, in which case it returns to the first file. This command requires a tags table to be selected.

Next: , Previous: , Up: Xref   [Contents][Index]

28.4.2 Tags Tables

A tags table records the tags15 extracted by scanning the source code of a certain program or a certain document. Tags extracted from generated files reference the original files, rather than the generated files that were scanned during tag extraction. Examples of generated files include C files generated from Cweb source files, from a Yacc parser, or from Lex scanner definitions; .i preprocessed C files; and Fortran files produced by preprocessing .fpp source files.

To produce a tags table, you run the etags shell command on a document or the source code file. The ‘etags’ program writes the tags to a tags table file, or tags file in short. The conventional name for a tags file is TAGS. See Create Tags Table. (It is also possible to create a tags table by using one of the commands from other packages that can produce such tables in the same format.)

Emacs uses the tags tables via the etags package as one of the supported backends for xref. Because tags tables are produced by the etags command that is part of an Emacs distribution, we describe tags tables in more detail here.

The Ebrowse facility is similar to etags but specifically tailored for C++. See Ebrowse in Ebrowse User’s Manual. The Semantic package provides another way to generate and use tags, separate from the etags facility. See Semantic.

28.4.2.1 Source File Tag Syntax

Here is how tag syntax is defined for the most popular languages:

Several other languages are also supported:

You can also generate tags based on regexp matching (see Etags Regexps) to handle other formats and languages.

Next: , Previous: , Up: Tags Tables   [Contents][Index]

28.4.2.2 Creating Tags Tables

The etags program is used to create a tags table file. It knows the syntax of several languages, as described in Tag Syntax. Here is how to run etags:

etags inputfiles

The etags program reads the specified files, and writes a tags table named TAGS in the current working directory. You can optionally specify a different file name for the tags table by using the ‘--output=file’ option; specifying - as a file name prints the tags table to standard output. You can also append the newly created tags table to an existing file by using the ‘--append’ option.

If the specified files don’t exist, etags looks for compressed versions of them and uncompresses them to read them. Under MS-DOS, etags also looks for file names like mycode.cgz if it is given ‘mycode.c’ on the command line and mycode.c does not exist.

If the tags table becomes outdated due to changes in the files described in it, you can update it by running the etags program again. If the tags table does not record a tag, or records it for the wrong file, then Emacs will not be able to find that definition until you update the tags table. But if the position recorded in the tags table becomes a little bit wrong (due to other editing), Emacs will still be able to find the right position, with a slight delay.

Thus, there is no need to update the tags table after each edit. You should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial.

You can make a tags table include another tags table, by passing the ‘--include=file’ option to etags. It then covers all the files covered by the included tags file, as well as its own.

If you specify the source files with relative file names when you run etags, the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files. If the tags file is - or is in the /dev directory, however, the file names are made relative to the current working directory. This is useful, for example, when writing the tags to the standard output.

When using a relative file name, it should not be a symbolic link pointing to a tags file in a different directory, because this would generally render the file names invalid.

If you specify absolute file names as arguments to etags, then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with ‘/’, or with ‘device:/’ on MS-DOS and MS-Windows.

When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. You can circumvent this limit by telling etags to read the file names from its standard input, by typing a dash in place of the file names, like this:

find . -name "*.[chCH]" -print | etags -

etags recognizes the language used in an input file based on its file name and contents. It first tries to match the file’s name and extension to the ones commonly used with certain languages. Some languages have interpreters with known names (e.g., perl for Perl or pl for Prolog), so etags next looks for an interpreter specification of the form ‘#!interp’ on the first line of an input file, and matches that against known interpreters. If none of that works, or if you want to override the automatic detection of the language, you can specify the language explicitly with the ‘--language=name’ option. You can intermix these options with file names; each one applies to the file names that follow it. Specify ‘--language=auto’ to tell etags to resume guessing the language from the file names and file contents. Specify ‘--language=none’ to turn off language-specific processing entirely; then etags recognizes tags by regexp matching alone (see Etags Regexps). This comes in handy when an input file uses a language not yet supported by etags, and you want to avoid having etags fall back on Fortran and C as the default languages.

The option ‘--parse-stdin=file’ is mostly useful when calling etags from programs. It can be used (only once) in place of a file name on the command line. etags will read from standard input and mark the produced tags as belonging to the file file.

etags --help’ outputs the list of the languages etags knows, and the file name rules for guessing the language. It also prints a list of all the available etags options, together with a short explanation. If followed by one or more ‘--language=lang’ options, it outputs detailed information about how tags are generated for lang.

28.4.2.3 Etags Regexps

The ‘--regex’ option to etags allows tags to be recognized by regular expression matching. You can intermix this option with file names; each one applies to the source files that follow it. If you specify multiple ‘--regex’ options, all of them are used in parallel. The syntax is:

--regex=[{language}]/tagregexp/[nameregexp/]modifiers

The essential part of the option value is tagregexp, the regexp for matching tags. It is always used anchored, that is, it only matches at the beginning of a line. If you want to allow indented tags, use a regexp that matches initial whitespace; start it with ‘[ \t]*’.

In these regular expressions, ‘\’ quotes the next character, and all the C character escape sequences are supported: ‘\a’ for bell, ‘\b’ for back space, ‘\e’ for escape, ‘\f’ for formfeed, ‘\n’ for newline, ‘\r’ for carriage return, ‘\t’ for tab, and ‘\v’ for vertical tab. In addition, ‘\d’ stands for the DEL character.

Ideally, tagregexp should not match more characters than are needed to recognize what you want to tag. If the syntax requires you to write tagregexp so it matches more characters beyond the tag itself, you should add a nameregexp, to pick out just the tag. This will enable Emacs to find tags more accurately and to do completion on tag names more reliably. In nameregexp, it is frequently convenient to use “back references” (see Regexp Backslash) to parenthesized groupings ‘\( … \) in tagregexp. For example, ‘\1’ refers to the first such parenthesized grouping. You can find some examples of this below.

The modifiers are a sequence of zero or more characters that modify the way etags does the matching. A regexp with no modifiers is applied sequentially to each line of the input file, in a case-sensitive way. The modifiers and their meanings are:

i

Ignore case when matching this regexp.

m

Match this regular expression against the whole file, so that multi-line matches are possible.

s

Match this regular expression against the whole file, and allow ‘.’ in tagregexp to match newlines.

The ‘-R’ option cancels all the regexps defined by preceding ‘--regex’ options. It too applies to the file names following it. Here’s an example:

etags --regex=/reg1/i voo.doo --regex=/reg2/m \
    bar.ber -R --lang=lisp los.er

Here etags chooses the parsing language for voo.doo and bar.ber according to their contents. etags also uses reg1 to recognize additional tags in voo.doo, and both reg1 and reg2 to recognize additional tags in bar.ber. reg1 is checked against each line of voo.doo and bar.ber, in a case-insensitive way, while reg2 is checked against the whole bar.ber file, permitting multi-line matches, in a case-sensitive way. etags uses only the Lisp tags rules, with no user-specified regexp matching, to recognize tags in los.er.

You can restrict a ‘--regex’ option to match only files of a given language by using the optional prefix {language}. (‘etags --help’ prints the list of languages recognized by etags.) This is particularly useful when storing many predefined regular expressions for etags in a file. The following example tags the DEFVAR macros in the Emacs source files, for the C language only:

--regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'

When you have complex regular expressions, you can store the list of them in a file. The following option syntax instructs etags to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case.

--regex=@case-sensitive-file --ignore-case-regex=@ignore-case-file

A regex file for etags contains one regular expression per line. Empty lines, and lines beginning with space or tab are ignored. When the first character in a line is ‘@’, etags assumes that the rest of the line is the name of another file of regular expressions; thus, one such file can include another file. All the other lines are taken to be regular expressions. If the first non-whitespace text on the line is ‘--’, that line is a comment.

For example, we can create a file called ‘emacs.tags’ with the following contents:

        -- This is for GNU Emacs C source files
{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/

and then use it like this:

etags --regex=@emacs.tags *.[ch] */*.[ch]

Here are some more examples. The regexps are quoted to protect them from shell interpretation.

Previous: , Up: Xref   [Contents][Index]

28.4.3 Selecting a Tags Table

Emacs has at any time at most one selected tags table. All the commands for working with tags tables use the selected one. To select a tags table, type M-x visit-tags-table, which reads the tags table file name as an argument, with TAGS defaulting to the first directory that contains a file named TAGS encountered when recursively searching upward from the default directory.

Emacs does not actually read in the tags table contents until you try to use them; all visit-tags-table does is store the file name in the variable tags-file-name, and not much more. The variable’s initial value is nil; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use.

Using visit-tags-table when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used instead of others. If you add the new table to the current list, it is used as well as the others.

You can specify a precise list of tags tables by setting the variable tags-table-list to a list of strings, like this:

(setq tags-table-list
      '("~/.emacs.d" "/usr/local/lib/emacs/src"))

This tells the tags commands to look at the TAGS files in your ~/.emacs.d directory and in the /usr/local/lib/emacs/src directory. The order depends on which file you are in and which tags table mentions that file.

Do not set both tags-file-name and tags-table-list.

Next: , Previous: , Up: Maintaining   [Contents][Index]

28.5 Emacs Development Environment

EDE (Emacs Development Environment) is a package that simplifies the task of creating, building, and debugging large programs with Emacs. It provides some of the features of an IDE, or Integrated Development Environment, in Emacs.

This section provides a brief description of EDE usage. For full details, see EDE in Emacs Development Environment.

EDE is implemented as a global minor mode (see Minor Modes). To enable it, type M-x global-ede-mode or click on the ‘Project Support (EDE)’ item in the ‘Tools’ menu. You can also enable EDE each time you start Emacs, by adding the following line to your initialization file:

(global-ede-mode t)

Activating EDE adds a menu named ‘Development’ to the menu bar. Many EDE commands, including the ones described below, can be invoked from this menu.

EDE organizes files into projects, which correspond to directory trees. The project root is the topmost directory of a project. To define a new project, visit a file in the desired project root and type M-x ede-new. This command prompts for a project type, which refers to the underlying method that EDE will use to manage the project (see EDE in Emacs Development Environment). The most common project types are ‘Make’, which uses Makefiles, and ‘Automake’, which uses GNU Automake (see Automake in Automake). In both cases, EDE also creates a file named Project.ede, which stores information about the project.

A project may contain one or more targets. A target can be an object file, executable program, or some other type of file, which is built from one or more of the files in the project.

To add a new target to a project, type C-c . t (M-x ede-new-target). This command also asks if you wish to add the current file to that target, which means that the target is to be built from that file. After you have defined a target, you can add more files to it by typing C-c . a (ede-add-file).

To build a target, type C-c . c (ede-compile-target). To build all the targets in the project, type C-c . C (ede-compile-project). EDE uses the file types to guess how the target should be built.

Previous: , Up: Maintaining   [Contents][Index]

28.6 Merging Files with Emerge

It’s not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, you need to merge the two versions. Emerge makes this easier. For other ways to compare files, see Comparing Files, and Ediff in The Ediff Manual.

28.6.1 Overview of Emerge

To start Emerge, run one of these four commands:

M-x emerge-files

Merge two specified files.

M-x emerge-files-with-ancestor

Merge two specified files, with reference to a common ancestor.

M-x emerge-buffers

Merge two buffers.

M-x emerge-buffers-with-ancestor

Merge two buffers with reference to a common ancestor in a third buffer.

The Emerge commands compare two files or buffers, and display the comparison in three buffers: one for each input text (the A buffer and the B buffer), and one (the merge buffer) where merging takes place. The merge buffer shows the full merged text, not just the differences. Wherever the two input texts differ, you can choose which one of them to include in the merge buffer.

The Emerge commands that take input from existing buffers use only the accessible portions of those buffers, if they are narrowed. 请参阅聚焦

If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the ‘with-ancestor’ commands if you want to specify a common ancestor text. These commands read three file or buffer names—variant A, variant B, and the common ancestor.

After the comparison is done and the buffers are prepared, the interactive merging starts. You control the merging by typing special merge commands in the merge buffer (see Merge Commands). For each run of differences between the input texts, you can choose which one of them to keep, or edit them both together.

The merge buffer uses a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands.

At any given time, the attention of Emerge is focused on one particular difference, called the selected difference. This difference is marked off in the three buffers like this:

vvvvvvvvvvvvvvvvvvvv
text that differs
^^^^^^^^^^^^^^^^^^^^

Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference.

Normally, the merge buffer starts out with the A version of the text. But when the A version of a difference agrees with the common ancestor, then the B version is initially preferred for that difference.

Emerge leaves the merged text in the merge buffer when you exit. At that point, you can save it in a file with C-x C-w. If you give a numeric argument to emerge-files or emerge-files-with-ancestor, it reads the name of the output file using the minibuffer. (This is the last file name those commands read.) Then exiting from Emerge saves the merged text in the output file.

Normally, Emerge commands save the output buffer in its file when you exit. If you abort Emerge with C-], the Emerge command does not save the output buffer, but you can save it yourself if you wish.

28.6.2 Submodes of Emerge

You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic merge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only merge commands. In Edit mode, all merge commands start with the prefix key C-c C-c, and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations.

Use e to switch to Edit mode, and C-c C-c f to switch to Fast mode. The mode line indicates Edit and Fast modes with ‘E’ and ‘F’.

Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode.

If Auto Advance mode is in effect, the a and b commands advance to the next difference. This lets you go through the merge faster as long as you simply choose one of the alternatives from the input. The mode line indicates Auto Advance mode with ‘A’.

If Skip Prefers mode is in effect, the n and p commands skip over differences in states “prefer-A” and “prefer-B” (see State of Difference). Thus you see only differences for which neither version is presumed correct. The mode line indicates Skip Prefers mode with ‘S’. This mode is only relevant when there is an ancestor.

Use the command s a (emerge-auto-advance) to set or clear Auto Advance mode. Use s s (emerge-skip-prefers) to set or clear Skip Prefers mode. These commands turn on the mode with a positive argument, turn it off with a negative or zero argument, and toggle the mode with no argument.

Next: , Previous: , Up: Emerge   [Contents][Index]

28.6.3 State of a Difference

In the merge buffer, a difference is marked with lines of ‘v’ and ‘^’ characters. Each difference has one of these seven states:

A

The difference is showing the A version. The a command always produces this state; the mode line indicates it with ‘A’.

B

The difference is showing the B version. The b command always produces this state; the mode line indicates it with ‘B’.

default-A
default-B

The difference is showing the A or the B state by default, because you haven’t made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for which one alternative is preferred (see below).

When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line.

The command d a chooses default-A as the default state, and d b chooses default-B. This chosen default applies to all differences that you have never selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven’t selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using d a and d b between sections.

prefer-A
prefer-B

The difference is showing the A or B state because it is preferred. This means that you haven’t made an explicit choice, but one alternative seems likely to be right because the other alternative agrees with the common ancestor. Thus, where the A buffer agrees with the common ancestor, the B version is preferred, because chances are it is the one that was actually changed.

These two states are displayed in the mode line as ‘A*’ and ‘B*’.

combined

The difference is showing a combination of the A and B states, as a result of the x c or x C commands.

Once a difference is in this state, the a and b commands don’t do anything to it unless you give them a numeric argument.

The mode line displays this state as ‘comb’.

28.6.4 Merge Commands

Here are the Merge commands for Fast mode; in Edit mode, precede them with C-c C-c:

p

Select the previous difference.

n

Select the next difference.

a

Choose the A version of this difference.

b

Choose the B version of this difference.

C-u n j

Select difference number n.

.

Select the difference containing point.

q

Quit—finish the merge.

C-]

Abort—exit merging and do not save the output.

f

Go into Fast mode. (In Edit mode, this is actually C-c C-c f.)

e

Go into Edit mode.

l

Recenter (like C-l) all three windows. With an argument, reestablish the default three-window display.

-

Specify part of a prefix numeric argument.

digit

Also specify part of a prefix numeric argument.

d a

Choose the A version as the default from here down in the merge buffer.

d b

Choose the B version as the default from here down in the merge buffer.

c a

Copy the A version of this difference into the kill ring.

c b

Copy the B version of this difference into the kill ring.

i a

Insert the A version of this difference at point.

i b

Insert the B version of this difference at point.

m

Put point and mark around the difference.

^

Scroll all three windows down (like M-v).

v

Scroll all three windows up (like C-v).

<

Scroll all three windows left (like C-x <).

>

Scroll all three windows right (like C-x >).

|

Reset horizontal scroll on all three windows.

x 1

Shrink the merge window to one line. (Use C-u l to restore it to full size.)

x c

Combine the two versions of this difference (see Combining in Emerge).

x f

Show the names of the files/buffers Emerge is operating on, in a Help window. (Use C-u l to restore windows.)

x j

Join this difference with the following one. (C-u x j joins this difference with the previous one.)

x s

Split this difference into two differences. Before you use this command, position point in each of the three buffers at the place where you want to split the difference.

x t

Trim identical lines off the top and bottom of the difference. Such lines occur when the A and B versions are identical but differ from the ancestor version.

28.6.5 Exiting Emerge

The q command (emerge-quit) finishes the merge, storing the results into the output file if you specified one. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge and you haven’t changed them. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers.

C-] aborts the merge. This means exiting without writing the output file. If you didn’t specify an output file, then there is no real difference between aborting and finishing the merge.

If the Emerge command was called from another Lisp program, then its return value is t for successful completion, or nil if you abort.

28.6.6 Combining the Two Versions

Sometimes you want to keep both alternatives for a particular difference. To do this, use x c, which edits the merge buffer like this:

#ifdef NEW
version from B buffer
#else /* not NEW */
version from A buffer
#endif /* not NEW */

While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings to use by setting the variable emerge-combine-versions-template to a string of your choice. In the string, ‘%a’ says where to put version A, and ‘%b’ says where to put version B. The default setting, which produces the results shown above, looks like this:

"#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n"

Previous: , Up: Emerge   [Contents][Index]

28.6.7 Fine Points of Emerge

During the merge, you mustn’t try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were.

You can have any number of merges going at once—just don’t use any one buffer as input to more than one merge at once, since the temporary changes made in these buffers would get in each other’s way.

Starting Emerge can take a long time because it needs to compare the files fully. Emacs can’t do anything else until diff finishes. Perhaps in the future someone will change Emerge to do the comparison in the background when the input files are large—then you could keep on doing other things with Emacs until Emerge is ready to accept commands.

After setting up the merge, Emerge runs the hook emerge-startup-hook. See Hooks.


Next: , Previous: , Up: Top   [Contents][Index]

29 Abbrevs

A defined abbrev is a word which expands, if you insert it, into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define ‘foo’ as an abbrev expanding to ‘find outer otter’. Then you could insert ‘find outer otter ’ into the buffer by typing f o o SPC.

A second kind of abbreviation facility is called dynamic abbrev expansion. You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. See Dynamic Abbrevs.

A third kind, hippie expansion, generalizes abbreviation expansion. See Hippie Expansion in Features for Automatic Typing.

29.1 Abbrev Concepts

An abbrev is a word that has been defined to expand into a specified expansion. When you insert a word-separator character following the abbrev, that expands the abbrev—replacing the abbrev with its expansion. For example, if ‘foo’ is defined as an abbrev expanding to ‘find outer otter’, then typing f o o . will insert ‘find outer otter.’.

Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is enabled. Disabling Abbrev mode does not cause abbrev definitions to be forgotten, but they do not expand until Abbrev mode is enabled again. The command M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. See Minor Modes.

Abbrevs can have mode-specific definitions, active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition.

You can define abbrevs interactively during the editing session, irrespective of whether Abbrev mode is enabled. You can also save lists of abbrev definitions in files, which you can then reload for use in later sessions.

29.2 Defining Abbrevs

C-x a g

Define an abbrev, using one or more words before point as its expansion (add-global-abbrev).

C-x a l

Similar, but define an abbrev specific to the current major mode (add-mode-abbrev).

C-x a i g

Define a word in the buffer as an abbrev (inverse-add-global-abbrev).

C-x a i l

Define a word in the buffer as a mode-specific abbrev (inverse-add-mode-abbrev).

M-x define-global-abbrev RET abbrev RET exp RET

Define abbrev as an abbrev expanding into exp.

M-x define-mode-abbrev RET abbrev RET exp RET

Define abbrev as a mode-specific abbrev expanding into exp.

M-x kill-all-abbrevs

Discard all abbrev definitions, leaving a blank slate.

The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type C-x a g (add-global-abbrev). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev ‘foo’ as mentioned above, insert the text ‘find outer otter’ and then type C-u 3 C-x a g f o o RET.

An argument of zero to C-x a g means to use the contents of the region as the expansion of the abbrev being defined.

The command C-x a l (add-mode-abbrev) is similar, but defines a mode-specific abbrev for the current major mode. The arguments work the same as for C-x a g.

C-x a i g (inverse-add-global-abbrev) and C-x a i l (inverse-add-mode-abbrev) perform the opposite task: if the abbrev text is already in the buffer, you use these commands to define an abbrev by specifying the expansion in the minibuffer. These commands will expand the abbrev text used for the definition.

You can define an abbrev without inserting either the abbrev or its expansion in the buffer using the command define-global-abbrev. It reads two arguments—the abbrev, and its expansion. The command define-mode-abbrev does likewise for a mode-specific abbrev.

To change the definition of an abbrev, just make a new definition. When an abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it.

To remove an abbrev definition, give a negative argument to the abbrev definition command: C-u - C-x a g or C-u - C-x a l. The former removes a global definition, while the latter removes a mode-specific definition. M-x kill-all-abbrevs removes all abbrev definitions, both global and local.

Next: , Previous: , Up: Abbrevs   [Contents][Index]

29.3 Controlling Abbrev Expansion

When Abbrev mode is enabled, an abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (SPC, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, and any word-constituent character can be part of an abbrev. The most common way to use an abbrev is to insert it and then insert a punctuation or whitespace character to expand it.

Abbrev expansion preserves case: ‘foo’ expands to ‘find outer otter’, and ‘Foo’ to ‘Find outer otter’. ‘FOO’ expands to ‘Find Outer Otter’ by default, but if you change the variable abbrev-all-caps to a non-nil value, it expands to ‘FIND OUTER OTTER’.

These commands are used to control abbrev expansion:

M-'

Separate a prefix from a following abbrev to be expanded (abbrev-prefix-mark).

C-x a e

Expand the abbrev before point (expand-abbrev). This is effective even when Abbrev mode is not enabled.

M-x unexpand-abbrev

Undo the expansion of the last expanded abbrev.

M-x expand-region-abbrevs

Expand some or all abbrevs found in the region.

You may wish to expand an abbrev and attach a prefix to the expansion; for example, if ‘cnst’ expands into ‘construction’, you might want to use it to enter ‘reconstruction’. It does not work to type recnst, because that is not necessarily a defined abbrev. What you can do is use the command M-' (abbrev-prefix-mark) in between the prefix ‘re’ and the abbrev ‘cnst’. First, insert ‘re’. Then type M-'; this inserts a hyphen in the buffer to indicate that it has done its work. Then insert the abbrev ‘cnst’; the buffer now contains ‘re-cnst’. Now insert a non-word character to expand the abbrev ‘cnst’ into ‘construction’. This expansion step also deletes the hyphen that indicated M-' had been used. The result is the desired ‘reconstruction’.

If you actually want the text of the abbrev in the buffer, rather than its expansion, you can accomplish this by inserting the following punctuation with C-q. Thus, foo C-q , leaves ‘foo,’ in the buffer, not expanding it.

If you expand an abbrev by mistake, you can undo the expansion by typing C-/ (undo). See Undo. This undoes the insertion of the abbrev expansion and brings back the abbrev text. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with C-q. You can also use the command M-x unexpand-abbrev to cancel the last expansion without deleting the terminating character.

M-x expand-region-abbrevs searches through the region for defined abbrevs, and for each one found offers to replace it with its expansion. This command is useful if you have typed in text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled.

The function expand-abbrev performs the expansion by calling the function that abbrev-expand-function specifies. By changing this function you can make arbitrary changes to the abbrev expansion. See Abbrev Expansion in The Emacs Lisp Reference Manual.

Next: , Previous: , Up: Abbrevs   [Contents][Index]

29.4 Examining and Editing Abbrevs

M-x list-abbrevs

Display a list of all abbrev definitions. With a numeric argument, list only local abbrevs.

M-x edit-abbrevs

Edit a list of abbrevs; you can add, alter or remove definitions.

The output from M-x list-abbrevs looks like this:

various other tables…
(lisp-mode-abbrev-table)
"dk"          0    "define-key"
(global-abbrev-table)
"dfn"         0    "definition"

(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)

A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; global-abbrev-table contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs.

Within each abbrev table, each nonblank line defines one abbrev. The word at the beginning of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don’t use often. The string at the end of the line is the expansion.

Some abbrevs are marked with ‘(sys)’. These system abbrevs (see Abbrevs in The Emacs Lisp Reference Manual) are pre-defined by various modes, and are not saved to your abbrev file. To disable a system abbrev, define an abbrev of the same name that expands to itself, and save it to your abbrev file.

M-x edit-abbrevs allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the same format described above. The buffer of abbrevs is called *Abbrevs*, and is in Edit-Abbrevs mode. Type C-c C-c in this buffer to install the abbrev definitions as specified in the buffer—and delete any abbrev definitions not listed.

The command edit-abbrevs is actually the same as list-abbrevs except that it selects the buffer *Abbrevs* whereas list-abbrevs merely displays it in another window.

Next: , Previous: , Up: Abbrevs   [Contents][Index]

29.5 Saving Abbrevs

These commands allow you to keep abbrev definitions between editing sessions.

M-x write-abbrev-file RET file RET

Write a file file describing all defined abbrevs.

M-x read-abbrev-file RET file RET

Read the file file and define abbrevs as specified therein.

M-x define-abbrevs

Define abbrevs from definitions in current buffer.

M-x insert-abbrevs

Insert all abbrevs and their expansions into current buffer.

M-x write-abbrev-file reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have.

M-x read-abbrev-file reads a file name using the minibuffer and then reads the file, defining abbrevs according to the contents of the file. The function quietly-read-abbrev-file is similar except that it does not display a message in the echo area; you cannot invoke it interactively, and it is used primarily in your init file (see Init File). If either of these functions is called with nil as the argument, it uses the file given by the variable abbrev-file-name, which is ~/.emacs.d/abbrev_defs by default. This is your standard abbrev definition file, and Emacs loads abbrevs from it automatically when it starts up. (As an exception, Emacs does not load the abbrev file when it is started in batch mode. See Initial Options, for a description of batch mode.)

Emacs will offer to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for C-x s or C-x C-c). It saves them in the file specified by abbrev-file-name. This feature can be inhibited by setting the variable save-abbrevs to nil; setting it to silently will save the abbrevs automatically without asking.

The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer after point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.

29.6 Dynamic Abbrev Expansion

The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, dynamic abbrevs allow the meanings of abbreviations to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly.

M-/

Expand the word in the buffer before point as a dynamic abbrev, by searching for words starting with that abbreviation (dabbrev-expand).

C-M-/

Complete the word before point as a dynamic abbrev (dabbrev-completion).

For example, if the buffer contains ‘does this follow ’ and you type f o M-/, the effect is to insert ‘follow’ because that is the last word in the buffer that starts with ‘fo’. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After scanning all the text before point, it searches the text after point. The variable dabbrev-limit, if non-nil, specifies how far away in the buffer to search for an expansion.

After scanning the current buffer, M-/ normally searches other buffers. The variables dabbrev-check-all-buffers and dabbrev-check-other-buffers can be used to determine which other buffers, if any, are searched.

For finer control over which buffers to scan, customize the variables dabbrev-ignored-buffer-names and dabbrev-ignored-buffer-regexps. The value of the former is a list of buffer names to skip. The value of the latter is a list of regular expressions; if a buffer’s name matches any of these regular expressions, dynamic abbrev expansion skips that buffer.

A negative argument to M-/, as in C-u - M-/, says to search first for expansions after point, then other buffers, and consider expansions before point only as a last resort. If you repeat the M-/ to look for another expansion, do not specify an argument. Repeating M-/ cycles through all the expansions after point and then the expansions before point.

After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type SPC M-/ for each additional word you want to copy. The spacing and punctuation between words is copied along with the words.

You can control the way M-/ determines the word to expand and how to expand it, see Dabbrev Customization.

The command C-M-/ (dabbrev-completion) performs completion of a dynamic abbrev. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, C-M-/ displays a list of completions, from which you can select a choice in the usual manner. See Completion.

Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.

Previous: , Up: Abbrevs   [Contents][Index]

29.7 Customizing Dynamic Abbreviation

Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding.

This feature is controlled by the variable dabbrev-case-fold-search. If it is t, case is ignored in this search; if it is nil, the word and the expansion must match in case. If the value is case-fold-search (the default), then the variable case-fold-search controls whether to ignore case while searching for expansions (see Lax Search).

Normally, dynamic abbrev expansion preserves the case pattern of the dynamic abbrev you are expanding, by converting the expansion to that case pattern.

The variable dabbrev-case-replace controls whether to preserve the case pattern of the dynamic abbrev. If it is t, the dynamic abbrev’s case pattern is preserved in most cases; if it is nil, the expansion is always copied verbatim. If the value is case-replace (the default), then the variable case-replace controls whether to copy the expansion verbatim (see Replacement and Lax Matches).

However, if the expansion contains a complex mixed case pattern, and the dynamic abbrev matches this pattern as far as it goes, then the expansion is always copied verbatim, regardless of those variables. Thus, for example, if the buffer contains variableWithSillyCasePattern, and you type v a M-/, it copies the expansion verbatim including its case pattern.

The variable dabbrev-abbrev-char-regexp, if non-nil, controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The (default) value nil has a special meaning: dynamic abbrevs (i.e. the word at point) are made of word characters, but their expansions are looked for as sequences of word and symbol characters. This is generally appropriate for expanding symbols in a program source and also for human-readable text in many languages, but may not be what you want in a text buffer that includes unusual punctuation characters; in that case, the value "\\sw" might produce better results.

In shell scripts and makefiles, a variable name is sometimes prefixed with ‘$’ and sometimes not. Major modes for this kind of text can customize dynamic abbrev expansion to handle optional prefixes by setting the variable dabbrev-abbrev-skip-leading-regexp. Its value should be a regular expression that matches the optional prefix that dynamic abbrev expression should ignore. The default is nil, which means no characters should be skipped.


Next: , Previous: , Up: Top   [Contents][Index]

30 Dired, the Directory Editor

Dired makes an Emacs buffer containing a listing of a directory, and optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the listed files. Dired works with both local and remote directories.

The Dired buffer is normally read-only, and inserting text in it is not allowed (however, the Wdired mode allows that, see Wdired). Ordinary printing characters such as d and x are redefined for special Dired commands. Some Dired commands mark or flag the current file (that is, the file on the current line); other commands operate on the marked files or on the flagged files. You first mark certain files in order to operate on all of them with one command.

The Dired-X package provides various extra features for Dired mode. See Dired-X in Dired Extra User’s Manual.

You can also view a list of files in a directory with C-x C-d (list-directory). Unlike Dired, this command does not allow you to operate on the listed files. See Directories.

30.1 Entering Dired

To invoke Dired, type C-x d (dired). This reads a directory’s name using the minibuffer, and opens a Dired buffer listing the files in that directory. You can also supply a wildcard file name pattern as the minibuffer argument, in which case the Dired buffer lists all files matching that pattern. A wildcard may appear in the directory part as well. For instance,

C-x d  ~/foo/*.el  RET
C-x d  ~/foo/*/*.el  RET

The former lists all the files with extension ‘.el’ in directory ‘foo’. The latter lists the files with extension ‘.el’ in all the subdirectories of ‘foo’.

The usual history and completion commands can be used in the minibuffer; in particular, M-n puts the name of the visited file (if any) in the minibuffer (see Minibuffer History).

You can also invoke Dired by giving C-x C-f (find-file) a directory’s name.

The variable dired-listing-switches specifies the options to give to ls for listing the directory; this string must contain ‘-l’. If you use a prefix argument with the dired command, you can specify the ls switches with the minibuffer before you enter the directory specification. No matter how they are specified, the ls switches can include short options (that is, single characters) requiring no arguments, and long options (starting with ‘--’) whose arguments are specified with ‘=’.

If your ls program supports the ‘--dired’ option, Dired automatically passes it that option; this causes ls to emit special escape sequences for certain unusual file names, without which Dired will not be able to parse those names. The first time you run Dired in an Emacs session, it checks whether ls supports the ‘--dired’ option by calling it once with that option. If the exit code is 0, Dired will subsequently use the ‘--dired’ option; otherwise it will not. You can inhibit this check by customizing the variable dired-use-ls-dired. The value unspecified (the default) means to perform the check; any other non-nil value means to use the ‘--dired’ option; and nil means not to use the ‘--dired’ option.

On MS-Windows and MS-DOS systems, and also on some remote systems, Emacs emulates ls. See ls in Lisp, for options and peculiarities of this emulation.

To display the Dired buffer in another window, use C-x 4 d (dired-other-window). C-x 5 d (dired-other-frame) displays the Dired buffer in a separate frame.

Typing q (quit-window) buries the Dired buffer, and deletes its window if the window was created just for that buffer.

Next: , Previous: , Up: Dired   [Contents][Index]

30.2 Navigation in the Dired Buffer

All the usual Emacs cursor motion commands are available in Dired buffers. The keys C-n and C-p are redefined to run dired-next-line and dired-previous-line, respectively, and they put the cursor at the beginning of the file name on the line, rather than at the beginning of the line.

For extra convenience, SPC and n in Dired are equivalent to C-n. p is equivalent to C-p. (Moving by lines is so common in Dired that it deserves to be easy to type.) DEL (move up and unflag) is also often useful simply for moving up (see Dired Deletion).

j (dired-goto-file) prompts for a file name using the minibuffer, and moves point to the line in the Dired buffer describing that file.

M-s f C-s (dired-isearch-filenames) performs a forward incremental search in the Dired buffer, looking for matches only amongst the file names and ignoring the rest of the text in the buffer. M-s f M-C-s (dired-isearch-filenames-regexp) does the same, using a regular expression search. If you change the variable dired-isearch-filenames to t, then the usual search commands also limit themselves to the file names; for instance, C-s behaves like M-s f C-s. If the value is dwim, then search commands match the file names only when point was on a file name initially. See Search, for information about incremental search.

Some additional navigation commands are available when the Dired buffer includes several directories. See Subdirectory Motion.

30.3 Deleting Files with Dired

One of the most frequent uses of Dired is to first flag files for deletion, then delete the files that were flagged.

d

Flag this file for deletion (dired-flag-file-deletion).

u

Remove the deletion flag (dired-unmark).

DEL

Move point to previous line and remove the deletion flag on that line (dired-unmark-backward).

x

Delete files flagged for deletion (dired-do-flagged-delete).

You can flag a file for deletion by moving to the line describing the file and typing d (dired-flag-file-deletion). The deletion flag is visible as a ‘D’ at the beginning of the line. This command moves point to the next line, so that repeated d commands flag successive files. A numeric prefix argument serves as a repeat count; a negative count means to flag preceding files.

If the region is active, the d command flags all files in the region for deletion; in this case, the command does not move point, and ignores any prefix argument.

The reason for flagging files for deletion, rather than deleting files immediately, is to reduce the danger of deleting a file accidentally. Until you direct Dired to delete the flagged files, you can remove deletion flags using the commands u and DEL. u (dired-unmark) works just like d, but removes flags rather than making flags. DEL (dired-unmark-backward) moves upward, removing flags; it is like u with argument -1. A numeric prefix argument to either command serves as a repeat count, with a negative count meaning to unflag in the opposite direction. If the region is active, these commands instead unflag all files in the region, without moving point.

To delete flagged files, type x (dired-do-flagged-delete). This command displays a list of all the file names flagged for deletion, and requests confirmation with yes. If you confirm, Dired deletes the flagged files, then deletes their lines from the text of the Dired buffer. The Dired buffer, with somewhat fewer lines, remains selected.

If you answer no or quit with C-g when asked to confirm, you return immediately to Dired, with the deletion flags still present in the buffer, and no files actually deleted.

You can delete empty directories just like other files, but normally Dired cannot delete directories that are nonempty. However, if the variable dired-recursive-deletes is non-nil, then Dired is allowed to delete nonempty directories including all their contents. That can be somewhat risky. If the value of the variable is always, Dired will delete nonempty directories recursively, which is even more risky.

Even if you have set dired-recursive-deletes to nil, you might want sometimes to delete directories recursively without being asked for confirmation for all of them. For example, you may want that when you have marked many directories for deletion and you are very sure that all of them can safely be deleted. For every nonempty directory you are asked for confirmation to delete, if you answer all, then all the remaining directories will be deleted without any further questions.

If you change the variable delete-by-moving-to-trash to t, the above deletion commands will move the affected files or directories into the operating system’s Trash, instead of deleting them outright. See Misc File Ops.

An alternative way of deleting files is to mark them with m and delete with D, see Operating on Files.

Next: , Previous: , Up: Dired   [Contents][Index]

30.4 Flagging Many Files at Once

The #, ~, ., % &, and % d commands flag many files for deletion, based on their file names:

#

Flag all auto-save files (files whose names start and end with ‘#’) for deletion (see Auto Save).

~

Flag all backup files (files whose names end with ‘~’) for deletion (see Backup).

. (Period)

Flag excess numeric backup files for deletion. The oldest and newest few backup files of any one file are exempt; the middle ones are flagged.

% &

Flag for deletion all files with certain kinds of names which suggest you could easily create those files again.

% d regexp RET

Flag for deletion all files whose names match the regular expression regexp.

# (dired-flag-auto-save-files) flags all files whose names look like auto-save files—that is, files whose names begin and end with ‘#’. See Auto Save.

~ (dired-flag-backup-files) flags all files whose names say they are backup files—that is, files whose names end in ‘~’. See Backup.

. (period, dired-clean-directory) flags just some of the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally, the number of newest versions kept for each file is given by the variable dired-kept-versions (not kept-new-versions; that applies only when saving). The number of oldest versions to keep is given by the variable kept-old-versions.

Period with a positive numeric argument, as in C-u 3 ., specifies the number of newest versions to keep, overriding dired-kept-versions. A negative numeric argument overrides kept-old-versions, using minus the value of the argument to specify the number of oldest versions of each file to keep.

% & (dired-flag-garbage-files) flags files whose names match the regular expression specified by the variable dired-garbage-files-regexp. By default, this matches certain files produced by TeX, ‘.bak’ files, and the ‘.orig’ and ‘.rej’ files produced by patch.

% d flags all files whose names match a specified regular expression (dired-flag-files-regexp). Only the non-directory part of the file name is used in matching. You can use ‘^’ and ‘$’ to anchor matches. You can exclude certain subdirectories from marking by hiding them while you use % d. See Hiding Subdirectories.

Next: , Previous: , Up: Dired   [Contents][Index]

30.5 Visiting Files in Dired

There are several Dired commands for visiting or examining the files listed in the Dired buffer. All of them apply to the current line’s file; if that file is really a directory, these commands invoke Dired on that subdirectory (making a separate Dired buffer).

f

Visit the file described on the current line, like typing C-x C-f and supplying that file name (dired-find-file). See Visiting.

RET
e

Equivalent to f.

o

Like f, but uses another window to display the file’s buffer (dired-find-file-other-window). The Dired buffer remains visible in the first window. This is like using C-x 4 C-f to visit the file. See Windows.

C-o

Visit the file described on the current line, and display the buffer in another window, but do not select that window (dired-display-file).

鼠标左键
鼠标中键

Visit the file whose name you clicked on (dired-mouse-find-file-other-window). This uses another window to display the file, like the o command.

v

View the file described on the current line, with View mode (dired-view-file). View mode provides convenient commands to navigate the buffer but forbids changing it; See View Mode.

^

Visit the parent directory of the current directory (dired-up-directory). This is equivalent to moving to the line for .. and typing f there.

Next: , Previous: , Up: Dired   [Contents][Index]

30.6 Dired Marks vs. Flags

Instead of flagging a file with ‘D’, you can mark the file with some other character (usually ‘*’). Most Dired commands to operate on files use the files marked with ‘*’. The only command that operates on flagged files is x, which deletes them.

Here are some commands for marking with ‘*’, for unmarking, and for operating on marks. (See Dired Deletion, for commands to flag and unflag files.)

m
* m

Mark the current file with ‘*’ (dired-mark). If the region is active, mark all files in the region instead; otherwise, if a numeric argument n is supplied, mark the next n files instead, starting with the current file (if n is negative, mark the previous -n files). If invoked on a subdirectory header line (see Subdirectories in Dired), this command marks all the files in that subdirectory.

* N

Report what the number and size of the marked files are (dired-number-of-marked-files).

* *

Mark all executable files with ‘*’ (dired-mark-executables). With a numeric argument, unmark all those files.

* @

Mark all symbolic links with ‘*’ (dired-mark-symlinks). With a numeric argument, unmark all those files.

* /

Mark with ‘*’ all files which are directories, except for . and .. (dired-mark-directories). With a numeric argument, unmark all those files.

* s

Mark all the files in the current subdirectory, aside from . and .. (dired-mark-subdir-files).

u
* u

Remove any mark on this line (dired-unmark). If the region is active, unmark all files in the region instead; otherwise, if a numeric argument n is supplied, unmark the next n files instead, starting with the current file (if n is negative, unmark the previous -n files).

DEL
* DEL

Move point to previous line and remove any mark on that line (dired-unmark-backward). If the region is active, unmark all files in the region instead; otherwise, if a numeric argument n is supplied, unmark the n preceding files instead, starting with the current file (if n is negative, unmark the next -n files).

* !
U

Remove all marks from all the files in this Dired buffer (dired-unmark-all-marks).

* ? markchar
M-DEL

Remove all marks that use the character markchar (dired-unmark-all-files). If invoked with M-DEL, the command prompts for markchar. That markchar is a single character—do not use RET to terminate it. See the description of the * c command below, which lets you replace one mark character with another.

With a numeric argument, this command queries about each marked file, asking whether to remove its mark. You can answer y meaning yes, n meaning no, or ! to remove the marks from the remaining files without asking about them.

* C-n
M-}

Move down to the next marked file (dired-next-marked-file). A file is “marked” if it has any kind of mark.

* C-p
M-{

Move up to the previous marked file (dired-prev-marked-file).

t
* t

Toggle all marks (dired-toggle-marks): files marked with ‘*’ become unmarked, and unmarked files are marked with ‘*’. Files marked in any other way are not affected.

* c old-markchar new-markchar

Replace all marks that use the character old-markchar with marks that use the character new-markchar (dired-change-marks). This command is the primary way to create or use marks other than ‘*’ or ‘D’. The arguments are single characters—do not use RET to terminate them.

You can use almost any character as a mark character by means of this command, to distinguish various classes of files. If old-markchar is a space (‘ ’), then the command operates on all unmarked files; if new-markchar is a space, then the command unmarks the files it acts on.

To illustrate the power of this command, here is how to put ‘D’ flags on all the files that have no marks, while unflagging all those that already have ‘D’ flags:

* c D t  * c SPC D  * c t SPC

This assumes that no files were already marked with ‘t’.

% m regexp RET
* % regexp RET

Mark (with ‘*’) all files whose names match the regular expression regexp (dired-mark-files-regexp). This command is like % d, except that it marks files with ‘*’ instead of flagging with ‘D’.

Only the non-directory part of the file name is used in matching. Use ‘^’ and ‘$’ to anchor matches. You can exclude subdirectories by temporarily hiding them (see Hiding Subdirectories).

% g regexp RET

Mark (with ‘*’) all files whose contents contain a match for the regular expression regexp (dired-mark-files-containing-regexp). This command is like % m, except that it searches the file contents instead of the file name. Note that if a file is visited in an Emacs buffer, and dired-always-read-filesystem is nil (the default), this command will look in the buffer without revisiting the file, so the results might be inconsistent with the file on disk if its contents have changed since it was last visited. If you don’t want this, you may wish to revert the files you have visited in your buffers, or to turn on Auto-Revert mode in those buffers, before invoking this command. See Reverting. If you prefer that this command should always revisit the file, without you having to revert the file or enable Auto-Revert mode, you might want to set dired-always-read-filesystem to non-nil.

C-/
C-x u
C-_

Undo changes in the Dired buffer, such as adding or removing marks (dired-undo). This command does not revert the actual file operations, nor recover lost files! It just undoes changes in the buffer itself.

In some cases, using this after commands that operate on files can cause trouble. For example, after renaming one or more files, dired-undo restores the original names in the Dired buffer, which gets the Dired buffer out of sync with the actual contents of the directory.

30.7 Operating on Files

This section describes the basic Dired commands to operate on one file or several files. All of these commands are capital letters; all of them use the minibuffer, either to read an argument or to ask for confirmation, before they act. All of them let you specify the files to manipulate in these ways:

Certain other Dired commands, such as ! and the ‘%’ commands, use the same conventions to decide which files to work on.

Commands which ask for a destination directory, such as those which copy and rename files or create links for them, try to guess the default target directory for the operation. Normally, they suggest the Dired buffer’s default directory, but if the option dired-dwim-target is non-nil, and if there is another Dired buffer displayed in some window, that other buffer’s directory is suggested instead. You can customize dired-dwim-target to prefer either the next window with a Dired buffer, or the most recently used window with a Dired buffer, or to use any other function. When the value is a function, it will be called with no arguments and is expected to return a list of directories which will be used as defaults (i.e. default target and “future history”).

Here are the file-manipulating Dired commands that operate on files.

C new RET

Copy the specified files (dired-do-copy). The argument new is the directory to copy into, or (if copying a single file) the new name. This is like the shell command cp.

The option dired-create-destination-dirs controls whether Dired should create non-existent directories in the destination while copying/renaming files. The default value nil means Dired never creates such missing directories; the value always, means Dired automatically creates them; the value ask means Dired asks you for confirmation before creating them.

If dired-copy-preserve-time is non-nil, then copying with this command preserves the modification time of the old file in the copy, like ‘cp -p’.

The variable dired-recursive-copies controls whether to copy directories recursively (like ‘cp -r’). The default is top, which means to ask before recursively copying a directory.

D

Delete the specified files (dired-do-delete). This is like the shell command rm.

Like the other commands in this section, this command operates on the marked files, or the next n files. By contrast, x (dired-do-flagged-delete) deletes all flagged files.

R new RET

Rename the specified files (dired-do-rename). If you rename a single file, the argument new is the new name of the file. If you rename several files, the argument new is the directory into which to move the files (this is like the shell command mv).

The option dired-create-destination-dirs controls whether Dired should create non-existent directories in new.

Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names.

If the value of the variable dired-vc-rename-file is non-nil, files are renamed using the commands of the underlying VCS, via vc-rename-file (see VC Delete/Rename).

H new RET

Make hard links to the specified files (dired-do-hardlink). This is like the shell command ln. The argument new is the directory to make the links in, or (if making just one link) the name to give the link.

S new RET

Make symbolic links to the specified files (dired-do-symlink). This is like ‘ln -s’. The argument new is the directory to make the links in, or (if making just one link) the name to give the link.

M modespec RET

Change the mode (also called permission bits) of the specified files (dired-do-chmod). modespec can be in octal or symbolic notation, like arguments handled by the chmod program.

G newgroup RET

Change the group of the specified files to newgroup (dired-do-chgrp).

O newowner RET

Change the owner of the specified files to newowner (dired-do-chown). (On most systems, only the superuser can do this.)

The variable dired-chown-program specifies the name of the program to use to do the work. (This variable is necessary because different systems put chown in different places).

T timestamp RET

Touch the specified files (dired-do-touch). This means updating their modification times to the present time. This is like the shell command touch.

P command RET

Print the specified files (dired-do-print). You must specify the command to print them with, but the minibuffer starts out with a suitable guess made using the variables lpr-command and lpr-switches (the same variables that lpr-buffer uses; see Printing).

Z

Compress the specified files (dired-do-compress). If the file appears to be a compressed file already, uncompress it instead. Each marked file is compressed into its own archive; this uses the gzip program if it is available, otherwise it uses compress. On a directory name, this command produces a compressed .tar.gz archive containing all of the directory’s files, by running the tar command with output piped to gzip. To allow decompression of compressed directories, typing Z on a .tar.gz or .tgz archive file unpacks all the files in the archive into a directory whose name is the archive name with the extension removed.

c

Compress the specified files (dired-do-compress-to) into a single archive anywhere on the file system. The compression algorithm is determined by the extension of the archive, see dired-compress-files-alist.

:d

Decrypt the specified files (epa-dired-do-decrypt). See Dired integration in EasyPG Assistant User’s Manual.

:v

Verify digital signatures on the specified files (epa-dired-do-verify). See Dired integration in EasyPG Assistant User’s Manual.

:s

Digitally sign the specified files (epa-dired-do-sign). See Dired integration in EasyPG Assistant User’s Manual.

:e

Encrypt the specified files (epa-dired-do-encrypt). See Dired integration in EasyPG Assistant User’s Manual.

L

Load the specified Emacs Lisp files (dired-do-load). See Lisp Libraries.

B

Byte compile the specified Emacs Lisp files (dired-do-byte-compile). See Byte Compilation in The Emacs Lisp Reference Manual.

A regexp RET

Search all the specified files for the regular expression regexp (dired-do-find-regexp).

This command is a variant of xref-find-references (see Identifier Search), it displays the *xref* buffer, where you can navigate between matches and display them as needed using the commands described in Xref Commands.

If any of the marked files are directories, then this command searches all of the files in those directories, and any of their subdirectories, recursively, except files whose names match grep-find-ignored-files and subdirectories whose names match grep-find-ignored-directories.

Q regexp RET to RET

Perform query-replace-regexp on each of the specified files, replacing matches for regexp with the string to (dired-do-find-regexp-and-replace).

This command is a variant of xref-query-replace-in-results. It presents an *xref* buffer that lists all the matches of regexp, and you can use the special commands in that buffer (see Xref Commands). In particular, if you exit the query replace loop, you can use r in that buffer to replace more matches. See Identifier Search.

Like with dired-do-find-regexp, if any of the marked files are directories, this command performs replacements in all of the files in those directories, and in any of their subdirectories, recursively, except for files whose names match grep-find-ignored-files and subdirectories whose names match grep-find-ignored-directories.

30.8 Shell Commands in Dired

The Dired command ! (dired-do-shell-command) reads a shell command string in the minibuffer, and runs that shell command on one or more files. The files that the shell command operates on are determined in the usual way for Dired commands (see Operating on Files). The command X is a synonym for !.

The command & (dired-do-async-shell-command) does the same, except that it runs the shell command asynchronously. (You can also do this with !, by appending a ‘&’ character to the end of the shell command.) When the command operates on more than one file, it runs multiple parallel copies of the specified shell command, one for each file. As an exception, if the specified shell command ends in ‘;’ or ‘;&’, the shell command is run in the background on each file sequentially; Emacs waits for each invoked shell command to terminate before running the next one.

For both ! and &, the working directory for the shell command is the top-level directory of the Dired buffer.

If you tell ! or & to operate on more than one file, the shell command string determines how those files are passed to the shell command:

To iterate over the file names in a more complicated fashion, you might prefer to use an explicit shell loop. For example, here is how to uuencode each file, making the output file name by appending ‘.uu’ to the input file name:

for file in * ; do uuencode "$file" "$file" >"$file".uu; done

The same example with ‘`?`’ notation:

uuencode ??> `?`.uu

The ! and & commands do not attempt to update the Dired buffer to show new or modified files, because they don’t know what files will be changed. Use the g command to update the Dired buffer (see Dired Updating).

See Single Shell, for information about running shell commands outside Dired.

30.9 Transforming File Names in Dired

This section describes Dired commands which alter file names in a systematic way. Each command operates on some or all of the marked files, using a new name made by transforming the existing name.

Like the basic Dired file-manipulation commands (see Operating on Files), the commands described here operate either on the next n files, or on all files marked with ‘*’, or on the current file. (To mark files, use the commands described in Marks vs Flags.)

All of the commands described in this section work interactively: they ask you to confirm the operation for each candidate file. Thus, you can select more files than you actually need to operate on (e.g., with a regexp that matches many files), and then filter the selected names by typing y or n when the command prompts for confirmation.

% u

Rename each of the selected files to an upper-case name (dired-upcase). If the old file names are Foo and bar, the new names are FOO and BAR.

% l

Rename each of the selected files to a lower-case name (dired-downcase). If the old file names are Foo and bar, the new names are foo and bar.

% R from RET to RET
% C from RET to RET
% H from RET to RET
% S from RET to RET

These four commands rename, copy, make hard links and make soft links, in each case computing the new name by regular-expression substitution from the name of the old file.

The four regular-expression substitution commands effectively perform a search-and-replace on the selected file names. They read two arguments: a regular expression from, and a substitution pattern to; they match each old file name against from, and then replace the matching part with to. You can use ‘\&’ and ‘\digit’ in to to refer to all or part of what the pattern matched in the old file name, as in replace-regexp (see Regexp Replace). If the regular expression matches more than once in a file name, only the first match is replaced.

For example, % R ^.*$ RET x-\& RET renames each selected file by prepending ‘x-’ to its name. The inverse of this, removing ‘x-’ from the front of each file name, is also possible: one method is % R ^x-\(.*\)$ RET \1 RET; another is % R ^x- RET RET. (Use ‘^’ and ‘$’ to anchor matches that should span the whole file name.)

Normally, the replacement process does not consider the files’ directory names; it operates on the file name within the directory. If you specify a numeric argument of zero, then replacement affects the entire absolute file name including directory name. (A non-zero argument specifies the number of files to operate on.)

You may want to select the set of files to operate on using the same regexp from that you will use to operate on them. To do this, mark those files with % m from RET, then use the same regular expression in the command to operate on the files. To make this more convenient, the % commands to operate on files use the last regular expression specified in any % command as a default.

30.10 File Comparison with Dired

The = (dired-diff) command compares the current file (the file at point) with another file (read using the minibuffer) using the diff program. The file specified with the minibuffer is the first argument of diff, and file at point is the second argument. The output of the diff program is shown in a buffer using Diff mode (see Comparing Files).

If the region is active, the default for the file read using the minibuffer is the file at the mark (i.e., the ordinary Emacs mark, not a Dired mark; see Setting Mark). Otherwise, if the file at point has a backup file (see Backup), that is the default.

You could also compare files using ediff-files, see Major Entry Points in Ediff User’s Manual.

30.11 Subdirectories in Dired

A Dired buffer usually displays just one directory, but you can optionally include its subdirectories as well.

The simplest way to include multiple directories in one Dired buffer is to specify the options ‘-lR’ for running ls. (If you give a numeric argument when you run Dired, then you can specify these options in the minibuffer.) That produces a recursive directory listing showing all subdirectories at all levels.

More often, you will want to show only specific subdirectories. You can do this with i (dired-maybe-insert-subdir):

i

Insert the contents of a subdirectory later in the buffer.

If you use this command on a line that describes a file which is a directory, it inserts the contents of that directory into the same Dired buffer, and moves there. Inserted subdirectory contents follow the top-level directory of the Dired buffer, just as they do in ‘ls -lR’ output.

If the subdirectory’s contents are already present in the buffer, the i command just moves to it.

In either case, i sets the Emacs mark before moving, so C-u C-SPC returns to your previous position in the Dired buffer (see Setting Mark). You can also use ‘^’ to return to the parent directory in the same Dired buffer (see Dired Visiting).

Use the l command (dired-do-redisplay) to update the subdirectory’s contents, and use C-u k on the subdirectory header line to remove the subdirectory listing (see Dired Updating). You can also hide and show inserted subdirectories (see Hiding Subdirectories).

30.12 Subdirectory Switches in Dired

You can insert subdirectories with specified ls switches in Dired buffers using C-u i. You can change the ls switches of an already inserted subdirectory at point using C-u l.

Dired preserves the switches if you revert the buffer. Deleting a subdirectory forgets about its switches.

Using dired-undo (see Marks vs Flags) to reinsert or delete subdirectories that were inserted with explicit switches can bypass Dired’s machinery for remembering (or forgetting) switches. Deleting a subdirectory using dired-undo does not forget its switches. When later reinserted using i, it will be reinserted using its old switches. Using dired-undo to reinsert a subdirectory that was deleted using the regular Dired commands (not dired-undo) will originally insert it with its old switches. Reverting the buffer, however, will relist it using the buffer’s default switches. If any of this yields problems, you can easily correct the situation using C-u i or C-u l.

Dired does not remember the R switch. Inserting a subdirectory with switches that include the R switch is equivalent to inserting each of its subdirectories using all remaining switches. For instance, updating or killing a subdirectory that was inserted with the R switch will not update or kill its subdirectories.

The buffer’s default switches do not affect subdirectories that were inserted using explicitly specified switches. In particular, commands such as s that change the buffer’s switches do not affect such subdirectories. (They do, however, affect subdirectories without explicitly assigned switches.)

You can make Dired forget about all subdirectory switches and relist all subdirectories with the buffer’s default switches using M-x dired-reset-subdir-switches. This also reverts the Dired buffer.

30.13 Moving Over Subdirectories

When a Dired buffer lists subdirectories, you can use the page motion commands C-x [ and C-x ] to move by entire directories (see Pages).

The following commands move across, up and down in the tree of directories within one Dired buffer. They move to directory header lines, which are the lines that give a directory’s name, at the beginning of the directory’s contents.

C-M-n

Go to next subdirectory header line, regardless of level (dired-next-subdir).

C-M-p

Go to previous subdirectory header line, regardless of level (dired-prev-subdir).

C-M-u

Go up to the parent directory’s header line (dired-tree-up).

C-M-d

Go down in the directory tree, to the first subdirectory’s header line (dired-tree-down).

<

Move up to the previous directory-file line (dired-prev-dirline). These lines are the ones that describe a directory as a file in its parent directory.

>

Move down to the next directory-file line (dired-next-dirline).

Next: , Previous: , Up: Dired   [Contents][Index]

30.14 Hiding Subdirectories

Hiding a subdirectory means to make it invisible, except for its header line.

$

Hide or show the subdirectory that point is in, and move point to the next subdirectory (dired-hide-subdir). This is a toggle. A numeric argument serves as a repeat count.

M-$

Hide all subdirectories in this Dired buffer, leaving only their header lines (dired-hide-all). Or, if any subdirectory is currently hidden, make all subdirectories visible again. You can use this command to get an overview in very deep directory trees or to move quickly to subdirectories far away.

Ordinary Dired commands never consider files inside a hidden subdirectory. For example, the commands to operate on marked files ignore files in hidden directories even if they are marked. Thus you can use hiding to temporarily exclude subdirectories from operations without having to remove the Dired marks on files in those subdirectories.

See Subdirectories in Dired, for how to insert a subdirectory listing, and see Dired Updating, for how to delete it.

30.15 Updating the Dired Buffer

This section describes commands to update the Dired buffer to reflect outside (non-Dired) changes in the directories and files, and to delete part of the Dired buffer.

g

Update the entire contents of the Dired buffer (revert-buffer).

l

Update the specified files (dired-do-redisplay). You specify the files for l in the same way as for file operations.

k

Delete the specified file lines—not the files, just the lines (dired-do-kill-lines).

s

Toggle between alphabetical order and date/time order (dired-sort-toggle-or-edit).

C-u s switches RET

Refresh the Dired buffer using switches as dired-listing-switches.

Type g (revert-buffer) to update the contents of the Dired buffer, based on changes in the files and directories listed. This preserves all marks except for those on files that have vanished. Hidden subdirectories are updated but remain hidden.

To update only some of the files, type l (dired-do-redisplay). Like the Dired file-operating commands, this command operates on the next n files (or previous -n files), or on the marked files if any, or on the current file. Updating the files means reading their current status, then updating their lines in the buffer to indicate that status.

If you use l on a subdirectory header line, it updates the contents of the corresponding subdirectory.

If you use C-x d or some other Dired command to visit a directory that is already being shown in a Dired buffer, Dired switches to that buffer but does not update it. If the buffer is not up-to-date, Dired displays a warning telling you to type g to update it. You can also tell Emacs to revert each Dired buffer automatically when you revisit it, by setting the variable dired-auto-revert-buffer to a non-nil value.

To delete file lines from the buffer—without actually deleting the files—type k (dired-do-kill-lines). Like the file-operating commands, this command operates on the next n files, or on the marked files if any. However, it does not operate on the current file, since otherwise mistyping k could be annoying.

If you use k to kill the line for a directory file which you had inserted in the Dired buffer as a subdirectory (see Subdirectories in Dired), it removes the subdirectory listing as well. Typing C-u k on the header line for a subdirectory also removes the subdirectory line from the Dired buffer.

The g command brings back any individual lines that you have killed in this way, but not subdirectories—you must use i to reinsert a subdirectory.

The files in a Dired buffers are normally listed in alphabetical order by file names. Alternatively Dired can sort them by date/time. The Dired command s (dired-sort-toggle-or-edit) switches between these two sorting modes. The mode line in a Dired buffer indicates which way it is currently sorted—by name, or by date.

C-u s switches RET lets you specify a new value for dired-listing-switches.

Next: , Previous: , Up: Dired   [Contents][Index]

30.16 Dired and find

You can select a set of files for display in a Dired buffer more flexibly by using the find utility to choose the files.

To search for files with names matching a wildcard pattern use M-x find-name-dired. It reads arguments directory and pattern, and chooses all the files in directory or its subdirectories whose individual names match pattern.

The files thus chosen are displayed in a Dired buffer, in which the ordinary Dired commands are available.

If you want to test the contents of files, rather than their names, use M-x find-grep-dired. This command reads two minibuffer arguments, directory and regexp; it chooses all the files in directory or its subdirectories that contain a match for regexp. It works by running the programs find and grep. See also M-x grep-find, in Grep Searching. Remember to write the regular expression for grep, not for Emacs. (An alternative method of showing files whose contents match a given regexp is the % g regexp command, see Marks vs Flags.)

The most general command in this series is M-x find-dired, which lets you specify any condition that find can test. It takes two minibuffer arguments, directory and find-args; it runs find in directory, passing find-args to tell find what condition to test. To use this command, you need to know how to use find.

The format of listing produced by these commands is controlled by the variable find-ls-option. This is a pair of options; the first specifying how to call find to produce the file listing, and the second telling Dired to parse the output.

The command M-x locate provides a similar interface to the locate program. M-x locate-with-filter is similar, but keeps only files whose names match a given regular expression.

These buffers don’t work entirely like ordinary Dired buffers: file operations work, but do not always automatically update the buffer. Reverting the buffer with g deletes all inserted subdirectories, and erases all flags and marks.

Next: , Previous: , Up: Dired   [Contents][Index]

30.17 Editing the Dired Buffer

Wdired is a special mode that allows you to perform file operations by editing the Dired buffer directly (the “W” in “Wdired” stands for “writable”). To enter Wdired mode, type C-x C-q (dired-toggle-read-only) while in a Dired buffer. Alternatively, use the ‘Immediate / Edit File Names’ menu item.

While in Wdired mode, you can rename files by editing the file names displayed in the Dired buffer. All the ordinary Emacs editing commands, including rectangle operations and query-replace, are available for this. Once you are done editing, type C-c C-c (wdired-finish-edit). This applies your changes and switches back to ordinary Dired mode.

Apart from simply renaming files, you can move a file to another directory by typing in the new file name (either absolute or relative). To mark a file for deletion, delete the entire file name. To change the target of a symbolic link, edit the link target name which appears next to the link name.

If you edit the file names to create a new subdirectory, Wdired will automatically create these new directories. To inhibit this behavior, set wdired-create-parent-directories to nil.

The rest of the text in the buffer, such as the file sizes and modification dates, is marked read-only, so you can’t edit it. However, if you set wdired-allow-to-change-permissions to t, you can edit the file permissions. For example, you can change ‘-rw-r--r--’ to ‘-rw-rw-rw-’ to make a file world-writable. These changes also take effect when you type C-c C-c.

Next: , Previous: , Up: Dired   [Contents][Index]

30.18 Viewing Image Thumbnails in Dired

Image-Dired is a facility for browsing image files. It provides viewing the images either as thumbnails or in full size, either inside Emacs or through an external viewer. This is different from Image mode (see Image Mode) for visiting an image file in the Emacs buffer.

To enter Image-Dired, mark the image files you want to look at in the Dired buffer, using m as usual. Then type C-t d (image-dired-display-thumbs). This creates and switches to a buffer containing image-dired, corresponding to the marked files.

You can also enter Image-Dired directly by typing M-x image-dired. This prompts for a directory; specify one that has image files. This creates thumbnails for all the images in that directory, and displays them all in the thumbnail buffer. This takes a long time if the directory contains many image files, and it asks for confirmation if the number of image files exceeds image-dired-show-all-from-dir-max-files.

With point in the thumbnail buffer, you can type RET (image-dired-display-thumbnail-original-image) to display a sized version of it in another window. This sizes the image to fit the window. Use the arrow keys to move around in the buffer. For easy browsing, use SPC (image-dired-display-next-thumbnail-original) to advance and display the next image. Typing DEL (image-dired-display-previous-thumbnail-original) backs up to the previous thumbnail and displays that instead.

To view the image in its original size, either provide a prefix argument (C-u) before pressing RET, or type C-RET (image-dired-thumbnail-display-external) to display the image in an external viewer. You must first configure image-dired-external-viewer.

You can delete images through Image-Dired also. Type d (image-dired-flag-thumb-original-file) to flag the image file for deletion in the Dired buffer. You can also delete the thumbnail image from the thumbnail buffer with C-d (image-dired-delete-char).

More advanced features include image tags, which are metadata used to categorize image files. The tags are stored in a plain text file configured by image-dired-db-file.

To tag image files, mark them in the dired buffer (you can also mark files in Dired from the thumbnail buffer by typing m) and type C-t t (image-dired-tag-files). This reads the tag name in the minibuffer. To mark files having a certain tag, type C-t f (image-dired-mark-tagged-files). After marking image files with a certain tag, you can use C-t d to view them.

You can also tag a file directly from the thumbnail buffer by typing t t and you can remove a tag by typing t r. There is also a special tag called “comment” for each file (it is not a tag in the exact same sense as the other tags, it is handled slightly differently). That is used to enter a comment or description about the image. You comment a file from the thumbnail buffer by typing c. You will be prompted for a comment. Type C-t c to add a comment from Dired (image-dired-dired-comment-files).

Image-Dired also provides simple image manipulation. In the thumbnail buffer, type L to rotate the original image 90 degrees anti clockwise, and R to rotate it 90 degrees clockwise. This rotation is lossless, and uses an external utility called jpegtran, which you need to install first.

Previous: , Up: Dired   [Contents][Index]

30.19 Other Dired Features

The command + (dired-create-directory) reads a directory’s name, and creates that directory. It signals an error if the directory already exists.

The command (dired-create-empty-file) reads a file name, and creates that file. It signals an error if the file already exists.

The command M-s a C-s (dired-do-isearch) begins a multi-file incremental search on the marked files. If a search fails at the end of a file, typing C-s advances to the next marked file and repeats the search; at the end of the last marked file, the search wraps around to the first marked file. The command M-s a M-C-s (dired-do-isearch-regexp) does the same with a regular expression search. See Repeat Isearch, for information about search repetition.

The command w (dired-copy-filename-as-kill) puts the names of the marked (or next n) files into the kill ring, as if you had killed them with C-w. The names are separated by a space.

With a zero prefix argument, this uses the absolute file name of each marked file. With just C-u as the prefix argument, it uses file names relative to the Dired buffer’s default directory. (This can still contain slashes if in a subdirectory.) As a special case, if point is on a directory header line, w gives you the absolute name of that directory. Any prefix argument or marked files are ignored in this case.

The main purpose of this command is so that you can yank the file names into arguments for other Emacs commands. It also displays what it added to the kill ring, so you can use it to display the list of currently marked files in the echo area.

If you have an HTML file in the file listing, it can be useful to view that file with a browser. The W (browse-url-of-dired-file) command will use the standard configured browser to view that file.

The command ( (dired-hide-details-mode) toggles whether details, such as ownership or file permissions, are visible in the current Dired buffer. By default, it also hides the targets of symbolic links, and all lines other than the header line and file/directory listings. To change this, customize the options dired-hide-details-hide-symlink-targets and dired-hide-details-hide-information-lines, respectively.

If the directory you are visiting is under version control (see Version Control), then the normal VC diff and log commands will operate on the selected files.

The command M-x dired-compare-directories is used to compare the current Dired buffer with another directory. It marks all the files that differ between the two directories. It puts these marks in all Dired buffers where these files are listed, which of course includes the current buffer.

The default comparison method (used if you type RET at the prompt) is to compare just the file names—file names differ if they do not appear in the other directory. You can specify more stringent comparisons by entering a Lisp expression, which can refer to the variables size1 and size2, the respective file sizes; mtime1 and mtime2, the last modification times in seconds, as floating point numbers; and fa1 and fa2, the respective file attribute lists (as returned by the function file-attributes). This expression is evaluated for each pair of like-named files, and files differ if the expression’s value is non-nil.

For instance, the sequence M-x dired-compare-directories RET (> mtime1 mtime2) RET marks files newer in this directory than in the other, and marks files older in the other directory than in this one. It also marks files with no counterpart, in both directories, as always.

On the X Window System, Emacs supports the drag and drop protocol. You can drag a file object from another program, and drop it onto a Dired buffer; this either moves, copies, or creates a link to the file in that directory. Precisely which action is taken is determined by the originating program. Dragging files out of a Dired buffer is currently not supported.


Next: , Previous: , Up: Top   [Contents][Index]

31 The Calendar and the Diary

Emacs provides the functions of a desk calendar, with a diary of planned or past events. It also has facilities for managing your appointments, and keeping track of how much time you spend working on certain projects.

To enter the calendar, type M-x calendar. This displays a three-month calendar centered on the current month, with point on the current date. With a numeric argument, as in C-u M-x calendar, it prompts you for the month and year to be the center of the three-month calendar. The calendar uses its own buffer, whose major mode is Calendar mode.

mouse-3 in the calendar brings up a menu of operations on a particular date; mouse-2 brings up a menu of commonly used calendar features that are independent of any particular date. To exit the calendar, type q.

31.1 Movement in the Calendar

Calendar mode provides commands to move through the calendar in logical units of time such as days, weeks, months, and years. If you move outside the three months originally displayed, the calendar display scrolls automatically through time to make the selected date visible. Moving to a date lets you view its holidays or diary entries, or convert it to other calendars; moving by long time periods is also useful simply to scroll the calendar.

31.1.1 Motion by Standard Lengths of Time

The commands for movement in the calendar buffer parallel the commands for movement in text. You can move forward and backward by days, weeks, months, and years.

C-f

Move point one day forward (calendar-forward-day).

C-b

Move point one day backward (calendar-backward-day).

C-n

Move point one week forward (calendar-forward-week).

C-p

Move point one week backward (calendar-backward-week).

M-}

Move point one month forward (calendar-forward-month).

M-{

Move point one month backward (calendar-backward-month).

C-x ]

Move point one year forward (calendar-forward-year).

C-x [

Move point one year backward (calendar-backward-year).

The day and week commands are natural analogues of the usual Emacs commands for moving by characters and by lines. Just as C-n usually moves to the same column in the following line, in Calendar mode it moves to the same day in the following week. And C-p moves to the same day in the previous week.

The arrow keys are equivalent to C-f, C-b, C-n and C-p, just as they normally are in other modes.

The commands for motion by months and years work like those for weeks, but move a larger distance. The month commands M-} and M-{ move forward or backward by an entire month. The year commands C-x ] and C-x [ move forward or backward a whole year.

The easiest way to remember these commands is to consider months and years analogous to paragraphs and pages of text, respectively. But the calendar movement commands themselves do not quite parallel those for movement through text: the ordinary Emacs paragraph commands move to the beginning or end of a paragraph, whereas these month and year commands move by an entire month or an entire year, keeping the same date within the month or year.

All these commands accept a numeric argument as a repeat count. For convenience, the digit keys and the minus sign specify numeric arguments in Calendar mode even without the Meta modifier. For example, 100 C-f moves point 100 days forward from its present location.

31.1.2 Beginning or End of Week, Month or Year

A week (or month, or year) is not just a quantity of days; we think of weeks (months, years) as starting on particular dates. So Calendar mode provides commands to move to the start or end of a week, month or year:

C-a

Move point to start of week (calendar-beginning-of-week).

C-e

Move point to end of week (calendar-end-of-week).

M-a

Move point to start of month (calendar-beginning-of-month).

M-e

Move point to end of month (calendar-end-of-month).

M-<

Move point to start of year (calendar-beginning-of-year).

M->

Move point to end of year (calendar-end-of-year).

These commands also take numeric arguments as repeat counts, with the repeat count indicating how many weeks, months, or years to move backward or forward.

By default, weeks begin on Sunday. To make them begin on Monday instead, set the variable calendar-week-start-day to 1. To change which day headers are highlighted as weekend days, set the variable calendar-weekend-days.

31.1.3 Specified Dates

Calendar mode provides commands for moving to a particular date specified in various ways.

g d

Move point to specified date (calendar-goto-date).

g D

Move point to specified day of year (calendar-goto-day-of-year).

g w

Move point to specified week of year (calendar-iso-goto-week).

o

Center calendar around specified month (calendar-other-month).

.

Move point to today’s date (calendar-goto-today).

g d (calendar-goto-date) prompts for a year, a month, and a day of the month, and then moves to that date. Because the calendar includes all dates from the beginning of the current era, you must type the year in its entirety; that is, type ‘2010’, not ‘10’.

g D (calendar-goto-day-of-year) prompts for a year and day number, and moves to that date. Negative day numbers count backward from the end of the year. g w (calendar-iso-goto-week) prompts for a year and week number, and moves to that week.

o (calendar-other-month) prompts for a month and year, then centers the three-month calendar around that month.

You can return to today’s date with . (calendar-goto-today).

31.2 Scrolling in the Calendar

The calendar display scrolls automatically through time when you move out of the visible portion. You can also scroll it manually. Imagine that the calendar window contains a long strip of paper with the months on it. Scrolling the calendar means moving the strip horizontally, so that new months become visible in the window.

>

Scroll calendar one month forward (calendar-scroll-left).

<

Scroll calendar one month backward (calendar-scroll-right).

C-v
PageDown
next

Scroll forward by three months (calendar-scroll-left-three-months).

M-v
PageUp
prior

Scroll backward by three months (calendar-scroll-right-three-months).

The most basic calendar scroll commands scroll by one month at a time. This means that there are two months of overlap between the display before the command and the display after. > scrolls the calendar contents one month forward in time. < scrolls the contents one month backwards in time.

The commands C-v and M-v scroll the calendar by an entire screenful—three months—in analogy with the usual meaning of these commands. C-v makes later dates visible and M-v makes earlier dates visible. These commands take a numeric argument as a repeat count; in particular, since C-u multiplies the next command by four, typing C-u C-v scrolls the calendar forward by a year and typing C-u M-v scrolls the calendar backward by a year.

The function keys PageDown (or next) and PageUp (or prior) are equivalent to C-v and M-v, just as they are in other modes.

31.3 Counting Days

M-=

Display the number of days in the current region (calendar-count-days-region).

To determine the number of days in a range, set the mark on one date using C-SPC, move point to another date, and type M-= (calendar-count-days-region). The numbers of days shown is inclusive; that is, it includes the days specified by mark and point.

31.4 Miscellaneous Calendar Commands

p d

Display day-in-year (calendar-print-day-of-year).

C-c C-l

Regenerate the calendar window (calendar-redraw).

SPC

Scroll the next window up (scroll-other-window).

DEL
S-SPC

Scroll the next window down (scroll-other-window-down).

q

Exit from calendar (calendar-exit).

To display the number of days elapsed since the start of the year, or the number of days remaining in the year, type the p d command (calendar-print-day-of-year). This displays both of those numbers in the echo area. The count of days elapsed includes the selected date. The count of days remaining does not include that date.

If the calendar window text gets corrupted, type C-c C-l (calendar-redraw) to redraw it. (This can only happen if you use non-Calendar-mode editing commands.)

In Calendar mode, you can use SPC (scroll-other-window) and DEL (scroll-other-window-down) to scroll the other window (if there is one) up or down, respectively. This is handy when you display a list of holidays or diary entries in another window.

To exit from the calendar, type q (calendar-exit). This buries all buffers related to the calendar, selecting other buffers. (If a frame contains a dedicated calendar window, exiting from the calendar deletes or iconifies that frame depending on the value of calendar-remove-frame-by-deleting.)

Next: , Previous: , Up: Calendar/Diary   [Contents][Index]

31.5 Writing Calendar Files

You can write calendars and diary entries to HTML and LaTeX files.

The Calendar HTML commands produce files of HTML code that contain calendar, holiday, and diary entries. Each file applies to one month, and has a name of the format yyyy-mm.html, where yyyy and mm are the four-digit year and two-digit month, respectively. The variable cal-html-directory specifies the default output directory for the HTML files. To prevent holidays from being shown, customize cal-html-holidays.

Diary entries enclosed by < and > are interpreted as HTML tags (for example: this is a diary entry with <font color=”red”>some red text</font>). You can change the overall appearance of the displayed HTML pages (for example, the color of various page elements, header styles) via a stylesheet cal.css in the directory containing the HTML files (see the value of the variable cal-html-css-default for relevant style settings).

H m

Generate a one-month calendar (cal-html-cursor-month).

H y

Generate a calendar file for each month of a year, as well as an index page (cal-html-cursor-year). By default, this command writes files to a yyyy subdirectory—if this is altered some hyperlinks between years will not work.

If the variable cal-html-print-day-number-flag is non-nil, then the monthly calendars show the day-of-the-year number. The variable cal-html-year-index-cols specifies the number of columns in the yearly index page.

The Calendar LaTeX commands produce a buffer of LaTeX code that prints as a calendar. Depending on the command you use, the printed calendar covers the day, week, month or year that point is in.

t m

Generate a one-month calendar (cal-tex-cursor-month).

t M

Generate a sideways-printing one-month calendar (cal-tex-cursor-month-landscape).

t d

Generate a one-day calendar (cal-tex-cursor-day).

t w 1

Generate a one-page calendar for one week, with hours (cal-tex-cursor-week).

t w 2

Generate a two-page calendar for one week, with hours (cal-tex-cursor-week2).

t w 3

Generate an ISO-style calendar for one week, without hours (cal-tex-cursor-week-iso).

t w 4

Generate a calendar for one Monday-starting week, with hours (cal-tex-cursor-week-monday).

t w W

Generate a two-page calendar for one week, without hours (cal-tex-cursor-week2-summary).

t f w

Generate a Filofax-style two-weeks-at-a-glance calendar (cal-tex-cursor-filofax-2week).

t f W

Generate a Filofax-style one-week-at-a-glance calendar (cal-tex-cursor-filofax-week).

t y

Generate a calendar for one year (cal-tex-cursor-year).

t Y

Generate a sideways-printing calendar for one year (cal-tex-cursor-year-landscape).

t f y

Generate a Filofax-style calendar for one year (cal-tex-cursor-filofax-year).

Some of these commands print the calendar sideways (in landscape mode), so it can be wider than it is long. Some of them use Filofax paper size (3.75in x 6.75in). All of these commands accept a prefix argument, which specifies how many days, weeks, months or years to print (starting always with the selected one).

If the variable cal-tex-holidays is non-nil (the default), then the printed calendars show the holidays in calendar-holidays. If the variable cal-tex-diary is non-nil (the default is nil), diary entries are included also (in monthly, Filofax, and iso-week calendars only). If the variable cal-tex-rules is non-nil (the default is nil), the calendar displays ruled pages in styles that have sufficient room. Consult the documentation of the individual cal-tex functions to see which calendars support which features.

You can use the variable cal-tex-preamble-extra to insert extra LaTeX commands in the preamble of the generated document if you need to.

31.6 Holidays

The Emacs calendar knows about many major and minor holidays, and can display them. You can add your own holidays to the default list.

mouse-3 Holidays
h

Display holidays for the selected date (calendar-cursor-holidays).

x

Mark holidays in the calendar window (calendar-mark-holidays).

u

Unmark calendar window (calendar-unmark).

a

List all holidays for the displayed three months in another window (calendar-list-holidays).

M-x holidays

List all holidays for three months around today’s date in another window.

M-x list-holidays

List holidays in another window for a specified range of years.

To see if any holidays fall on a given date, position point on that date in the calendar window and use the h command. Alternatively, click on that date with mouse-3 and then choose Holidays from the menu that appears. Either way, this displays the holidays for that date, in the echo area if they fit there, otherwise in a separate window.

To view the distribution of holidays for all the dates shown in the calendar, use the x command. This displays the dates that are holidays in a different face. See calendar-holiday-marker. The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type u, which also erases any diary marks (see Diary). If the variable calendar-mark-holidays-flag is non-nil, creating or updating the calendar marks holidays automatically.

To get even more detailed information, use the a command, which displays a separate buffer containing a list of all holidays in the current three-month range. You can use SPC and DEL in the calendar window to scroll that list up and down, respectively.

The command M-x holidays displays the list of holidays for the current month and the preceding and succeeding months; this works even if you don’t have a calendar window. If the variable calendar-view-holidays-initially-flag is non-nil, creating the calendar displays holidays in this way. If you want the list of holidays centered around a different month, use C-u M-x holidays, which prompts for the month and year.

The holidays known to Emacs include United States holidays and the major Bahá’í, Chinese, Christian, Islamic, and Jewish holidays; also the solstices and equinoxes.

The command M-x holiday-list displays the list of holidays for a range of years. This function asks you for the starting and stopping years, and allows you to choose all the holidays or one of several categories of holidays. You can use this command even if you don’t have a calendar window.

The dates used by Emacs for holidays are based on current practice, not historical fact. For example Veteran’s Day began in 1919, but is shown in earlier years.

Next: , Previous: , Up: Calendar/Diary   [Contents][Index]

31.7 Times of Sunrise and Sunset

Special calendar commands can tell you, to within a minute or two, the times of sunrise and sunset for any date.

mouse-3 Sunrise/sunset
S

Display times of sunrise and sunset for the selected date (calendar-sunrise-sunset).

M-x sunrise-sunset

Display times of sunrise and sunset for today’s date.

C-u M-x sunrise-sunset

Display times of sunrise and sunset for a specified date.

M-x calendar-sunrise-sunset-month

Display times of sunrise and sunset for the selected month.

Within the calendar, to display the local times of sunrise and sunset in the echo area, move point to the date you want, and type S. Alternatively, click mouse-3 on the date, then choose ‘Sunrise/sunset’ from the menu that appears. The command M-x sunrise-sunset is available outside the calendar to display this information for today’s date or a specified date. To specify a date other than today, use C-u M-x sunrise-sunset, which prompts for the year, month, and day.

You can display the times of sunrise and sunset for any location and any date with C-u C-u M-x sunrise-sunset. This asks you for a longitude, latitude, number of minutes difference from Coordinated Universal Time, and date, and then tells you the times of sunrise and sunset for that location on that date.

Because the times of sunrise and sunset depend on the location on earth, you need to tell Emacs your latitude, longitude, and location name before using these commands. Here is an example of what to set:

(setq calendar-latitude 40.1)
(setq calendar-longitude -88.2)
(setq calendar-location-name "Urbana, IL")

Use one decimal place in the values of calendar-latitude and calendar-longitude.

Your time zone also affects the local time of sunrise and sunset. Emacs usually gets time zone information from the operating system, but if these values are not what you want (or if the operating system does not supply them), you must set them yourself. Here is an example:

(setq calendar-time-zone -360)
(setq calendar-standard-time-zone-name "CST")
(setq calendar-daylight-time-zone-name "CDT")

The value of calendar-time-zone is the number of minutes difference between your local standard time and Coordinated Universal Time (Greenwich time). The values of calendar-standard-time-zone-name and calendar-daylight-time-zone-name are the abbreviations used in your time zone. Emacs displays the times of sunrise and sunset corrected for daylight saving time. See Daylight Saving, for how daylight saving time is determined.

As a user, you might find it convenient to set the calendar location variables for your usual physical location in your .emacs file. If you are a system administrator, you may want to set these variables for all users in a default.el file. See Init File.

31.8 Phases of the Moon

These calendar commands display the dates and times of the phases of the moon (new moon, first quarter, full moon, last quarter). This feature is useful for debugging problems that depend on the phase of the moon.

M

Display the dates and times for all the quarters of the moon for the three-month period shown (calendar-lunar-phases).

M-x lunar-phases

Display dates and times of the quarters of the moon for three months around today’s date.

Within the calendar, use the M command to display a separate buffer of the phases of the moon for the current three-month range. The dates and times listed are accurate to within a few minutes.

Outside the calendar, use the command M-x lunar-phases to display the list of the phases of the moon for the current month and the preceding and succeeding months. For information about a different month, use C-u M-x lunar-phases, which prompts for the month and year.

The dates and times given for the phases of the moon are given in local time (corrected for daylight saving, when appropriate). See the discussion in the previous section. See Sunrise/Sunset.

Next: , Previous: , Up: Calendar/Diary   [Contents][Index]

31.9 Conversion To and From Other Calendars

The Emacs calendar displayed is always the Gregorian calendar, sometimes called the New Style calendar, which is used in most of the world today. However, this calendar did not exist before the sixteenth century and was not widely used before the eighteenth century; it did not fully displace the Julian calendar and gain universal acceptance until the early twentieth century. The Emacs calendar can display any month since January, year 1 of the current era, but the calendar displayed is always the Gregorian, even for a date at which the Gregorian calendar did not exist.

While Emacs cannot display other calendars, it can convert dates to and from several other calendars.

31.9.1 Supported Calendar Systems

The ISO commercial calendar is often used in business.

The Julian calendar, named after Julius Caesar, was the one used in Europe throughout medieval times, and in many countries up until the nineteenth century.

Astronomers use a simple counting of days elapsed since noon, Monday, January 1, 4713 BC on the Julian calendar. The number of days elapsed is called the Julian day number or the Astronomical day number.

The Hebrew calendar is used by tradition in the Jewish religion. The Emacs calendar program uses the Hebrew calendar to determine the dates of Jewish holidays. Hebrew calendar dates begin and end at sunset.

The Islamic calendar is used in many predominantly Islamic countries. Emacs uses it to determine the dates of Islamic holidays. There is no universal agreement in the Islamic world about the calendar; Emacs uses a widely accepted version, but the precise dates of Islamic holidays often depend on proclamation by religious authorities, not on calculations. As a consequence, the actual dates of observance can vary slightly from the dates computed by Emacs. Islamic calendar dates begin and end at sunset.

The French Revolutionary calendar was created by the Jacobins after the 1789 revolution, to represent a more secular and nature-based view of the annual cycle, and to install a 10-day week in a rationalization measure similar to the metric system. The French government officially abandoned this calendar at the end of 1805.

The Maya of Central America used three separate, overlapping calendar systems, the long count, the tzolkin, and the haab. Emacs knows about all three of these calendars. Experts dispute the exact correlation between the Mayan calendar and our calendar; Emacs uses the Goodman-Martinez-Thompson correlation in its calculations.

The Copts use a calendar based on the ancient Egyptian solar calendar. Their calendar consists of twelve 30-day months followed by an extra five-day period. Once every fourth year they add a leap day to this extra period to make it six days. The Ethiopic calendar is identical in structure, but has different year numbers and month names.

The Persians use a solar calendar based on a design of Omar Khayyam. Their calendar consists of twelve months of which the first six have 31 days, the next five have 30 days, and the last has 29 in ordinary years and 30 in leap years. Leap years occur in a complicated pattern every four or five years. The calendar implemented here is the arithmetical Persian calendar championed by Birashk, based on a 2,820-year cycle. It differs from the astronomical Persian calendar, which is based on astronomical events. As of this writing the first future discrepancy is projected to occur on March 20, 2025. It is currently not clear what the official calendar of Iran will be at that time.

The Chinese calendar is a complicated system of lunar months arranged into solar years. The years go in cycles of sixty, each year containing either twelve months in an ordinary year or thirteen months in a leap year; each month has either 29 or 30 days. Years, ordinary months, and days are named by combining one of ten celestial stems with one of twelve terrestrial branches for a total of sixty names that are repeated in a cycle of sixty.

The Bahá’í calendar system is based on a solar cycle of 19 months with 19 days each. The four remaining intercalary days are placed between the 18th and 19th months.

31.9.2 Converting To Other Calendars

The following commands describe the selected date (the date at point) in various other calendar systems:

mouse-3 Other calendars
p o

Display the selected date in various other calendars. (calendar-print-other-dates).

p c

Display ISO commercial calendar equivalent for selected day (calendar-iso-print-date).

p j

Display Julian date for selected day (calendar-julian-print-date).

p a

Display astronomical (Julian) day number for selected day (calendar-astro-print-day-number).

p h

Display Hebrew date for selected day (calendar-hebrew-print-date).

p i

Display Islamic date for selected day (calendar-islamic-print-date).

p f

Display French Revolutionary date for selected day (calendar-french-print-date).

p b

Display Bahá’í date for selected day (calendar-bahai-print-date).

p C

Display Chinese date for selected day (calendar-chinese-print-date).

p k

Display Coptic date for selected day (calendar-coptic-print-date).

p e

Display Ethiopic date for selected day (calendar-ethiopic-print-date).

p p

Display Persian date for selected day (calendar-persian-print-date).

p m

Display Mayan date for selected day (calendar-mayan-print-date).

Otherwise, move point to the date you want to convert, then type the appropriate command starting with p from the table above. The prefix p is a mnemonic for “print”, since Emacs “prints” the equivalent date in the echo area. p o displays the date in all forms known to Emacs. You can also use mouse-3 and then choose Other calendars from the menu that appears. This displays the equivalent forms of the date in all the calendars Emacs understands, in the form of a menu. (Choosing an alternative from this menu doesn’t actually do anything—the menu is used only for display.)

31.9.3 Converting From Other Calendars

You can use the other supported calendars to specify a date to move to. This section describes the commands for doing this using calendars other than Mayan; for the Mayan calendar, see the