[comp.sources.wanted] A mail Readerditor for Ultrx? <- the lad needs GNU Emacs

Dan_Jacobson@ATT.COM (01/20/91)

>>>>> On 19 Jan 91 20:45:22 GMT, dlittlej@beach.csulb.edu ("Darren Littlejohn") said:

Darren> 	Is there a mail tool, like the one Sun uses on sparcs, that
Darren> will run on Ultrix 4.1? I want to be able to do easy editing and

well, I know of one that works on many machines, but if you insist, it
can be hacked to work only on ultrix, I guess :-).

Darren> get it, please let me know. I want to be able to do this kind of thing:
Darren> Joe programmer writes in article <nananadededededee>:
jo> nanananana dedededede
jo> dadada dedede
Darren> And then my text......

["Ah, my son..."] it's time to graduate, to get with the program, to
get on the bandwagon.

Here's an a ad for supercite the citation maker, write to
info-vm-request@uunet.uu.net for the mailer, and read gnu.emacs.help
for the editor.  Over and out.  Oh, supercite's new address is
supercite-request@warsaw.nlm.nih.gov

-----------
sc-describe:
Describe the Supercite 2.1 package.

This package provides mechanisms for doing sophisticated citing of
yanked text in the reply buffers of the major news and email reading
modes.

Supercite 2.1 has been tested and *seems* to work with GNUS 3.12-3.13
RMAIL 18.55 and VM 4.37-4.41. It is also supposed to work with MH-E
mode and perhaps even GNEWS, RNEWS, PCMAIL and other packages.  Some
modifications may be necessary to run supercite with these packages.
See the accompanying README file for details on how to link up with
supercite. 

Author:

NAME: Barry A. Warsaw            USMAIL: National Institute of
TELE: (301) 975-3460                     Standards and Technology
UUCP: uunet!cme.nist.gov!warsaw          Rm. B-124, Bldg. 220
INET: warsaw@cme.nist.gov                Gaithersburg, MD 20899

Get on the Supercite mailing list:

Send articles to:
          INET: supercite@cme.nist.gov
          UUCP: uunet!cme.nist.gov!supercite

Send administrivia (additions/deletions to list, etc) to:
          INET: supercite-request@cme.nist.gov
          UUCP: uunet!cme.nist.gov!supercite-request

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

What is a citation?  A "citation" is the acknowledgment of the
original author of a mail message, in the body of the reply. The
"attribution string" is the part of the author's name that will be
used to cite the body of the text (e.g. "John", the author's first
name). The "citation string" is built from the "citation leader",
the attribution string, the "citation delimiter", and the "citation
separator".  It is the string that is inserted in front of every line
to be cited in the reply body (e.g. "John> ").

There are two general forms of citation.  In "nested citations",
indication is made that the cited line was written by someone *other*
than the current message author, but no reference is made as to the
identity of the original author.  Here's an example of what a message
buffer would look like using nested citations after multiple replies:

     >> John originally wrote this
     >> and this as well
     > Jane said that John didn't know
     > what he was talking about
     And that's what I think too.

In "non-nested citations" each cited line begins with an informative
string referencing the original author.  Only the first level of
referencing will be shown; subsequent citations don't nest the
references.  The same message described above might look like this if
non-nested citations were used:

     John> John originally wrote this
     John> and this as well
     Jane> Jane said that John didn't know
     Jane> what he was talking about
     And that's what I think too.

Notice that my inclusion of Jane's inclusion of John's original
message did not result in a cited line beginning with: "Jane>John>".
Thus no nested citations.

Heuristics are used to extract such information as the author's name
and email address from the mail headers in the reply buffer. This
information is made available to the supercite user for use in
building the citation string and reference header.  The "reference
header" is header placed at the top of the cited body of text
describing who the author is in more detail.

The citing of the text body is undoable, so the user could yank and
cite the text, undo, then continually re-cite the text until the
desired citation string is inserted. Often people would like a
nickname to be used as the citation string, but this nickname cannot
be picked up by supercite.  It is a simple matter to undo the original
citation, and then perform a citation with the nickname as the
attribution string.

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

There are a number of variables which control some of the features
described thus far. First there is the variable which controls whether
nested or non-nested citations will be used:

     Variable: sc-nested-citation-p
          Controls citation style.  If nil, non-nested citations are
          used.  If non-nil, old-style nested citations are used.
          Default: nil.

