X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/20ea8f1d69129a3ea184b12fc1ae48295d4bdce1..de3054d5173bdc29f611685148830e87d78b89b8:/etc/enriched.doc diff --git a/etc/enriched.doc b/etc/enriched.doc index 6543d918d0..50dcf0bdac 100644 --- a/etc/enriched.doc +++ b/etc/enriched.doc @@ -1,338 +1,277 @@ Content-Type: text/enriched Text-Width: 70 -Content-type: text/enriched +
bluewhiteenriched.el: -Text-width: 86 +bluewhiteWYSIWYG rich text editing for GNU Emacs -<
<<<gray<<<blue<Enriched: +
bluewhiteINTRODUCTION -A WYSIWYG enriched-text editing environment for GNU Emacs -<<<<
<INTRODUCTION +Emacs now has the ability to edit enriched text, which is text +containing faces, colors, indentation, and other properties. This +document is a quick introduction to some of the new features, and +is also an example file in the text/enriched format. -<<This package, along with the <facemenu< package, is the beginning of a WYSIWYG -("what you see is what you get") Emacs mode for editing <enriched text: <text with -different faces, colors, etc. Facemenu allows you to add faces (such as -<boldface<, <italics<, and <underlining<) your documents, while <enriched< allows you to -save the documents with those "text properties" included. The format in which -they are saved is called <text/enriched<, and is defined as part of the MIME -standard, so that your documents are transportable (even through email) to many -other systems. +bluewhiteINSTALLATION and STARTUP -Not all systems will be able to recreate all of the features of your document, -but they will get as close as possible. For systems that do not understand it at -all, the text of the document should still be legible; the reader can simply -ignore the annotations specifying face changes and the like. +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 +text/enriched format, it will automatically be decoded, Emacs will +enter `enriched-mode' while visiting it, and whenever you save it +it will be saved in the same format it was read in. +If you wish to create a new file, however, you will need to turn +on enriched-mode yourself: -<<INSTALLATION and STARTUP < +M-x enriched-mode RET -<The <enriched.el< file should be installed somewhere that emacs will find it (ie, -one of the directories on emacs's <load-path <variable), and byte-compiled for -speed. +Or, if you get a text/enriched file that Emacs does not +automatically recognize and decode, you can tell Emacs to decode +it (which also turns on enriched-mode automatically): -The documentation below assumes that you have my <facemenu.el< (which is included -in recent versions of emacs). You may also find it useful to have Jim Thompson's -<ps-print.el<, which will allow you to print out buffers including their faces -(unfortunately it is not currently able to deal with merged faces; hopefully it -will be revised soon.) These two files should also be installed into your lisp -directory and byte-compiled. +M-x format-decode-buffer RET text/enriched RET -Put the following code into your .emacs file to automatically load enriched when -needed: + +bluewhiteWHAT IS ENCODED -<<(autoload 'enriched-mode "enriched" nil t)<< +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). -<Enriched <puts an identifying header into files it writes, which allows it to -recognize any emacs-generated <text/enriched< file and put itself into the proper -mode. If you get a file from some other source, however, such as through the -mail, you may have to enter enriched-mode manually: +Faces: default, bold, italic, underline, etc. +Colors: redDarkSlateGrayanyDarkSlateGrayorangething yellowyourgreen screenblue light bluecanviolet display... -<<M-x enriched-mode<< +Newlines: Which ones are real ("hard") newlines, and which can be +changed to fit lines into the margins. +Margins: can be indented on the left or right. -You may be asked a couple of questions at this point: +Justification (whether lines should be flush with the left margin, +the right margin, fully justified, centered, or left alone). +Excerpts: "For quoted material." -<Does the buffer need to be translated now?< If the buffer contains <text/enriched -<data which needs to be translated into a readable document with fonts and such, -then answer "yes". If you are putting a new document into text/enriched format -for the first time, then say "no". +Read-only regions. + -<Reformat for current display width?< If emacs knows that the document was created -with the same display width that is currently in effect, it will trust the line -breaks that are in the file, which saves some time. If it was saved at a -different width, or emacs doesn't know what width it was saved at, then it may -ask whether it should reformat. Actually it does not ask by default; it just -goes ahead and fills. But if you want it to ask, you can set the variable -<enriched-fill-after-visiting< to <'ask<. +bluewhiteFACES and COLORS -In the future, other modes such as mail and news may recognize messages that are -enriched text, and automatically call on <enriched< to display them for you. +You can add faces either with the menu or with M-g. The face is +applied to the current region. If you are using +`transient-mark-mode' and the region is not active, then the face +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. -<<WHAT IS ENCODED< +bluewhiteNEWLINES and PARAGRAPHS -<Aside from the text itself, various properties are saved. More will eventually -be added, so that you will be able to save and read just about anything that can -be displayed in an emacs frame. Following is the list of properties that are -currently understood; each is covered in more detail below. +Text/enriched format distinguishes between hard and soft newlines. +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 C-o +(open-line) function. -<Faces:< default, <bold<, <italic<, <underline<, <fixed<, etc. +bluewhiteINDENTATION -<Colors:< <<red<<<DarkSlateGray<any<<<<DarkSlateGray<<<orange<thing< <<yellow<your<<<green< screen<<<blue< <<<light blue<can<<<violet< display... << -<Newlines:< <Which ones are real ("hard") newlines, and which can be changed to fit -lines into the ma<rgins. +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 +setting the margins absolutely: C-c [ (set-left-margin) and C-c +] (set-right-margin). -<Margins:< can be indented on the left or right. -<Justification <<(whether lines should be flush with the left margin, the right -margin, fully justified, centered, or left alo<ne). +You 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 +region from the second word to the end of the paragraph, and +indenting only that part. -<Excerpts: "<<For quoted material." < -<Read-only< regions. +bluewhiteJUSTIFICATION -<<FACES +Several styles of justification are possible, the simplest being unfilled. +This means that your lines will be left as you write them. +This paragraph is unfilled. -<<The easiest way to add a face to a region is to use the <facemenu <package. This -defines a menu obtained by clicking the right mouse button while holding the -control key. For example, to make a word boldface, you could select the word by -double-clicking on it, then hold C-mouse-3 and select <Bold< from the <Face -<<sub-menu<. Selecting a face from the menu when the region is not active will apply -that face to whatever you type next. +The most common (for English) style is FlushLeft. This means +lines are aligned at the left margin but left uneven at the right. -<<NEWLINES and PARAGRAPHS + FlushRight makes each line flush with the right margin instead. + This paragraph is FlushRight. -<<<Text/enriched< format distinguishes between <hard< newlines and <soft <newlines. 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. Auto-fill-mode and -enriched-mode's fill functions insert soft newlines as necessary, but hard -newlines are only inserted by direct request, such as using the return key or the -<C-o (open-line)< function. + +FlushBoth regions, which are sometimes called "fully justified" +are aligned evenly on both edges, so that the text on the page has +a smooth appearance as in a book or newspaper article. +Unfortunately this does not look as nice with a fixed-width font +as it does in a proportionally-spaced printed document; the extra +spaces that are needed on the screen can make it hard to read. -<<INDENTATION +
+ Center -<<Indentation of regions of the document can be flexibly controlled. The face menu -contains an <Indent< item, which indents the region by the width of 4 characters -and an <UnIndent <item which removes 4 character-widths of indentation. All of the -text paragraphs in this file are singly indented relative to the headings, for -example. In addition, you can indent and unindent the <right <margin though use of -the <IndentRight< and <UnindentRight <menu items. The indentation commands can be -used repeatedly to get further levels of indentation. There are also shortcut -commands to set the left and right margins directly. + Finally, there is center justification. The normal + center-paragraph key, M-S, can be used to turn on center + justification in enriched-mode. -The basic editing commands in enriched-mode have been modified as necessary to -maintain proper indentation, but if it gets messed up, you can use <C-q< to -reformat the current paragraph. This may be necessary, for example, after -yanking or pasting text into the buffer. Eventually all commands should respect -indentation. <<<<< + M-j or the "Text Properties" menu also can be used to change + justification. + -<Not <only whole paragraphs can be indented, but in fact any region. -This makes it possible to have hanging-indents on paragraphs like -this one: it was accomplished by selecting the region starting -after the first word of the paragraph and going to the end of the -paragraph, and indenting that. <<<<<Also notice that this paragraph had been -indented on the right until the beginning of this sentence, when it resumed -normal w<i<<<dth. +
Note that justification can only change at hard newlines, because +that is the unit over which filling gets done. -<JUSTIFICATION< +bluewhiteEXCERPTS -<<<<<Several styles of justification are possible, the simplest being <unfilled. -<This means that your lines will be left as you write them. -This paragraph, for instance, is unfilled. -It was written with one sentence on a line. -<Enriched <will not change that, no matter what size display it is shown on. -There is no hard/soft newline distinction in unfilled text. +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 +face, which is the same as the `italic' face by default. -The most common (for English) style is <FlushLeft. <This means -lines are aligned at the left margin but left uneven at the -right. -<<<FlushRight<<<, as you may have guessed, makes each line flush with the right margin, -but not necessarily the left. +bluewhiteTHE FILE FORMAT -This is usually, but by no means necessarily, used for headings. -This paragraph is FlushRight. +Enriched-mode documents are saved in an extended version of a +format called text/enriched, which is defined as part of the MIME +standard. This means that your documents are transportable (even +through email) to many other systems. In the future other file +formats may be supported as well. -<<<FlushBoth <<<regions, which are sometimes called "fully justified" (or, confusingly, -"right justified") are aligned evenly on both edges, so that the text on the page -has a smooth appearance as in a book or newspaper article. Unfortunately this -does not look as nice with a fixed-width font as it does in a -proportionally-spaced printed document; the extra spaces that are needed on the -screen can make it hard to read. <<<< +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 +as possible. -<<<<The narrower the column, the uglier <FlushBoth -<text will be. If you think <flushboth <paragraphs -look pretty, though, you can set -<enriched-default-justification <to <'both <to -justify everything that is not otherwise -specified. +The MIME standard is defined in Internet RFC 1521; text/enriched +is defined in RFC 1563. Details on obtaining these documents via +FTP or email may be obtained by sending an email message to +rfc-info@isi.edu with the message body: -<<<<<<<<<<<
Center +help: ways_to_get_rfcs -<
<<
You can probably guess what <center <justification is for. -The normal center-paragraph key, M-S, can be used to turn on center justification -in enriched-mode. M-j also brings up a justification menu. +See also the newsgroup comp.mail.mime. -<
<Note that justification can only be changed for complete paragraphs (ie, a -justified region must start and end at hard newlines). The menu items in the -"Justification" menu will all operate on the current paragraph, or, if the region -is active, on all paragraphs which are inside or overlapping the region. +bluewhiteCUSTOMIZATION -<<<EXCERPTS< +- The fixed and excerpt faces should be set to your liking. +- User-preference variables: default-justification, +enriched-verbose. -<<This is an example of an excerpt. You can use them for quoted parts of other -people's email messages and the like. Currently it just displays as italics -(unless some <other< style is in effect), but this can be changed (see -<Customization< below). << +- You can add annotations for your own text properties by making +additions to enriched-translations. Note that the standard +requires you to name your annotation starting "x-" (as in +"x-read-only"). Please send me any such additions that you +think might be of general interest so that I can include them +in the distribution. + -<DEBUGGING< +bluewhiteTO-DO LIST -<The function <enriched-show-codes< can be helpful in figuring out what is going if -things don't seem to be working. The function can highlight (with a blue or gray -background) various items of interest. <Type <C<-c C-s<<<, then what should be -highlighted: +[Feel free to work on these and send me the results!] ++ Conform to updated text/enriched spec in RFC 1896. -<<indent:< <<<Highlight the indentation at the beginning of each line. < ++ Be smarter about fixing malformed files. -<margin: <Highlight regions that are indented. ++ Make the indentation work more seamlessly and robustly: -<newline: <Highlight hard newlines. ++ Create an aggressive auto-fill function that will keep the +paragraph properly filled all the time, without slowing down +editing too much. Refill mode is a start at this, but needs -<none: <Turn off all highlighting. << + improvment. ++ Refill after yank. [Refill mode does that.] -<<<<<CUSTOMIZATION ++ Make deleting a newline also delete the indentation following +it. ++ Never let point enter indentation?? -<<-< Set the default faces to things you like. The faces named <fixed <and <excerpt, -<especially, can be set to your liking. < ++ Notice and re-fill when window changes widths (optionally). -- <User-preference variables: <enriched-default-right-margin, -enriched-default-justification, enriched-verbose, -enriched-auto-save-interval<<, <and <enriched-fill-after-visiting <(mentioned -above)<. <See their documentation for det<ails. ++ Deal with the `category' text-property in a smart way. -- <You can add annotations for your own text properties by making additions to -<enriched-annotation-alist<. Note that the standard requires you to name your -annotation starting< "x-" <(as in <"x-read-only"<). Please send me any such -additions that you think might be of general interest so that I can include -them in the distribution. ++ Interface w/ Gnus, VM, RMAIL. Maybe Info too? (Gnus 5.9 copes -<- <My eventual hope is that people will use the basic code in this file to -implement more of the various file formats that are in common use, so that -emacs will understand them all and be able to edit them with a common -interface. If you are interested in taking on the project of implementing a -format, let me know. The code attempts to be as general as possible; a lot -of different formats can be defined just by setting up the lists of -properties to save and how to represent them in the file. + with text/enriched incoming mail.) ++ Support more formats: RTF, HTML... -<<<TO-DO LIST ++ Use Emacs 21 display features. + -<<<[Feel free to work on these and send me the results!] < +bluewhiteFinal Notes: -- Be more tolerant of malformed files. -- Make the indentation work more seamlessly and robustly: +This code and documentation is under development. Comments and +bug reports are welcome. -<+ Create< an aggressive auto-fill function that will keep the paragraph -properly filled all the time, without slowing down editing too much. < -+ Refill after yank. +whiteblueBoris Goldowskylight blue light blue<blue -+ <Make deleting a newline also delete the indentation following it. < +bluewhiteApril 1995; updated August 1997 -+ Never let point enter indentation?? -+< Optional never-let-things-get-unfilled (ok for fast terminals). < -<- Do the right thing for insert-file. + +Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +Free Software Foundation, Inc. -- Notice and re-fill when window changes widths (optionally). - Nicer formatting -for excerpts. +COPYING PERMISSIONS: -- Interface w/ GNUS, VM, RMAIL. + This document is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3, or (at your option) + any later version. -- For documentation, make INFO aware of text/enriched format. + 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. --< Have another set of alists for reading and writing RTF, etc (this will take -work not only on the alists, of course, but also on the code for interpreting -them). - - - -<<<Final Notes: - - -<<The MIME standard is defined in internet RFC 1521; text/enriched is defined in -RFC 1563. Details on obtaining these documents via FTP or email may be obtained -by sending an email message to <rfc-info@isi.edu< with the message body: - -< <help: ways_to_get_rfcs < < - - -This code and documentation is under development. The most current version -should always be available from: - -<</anonymous@cs.rochester.edu:pub/boris/enriched.shar< - -<It is helpful to make sure you have the newest version before reporting a bug. - -<Please send any and all comments to: - - -<<<blue<Boris Goldowsky <<<<<<<<<blue< - -October 1994 - - - - - - - - - - - -< + You should have received a copy of the GNU General Public License + along with this program; see the file COPYING. If not, write to + the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, + Boston, MA 02110-1301 USA.