view etc/enriched.doc @ 20102:c00f010468c2

Using cl macros push, pop, when, unless throughout the file. This is not further mentioned in this ChangeLog entry. Documentation largely updated. Parser rewritten for better Multifile Document processing. Macros with naked label arguments supported. Some Mule related changes. (reftex-default-label-alist-entries): Customization type is now computed from reftex-label-alist-builtin. Enumerate has new typekey `i'. `n' is now reserved for footnotes etc. (reftex-label-alist): Introduced default regular expressions. Customization type is now computed from reftex-label-alist-builtin. (reftex-label-menu-flags): New flag for showing file borders. (reftex-refontify-context): New option. (reftex-bibfile-ignore-list): Now a user option (was: variable). (reftex-cite-format): Now a user option (was: variable). Customization type is now computed from reftex-cite-format-builtin. (reftex-comment-citations): Now a user option (was: variable). (reftex-toc-follow-mode): Now a user option (was: variable). (reftex-optimizations-for-large-documents): New custom group. (reftex-keep-temporary-buffers): 1 as additional value. (reftex-initialize-temporary-buffers): New option. (reftex-enable-partial-scans): New option. (reftex-save-parse-info): New option. (reftex-plug-into-AUCTeX): Now a user option (was: variable). (reftex-auto-show-entry): New value 'copy allowed. (reftex-load-hook): Now a declared variable. (reftex-mode-hook): Now a declared variable. (reftex-label-numbers-symbol): Variable removed. (reftex-list-of-labels-symbol): Variable removed. (reftex-label-numbers-symbol): Variable removed. (reftex-bibfile-list-symbol): Variable removed. (reftex-docstruct-symbol): New variable (buffer-local). (reftex-master-include-list): Variable removed. (reftex-make-master-buffer): Function removed. (reftex-make-master-buffer-hook): Hook removed. (reftex-insert-buffer-or-file): Function removed. (reftex-parse-document): Function adapted to new parser. (reftex-access-scan-info): Changed to fit new parser. Now detects changes in label-alist related variables automatically. (reftex-parse-one,reftex-parse-all): New functions. (reftex-all-document-files): New function. (reftex-grep-document,reftex-search-document, reftex-query-replace-document): Now use `reftex-all-document-files'. (reftex-section-or-include-regexp): New variable. (reftex-everything-regexp): New variable. (reftex-find-label-regexp-format): New variable. (reftex-find-label-regexp-format2): New variable. (reftex-do-parse): New function. (reftex-is-multi): New function. (reftex-parse-from-file): New function. (reftex-locate-bibliography-files): New function. (reftex-last-assoc-before-elt): New function. (reftex-replace-label-list-segment): New function. (reftex-silence-toc-markers): New function. (reftex-access-parse-file): New function. (reftex-label): Now uses `reftex-where-am-I'. (reftex-offer-label-menu): New keys `%' and `i' and `r'. (reftex-select-item): Recursive edit moved to key `e'. New key `x' for external documents. Works now also with nin-nil pop-frame. (reftex-offer-label-menu): Now uses `reftex-where-am-I'. (reftex-make-and-insert-label-menu): More efficient, allow optional extra fontification. (reftex-find-nearby-label): Function removed. (reftex-scan-buffer-for-labels): Function removed. (reftex-section-info): New function. (reftex-nth-parens-substring): Renamed to reftex-nth-arg. Return nil when not enough args are present. (reftex-move-over-touching-args): New function. (reftex-where-am-I): New function. (reftex-nth-arg-wrapper): New function. (reftex-select-label-callback): Deal with special macros as well. (reftex-find-duplicate-labels): Ignore special entries in docstruct. (reftex-kill-temporary-buffers): New arg buffer. (reftex-show-entry): Copy context when necessary. (reftex-toc): New key `R', use reftex-where-am-I. (reftex-nearest-section): Use reftex-where-am-I. (reftex-toc-visit-line): Completely rewritten. Uses markers and several backup methods. (reftex-citation): Recursive edit moved to `e' key. (reftex-scan-buffer): Function removed. (reftex-get-bibfile-list): Changed to work with chapterbib package. (reftex-find-tex-file): New function. (reftex-find-files-on-path): Now first looks for file with additional .tex extension, then for the naked file name. (reftex-citation): Split into reftex-citation and reftex-do-citation. (reftex-do-citation): Recursive edit now on `e' key. (reftex-what-macro): Allow white space between macro arguments. (reftex-allow-for-ctrl-m): Renamed to `reftex-make-regexp-allow-for-ctrl-m'. (reftex-nearest-match): New function. (reftex-auto-mode-alist): New function. (reftex-make-desparate-section-regexp): New funtion. (reftex-get-file-buffer-force): Rewritten to use new variable `reftex-initialize-temporary-buffers'. (reftex-label-alist-builtin): Use abbreviated regexps. (reftex-label-mac-list): New variable. (reftex-parse-args): New function. (easy-menu-define): Menu extended. Some parts are now computed. from the user options. (reftex-move-to-next-arg,reftex-move-to-previous-arg) New functions. Now we can parse macros with distributed arguments. (reftex-goto-label): Function removed. (reftex-position-cursor): Function removed. (reftex-item): Function removed. (reftex-add-to-label-alist): No longer autoloaded. (reftex-toc-indent): Constant removed. (reftex-label-indent): Constant removed. (reftex-context-indent): Constant removed. (reftex-match-string): New function. (reftex-memory): New variable (reftex-reset-mode): No longer hacks local variables. Now resets path variables as well. (reftex-truncate): New functions, to make RefTeX work with Mule. (reftex-fp): New macro, to make RefTeX work with Mule. (reftex-format-bib-entry): Now uses `reftex-truncate' to truncate author names. `extra' and `title' are no longer truncated at all. (reftex-all-assq): New function. (reftex-view-crossref): Works now also if mouse click is on macro. (reftex-context-substring): Now returns substring without text properties. (reftex-tex-path,reftex-bib-path): New variables. (reftex-split): Function replaced with builtin `split-string'. (reftex-find-bib-file): New function. (reftex-find-files-on-path): Function removed. (reftex-find-file-on-path): New function. (reftex-access-search-path,reftex-parse-colon-path, reftex-recursive-directory-list,reftex-expand-path): New functions, dealing with recursive TEXINPUTS and BIBINPUTS definitions.