For non-nested citations, the citation string is made up of four
parts, the citation leader, the attribution string, the citation
delimiter and the citation separator.  The attribution string is
determined by supercite (though you can override this -- see below);
the other three parts are user defined.  Nested citations use only the
citation separator:

     Variable: sc-citation-leader 
          String that leads the composed citation string.
          Default: " ".

     Variable: sc-citation-delimiter
          String that indicates a line has been cited. For nested
          citations this string is inserted in front of all cited
          lines. For non-nested citations, this string is inserted
          after the attribution string but before the citation
          separator.  Default: ">".

     Variable: sc-citation-separator
          String that ends a composed citation string. Placed between
          the citation delimiter and the original line of text.

For example, say the following preferences are in use:

          (setq sc-citation-leader    "    ")
          (setq sc-citation-delimiter ">")
          (setq sc-citation-separator " ")

and the attribution string was "Jane".  The composed citation string
would be "    Jane> ", which would be used in non-nested citations.
Of course, only ">" would be used in nested citations.

Occasionally, for whatever reason, the author's name cannot be found
in the mail header, and so a default author name may be used:

     Variable: sc-default-author-name
          String used when author's name cannot be found.
          Default: "Anonymous".

Also if the author's name cannot be found, a default attribution
string may be used, from which a legal citation string will be built:

     Variable: sc-default-attribution
          String used when author's attribution string cannot be
          found. Default: "Anon".

Finally, how does the package determine if a line has already been
cited, so that for non-nested citations, the line won't be recited?
This is accomplished through the use of a regular expression:

     Variable: sc-cite-regexp
          Regular expression that describes how an already cited line
          begins.  Default: "\\s *[a-zA-Z0-9]*\\s *>+\\s *".

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Supercite employs a number of heuristics to decipher the author's name
based on the "From:" field which is usually present in all mail and
news reading buffers.  If possible, it will pick out the author's
first, last and middle names, the author's initials and the author's
email terminus.  Supercite can recognize "From:" lines with the
following forms:

     From: John Xavier Doe <doe@speedy.computer.com>
     From: "John Xavier Doe" <doe@speedy.computer.com>
     From: doe@speedy.computer.com (John Xavier Doe)
     From: computer!speedy!doe (John Xavier Doe)
     From: doe%speedy@computer.com (John Xavier Doe)
     From: computer!speedy!doe (John Xavier-Doe)
     From: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)

Once supercite has parsed this field, it puts together a list of these
names and may present them to the user for selection.

Note that some author fields (as in the last example above) will
contain a descriptive title.  The user can choose to ignore the title,
while still recognizing hyphenated names, through the use of a regular
expression:

     Variable: sc-titlecue-regexp
          Regular expression that delineates names from titles in the
          author's name fields.  Default: "\\s +-+\\s +".

Once an attribution string is extracted, supercite will normally
use it to build the citation string automatically.  However, you can
tell supercite to request confirmation of the selected attribution
before the citation string is built:

     Variable: sc-confirm-always-p
          If non-nil, always confirm attribution string with user
          before using to cite text.  If nil, use automatic selection
          to choose attribution string. Default: t.

If you choose to confirm the attribution before the citation string is
built, you will be presented with a list of choices.  Supercite
maintains a notion of your "preferred" attribution string and this
is presented as the default choice. Hitting the carriage return will
select this preferred default.  You are free to type in any string at
the prompt, even if it is not one of the presented choices, and this
string becomes the literal attribution string when you hit return.
When an attribution string is confirmed, or typed in, it now becomes
the preferred default attribution string for future insertions.

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

You can tell supercite which part of the author's name is your
preference for use as the attribution string:

     Variable: sc-preferred-attribution
          Quoted symbol specifying which portion of an author's name
          should be used when building the attribution string using
          the following key:

          emailname   -- email terminus
          initials    -- author's initials
          firstname   -- first name
          lastname    -- last name
          middlename1 -- first middle name
          middlename2 -- second middle name
          ...

          Middlename indexes can be any positive integer greater than
          0, though it is unlikely that many authors will supply more
          than one middle name, if that many.  Default: 'firstname.

If you are using automatic selection, and your preferred attribution
can't be found (i.e. is either nil, or the empty string), then a
secondary method can be employed to find a valid attribution string.
A variable controls whether a secondary method will be used in this
case, or whether supercite should just use the default attribution (in
sc-default-attribution):

     Variable: sc-use-only-preference-p
          Controls what happens when the preferred attribution string
          cannot be found.  If non-nil, then sc-default-attribution is
          used, otherwise a secondary scheme is employed.
          Default: nil.

The following steps are taken to find a valid attribution string when
sc-use-only-preference-p is nil.  The first step to return a non-nil,
non-empty string becomes the attribution.

     1. Use the author's first name.
     2. Find the first non-nil, non-empty attribution string in the
        attribution list.
     3. If sc-confirm-always-p is non-nil, then the user is queried
        for an attribution, otherwise,
     4. sc-default-attribution is used.

