7.2. Indenting Text

Emacs provides the ability to indent paragraphs, like a block quote in a paper. It also allows you to use a paragraph style that indents just the first line of a paragraph. This section describes indentation-related commands, including how to change the margins for the current session.

Before we start, make sure you're in text mode. Look at the mode line and, if the word Text is displayed, you are in text mode. If not, type M-x text-mode Enter to enter text mode.

7.2.1 Indenting Paragraphs

Let's say you're writing a paper and want to include some indented block quotes. Emacs's default behavior makes this a no-brainer.^[2] After you finish your first paragraph, use tabs or spaces to indent to the desired level and start typing the quote. Emacs automatically fills the paragraph and the quote correctly, as shown in the following screen.

^[2] Once upon a time, you had to enter indented text mode explicitly to get the behavior we describe here. Now it is on by default in text mode.

Some indented text:

Emacs indents the text properly and fills it correctly in auto-fill mode.

What if an indented quote has multiple paragraphs? You could just press Enter and then Tab again at the beginning of subsequent paragraphs or you could press C-j (for newline-and-indent). Pressing C-j twice gives you a blank line between paragraphs.

7.2.2 Indenting the First Line of a Paragraph

Some people prefer paragraphs in which the first line is indented. Knowing about the intricacies of tabs, you might be concerned that pressing Tab to indent the opening line of your paragraph will incite Emacs to indent the whole paragraph as you continue typing. And it would, to be honest.

Emacs provides a special mode for this purpose: paragraph indent text mode. It's also available as a minor mode. Enter either M-x paragraph-indent-text-mode or M-x paragraph-ident-minor-mode respectively. If you run the major mode, Emacs displays Parindent on the mode line.

When you press Tab to start a paragraph, Emacs inserts a tab's worth of space. When you start a new paragraph, you don't have to skip a line in between and pressing Tab to start that second paragraph yields again a tab's worth of space, not aligning with the second word of the previous line as Emacs would do in text mode or fundamental mode.

Pressing M-q reformats paragraphs without mushing them all together. If you prefer indented paragraphs, this mode is exactly what you want. When you need to indent a block quote, you may want to temporarily enter text mode to make it easier and add your paragraph indentations manually.

7.2.3 Filling Indented Paragraphs

Let's say you've got a paper with paragraphs indented at various levels. What if you edit them and need to fill them again? Especially if there are no blank lines in between paragraphs, M-q munges all the text into one big (nonindented) paragraph. Instead of M-q, mark the region in question and use a special fill command: M-x fill-individual-paragraphs. Emacs preserves each paragraph's indentation.

Let's contrast these two commands with an example. We'll use our previous Henry James example, but delete the lines between paragraphs to show what happens if you use M-q in this case. These paragraphs need to be reformatted.

Initial state:

Some sample paragraphs from Henry James, in need of reformatting.

Type: M-q

Emacs munges it all into one large paragraph.

We'll undo that command, mark the buffer as a region, and use the fill-individual-paragraphs command.

Type: C- _ C-x h M-x fill-individual-paragraphs Enter

Emacs refills the paragraphs properly.

7.2.3.1 Indenting regions

What if you have already typed your text without indentation and want to indent it later? Two commands can handle this, depending on how far you want to indent the region.

The indent-region command, bound to C-M-\, can indent a region one level easily. If you want to indent two levels, it is unpredictable. (This command is designed for indenting code.)

Here's an example. The second paragraph is marked as a region.

Type: C-M-\

Emacs indents the paragraph one level.

You decide that's not far enough.

Type: C-M-\

Emacs creates a stairstep hanging indent.

So you can see that this works fine if you're indenting one level. If you try this with multiple paragraphs of different indentation levels, indent-region pulls them all to the right, aligning them with the least indented paragraph, probably not what you intended. If you write code, however, this command is great for cleaning up messy indentation.

The other option is to mark the region and type C-x Tab (for indent-rigidly). By default, this command indents only one space, so if you want to indent further, you need to give it an argument. For example, to indent the previous paragraph 15 spaces:

Mark the region then type: M-15 C-x Tab

Emacs indents the paragraph 15 spaces.

Although arguably it can be a pain to supply an argument, indent-rigidly uniformly indents text, leaving indented paragraphs indented. If you find yourself wanting to indent whole files, you may actually want to change the margin settings, as described in the next section.

7.2.3.2 Other indentation tricks

Whenever you are using indentation, you can use M-m (for back-to-indentation) to move to the first nonblank character on a line. On a line that's not indented, this command simply moves you to the beginning of the line. In other words, M-m brings you to the "logical" beginning of the line, which is what you usually mean when you type C-a.

Another indentation command is C-M-o (for split-line). You can use this command to create a stairstep effect. Move the cursor to the text that you want to put on the next line and press C-M-o. Note that there must be some text following the cursor in order for this command to work properly; if you try it at the end of a line, it does nothing.

Initial state:

We want to split this line.

Type: C-M-o

C-M-o splits the line at the cursor position.

7.2.4 Changing Margins

Emacs is not a word processor, but it does have a few commands that change left and right indentation for a buffer for the current session. First, mark the whole buffer using C-x h. You can then gchange the indention using M-x followed by one of the following commands:

increase-left-margin

decrease-left-margin

increase-right-margin

decrease-right-margin

These commands are also available through the Edit menu. Choose Edit Text Properties Indentation to see the options.

Unless you supply a numeric argument using C-u or M-n preceding these commands, Emacs increases or decreases the margins by the number of characters in the variable standard-indent, which defaults to 4. If auto-fill mode is on, Emacs also reformats the paragraphs automatically.

Margin settings remain in effect for the current session and the current buffer only. Although the values don't persist to another session, any text that is indented using this method remains indented when you reopen the file. If you open the file again and add some text, however, it is not indented; you have to set the margins again.

These commands work best in cases where you want to change the margin for the whole buffer. If you define a smaller region, the commands work but if you type more paragraphs, the margin settings persist whether you want them to or not. These commands work fine if you've completed the file and then decide to change the indentation.

Alternatively, you can set and save margins using enriched mode, a minor mode that allows Emacs to save text properties, including margin settings and font changes. See Chapter 10 for more details on enriched mode.

7.2.5 Using Fill Prefixes

Fill prefixes are a way of putting a certain string of characters at the beginning of each line in a paragraph or a file. Developers will immediately think of comments as a potential fill prefix. When writing email or newsposts, email programs often insert a string to help readers distinguish the threads of a discussion. For those of us writing text files, fill prefixes can be used to insert whitespace in paragraphs or any relevant string of characters.

The term fill prefix comes from the fact that Emacs calls word wrap auto-fill mode; in other words, a fill prefix is a string that Emacs should insert at the beginning of each line (or "prefix" each line with) when doing word wrap.

To use fill prefixes, it's best to be in auto-fill mode. If your mode line says Fill on it, you're already in auto-fill mode. If it doesn't, type M-x auto-fill-mode Enter.

Now let's assume that you want to indent a letter. For the first line of the letter, type your indentation by hand say, eight spaces. Then type C-x . (for set-fill-prefix). Emacs displays the message: fill prefix " " in the minibuffer. Then start typing normally. Whenever you type past the right margin and Emacs breaks a line for you, it automatically inserts your eight-space indentation at the beginning of the line.

Here's a slightly more exciting example. There's no reason that fill prefixes must to be spaces; they can be anything you choose. Assume that you're sending an email message to your friends to announce a unique event and you want an eye-catching fill prefix.

Type: Elephant Riding Party!!! C-x .

Type the prefix, then C-x . to set it.

Once you've set the prefix, you can type your message normally.

Type: The time . . . the zoo.

Emacs inserts the fill prefix at the beginning of each line of the message.

You had to type "Elephant Riding Party!!!" only once; Emacs inserted the rest automatically. Here are some things you might want to know about fill prefixes:

• Emacs never applies the fill prefix to the first line of a paragraph. You obviously can't apply it to the first line of the first paragraph (you have to type it somewhere). But Emacs can't apply it to the first line of any paragraph. In other words, if the "elephant riding" message had two paragraphs, you'd have to type (or yank) the phrase "Elephant Riding Party!!!" at the beginning of the second paragraph.

• However, you don't need to set the fill prefix again. Emacs supplies your prefix for all lines but the first in subsequent paragraphs. It just gets confused about the initial line of any paragraph.

• Once you've started using a fill prefix, how do you turn it off? There's no special command. All you do is put the cursor at the left margin and type C-x . to define a new, empty fill prefix.

• You can edit paragraphs with fill prefixes, then reformat them with M-q, as long as the fill prefix is still defined. If you have cleared the fill prefix, Emacs reformats the paragraph without regard to the fill prefix. If you need to reformat your paragraphs later, after you've canceled the fill prefix, define it again and then type M-q.

Table 7-2 lists the indentation commands we've discussed.

Table 7-2. Indentation commands

Keystrokes	Command name	Action
C-j	newline-and-indent	Move to the next line and indent to the current level.
(none)	paragraph-indent-text-mode	A major mode for writing paragraphs with indented first lines and no blank lines between paragraphs.
(none)	paragraph-indent-minor-mode	The minor mode equivalent of paragraph-indent-text mode.
(none)	fill-individual-paragraphs	Reformat indented paragraphs, preserving indentation.
C-x Tab	indent-rigidly	Indent one column; preface with C-u or M-n to specify multiple columns.
C-M-\	indent-region	Indent a region to match the first line in the region.
M-m	back-to-indentation	Move the cursor to the first non-whitespace character on a line.
C-M-o	split-line	Split the line at the cursor position and indent it to the column of the cursor position.
(none)Edit Text Properties Indentation increase-left-margin	Increase the left indentation level for the buffer by four characters by default.
(none)Edit Text Properties Indentation decrease-left-margin	Decrease the left indentation level for the buffer by four characters by default.
(none)Edit Text Properties ndentation decrease-right-margin	Decrease the right indentation level for the buffer by four characters by default.
(none)Edit Text Properties Indentation increase-right-margin	Increase the right indentation level for the buffer by four characters by default.
C-x .	set-fill-prefix	Use the information up to the cursor column as a prefix to each line of the paragraph; typing this command in column 1 cancels the fill prefix.