Content-Type: text/enriched
Text-Width: 70

<center><x-bg-color><param>blue</param><x-color><param>white</param><bold><fixed>enriched.el:</fixed></bold></x-color></x-bg-color>

<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>


</center><bold><x-bg-color><param>blue</param><x-color><param>white</param>INTRODUCTION</x-color></x-bg-color></bold>



<indent>Emacs now has the ability to edit <italic>enriched text</italic>, 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 <italic>text/enriched </italic>format.</indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>INSTALLATION and STARTUP</bold></x-color></x-bg-color>


<indent>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
<italic>text/enriched</italic> 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:


<fixed><indent>M-x enriched-mode RET</indent></fixed>


Or, if you get a <italic>text/enriched </italic>file that Emacs does not
automatically recognize and decode, you can tell Emacs to decode
it (which also turns on enriched-mode automatically):


<fixed><indent>M-x format-decode-buffer RET text/enriched RET</indent></fixed></indent>

    

<x-bg-color><param>blue</param><x-color><param>white</param><bold>WHAT IS ENCODED</bold></x-color></x-bg-color>


<indent>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).

<bold>Faces:</bold> <indent>default, <bold>bold</bold>, <italic>italic</italic>, <underline>underline</underline>, etc.</indent>

<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>

<bold>Newlines:</bold> <indent>Which ones are real ("hard") newlines, and which can be
changed to fit lines into the margins.</indent>

<bold>Margins:</bold> <indent>can be indented on the left or right.</indent>

<bold>Justification</bold> <indent>(whether lines should be flush with the left margin,
the right margin, fully justified, centered, or left alone).</indent>

<bold>Excerpts:</bold><indent> <excerpt>"For quoted material."</excerpt></indent>

<bold>Read-only</bold> regions.

</indent>

