enriched.txt 10.4 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

Boris Goldowsky's avatar
Boris Goldowsky committed
67
<bold>Read-only</bold> regions.
Boris Goldowsky's avatar
Boris Goldowsky committed
68

Richard M. Stallman's avatar
Richard M. Stallman committed
69
</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
70

Richard M. Stallman's avatar
Richard M. Stallman committed
71
<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
72 73


74
<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
75
applied to the current region.  If you are using
76
'transient-mark-mode' and the region is not active, then the face
77 78 79
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
80 81


Richard M. Stallman's avatar
Richard M. Stallman committed
82
<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
83 84


Richard M. Stallman's avatar
Richard M. Stallman committed
85
<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
86 87 88 89 90 91
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
92 93
(open-line)</fixed> function.</indent>

Boris Goldowsky's avatar
Boris Goldowsky committed
94

Richard M. Stallman's avatar
Richard M. Stallman committed
95
<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
96 97


Richard M. Stallman's avatar
Richard M. Stallman committed
98 99 100
<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
101 102
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
103 104


Richard M. Stallman's avatar
Richard M. Stallman committed
105 106 107
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
108
region from the second word to the end of the paragraph, and
Richard M. Stallman's avatar
Richard M. Stallman committed
109
indenting only that part.</indent></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
110 111


Richard M. Stallman's avatar
Richard M. Stallman committed
112
<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
113 114


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

116 117
<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
118 119
This paragraph is unfilled.</nofill>

Boris Goldowsky's avatar
Boris Goldowsky committed
120

Richard M. Stallman's avatar
Richard M. Stallman committed
121 122
<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
123 124


Richard M. Stallman's avatar
Richard M. Stallman committed
125 126
<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
127 128


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

136
<center>
Boris Goldowsky's avatar
Boris Goldowsky committed
137

Richard M. Stallman's avatar
Richard M. Stallman committed
138
    <bold>Center</bold>
Boris Goldowsky's avatar
Boris Goldowsky committed
139

Richard M. Stallman's avatar
Richard M. Stallman committed
140 141 142
    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
143

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

147

Boris Goldowsky's avatar
Boris Goldowsky committed
148

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


Richard M. Stallman's avatar
Richard M. Stallman committed
153
<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
154 155


Boris Goldowsky's avatar
Boris Goldowsky committed
156 157
<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
158
face, which is the same as the 'italic' face by default.</indent></excerpt>
Boris Goldowsky's avatar
Boris Goldowsky committed
159 160


Richard M. Stallman's avatar
Richard M. Stallman committed
161
<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
162

Richard M. Stallman's avatar
Richard M. Stallman committed
163 164

<indent>Enriched-mode documents are saved in an extended version of a
Boris Goldowsky's avatar
Boris Goldowsky committed
165 166
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
167
through email) to many other systems.  In the future other file
Boris Goldowsky's avatar
Boris Goldowsky committed
168
formats may be supported as well.
Boris Goldowsky's avatar
Boris Goldowsky committed
169 170


Boris Goldowsky's avatar
Boris Goldowsky committed
171 172 173
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
174
as possible.
Boris Goldowsky's avatar
Boris Goldowsky committed
175 176


177 178
The text/enriched standard is defined in </indent>Internet<indent> RFC 1896
(<<http://www.ietf.org/rfc/rfc1896.txt>).</indent></indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
179 180


Richard M. Stallman's avatar
Richard M. Stallman committed
181
<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
182 183


Boris Goldowsky's avatar
Boris Goldowsky committed
184
</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
185

Richard M. Stallman's avatar
Richard M. Stallman committed
186 187 188 189
-<indent> User-preference variables: <fixed>default-justification,
enriched-verbose.

</fixed></indent>-<indent> You can add annotations for your own text properties by making
190 191
additions to <fixed>enriched-translations</fixed>.  Note that the standard
requires you to name your annotation starting<italic> "x-" </italic>(as in
192 193
<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
194 195

</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
196

197
<x-bg-color><param>blue</param><x-color><param>white</param><bold>TODO LIST</bold></x-color></x-bg-color>
Boris Goldowsky's avatar
Boris Goldowsky committed
198 199


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

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

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

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

Richard M. Stallman's avatar
Richard M. Stallman committed
208 209
+ 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
210
editing too much.  Refill mode is a start at this, but needs
Boris Goldowsky's avatar
Boris Goldowsky committed
211

212
</indent></indent>	<indent>improvement.
Dave Love's avatar
Dave Love committed
213 214

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

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

Boris Goldowsky's avatar
Boris Goldowsky committed
219
+ Never let point enter indentation??
Boris Goldowsky's avatar
Boris Goldowsky committed
220

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

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

Dave Love's avatar
Dave Love committed
225 226 227
+ 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
228

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

231
+ Use modern Emacs display features.
Dave Love's avatar
Dave Love committed
232

Richard M. Stallman's avatar
Richard M. Stallman committed
233
</indent>
Boris Goldowsky's avatar
Boris Goldowsky committed
234

235
<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
236 237


Boris Goldowsky's avatar
Boris Goldowsky committed
238
<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><x-color><param>blue</param>
Boris Goldowsky's avatar
Boris Goldowsky committed
239

240 241


Paul Eggert's avatar
Paul Eggert committed
242
Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc.
243 244 245

COPYING PERMISSIONS:

246
    This document is free software: you can redistribute it and/or modify
247
    it under the terms of the GNU General Public License as published by
248 249
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
250 251 252 253 254 255 256

    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
257
    along with this program.  If not, see <<http://www.gnu.org/licenses/>.