Once a legal attribution string is found, you can force the string to
lower case characters.

     Variable: sc-downcase-p
          Non-nil means downcase the attribution string.
          Default: nil.

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Typically, citing is performed on a body of text that has been yanked
from a mail or news reading buffer.  This yanked text should have the
verbose headers at the top of the region to be cited.  As mentioned
above, Supercite will parse these headers, picking out useful
information (most notably the "From:" line), then delete those mail
headers, and replace them in the reply buffer with user customizable
reference headers.  You can have multiple references header styles at
your disposal and can customize your own headers, adding them to the
list of those available. This list is kept in the variable:

     Variable: sc-rewrite-header-list
          List of user customizable reference header rewrite
          functions.
          Default: '((sc-no-header)
                     (sc-header-on-said)
                     (sc-header-inarticle-writes)
                     (sc-header-regarding-writes)
                     (sc-header-attributed-writes)).

Add your own functions to this list or re-order the list to utilize
your own custom reference headers.  A reference header is rewritten
automatically when the text is originally yanked, and a command is
provided that allows the user to insert any reference header in the
list. The header written by default is user customizable:

     Variable: sc-preferred-header-style
          Integer specifying which header rewrite function is used
          when automatically inserting the rewritten header.  This is
          an index into sc-rewrite-header-list, with the first element
          indexed as zero.  Default: 1.

Alternatively, you can use "electric reference" inserting to select
a reference header to use.  In electric reference insert mode, you are
placed in a recursive edit where you can scan back and forth through
the list of headers.  You can also set a new preferred header style.
Electric reference inserting is also available through the
sc-insert-reference command (see below).  This variable controls
whether you will automatically insert references, or use electric
reference mode:

     Variable: sc-electric-references-p
          Non-nil specifies use electric reference insert mode.
          Default: t.

While in electric reference mode, certain keys are bound to certain
functions.  All other keys, except those which self insert, are still
valid. Self inserting keys are reinstated when you exit electric
reference insert mode.  Here are the default keybindings in this mode:

C-h             Prefix Command
g               sc-eref-goto
q               sc-eref-exit
LFD             sc-eref-exit
RET             sc-eref-exit
x               sc-eref-abort
C-g             sc-eref-abort
j               sc-eref-jump
s               sc-eref-setn
n               sc-eref-next
p               sc-eref-prev

C-h m           sc-eref-describe


You cannot edit the references while in electric reference mode.
Also, there is a variable which controls whether the rewrite functions
list should be treated as circular in electric reference mode:

     Variable: sc-electric-circular-p
          If non-nil, treat the reference header rewrite list of
          functions as circular in electric reference mode.
          Default: t.

You may want to include some information about the author in your
custom reference headers.  This information can come from the mail
headers or some internal supercite variables.  There is a variable
that describes which mail headers should be fetched and remembered for
use in the reference headers:

     Variable: sc-mail-fields-list
          List of mail header fields that you want supercite to
          extract and remember. These can be accessed through the
          sc-field function in your reference header functions.
          Default: '("date" "message-id" "subject" "newsgroups"
                     "references" "return-path" "path" "reply"
                     "organization")

