Enriched mode is a minor mode for editing files that contain formatted text in WYSIWYG fashion, as in a word processor. Currently, formatted text in Enriched mode can specify fonts, colors, underlining, margins, and types of filling and justification. In the future, we plan to implement other formatting features as well.
Enriched mode is a minor mode (Section 32.1). Typically it is used in conjunction with Text mode (Section 23.7). However, you can also use it with other major modes such as Outline mode and Paragraph-Indent Text mode.
Potentially, Emacs can store formatted text files in various file formats. Currently, only one format is implemented: text/enriched format, which is defined by the MIME protocol. , for details of how Emacs recognizes and converts file formats.
The Emacs distribution contains a formatted text file that can serve as an example. Its name is etc/enriched.doc. It contains samples illustrating all the features described in this section. It also contains a list of ideas for future enhancements.
Whenever you visit a file that Emacs saved in the text/enriched format, Emacs automatically converts the formatting information in the file into Emacs's own internal format (text properties), and turns on Enriched mode.
To create a new file of formatted text, first visit the nonexistent file, then type M-x enriched-mode before you start inserting text. This command turns on Enriched mode. Do this before you begin inserting text, to ensure that the text you insert is handled properly.
More generally, the command enriched-mode turns Enriched mode on if it was off, and off if it was on. With a prefix argument, this command turns Enriched mode on if the argument is positive, and turns the mode off otherwise.
When you save a buffer while Enriched mode is enabled in it, Emacs automatically converts the text to text/enriched format while writing it into the file. When you visit the file again, Emacs will automatically recognize the format, reconvert the text, and turn on Enriched mode again.
Normally, after visiting a file in text/enriched format, Emacs refills each paragraph to fit the specified right margin. You can turn off this refilling, to save time, by setting the variable enriched-fill-after-visiting to nil or to ask.
However, when visiting a file that was saved from Enriched mode, there is no need for refilling, because Emacs saves the right margin settings along with the text.
You can add annotations for saving additional text properties, which Emacs normally does not save, by adding to enriched-translations. Note that the text/enriched standard requires any non-standard annotations to have names starting with x-, as in x-read-only. This ensures that they will not conflict with standard annotations that may be added later.
In formatted text, Emacs distinguishes between two different kinds of newlines, hard newlines and soft newlines.
Hard newlines are used to separate paragraphs, or items in a list, or anywhere that there should always be a line break regardless of the margins. The RET command (newline) and C-o (open-line) insert hard newlines.
Soft newlines are used to make text fit between the margins. All the fill commands, including Auto Fill, insert soft newlines--and they delete only soft newlines.
Although hard and soft newlines look the same, it is important to bear the difference in mind. Do not use RET to break lines in the middle of filled paragraphs, or else you will get hard newlines that are barriers to further filling. Instead, let Auto Fill mode break lines, so that if the text or the margins change, Emacs can refill the lines properly. Section 23.5.1.
On the other hand, in tables and lists, where the lines should always remain as you type them, you can use RET to end lines. For these lines, you may also want to set the justification style to unfilled. Section 23.11.7.
There are two ways to alter the formatting information for a formatted text file: with keyboard commands, and with the mouse.
The easiest way to add properties to your document is by using the Text Properties menu. You can get to this menu in two ways: from the Edit menu in the menu bar, or with C-mouse-2 (hold the CTRL key and press the middle mouse button).
Most of the items in the Text Properties menu lead to other submenus. These are described in the sections that follow. Some items run commands directly:
Delete from the region all the text properties that the Text Properties menu works with (facemenu-remove-props).
Delete all text properties from the region (facemenu-remove-all).
List all the text properties of the character following point (list-text-properties-at).
Display a list of all the defined faces.
Display a list of all the defined colors.
The Faces submenu lists various Emacs faces including bold, italic, and underline. Selecting one of these adds the chosen face to the region. Section 13.1. You can also specify a face with these keyboard commands:
Set the region, or the next inserted character, to the default face (facemenu-set-default).
Set the region, or the next inserted character, to the bold face (facemenu-set-bold).
Set the region, or the next inserted character, to the italic face (facemenu-set-italic).
Set the region, or the next inserted character, to the bold-italic face (facemenu-set-bold-italic).
Set the region, or the next inserted character, to the underline face (facemenu-set-underline).
Set the region, or the next inserted character, to the face face (facemenu-set-face).
If you use these commands with a prefix argument--or, in Transient Mark mode, if the region is not active--then these commands specify a face to use for your next self-inserting input. Section 11.2. This applies to both the keyboard commands and the menu commands.
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. This face is the same as italic unless you customize it (Section 32.2.2.3).
The fixed face is meant to say, "Use a fixed-width font for this part of the text." Emacs currently supports only fixed-width fonts; therefore, the fixed annotation is not necessary now. However, we plan to support variable width fonts in future Emacs versions, and other systems that display text/enriched format may not use a fixed-width font as the default. So if you specifically want a certain part of the text to use a fixed-width font, you should specify the fixed face for that part.
The fixed face is normally defined to use a different font from the default. However, systems have different fonts installed, you may need to customize this.
If your terminal cannot display different faces, you will not be able to see them, but you can still edit documents containing faces. You can even add faces and colors to documents. They will be visible when the file is viewed on a terminal that can display them.
You can specify foreground and background colors for portions of the text. There is a menu for specifying the foreground color and a menu for specifying the background color. Each color menu lists all the colors that you have used in Enriched mode in the current Emacs session.
If you specify a color with a prefix argument--or, in Transient Mark mode, if the region is not active--then it applies to your next self-inserting input. Section 11.2. Otherwise, the command applies to the region.
Each color menu contains one additional item: Other. You can use this item to specify a color that is not listed in the menu; it reads the color name with the minibuffer. To display list of available colors and their names, use the Display Colors menu item in the Text Properties menu (Section 23.11.3).
Any color that you specify in this way, or that is mentioned in a formatted text file that you read in, is added to both color menus for the duration of the Emacs session.
There are no key bindings for specifying colors, but you can do so with the extended commands M-x facemenu-set-foreground and M-x facemenu-set-background. Both of these commands read the name of the color with the minibuffer.
When editing formatted text, you can specify different amounts of indentation for the right or left margin of an entire paragraph or a part of a paragraph. The margins you specify automatically affect the Emacs fill commands (Section 23.5) and line-breaking commands.
The Indentation submenu provides a convenient interface for specifying these properties. The submenu contains four items:
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).
Remove 4 columns of indentation from the region.
Make the text narrower by indenting 4 columns at the right margin.
Remove 4 columns of indentation from the right margin.
You can use these commands repeatedly to increase or decrease the indentation.
The most common way to use these commands is to change the indentation of an entire paragraph. However, that is not the only use. You can change the margins at any point; the new values take effect at the end of the line (for right margins) or the beginning of the next line (for left margins).
This makes it possible to format paragraphs with hanging indents, which means that the first line is indented less than subsequent lines. To set up a hanging indent, increase the indentation of the region starting after the first word of the paragraph and running until the end of the paragraph.
Indenting the first line of a paragraph is easier. Set the margin for the whole paragraph where you want it to be for the body of the paragraph, then indent the first line by inserting extra spaces or tabs.
Sometimes, as a result of editing, the filling of a paragraph becomes messed up--parts of the paragraph may extend past the left or right margins. When this happens, use M-q (fill-paragraph) to refill the paragraph.
The variable standard-indent specifies how many columns these commands should add to or subtract from the indentation. The default value is 4.
The overall default right margin for Enriched mode is controlled by the variable fill-column, as usual.
When editing formatted text, you can specify various styles of justification for a paragraph. The style you specify automatically affects the Emacs fill commands.
The Justification submenu provides a convenient interface for specifying the style. The submenu contains five items:
This is the most common style of justification (at least for English). Lines are aligned at the left margin but left uneven at the right.
This aligns each line with the right margin. Spaces and tabs are added on the left, if necessary, to make lines line up on the right.
This justifies the text, aligning both edges of each line. Justified text looks very nice in a printed book, where the spaces can all be adjusted equally, but it does not look as nice with a fixed-width font on the screen. Perhaps a future version of Emacs will be able to adjust the width of spaces in a line to achieve elegant justification.
This centers every line between the current margins.
This turns off filling entirely. Each line will remain as you wrote it; the fill and auto-fill functions will have no effect on text which has this setting. You can, however, still indent the left margin. In unfilled regions, all newlines are treated as hard newlines (Section 23.11.2) .
In Enriched mode, you can also specify justification from the keyboard using the M-j prefix character:
Make the region left-filled (set-justification-left).
Make the region right-filled (set-justification-right).
Make the region fully-justified (set-justification-full).
Make the region centered (set-justification-center).
Make the region unfilled (set-justification-none).
Justification styles apply to entire paragraphs. All the justification-changing commands operate on the paragraph containing point, or, if the region is active, on all paragraphs which overlap the region.
The default justification style is specified by the variable default-justification. Its value should be one of the symbols left, right, full, center, or none.
The Other Properties menu lets you add or remove three other useful text properties: read-only, invisible and intangible. The intangible property disallows moving point within the text, the invisible text property hides text from display, and the read-only property disallows alteration of the text.
Each of these special properties has a menu item to add it to the region. The last menu item, Remove Special, removes all of these special properties from the text in the region.
Currently, the invisible and intangible properties are not saved in the text/enriched format. The read-only property is saved, but it is not a standard part of the text/enriched format, so other editors may not respect it.
Normally, Emacs knows when you are editing formatted text because it recognizes the special annotations used in the file that you visited. However, there are situations in which you must take special actions to convert file contents or turn on Enriched mode:
When you visit a file that was created with some other editor, Emacs may not recognize the file as being in the text/enriched format. In this case, when you visit the file you will see the formatting commands rather than the formatted text. Type M-x format-decode-buffer to translate it.
When you insert a file into a buffer, rather than visiting it. Emacs does the necessary conversions on the text which you insert, but it does not enable Enriched mode. If you wish to do that, type M-x enriched-mode.
The command format-decode-buffer translates text in various formats into Emacs's internal format. It asks you to specify the format to translate from; however, normally you can type just RET, which tells Emacs to guess the format.
If you wish to look at text/enriched file in its raw form, as a sequence of characters rather than as formatted text, use the M-x find-file-literally command. This visits a file, like find-file, but does not do format conversion. It also inhibits character code conversion (Section 20.6) and automatic uncompression (Section 16.11). To disable format conversion but allow character code conversion and/or automatic uncompression if appropriate, use format-find-file with suitable arguments.