"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/emacs/indent.texi" (14 Apr 2017, 10964 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "indent.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 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. @xref{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).

<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 section 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 (@pxref{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> (@pxref{Inserting Text}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 section 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. @xref{Fill Prefix}.

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 section 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>

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 section Indentation), and by commands like M-i (see section 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 (@pxref{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 (@pxref{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 (@pxref{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. @xref{Text Display}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Tabs vs. Spaces

Normally, indentation commands insert (or remove) an optimal mix of space characters and tab characters 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). @xref{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. @xref{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 (@pxref{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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 (@pxref{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.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 25, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on September 25, 2017 using texi2html.