<x-bg-color><param>blue</param><x-color><param>white</param><bold>FACES and COLORS</bold></x-color></x-bg-color>


<indent>You can add faces either with the menu or with <fixed>M-g.</fixed>  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.</indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>NEWLINES and PARAGRAPHS</bold></x-color></x-bg-color>


<italic><indent>Text/enriched</indent></italic><indent> format distinguishes between <underline>hard</underline> and <underline>soft</underline> 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 <fixed>C-o
(open-line)</fixed> function.</indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>INDENTATION</bold></x-color></x-bg-color>


<indent>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: <fixed>C-c C-l (set-left-margin)</fixed> and <fixed>C-c
C-r (set-right-margin)</fixed>.


You <indent>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.</indent></indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>JUSTIFICATION</bold></x-color></x-bg-color>



<indent><nofill>Several styles of justification are possible, the simplest being <italic>unfilled. 
</italic>This means that your lines will be left as you write them. 
This paragraph is unfilled.</nofill>


<flushleft>The most common (for English) style is <italic>FlushLeft.  </italic>This means
lines are aligned at the left margin but left uneven at the right.</flushleft>


<flushright>    <italic>FlushRight</italic> makes each line flush with the right margin instead.
    This paragraph is FlushRight.</flushright>

    

<flushboth><italic>FlushBoth </italic>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>

<center>    

    <bold>Center</bold>

    Finally, there is <italic>center </italic>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.

    

</center><flushboth>Note that justification can only change at hard newlines, because
that is the unit over which filling gets done. </flushboth></indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>EXCERPTS</bold></x-color></x-bg-color>


<excerpt><indent>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.</indent></excerpt>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>THE FILE FORMAT</bold></x-color></x-bg-color>


<indent>Enriched-mode documents are saved in an extended version of a
format called <italic>text/enriched</italic>, 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.


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 MIME standard is defined in </indent>Internet<indent> 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
<fixed>[e-mail]</fixed> with the message body:


<fixed><indent>help: ways_to_get_rfcs</indent></fixed>


<indent>See also the newsgroup <fixed>comp.mail.mime</fixed>.</indent></indent>


<x-bg-color><param>blue</param><x-color><param>white</param><bold>CUSTOMIZATION</bold></x-color></x-bg-color><bold>


</bold><indent>-<indent> The <fixed>fixed </fixed>and <excerpt>excerpt </excerpt>faces should be set to your liking.</indent>

-<indent> User-preference variables: <fixed>default-justification,
enriched-verbose.

</fixed></indent>-<indent> You can add annotations for your own text properties by making
additions to <fixed>enriched-annotation-alist</fixed>.  Note that the
standard requires you to name your annotation starting<italic> "x-"
</italic>(as in <italic>"x-read-only"</italic>).  Please send me any such additions that
you think might be of general interest so that I can include
them in the distribution.</indent>

</indent>

<x-bg-color><param>blue</param><x-color><param>white</param><bold>TO-DO LIST</bold></x-color></x-bg-color>


<italic><indent>[Feel free to work on these and send me the results!]</indent></italic><indent>

+ Conform to updated text/enriched spec in RFC 1896.

+ Be smarter about fixing malformed files.

+ Make the indentation work more seamlessly and robustly:

+ Create<indent> an aggressive auto-fill function that will keep the
paragraph properly filled all the time, without slowing down
editing too much.</indent>

+ Refill after yank.

+<indent> Make deleting a newline also delete the indentation following
it.</indent>

+ Never let point enter indentation??

+ Notice and re-fill when window changes widths (optionally).

+ Deal with the `category' text-property in a smart way.

+ Interface w/ GNUS, VM, RMAIL.  Maybe Info too?

+ Support more formats: RTF, HTML...

</indent>

<x-bg-color><param>blue</param><x-color><param>white</param><bold>Final Notes:</bold></x-color></x-bg-color>


<indent>This code and documentation is under development.  Comments and
bug reports are welcome.</indent>


<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><<[e-mail]></fixed></x-color><x-color><param>blue</param>

</x-color><x-bg-color><param>blue</param><x-color><param>white</param>April 1995; updated August 1997</x-color></x-bg-color>