enriched.txt 10.8 KB
Newer Older
Boris Goldowsky's avatar
Boris Goldowsky committed
1 2
Content-Type: text/enriched
Text-Width: 70
3

Boris Goldowsky's avatar
Boris Goldowsky committed
4
<center><x-bg-color><param>blue</param><x-color><param>white</param><bold><fixed>enriched.el:</fixed></bold></x-color></x-bg-color>
5

Boris Goldowsky's avatar
Boris Goldowsky committed
6
<x-bg-color><param>blue</param><x-color><param>white</param><bold>WYSIWYG rich text editing for GNU Emacs</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
7 8


Richard M. Stallman's avatar
Richard M. Stallman committed
9
</center><bold><x-bg-color><param>blue</param><x-color><param>white</param>INTRODUCTION</x-color></x-bg-color></bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
10 11 12



13 14 15 16
<indent>Emacs has the ability to edit <italic>enriched text</italic>, which is text
containing faces, colors, indentation, and other properties.
This document is a quick introduction to some of the features,
and is also an example file in the <italic>text/enriched </italic>format.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
17 18


Richard M. Stallman's avatar
Richard M. Stallman committed
19 20
<x-bg-color><param>blue</param><x-color><param>white</param><bold>INSTALLATION and STARTUP</bold></x-color></x-bg-color>

Boris Goldowsky's avatar
Boris Goldowsky committed
21

Boris Goldowsky's avatar
Boris Goldowsky committed
22 23 24
<indent>Most of the time, you need not do anything to get these features
to work.  If you visit a file that has been written out in
<italic>text/enriched</italic> format, it will automatically be decoded, Emacs will
25
enter 'enriched-mode' while visiting it, and whenever you save it
Boris Goldowsky's avatar
Boris Goldowsky committed
26
it will be saved in the same format it was read in.
Boris Goldowsky's avatar
Boris Goldowsky committed
27

Boris Goldowsky's avatar
Boris Goldowsky committed
28 29
If you wish to create a new file, however, you will need to turn
on enriched-mode yourself:
Boris Goldowsky's avatar
Boris Goldowsky committed
30 31


Richard M. Stallman's avatar
Richard M. Stallman committed
32
<fixed><indent>M-x enriched-mode RET</indent></fixed>
Boris Goldowsky's avatar
Boris Goldowsky committed
33 34


Boris Goldowsky's avatar
Boris Goldowsky committed
35 36 37
Or, if you get a <italic>text/enriched </italic>file that Emacs does not
automatically recognize and decode, you can tell Emacs to decode
it (which also turns on enriched-mode automatically):
Boris Goldowsky's avatar
Boris Goldowsky committed
38 39


Richard M. Stallman's avatar
Richard M. Stallman committed
40
<fixed><indent>M-x format-decode-buffer RET text/enriched RET</indent></fixed></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
41

42

Boris Goldowsky's avatar
Boris Goldowsky committed
43

Richard M. Stallman's avatar
Richard M. Stallman committed
44
<x-bg-color><param>blue</param><x-color><param>white</param><bold>WHAT IS ENCODED</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
45 46


Richard M. Stallman's avatar
Richard M. Stallman committed
47 48 49 50 51
<indent>Here is the current list of text-properties that are saved; they
are discussed in more detail below.  Most of these can be added or
changed with the "Text Properties" menu, available under the
"Edit" item in the menu-bar, or on C-mouse-2 (Control + the middle
mouse button).
Boris Goldowsky's avatar
Boris Goldowsky committed
52

Richard M. Stallman's avatar
Richard M. Stallman committed
53
<bold>Faces:</bold> <indent>default, <bold>bold</bold>, <italic>italic</italic>, <underline>underline</underline>, etc.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
54

Richard M. Stallman's avatar
Richard M. Stallman committed
55
<bold>Colors:</bold> <x-color><param>red</param><x-bg-color><param>DarkSlateGray</param><indent>any</indent></x-bg-color></x-color><x-bg-color><param>DarkSlateGray</param><indent><x-color><param>orange</param>thing</x-color> <x-color><param>yellow</param>your</x-color><x-color><param>green</param> screen</x-color><x-color><param>blue</param> </x-color><x-color><param>light blue</param>can</x-color><x-color><param>violet</param> display...</x-color></indent></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
56

Boris Goldowsky's avatar
Boris Goldowsky committed
57
<bold>Newlines:</bold> <indent>Which ones are real ("hard") newlines, and which can be
Richard M. Stallman's avatar
Richard M. Stallman committed
58
changed to fit lines into the margins.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
59

