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