In addition, supercite always provides the following information
fields:

     1. "sc-attribution"      (the selected attribution string)
     2. "sc-nested-citation"  (the nested citation string)
     3. "sc-citation"         (the non-nested citation string)
     4. "from"                (the From: mail header)
     5. "sc-author"           (the author's full name)
     6. "sc-firstname"        (the author's first name)
     7. "sc-lastname"         (the author's last name)
     8. "sc-middlename-1"     (the author's first middle name)
     9. ...                     (more middle names)

If you access a field with sc-field that does not exist in the
information list, supercite will return a mumble string:

     Variable: sc-mumble-string
          String returned by sc-field if chosen field can't be found.
          Default: "mumble".

After supercite has gleaned useful information from the mail headers,
it will usually remove them from the reply buffer.  You can tell
supercite to remove the headers or leave them in the buffer:

     Variable: sc-nuke-mail-headers-p
          If non-nil, nuke the mail headers, otherwise leave them in
          the reply buffer.
          Default: t.

The default reference header rewrite functions typically insert a
string which serves to visually separate the header from the cited
body of text.  You may want to change this for the default functions,
or use it in your custom header rewrite functions:

     Variable: sc-reference-tag-string
          String that is inserted before reference header lines on
          those reference rewrite functions which are predefined.
          Default: ">>>>> "


-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Supercite provides a paragraph filling function which recognizes the
citation string to properly fill a cited text body.  There are other
packages freely available which also work quite well when filling such
a prefixed paragraph, and so supercite calls the filling function via
a hook:

     Variable: sc-fill-paragraph-hook
          Hook for filling a paragraph. run when you fill a paragraph
          either automatically or manually.
          Default: 'sc-fill-paragraph.

Each cited paragraph can be automatically filled when cited:

     Variable: sc-auto-fill-region-p
          If non-nil, automatically fill each paragraph after it has
          been cited.  Default: nil.

There is a function available to manually fill a paragraph if you
don't want automatic filling (see below).


-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Here are a couple of other user definable variables.  For more
information on these or any supercite variable, type:
C-h v <variable-name>.

     Variable: sc-fixup-whitespace-p
          If non-nil, delete all leading white space before citing.
          Default: nil.

     Variable: sc-load-hook
          User definable hook which runs after supercite is loaded.
          Default: nil.

     Variable: sc-run-hook
          User definable hook which runs after sc-cite-original
          executes. Default: nil.


-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Since every email/news reader uses a different buffer name or
major-mode to reply in, supercite can't know ahead of time what the
buffer or major-mode name is. So supercite needs to leach onto
whatever buffer the reply is being made in, modifying the keymap and
the documentation string for that buffer. Many of the supercite 2.0
beta testers used many different readers, so a mechanism was developed
to provide a per-interface keymap, which installs itself into the
buffer's current-local-map based on the major-mode of the buffer.
There are two variables which control the keymap that gets installed:

          Variable: sc-default-keymap
               Default keymap to use if major-mode keybinding cannot
               be found in sc-local-keymaps.
               Keybindings:
                    (C-c C-r) sc-insert-reference
                    (C-c C-t) sc-cite
                    (C-c C-a) sc-recite
                    (C-c C-u) sc-uncite
                    (C-c C-i) sc-insert-citation
                    (C-c C-o) sc-open-line
                    (C-c C-q) sc-fill-paragraph-manually (also C-c q)
                    (C-c C-m) sc-modify-information
                    (C-c C-g) sc-glom-headers
                    (C-c C-v) sc-version
                    (C-c ?)   sc-describe

          Variable: sc-local-keymaps
               Variable which contains a list of interfaces and their
               keybindings.

Sc-local-keymaps is an association list of the form:

     ((MAJOR-MODE [FUNCTION | MAJOR-MODE])*)

When it is time to modify the keymap of the current buffer, supercite
looks up the `major-mode' of that buffer in this association list. If
it matches the major mode with a MAJOR-MODE key, the value is
returned, otherwise, the default keymap is installed (see above).

If the MAJOR-MODE is found and the value is returned, this value is
checked to see if it is a list.  If so, it is assumed that this value
is a lambda expression which will set the current local keymap as
desired.  If the value is not a list, it is assumed to be a previously
defined MAJOR-MODE.  This new major mode is looked up and the lambda
expression is evaluated.  Only one level of indirection is possible,
but this does allow you to save space when defining key bindings.

-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

There are a number of interactive commands that are provided as part
of the supercite package.  You can find out more details about each
command by entering C-h f <function>.

     Command: sc-insert-reference
          Insert a reference header into the body of the text.
          Key binding: C-c C-r.

     Command: sc-cite
          Cite the region of text between point and mark.
          Key binding: C-c C-t.

     Command: sc-uncite
          Uncite the region of text between point and mark.
          Key binding: C-c C-u.

     Command: sc-recite
          Recite the region of text between point and mark.
          Key binding: C-c C-a.

     Command: sc-insert-citation
          Insert the citation string at the beginning of the
          current line.
          Key binding: C-c TAB.

     Command: sc-open-line
          Insert a newline and leave point before it. Also, insert the
          citation string at the beginning of the new line.
          Key binding: C-c C-o.

     Command: sc-fill-paragraph-manually
          Fill paragraph containing or following point by running
          the hook, sc-fill-paragraph-hook.
          Key binding: C-c q.

     Command: sc-modify-information
          Interactively add, delete or modify a key value in the
          attribution list sc-gal-information.
          Key binding: C-c RET.

     Command: sc-glom-headers
          Glom information from mail headers in region between point
          and mark.
          Key binding: C-c C-g.

     Command: sc-version
          Show the supercite version number.
          Key binding: C-c C-v.

     Command: sc-describe
          Describe the supercite package.
          Key binding: C-c ?.


-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Enjoy, and please send the author your compliments, questions,
suggestions and bug reports.  Don't forget, if you're interested in
discussing supercite, join the mailing list by sending mail to the
request line mentioned above.
-- 
Dan_Jacobson@ATT.COM  Naperville IL USA  +1 708-979-6364