Richard M. Stallman's avatar
Richard M. Stallman committed
60
<bold>Margins:</bold> <indent>can be indented on the left or right.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
61

Richard M. Stallman's avatar
Richard M. Stallman committed
62 63
<bold>Justification</bold> <indent>(whether lines should be flush with the left margin,
the right margin, fully justified, centered, or left alone).</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
64

Richard M. Stallman's avatar
Richard M. Stallman committed
65
<bold>Excerpts:</bold><indent> <excerpt>"For quoted material."</excerpt></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
66

67 68 69 70 71
<bold>Read-only, Invisible, and Intangible</bold> regions.

<bold>Charset</bold> properties.

<bold>Display</bold> properties.
Boris Goldowsky's avatar
Boris Goldowsky committed
72

Richard M. Stallman's avatar
Richard M. Stallman committed
73
</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
74

Richard M. Stallman's avatar
Richard M. Stallman committed
75
<x-bg-color><param>blue</param><x-color><param>white</param><bold>FACES and COLORS</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
76 77


78
<indent>You can add faces either with the menu or with <fixed>M-o.</fixed>  The face is
Boris Goldowsky's avatar
Boris Goldowsky committed
79
applied to the current region.  If you are using
80
'transient-mark-mode' and the region is not active, then the face
81 82 83
applies to whatever you type next.  Any face can have colors.  If
this is its lone attribute, the face is put on the color submenus
of the "Text Properties" menu.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
84 85


Richard M. Stallman's avatar
Richard M. Stallman committed
86
<x-bg-color><param>blue</param><x-color><param>white</param><bold>NEWLINES and PARAGRAPHS</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
87 88


Richard M. Stallman's avatar
Richard M. Stallman committed
89
<italic><indent>Text/enriched</indent></italic><indent> format distinguishes between <underline>hard</underline> and <underline>soft</underline> newlines.
Boris Goldowsky's avatar
Boris Goldowsky committed
90 91 92 93 94 95
Hard newlines are used to separate paragraphs, or items in a list,
or anywhere that must be a line break no matter what the margins
are.  Soft newlines are the ones inserted in order to fit text
between the margins.  The fill and auto-fill functions insert soft
newlines as necessary, but hard newlines are only inserted by
direct request, such as using the return key or the <fixed>C-o
Richard M. Stallman's avatar
Richard M. Stallman committed
96 97
(open-line)</fixed> function.</indent>

Boris Goldowsky's avatar
Boris Goldowsky committed
98

Richard M. Stallman's avatar
Richard M. Stallman committed
99
<x-bg-color><param>blue</param><x-color><param>white</param><bold>INDENTATION</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
100 101


Richard M. Stallman's avatar
Richard M. Stallman committed
102 103 104
<indent>The fill functions also understand margins, which can be set for
any region of a document.  In addition to the menu items, which
increase or decrease the margins, there are two commands for
105 106
setting the margins absolutely: <fixed>C-c [ (set-left-margin)</fixed> and <fixed>C-c
] (set-right-margin)</fixed>.
Boris Goldowsky's avatar
Boris Goldowsky committed
107 108


Richard M. Stallman's avatar
Richard M. Stallman committed
109 110 111
You <indent>can change indentation at any point in a paragraph, which
makes it possible to do interesting things like
hanging-indents: this paragraph was indented by selecting the
Boris Goldowsky's avatar
Boris Goldowsky committed
112
region from the second word to the end of the paragraph, and
Richard M. Stallman's avatar
Richard M. Stallman committed
113
indenting only that part.</indent></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
114 115


Richard M. Stallman's avatar
Richard M. Stallman committed
116
<x-bg-color><param>blue</param><x-color><param>white</param><bold>JUSTIFICATION</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
117 118


Richard M. Stallman's avatar
Richard M. Stallman committed
119

120 121
<indent><nofill>Several styles of justification are possible, the simplest being <italic>unfilled.
</italic>This means that your lines will be left as you write them.
Richard M. Stallman's avatar
Richard M. Stallman committed
122 123
This paragraph is unfilled.</nofill>

Boris Goldowsky's avatar
Boris Goldowsky committed
124

Richard M. Stallman's avatar
Richard M. Stallman committed
125 126
<flushleft>The most common (for English) style is <italic>FlushLeft.  </italic>This means
lines are aligned at the left margin but left uneven at the right.</flushleft>
Boris Goldowsky's avatar
Boris Goldowsky committed
127 128


