Editing Formatted Text
======================

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 (see Minor Modes).  Typically it is used in conjunction with Text mode (see Text Mode).  However, you can also use it with other major modes such as Outline mode and Indented 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.

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.

Requesting to Edit Formatted Text
---------------------------------

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 reading a file in text/enriched format, Emacs refills each paragraph to fit the width of the window.  You can turn off this refilling, to save time, by setting the variable enriched-fill-after-visiting to nil or to ask.

In any case, if the window width is the same as the width with which the file was saved, Emacs trusts that the file is already properly filled.

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.

Hard and Soft Newlines
----------------------

In formatted text, Emacs distinguishes between two different kinds of newlines, hard newlines and soft and 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.  See Auto Fill.

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.  In this case you may also want to set the justification style to unfilled.  See Format Justification.

Editing Format Information
--------------------------

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.  There are four items that do something directly:

Remove Properties
     Delete all text properties from the region.

List Properties
     List all the text properties of the character following point.

Display Faces
     Display a list of all the defined faces.

Display Colors
     Display a list of all the defined colors.

Faces in Formatted Text
-----------------------

The Faces submenu lists various Emacs faces including bold, italic, and underline.  Selecting one of these adds the chosen face to the region.  See Faces.  You can also specify a face with these keyboard commands:

M-g d
     Set the region, or the next inserted character, to the default face (facemenu-set-default).

M-g b
     Set the region, or the next inserted character, to the bold face (facemenu-set-bold).

M-g i
     Set the region, or the next inserted character, to the italic face (facemenu-set-italic).

M-g l
     Set the region, or the next inserted character, to the bold-italic face (facemenu-set-bold-italic).

M-g u
     Set the region, or the next inserted character, to the underline face (facemenu-set-underline).

M-g o FACE RET
     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 subsequent self-inserting input.  See Transient Mark.  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 excerpts face is intended for quotations.  This face is the same as italic unless you customize it (see Modifying Faces).

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 you are not running Emacs under a window system, you will not be able to see the different faces, 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.

Colors in Formatted Text
------------------------

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 subsequent self-inserting input.  See Transient Mark.  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 a list of available colors and their names, use the Display Colors menu item in the Text Properties menu (see Editing Format Info).

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

Indentation in Formatted Text
-----------------------------

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 (see Filling) and line-breaking commands.

The Indentation submenu provides a convenient interface for specifying these properties.  The submenu contains four items:

Indent
     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).

Unindent
     Remove 4 columns of indentation from the region.

IndentRight
     Make the text narrower by indenting 4 columns at the right margin.

UnindentRight
     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.

Enriched mode automatically sets the variable fill-column based on the window width: it leaves a certain number of columns for the right margin.  The variable enriched-default-right-margin says how many columns.  The default value is 10.

Justification in Formatted Text
-------------------------------

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:

Flush Left
     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.

Flush 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.

Full
     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.

Center
     This centers every line between the current margins.

None
     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 (see Hard and Soft Newlines) .

In Enriched mode, you can also specify justification from the keyboard using the M-j prefix character:

M-j l
     Make the region left-filled (set-justification-left).

M-j r
     Make the region right-filled (set-justification-right).

M-j f
     Make the region fully-justified (set-justification-full).

M-j c
M-S
     Make the region centered (set-justification-center).

M-j u
     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.

Setting Other Text Properties
-----------------------------

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.

Forcing Enriched Mode
---------------------

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 always 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.