diff --git a/etc/enriched.doc b/etc/enriched.doc new file mode 100644 index 00000000000..afd1df88436 --- /dev/null +++ b/etc/enriched.doc @@ -0,0 +1,331 @@ +-*-enriched-*-width:86 +
grayblueEnriched: + +A WYSIWYG enriched-text editing environment for GNU Emacs + + +
INTRODUCTION + + +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. + + +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. + + +INSTALLATION and STARTUP + + +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. + + +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. + + +Put the following code into your .emacs file to automatically load enriched when +needed: + + +(autoload 'enriched-mode "enriched" nil t) + + +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: + + +M-x enriched-mode + + +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: 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. + + +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 width. + + +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 +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. + +This paragraph is FlushRight. + + +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. + + +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. + + +
Center + +
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. + + +
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. + + +EXCERPTS + + +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). + + +DEBUGGING + + +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: + + +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 details. + +- 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. + +- 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. + ++ Refill after yank. + ++ Make deleting a newline also delete the indentation following it. + ++ Never let point enter indentation?? + ++ Optional never-let-things-get-unfilled (ok for fast terminals). + +- Do the right thing for insert-file. + +- Notice and re-fill when window changes widths (optionally). - Nicer formatting +for excerpts. + +- 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). + + + +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: + + +blueBoris Goldowsky <blue + +October 1994 + + + + + + + + + + + +