Richard M. Stallman's avatar
Richard M. Stallman committed
129 130
<flushright>    <italic>FlushRight</italic> makes each line flush with the right margin instead.
    This paragraph is FlushRight.</flushright>
Boris Goldowsky's avatar
Boris Goldowsky committed
131 132


Richard M. Stallman's avatar
Richard M. Stallman committed
133
<flushboth><italic>FlushBoth </italic>regions, which are sometimes called "fully justified"
Boris Goldowsky's avatar
Boris Goldowsky committed
134
are aligned evenly on both edges, so that the text on the page has
135
a smooth appearance as in a book or newspaper article.
Boris Goldowsky's avatar
Boris Goldowsky committed
136 137
Unfortunately this does not look as nice with a fixed-width font
as it does in a proportionally-spaced printed document; the extra
138
spaces that are needed on the screen can make it hard to read.</flushboth>
Boris Goldowsky's avatar
Boris Goldowsky committed
139

140
<center>
Boris Goldowsky's avatar
Boris Goldowsky committed
141

Richard M. Stallman's avatar
Richard M. Stallman committed
142
    <bold>Center</bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
143

Richard M. Stallman's avatar
Richard M. Stallman committed
144 145 146
    Finally, there is <italic>center </italic>justification.  The normal
    center-paragraph key, M-S, can be used to turn on center
    justification in enriched-mode.
Boris Goldowsky's avatar
Boris Goldowsky committed
147

Richard M. Stallman's avatar
Richard M. Stallman committed
148
    M-j or the "Text Properties" menu also can be used to change
Boris Goldowsky's avatar
Boris Goldowsky committed
149
    justification.
Boris Goldowsky's avatar
Boris Goldowsky committed
150

151

Boris Goldowsky's avatar
Boris Goldowsky committed
152

Boris Goldowsky's avatar
Boris Goldowsky committed
153
</center><flushboth>Note that justification can only change at hard newlines, because
154
that is the unit over which filling gets done.</flushboth></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
155 156


Richard M. Stallman's avatar
Richard M. Stallman committed
157
<x-bg-color><param>blue</param><x-color><param>white</param><bold>EXCERPTS</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
158 159


Boris Goldowsky's avatar
Boris Goldowsky committed
160 161
<excerpt><indent>This is an example of an excerpt.  You can use them for quoted
parts of other people's email messages and the like.  It is just a
162
face, which is the same as the 'italic' face by default.</indent></excerpt>
Boris Goldowsky's avatar
Boris Goldowsky committed
163 164


165 166 167 168 169 170 171 172 173 174
<x-bg-color><param>blue</param><x-color><param>white</param><bold>CHARSET</bold></x-color></x-bg-color>


<indent>You can add character set information to stretches of text; this
is important for selecting the font that will display that text.
Users of various charsets, especially in East Asian cultures,
prefer the same characters to be rendered differently depending on
the language/charset context.</indent>


Richard M. Stallman's avatar
Richard M. Stallman committed
175
<x-bg-color><param>blue</param><x-color><param>white</param><bold>THE FILE FORMAT</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
176

Richard M. Stallman's avatar
Richard M. Stallman committed
177 178

<indent>Enriched-mode documents are saved in an extended version of a
Boris Goldowsky's avatar
Boris Goldowsky committed
179 180
format called <italic>text/enriched</italic>, which is defined as part of the MIME
standard.  This means that your documents are transportable (even
Richard M. Stallman's avatar
Richard M. Stallman committed
181
through email) to many other systems.  In the future other file
Boris Goldowsky's avatar
Boris Goldowsky committed
182
formats may be supported as well.
Boris Goldowsky's avatar
Boris Goldowsky committed
183 184


Boris Goldowsky's avatar
Boris Goldowsky committed
185 186 187
Since Emacs adds some non-standard features to the format (colors
and read-only regions), not all systems will be able to recreate
all of the features of your document, but they will get as close
Richard M. Stallman's avatar
Richard M. Stallman committed
188
as possible.
Boris Goldowsky's avatar
Boris Goldowsky committed
189 190


