diff --git a/etc/enriched.doc b/etc/enriched.doc index 93a59e525ba..0f001fe30cb 100644 --- a/etc/enriched.doc +++ b/etc/enriched.doc @@ -1,325 +1,254 @@ -Content-type: text/enriched -Text-width: 86 +Content-Type: text/enriched +Text-Width: 70 + +
bluewhiteenriched.el: + +bluewhiteWYSIWYG rich text editing for GNU Emacs -<
<<<gray<<<blue<Enriched: +
bluewhiteINTRODUCTION -A WYSIWYG enriched-text editing environment for GNU Emacs + + +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. -<<<<
<INTRODUCTION +bluewhiteINSTALLATION and STARTUP + + + +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: -<<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. +M-x enriched-mode RET -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. +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): -<<INSTALLATION and STARTUP < + M-x format-decode-buffer RET text/enriched RET + + + +bluewhiteWHAT IS ENCODED + + + +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). + +Faces: default, bold, italic, underline, fixed, etc. + +Colors: redDarkSlateGrayanyDarkSlateGrayorangething yellowyourgreen screenblue light bluecanviolet display... + +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. + +Justification (whether lines should be flush with the left margin, +the right margin, fully justified, centered, or left alone). + +Excerpts: "For quoted material." + +Read-only regions. -<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. +bluewhiteFACES and COLORS + + + +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, but +faces have no other attributes are put on the color submenus of +the "Text Properties" menu. -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. +bluewhiteNEWLINES and PARAGRAPHS + + + +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. -Put the following code into your .emacs file to automatically load enriched when -needed: +bluewhiteINDENTATION + -<<(autoload 'enriched-mode "enriched" nil t)<< +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 l (set-left-margin) +and C-c r (set-right-margin). + +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. -<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: + +bluewhiteJUSTIFICATION -<<M-x enriched-mode<< + +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. -You may be asked a couple of questions at this point: - - -<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". - - -<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<. - - -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. - - -<<WHAT IS ENCODED< - - -<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. - - -<Faces:< default, <bold<, <italic<, <underline<, <fixed<, etc. - -<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. - -<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). - -<Excerpts: "<<For quoted material." < - -<Read-only< regions. - - -<<FACES - - -<<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. - - -<<NEWLINES and PARAGRAPHS - - -<<<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. - - -<<INDENTATION - - -<<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. - -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. <<<<< - - -<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. - - -<JUSTIFICATION< - - -<<<<<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. - -The most common (for English) style is <FlushLeft. <This means +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. -This is usually, but by no means necessarily, used for headings. + FlushRight makes each line flush with the right margin instead. -This paragraph is FlushRight. + + +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. -<<<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. <<<< +
Center + +
Finally, there is center justification. + The normal center-paragraph key, M-S, can be used to turn on + center justification in enriched-mode. + + M-j or the "Text Properties" menu also can be used to change + justification. + + + +
Note that justification can only change at hard newlines, because +that is the unit over which filling gets done. -<<<<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. +bluewhiteEXCERPTS + + + +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. + + +bluewhiteTHE FILE FORMAT + + + +Enriched-mode docuemnts 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. -<<<<<<<<<<<
Center +Since Emacs adds some non-standard features to the format (colors -<
<<
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. +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. -<
<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. +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 -<<<EXCERPTS< +See also the newsgroup comp.mail.mime. -<<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). << +bluewhiteCUSTOMIZATION + + + +- The fixed and excerpt faces should be set to your liking. + +- User-preference variables: default-justification, enriched-verbose. +- 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. -<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!] - -<<indent:< <<<Highlight the indentation at the beginning of each line. < - -<margin: <Highlight regions that are indented. - -<newline: <Highlight hard newlines. - -<none: <Turn off all highlighting. << - - -<<<<<CUSTOMIZATION - - -<<-< Set the default faces to things you like. The faces named <fixed <and <excerpt, -<especially, can be set to your liking. < - -- <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. - -- <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. - -<- <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. - - -<<<TO-DO LIST - - -<<<[Feel free to work on these and send me the results!] < - -- Be more tolerant of malformed files. +- Be smarter about fixing malformed files. - Make the indentation work more seamlessly and robustly: -<+ Create< an aggressive auto-fill function that will keep the paragraph -properly filled all the time, without slowing down editing too much. < ++ 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. ++ Refill after yank. -+ <Make deleting a newline also delete the indentation following it. < ++ Make deleting a newline also delete the indentation +following it. -+ Never let point enter indentation?? ++ Never let point enter indentation?? -+< Optional never-let-things-get-unfilled (ok for fast terminals). < +- Notice and re-fill when window changes widths (optionally). -<- Do the right thing for insert-file. +- Deal with the `category' text-property in a smart way. -- Notice and re-fill when window changes widths (optionally). - Nicer formatting -for excerpts. +- Interface w/ GNUS, VM, RMAIL. Maybe Info too? -- Interface w/ GNUS, VM, RMAIL. - -- For documentation, make INFO aware of text/enriched format. - --< 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). +- Support more formats: RTF, HTML... +bluewhiteFinal Notes: -<<<Final Notes: + + +This code and documentation is under development. + Comments and bug reports are welcome. -<<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: +whiteblueBoris Goldowskylight blue light blue<blue -< <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 +bluewhite April 1995 blue @@ -331,4 +260,4 @@ October 1994 -< +