etc/enriched.txt

   1 Content-Type: text/enriched
   2 Text-Width: 70
   3
   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
   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>
   7
   8
   9 </center><bold><x-bg-color><param>blue</param><x-color><param>white</param>INTRODUCTION</x-color></x-bg-color></bold>
  10
  11
  12
  13 <indent>Emacs has the ability to edit <italic>enriched text</italic>, which is text
  14 containing faces, colors, indentation, and other properties.
  15 This document is a quick introduction to some of the features,
  16 and is also an example file in the <italic>text/enriched </italic>format.</indent>
  17
  18
  19 <x-bg-color><param>blue</param><x-color><param>white</param><bold>INSTALLATION and STARTUP</bold></x-color></x-bg-color>
  20
  21
  22 <indent>Most of the time, you need not do anything to get these features
  23 to work.  If you visit a file that has been written out in
  24 <italic>text/enriched</italic> format, it will automatically be decoded, Emacs will
  25 enter `enriched-mode' while visiting it, and whenever you save it
  26 it will be saved in the same format it was read in.
  27
  28 If you wish to create a new file, however, you will need to turn
  29 on enriched-mode yourself:
  30
  31
  32 <fixed><indent>M-x enriched-mode RET</indent></fixed>
  33
  34
  35 Or, if you get a <italic>text/enriched </italic>file that Emacs does not
  36 automatically recognize and decode, you can tell Emacs to decode
  37 it (which also turns on enriched-mode automatically):
  38
  39
  40 <fixed><indent>M-x format-decode-buffer RET text/enriched RET</indent></fixed></indent>
  41
  42
  43
  44 <x-bg-color><param>blue</param><x-color><param>white</param><bold>WHAT IS ENCODED</bold></x-color></x-bg-color>
  45
  46
  47 <indent>Here is the current list of text-properties that are saved; they
  48 are discussed in more detail below.  Most of these can be added or
  49 changed with the "Text Properties" menu, available under the
  50 "Edit" item in the menu-bar, or on C-mouse-2 (Control + the middle
  51 mouse button).
  52
  53 <bold>Faces:</bold> <indent>default, <bold>bold</bold>, <italic>italic</italic>, <underline>underline</underline>, etc.</indent>
  54
  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>
  56
  57 <bold>Newlines:</bold> <indent>Which ones are real ("hard") newlines, and which can be
  58 changed to fit lines into the margins.</indent>
  59
  60 <bold>Margins:</bold> <indent>can be indented on the left or right.</indent>
  61
  62 <bold>Justification</bold> <indent>(whether lines should be flush with the left margin,
  63 the right margin, fully justified, centered, or left alone).</indent>
  64
  65 <bold>Excerpts:</bold><indent> <excerpt>"For quoted material."</excerpt></indent>
  66
  67 <bold>Read-only</bold> regions.
  68
  69 </indent>
  70
  71 <x-bg-color><param>blue</param><x-color><param>white</param><bold>FACES and COLORS</bold></x-color></x-bg-color>
  72
  73
  74 <indent>You can add faces either with the menu or with <fixed>M-o.</fixed>  The face is
  75 applied to the current region.  If you are using
  76 `transient-mark-mode' and the region is not active, then the face
  77 applies to whatever you type next.  Any face can have colors.  If
  78 this is its lone attribute, the face is put on the color submenus
  79 of the "Text Properties" menu.</indent>
  80
  81
  82 <x-bg-color><param>blue</param><x-color><param>white</param><bold>NEWLINES and PARAGRAPHS</bold></x-color></x-bg-color>
  83
  84
  85 <italic><indent>Text/enriched</indent></italic><indent> format distinguishes between <underline>hard</underline> and <underline>soft</underline> newlines.
  86 Hard newlines are used to separate paragraphs, or items in a list,
  87 or anywhere that must be a line break no matter what the margins
  88 are.  Soft newlines are the ones inserted in order to fit text
  89 between the margins.  The fill and auto-fill functions insert soft
  90 newlines as necessary, but hard newlines are only inserted by
  91 direct request, such as using the return key or the <fixed>C-o
  92 (open-line)</fixed> function.</indent>
  93
  94
  95 <x-bg-color><param>blue</param><x-color><param>white</param><bold>INDENTATION</bold></x-color></x-bg-color>
  96
  97
  98 <indent>The fill functions also understand margins, which can be set for
  99 any region of a document.  In addition to the menu items, which
 100 increase or decrease the margins, there are two commands for
 101 setting the margins absolutely: <fixed>C-c [ (set-left-margin)</fixed> and <fixed>C-c
 102 ] (set-right-margin)</fixed>.
 103
 104
 105 You <indent>can change indentation at any point in a paragraph, which
 106 makes it possible to do interesting things like
 107 hanging-indents: this paragraph was indented by selecting the
 108 region from the second word to the end of the paragraph, and
 109 indenting only that part.</indent></indent>
 110
 111
 112 <x-bg-color><param>blue</param><x-color><param>white</param><bold>JUSTIFICATION</bold></x-color></x-bg-color>
 113
 114
 115
 116 <indent><nofill>Several styles of justification are possible, the simplest being <italic>unfilled.
 117 </italic>This means that your lines will be left as you write them.
 118 This paragraph is unfilled.</nofill>
 119
 120
 121 <flushleft>The most common (for English) style is <italic>FlushLeft.  </italic>This means
 122 lines are aligned at the left margin but left uneven at the right.</flushleft>
 123
 124
 125 <flushright>    <italic>FlushRight</italic> makes each line flush with the right margin instead.
 126     This paragraph is FlushRight.</flushright>
 127
 128
 129
 130 <flushboth><italic>FlushBoth </italic>regions, which are sometimes called "fully justified"
 131 are aligned evenly on both edges, so that the text on the page has
 132 a smooth appearance as in a book or newspaper article.
 133 Unfortunately this does not look as nice with a fixed-width font
 134 as it does in a proportionally-spaced printed document; the extra
 135 spaces that are needed on the screen can make it hard to read. </flushboth>
 136
 137 <center>
 138
 139     <bold>Center</bold>
 140
 141     Finally, there is <italic>center </italic>justification.  The normal
 142     center-paragraph key, M-S, can be used to turn on center
 143     justification in enriched-mode.
 144
 145     M-j or the "Text Properties" menu also can be used to change
 146     justification.
 147
 148
 149
 150 </center><flushboth>Note that justification can only change at hard newlines, because
 151 that is the unit over which filling gets done. </flushboth></indent>
 152
 153
 154 <x-bg-color><param>blue</param><x-color><param>white</param><bold>EXCERPTS</bold></x-color></x-bg-color>
 155
 156
 157 <excerpt><indent>This is an example of an excerpt.  You can use them for quoted
 158 parts of other people's email messages and the like.  It is just a
 159 face, which is the same as the `italic' face by default.</indent></excerpt>
 160
 161
 162 <x-bg-color><param>blue</param><x-color><param>white</param><bold>THE FILE FORMAT</bold></x-color></x-bg-color>
 163
 164
 165 <indent>Enriched-mode documents are saved in an extended version of a
 166 format called <italic>text/enriched</italic>, which is defined as part of the MIME
 167 standard.  This means that your documents are transportable (even
 168 through email) to many other systems.  In the future other file
 169 formats may be supported as well.
 170
 171
 172 Since Emacs adds some non-standard features to the format (colors
 173 and read-only regions), not all systems will be able to recreate
 174 all of the features of your document, but they will get as close
 175 as possible.
 176
 177
 178 The text/enriched standard is defined in </indent>Internet<indent> RFC 1896
 179 (<<http://www.ietf.org/rfc/rfc1896.txt>).</indent></indent>
 180
 181
 182 <x-bg-color><param>blue</param><x-color><param>white</param><bold>CUSTOMIZATION</bold></x-color></x-bg-color><bold>
 183
 184
 185 </bold><indent>-<indent> The <fixed>fixed </fixed>and <excerpt>excerpt </excerpt>faces should be set to your liking.</indent>
 186
 187 -<indent> User-preference variables: <fixed>default-justification,
 188 enriched-verbose.
 189
 190 </fixed></indent>-<indent> You can add annotations for your own text properties by making
 191 additions to <fixed>enriched-translations</fixed>.  Note that the standard
 192 requires you to name your annotation starting<italic> "x-" </italic>(as in
 193 <italic>"x-read-only"</italic>).  Please report any such additions that you
 194 think might be of general interest using <fixed>M-x report-emacs-bug</fixed>.</indent>
 195
 196 </indent>
 197
 198 <x-bg-color><param>blue</param><x-color><param>white</param><bold>TODO LIST</bold></x-color></x-bg-color>
 199
 200
 201 <italic><indent>[Feel free to work on these and send us the results!]</indent></italic><indent>
 202
 203 + Conform to updated text/enriched spec in RFC 1896.
 204
 205 + Be smarter about fixing malformed files.
 206
 207 + Make the indentation work more seamlessly and robustly:
 208
 209 + Create<indent> an aggressive auto-fill function that will keep the
 210 paragraph properly filled all the time, without slowing down
 211 editing too much.  Refill mode is a start at this, but needs
 212
 213 </indent></indent>      <indent>improvement.
 214
 215 + Refill after yank.  [Refill mode does that.]
 216
 217 +<indent> Make deleting a newline also delete the indentation following
 218 it.</indent>
 219
 220 + Never let point enter indentation??
 221
 222 + Notice and re-fill when window changes widths (optionally).
 223
 224 + Deal with the `category' text-property in a smart way.
 225
 226 + Interface w/ Gnus, VM, RMAIL.  Maybe Info too?  </indent>(Gnus 5.9 copes
 227
 228       with text/enriched incoming mail.)<indent>
 229
 230 + Support more formats: RTF, HTML...
 231
 232 + Use modern Emacs display features.
 233
 234 </indent>
 235
 236 <x-bg-color><param>blue</param><x-color><param>white</param><bold>Original Author:</bold></x-color></x-bg-color>
 237
 238
 239 <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>
 240
 241
 242 \f
 243 Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc.
 244
 245 COPYING PERMISSIONS:
 246
 247     This document is free software: you can redistribute it and/or modify
 248     it under the terms of the GNU General Public License as published by
 249     the Free Software Foundation, either version 3 of the License, or
 250     (at your option) any later version.
 251
 252     This program is distributed in the hope that it will be useful,
 253     but WITHOUT ANY WARRANTY; without even the implied warranty of
 254     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 255     GNU General Public License for more details.
 256
 257     You should have received a copy of the GNU General Public License
 258     along with this program.  If not, see <<http://www.gnu.org/licenses/>.