191
The text/enriched standard is defined in </indent>Internet<indent> RFC 1896
192
(<<http://www.ietf.org/rfc/rfc1896.txt>).</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
193 194


Richard M. Stallman's avatar
Richard M. Stallman committed
195
<x-bg-color><param>blue</param><x-color><param>white</param><bold>CUSTOMIZATION</bold></x-color></x-bg-color><bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
196 197


Boris Goldowsky's avatar
Boris Goldowsky committed
198
</bold><indent>-<indent> The <fixed>fixed </fixed>and <excerpt>excerpt </excerpt>faces should be set to your liking.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
199

Richard M. Stallman's avatar
Richard M. Stallman committed
200 201 202 203
-<indent> User-preference variables: <fixed>default-justification,
enriched-verbose.

</fixed></indent>-<indent> You can add annotations for your own text properties by making
204 205
additions to <fixed>enriched-translations</fixed>.  Note that the standard
requires you to name your annotation starting<italic> "x-" </italic>(as in
206 207
<italic>"x-read-only"</italic>).  Please report any such additions that you
think might be of general interest using <fixed>M-x report-emacs-bug</fixed>.</indent>
Richard M. Stallman's avatar
Richard M. Stallman committed
208

209
</indent><bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
210

211
<x-bg-color><param>blue</param><x-color><param>white</param>TODO LIST</x-color></x-bg-color></bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
212 213


214
<italic><indent>[Feel free to work on these and send us the results!]</indent></italic><indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
215

Richard M. Stallman's avatar
Richard M. Stallman committed
216
+ Conform to updated text/enriched spec in RFC 1896.
Boris Goldowsky's avatar
Boris Goldowsky committed
217

Richard M. Stallman's avatar
Richard M. Stallman committed
218
+ Be smarter about fixing malformed files.
Boris Goldowsky's avatar
Boris Goldowsky committed
219

Richard M. Stallman's avatar
Richard M. Stallman committed
220
+ Make the indentation work more seamlessly and robustly:
Boris Goldowsky's avatar
Boris Goldowsky committed
221

Richard M. Stallman's avatar
Richard M. Stallman committed
222 223
+ Create<indent> an aggressive auto-fill function that will keep the
paragraph properly filled all the time, without slowing down
Dave Love's avatar
Dave Love committed
224
editing too much.  Refill mode is a start at this, but needs
Boris Goldowsky's avatar
Boris Goldowsky committed
225

226
</indent></indent>	<indent>improvement.
Dave Love's avatar
Dave Love committed
227 228

+ Refill after yank.  [Refill mode does that.]
Boris Goldowsky's avatar
Boris Goldowsky committed
229

Richard M. Stallman's avatar
Richard M. Stallman committed
230 231
+<indent> Make deleting a newline also delete the indentation following
it.</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
232

Boris Goldowsky's avatar
Boris Goldowsky committed
233
+ Never let point enter indentation??
Boris Goldowsky's avatar
Boris Goldowsky committed
234

Richard M. Stallman's avatar
Richard M. Stallman committed
235
+ Notice and re-fill when window changes widths (optionally).
Boris Goldowsky's avatar
Boris Goldowsky committed
236

237
+ Deal with the 'category' text-property in a smart way.
Boris Goldowsky's avatar
Boris Goldowsky committed
238

Dave Love's avatar
Dave Love committed
239 240 241
+ Interface w/ Gnus, VM, RMAIL.  Maybe Info too?  </indent>(Gnus 5.9 copes

      with text/enriched incoming mail.)<indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
242

Richard M. Stallman's avatar
Richard M. Stallman committed
243
+ Support more formats: RTF, HTML...
Boris Goldowsky's avatar
Boris Goldowsky committed
244

245
+ Use modern Emacs display features.
Dave Love's avatar
Dave Love committed
246

Richard M. Stallman's avatar
Richard M. Stallman committed
247
</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
248

249
<x-bg-color><param>blue</param><x-color><param>white</param><bold>Original Author:</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
250 251


252
<bold><x-color><param>white</param><x-bg-color><param>blue</param>Boris Goldowsky</x-bg-color></x-color><x-color><param>light blue</param> </x-color></bold><x-color><param>light blue</param><fixed><<boris@gnu.ai.mit.edu></fixed></x-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
253

254 255


Paul Eggert's avatar
Paul Eggert committed
256
Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc.
257 258 259

COPYING PERMISSIONS:

260
    This document is free software: you can redistribute it and/or modify
261
    it under the terms of the GNU General Public License as published by
262 263
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
264 265 266 267 268 269 270

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
271
    along with this program.  If not, see <<https://www.gnu.org/licenses/>.