This document describes Supercite, an Emacs package for citing and
attributing replies to mail and news messages.
-Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1993, 2001--2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@contents
@ifnottex
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
+@node Top
+@top Supercite
-@insertcopying
+@insertcopying
The manual is divided
into the following chapters.
@menu
* Introduction::
* Citations::
+* Information Keys and the Info Alist::
+* Reference Headers::
* Getting Connected::
* Replying and Yanking::
* Selecting an Attribution::
* Configuring the Citation Engine::
* Post-yank Formatting Commands::
-* Information Keys and the Info Alist::
-* Reference Headers::
* Hints to MUA Authors::
* Thanks and History::
@end ifnottex
-@node Introduction, Usage Overview, Top, Top
+@node Introduction
@chapter Introduction
Supercite is a GNU Emacs package written entirely in Emacs Lisp. It
The preferred way to spell Supercite is with a capital @samp{S},
lowercase @samp{upercite}.
-@ifinfo
@menu
* Usage Overview::
* What Supercite Does Not Do::
* What Supercite Does::
@end menu
-@end ifinfo
@cindex MUA
@cindex NUA
sent. Supercite is re-initialized in each new reply buffer.
-@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
+@node Usage Overview
+@section Usage Overview
@kindex r
@kindex f
@kindex C-c C-y
@cindex yank
@cindex cite, citing
@cindex attribute, attributing
-@section Usage Overview
Typical usage is as follows. You want to reply or followup to a message
-in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
+in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
(i.e., ``forward'') to begin composing the reply. In response, the MUA
will create a reply buffer and initialize the outgoing mail headers
appropriately. The body of the reply will usually be empty at this
using Supercite you gain a wider flexibility in the look and style of
citations. Supercite's only job is to cite the original message.
-@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
+@node What Supercite Does Not Do
@section What Supercite Doesn't Do
Because of this clear division of labor, there are useful features which
outside the designated region. @xref{Hints to MUA Authors}, for more
details.@refill
-@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction
-@findex sc-cite-original
+@node What Supercite Does
@section What Supercite Does
+@findex sc-cite-original
Supercite is invoked for the first time on a reply buffer via your MUA's
reply or forward command. This command will actually perform citations
by calling a hook variable to which Supercite's top-level function
@code{sc-cite-original} has been added. When @code{sc-cite-original} is
executed, the original message must be set up in a very specific way,
-but this is handled automatically by the MUA. @xref{Hints to MUA
+but this is handled automatically by the MUA@. @xref{Hints to MUA
Authors}.@refill
@cindex info alist
(optionally) be filled by Supercite. However, if you manually edit the
cited text and want to re-fill it, you must use an add-on package such
as @cite{filladapt} or @cite{gin-mode}. These packages can recognize
-Supercited text and will fill them appropriately. Emacs' built-in
-filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
+Supercited text and will fill them appropriately. Emacs's built-in
+filling routines, e.g., @code{fill-paragraph}, do not recognize cited
text and will not re-fill them properly because it cannot guess the
@code{fill-prefix} being used.
@xref{Post-yank Formatting Commands}, for details.@refill
informative citations throughout. Supercite tries to be as configurable
as possible to allow for a wide range of personalized citation styles,
but it is also immediately useful with the default configuration, once
-it has been properly connected to your MUA. @xref{Getting Connected},
+it has been properly connected to your MUA@. @xref{Getting Connected},
for more details.@refill
-@node Citations, Citation Elements, What Supercite Does, Top
+@node Citations
+@chapter Citations
@cindex nested citations
@cindex citation
-@chapter Citations
-A @dfn{citation} is the acknowledgement of the original author of a mail
+A @dfn{citation} is the acknowledgment of the original author of a mail
message in the body of the reply. There are two basic citation styles
which Supercite supports. The first, called @dfn{nested citations} is
an anonymous form of citation; in other words, an indication is made
And that's what I think too.
@end example
-@ifinfo
@menu
* Citation Elements::
* Recognizing Citations::
@end menu
-@end ifinfo
Note that multiple inclusions of the original messages result in a
nesting of the @samp{@code{>}} characters. This can sometimes be quite
are used.
-@node Citation Elements, Recognizing Citations, Citations, Citations
-@cindex citation string
+@node Citation Elements
@section Citation Elements
+@cindex citation string
@dfn{Citation strings} are composed of one or more elements. Non-nested
citations are composed of four elements, three of which are directly
enough to not put additional spaces between citation delimiters for
multi-level nested citations.
-@node Recognizing Citations, Getting Connected, Citation Elements, Citations
+@node Recognizing Citations
@section Recognizing Citations
Supercite also recognizes citations in the original article, and can
change @code{sc-citation-root-regexp} you should always also change
@code{sc-citation-nonnested-root-regexp}.@refill
-@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
+@node Information Keys and the Info Alist
+@chapter Information Keys and the Info Alist
@cindex information keys
@cindex Info Alist
@cindex information extracted from mail fields
@findex sc-mail-field
@findex mail-field (sc-)
-@chapter Information Keys and the Info Alist
@dfn{Mail header information keys} are nuggets of information that
Supercite extracts from the various mail headers of the original
-message, placed in the reply buffer by the MUA. Information is kept in
+message, placed in the reply buffer by the MUA@. Information is kept in
the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
various places within Supercite, such as in header rewrite functions and
attribution selection. Other bits of data, composed and created by
info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
@dots{}). @xref{Selecting an Attribution}.@refill
-@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
-@cindex reference headers
+@node Reference Headers
@chapter Reference Headers
+@cindex reference headers
Supercite will insert an informative @dfn{reference header} at the
beginning of the cited body of text, which display more detail about the
information contained in the info alist can be inserted into a reference
header.
-@ifinfo
@menu
* The Built-in Header Rewrite Functions::
* Electric References::
@end menu
-@end ifinfo
@cindex header rewrite functions
@vindex sc-rewrite-header-list
integer which is an index into the @code{sc-rewrite-header-list},
beginning at zero.
-@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
-@cindex header rewrite functions, built-in
+@node The Built-in Header Rewrite Functions
@section The Built-in Header Rewrite Functions
+@cindex header rewrite functions, built-in
Below are examples of the various built-in header rewrite functions.
-Please note the following:@: first, the text which appears in the
+Please note the following: first, the text which appears in the
examples below as @var{infokey} indicates that the corresponding value
of the info key from the info alist will be inserted there.
(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said}
@code{>>>>> see @var{references} for more details}
@end table
-@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
-@cindex electric references
+@node Electric References
@section Electric References
+@cindex electric references
By default, when Supercite cites the original message for the first
time, it just goes ahead and inserts the reference header indexed by
Supercite will execute the hook @code{sc-electric-mode-hook} before
entering electric reference mode.
-@node Getting Connected, Replying and Yanking, Recognizing Citations, Top
-@cindex citation interface specification
+@node Getting Connected
@chapter Getting Connected
-
+@cindex citation interface specification
@vindex mail-citation-hook
@cindex .emacs file
One final note. After Supercite is loaded into your Emacs session, it
runs the hook @code{sc-load-hook}. You can put any customizations into
this hook since it is only run once. This will not work, however, if
-your Emacs maintainer has put Supercite into your dumped Emacs' image.
+your Emacs maintainer has put Supercite into your dumped Emacs image.
In that case, you can use the @code{sc-pre-hook} variable, but this will
get executed every time @code{sc-cite-original} is called. @xref{Reply
Buffer Initialization}.@refill
-@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top
+@node Replying and Yanking
@chapter Replying and Yanking
-@ifinfo
This chapter explains what happens when you reply and yank an original
message from an MUA.
* Reply Buffer Initialization::
* Filling Cited Text::
@end menu
-@end ifinfo
-@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
+
+@node Reply Buffer Initialization
+@section Reply Buffer Initialization
@findex sc-cite-original
@findex cite-original (sc-)
-@section Reply Buffer Initialization
Executing @code{sc-cite-original} performs the following steps as it
initializes the reply buffer:
reset certain variables set in @code{sc-pre-hook}.@refill
@end enumerate
-@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
+@node Filling Cited Text
+@section Filling Cited Text
@cindex filling paragraphs
@vindex sc-auto-fill-region-p
@vindex auto-fill-region-p (sc-)
@findex setup-filladapt (sc-)
@vindex sc-load-hook
@vindex load-hook (sc-)
-@section Filling Cited Text
Supercite will automatically fill newly cited text from the original
message unless the variable @code{sc-auto-fill-region-p} has a
I usually run with both these variables containing their default values.
When Supercite's automatic filling breaks on a particular message, I
-will use Emacs' undo feature to undo back before the citation was
+will use Emacs's undo feature to undo back before the citation was
applied to the original message. Then I'll toggle the variables and
manually cite those paragraphs that I don't want to fill or collapse
whitespace on. @xref{Variable Toggling Shortcuts}.@refill
containing lines greater than about 72 characters. So the default is to
fill cited text.
-@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
+@node Selecting an Attribution
+@chapter Selecting an Attribution
@cindex attribution list
@vindex sc-preferred-attribution-list
@vindex preferred-attribution-list (sc-)
-@chapter Selecting an Attribution
As you know, the attribution string is the part of the author's name
that will be used to composed a non-nested citation string. Supercite
information as the author's first name, middle names, and last name, the
author's initials, and the author's email terminus.
-@ifinfo
@menu
* Attribution Preferences::
* Anonymous Attributions::
* Author Names::
@end menu
-@end ifinfo
-@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
+@node Attribution Preferences
@section Attribution Preferences
When you cite an original message, you can tell Supercite which part of
@example
@group
-(@var{infokey} ((@var{regexp} @. @var{attribution})
- (@var{regexp} @. @var{attribution})
+(@var{infokey} ((@var{regexp} . @var{attribution})
+ (@var{regexp} . @var{attribution})
(@dots{})))
@end group
@end example
match against a specific mail field, e.g., @samp{From:@:}, allowing you
to cite your friend's message with the appropriate attribution.
-@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
+@node Anonymous Attributions
+@section Anonymous Attributions
@vindex sc-default-author-name
@vindex default-author-name (sc-)
@vindex sc-default-attribution
@vindex default-attribution (sc-)
-@section Anonymous Attributions
When the author's name cannot be found in the @samp{From:@:} mail
header, a fallback author name and attribution string must be supplied.
variables in your hook functions, you change the attribution and
citation strings used by Supercite. One possible use of this would be
to override any automatically derived attribution string when it is only
-one character long; e.g. you prefer to use @code{"initials"} but the
+one character long; e.g., you prefer to use @code{"initials"} but the
author only has one name.@refill
-@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
-@cindex author names
+@node Author Names
@section Author Names
+@cindex author names
Supercite employs a number of heuristics to decipher the author's name
based on value of the @samp{From:@:} mail field of the original message.
association list, where each element is a cons cell of the form:
@example
-(@var{regexp} @. @var{position})
+(@var{regexp} . @var{position})
@end example
@noindent
@code{sc-name-filter-alist} would have an entry such as:
@example
-("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
+("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" . 0)
@end example
@noindent
word in the name field, while @code{any} matches against every word in
the name field.
-@node Configuring the Citation Engine, Using Regi, Author Names, Top
+@node Configuring the Citation Engine
+@chapter Configuring the Citation Engine
@cindex Regi
@cindex frames (Regi)
@cindex entries (Regi)
-@chapter Configuring the Citation Engine
At the heart of Supercite is a regular expression interpreting engine
called @dfn{Regi}. Regi operates by interpreting a data structure
throughout Supercite, from mail header information extraction, to header
nuking, to citing text.
-@ifinfo
@menu
* Using Regi::
* Frames You Can Customize::
@end menu
-@end ifinfo
While the details of Regi are discussed below (@pxref{Using Regi}), only
those who wish to customize certain aspects of Supercite need concern
cite or fill those differently than normal text. None of this is
currently part of Supercite, but contributions are welcome!
-@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
+@node Using Regi
+@section Using Regi
@findex regi-interpret
@findex eval
@findex looking-at
-@section Using Regi
Regi works by interpreting frames with the function
@code{regi-interpret}. A frame is a list of arbitrary size where each
The current frame entry being interpreted.
@end table
-@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
-@vindex sc-nuke-mail-header
+@node Frames You Can Customize
@section Frames You Can Customize
+@vindex sc-nuke-mail-header
As mentioned earlier, Supercite uses various frames to perform
certain jobs such as mail header information extraction and mail header
@vindex sc-cite-frame-alist
@vindex sc-uncite-frame-alist
@vindex sc-recite-frame-alist
-For each of the actions -- citing, unciting, and reciting -- an alist is
+For each of the actions---citing, unciting, and reciting---an alist is
consulted to find the frame to use (@code{sc-cite-frame-alist},
@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
respectively). These frames can contain alists of the form:
@example
-((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
- (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
+((@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{})
+ (@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{})
(@dots{}))
@end example
the appropriate alist and attempts to find a frame to use. If one
is not found from the alist, then the appropriate default frame is used.
-@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
+@node Post-yank Formatting Commands
+@chapter Post-yank Formatting Commands
@vindex sc-mode-map-prefix
@vindex mode-map-prefix (sc-)
@kindex C-c C-p
-@chapter Post-yank Formatting Commands
Once the original message has been yanked into the reply buffer, and
@code{sc-cite-original} has had a chance to do its thing, a number of
chapter, we'll assume you've installed Supercite's keymap on the default
prefix.@refill
-@ifinfo
@menu
* Citing Commands::
* Insertion Commands::
* Mail Field Commands::
* Miscellaneous Commands::
@end menu
-@end ifinfo
-@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
-@vindex sc-cite-region-limit
+@node Citing Commands
@section Commands to Manually Cite, Recite, and Uncite
+@vindex sc-cite-region-limit
Probably the three most common post-yank formatting operations that you
will perform will be the manual citing, reciting, and unciting of
region, regardless of the value of @code{sc-confirm-always-p}.
@end table
-@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
+@node Insertion Commands
@section Insertion Commands
These two functions insert various strings into the reply buffer.
an error and will not cite the line.
@end table
-@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
-@cindex toggling variables
+@node Variable Toggling Shortcuts
@section Variable Toggling Shortcuts
+@cindex toggling variables
Supercite defines a number of commands that make it easier for you to
toggle and set various Supercite variables as you are editing the reply
@findex set-variable
The following commands let you set the value of multi-value variables,
-in the same way that Emacs' @code{set-variable} does:
+in the same way that Emacs's @code{set-variable} does:
@table @kbd
@item C-c C-p C-t a
brings up a Help message on the toggling keymap.
-@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
+@node Mail Field Commands
@section Mail Field Commands
These commands allow you to view, modify, add, and delete various bits
old information is lost.@refill
@end table
-@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
+@node Miscellaneous Commands
@section Miscellaneous Commands
@table @asis
@findex open-line
@kindex C-c C-p o
@item @code{sc-open-line} (@kbd{C-c C-p o})
-Similar to Emacs' standard @code{open-line} commands, but inserts the
+Similar to Emacs's standard @code{open-line} commands, but inserts the
citation string in front of the new line. As with @code{open-line},
an optional numeric argument inserts that many new lines.@refill
@end table
-@node Hints to MUA Authors, Thanks and History, Electric References, Top
+@node Hints to MUA Authors
@chapter Hints to MUA Authors
In June of 1989, some discussion was held between the various MUA
@item
Insert the original message, including the mail headers into the reply
buffer. At this point you should not modify the raw text in any way
-(except for any necessary decoding, e.g. of quoted-printable text), and
+(except for any necessary decoding, e.g., of quoted-printable text), and
you should place all the original headers into the body of the reply.
This means that many of the mail headers will be duplicated, one copy
above the @code{mail-header-separator} line and one copy below, however
If you do all this your MUA will join the ranks of those that conform to
this interface ``out of the box.''
-@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top
+@node Thanks and History
@chapter Thanks and History
The Supercite package was derived from its predecessor Superyank 1.11
Supercite mailing list participants.
With version 3, Supercite underwent an almost complete rewrite,
-benefitting in a number of ways, including vast improvements in the
+benefiting in a number of ways, including vast improvements in the
speed of performance, a big reduction in size of the code and in the use
of Emacs resources, and a much cleaner and flexible internal
architecture. Most of this work was internal and not of very great
Supercite was written by Barry Warsaw.
-@node GNU Free Documentation License, Concept Index, Thanks and History, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
-@node Concept Index, Command Index, GNU Free Documentation License, Top
+@node Concept Index
@unnumbered Concept Index
@printindex cp
-@node Command Index, Key Index, Concept Index, Top
+@node Command Index
@unnumbered Command Index
-@ifinfo
-@end ifinfo
Since all supercite commands are prepended with the string
``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
its @var{command} name.
@end iftex
@printindex fn
-@node Key Index, Variable Index, Command Index, Top
+@node Key Index
@unnumbered Key Index
@printindex ky
-@node Variable Index, , Key Index, Top
+@node Variable Index
@unnumbered Variable Index
-@ifinfo
-@end ifinfo
Since all supercite variables are prepended with the string
``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
its @var{variable} name.
@end iftex
@printindex vr
@bye
-
-@ignore
- arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436
-@end ignore