etc/enriched.doc

   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 now has the ability to edit <italic>enriched text</italic>, which is text
  14 containing faces, colors, indentation, and other properties.  This
  15 document is a quick introduction to some of the new features, and
  16 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-g.</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 C-l (set-left-margin)</fixed> and <fixed>C-c
 102 C-r (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 MIME standard is defined in </indent>Internet<indent> RFC 1521; text/enriched
 179 is defined in RFC 1563.  Details on obtaining these documents via
 180 FTP or email may be obtained by sending an email message to
 181 <fixed>rfc-info@isi.edu</fixed> with the message body:
 182
 183
 184 <fixed><indent>help: ways_to_get_rfcs</indent></fixed>
 185
 186
 187 <indent>See also the newsgroup <fixed>comp.mail.mime</fixed>.</indent></indent>
 188
 189
 190 <x-bg-color><param>blue</param><x-color><param>white</param><bold>CUSTOMIZATION</bold></x-color></x-bg-color><bold>
 191
 192
 193 </bold><indent>-<indent> The <fixed>fixed </fixed>and <excerpt>excerpt </excerpt>faces should be set to your liking.</indent>
 194
 195 -<indent> User-preference variables: <fixed>default-justification,
 196 enriched-verbose.
 197
 198 </fixed></indent>-<indent> You can add annotations for your own text properties by making
 199 additions to <fixed>enriched-annotation-alist</fixed>.  Note that the
 200 standard requires you to name your annotation starting<italic> "x-"
 201 </italic>(as in <italic>"x-read-only"</italic>).  Please send me any such additions that
 202 you think might be of general interest so that I can include
 203 them in the distribution.</indent>
 204
 205 </indent>
 206
 207 <x-bg-color><param>blue</param><x-color><param>white</param><bold>TO-DO LIST</bold></x-color></x-bg-color>
 208
 209
 210 <italic><indent>[Feel free to work on these and send me the results!]</indent></italic><indent>
 211
 212 + Conform to updated text/enriched spec in RFC 1896.
 213
 214 + Be smarter about fixing malformed files.
 215
 216 + Make the indentation work more seamlessly and robustly:
 217
 218 + Create<indent> an aggressive auto-fill function that will keep the
 219 paragraph properly filled all the time, without slowing down
 220 editing too much.  Refill mode is a start at this, but needs
 221
 222 </indent></indent>      <indent>improvment.
 223
 224 + Refill after yank.  [Refill mode does that.]
 225
 226 +<indent> Make deleting a newline also delete the indentation following
 227 it.</indent>
 228
 229 + Never let point enter indentation??
 230
 231 + Notice and re-fill when window changes widths (optionally).
 232
 233 + Deal with the `category' text-property in a smart way.
 234
 235 + Interface w/ Gnus, VM, RMAIL.  Maybe Info too?  </indent>(Gnus 5.9 copes
 236
 237       with text/enriched incoming mail.)<indent>
 238
 239 + Support more formats: RTF, HTML...
 240
 241 + Use Emacs 21 display features.
 242
 243 </indent>
 244
 245 <x-bg-color><param>blue</param><x-color><param>white</param><bold>Final Notes:</bold></x-color></x-bg-color>
 246
 247
 248 <indent>This code and documentation is under development.  Comments and
 249 bug reports are welcome.</indent>
 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><x-color><param>blue</param>
 253
 254 </x-color><x-bg-color><param>blue</param><x-color><param>white</param>April 1995; updated August 1997</x-color></x-bg-color>
 255
 256