home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / elisp / packages / sc-2.3 / README < prev    next >
Encoding:
Text File  |  1993-01-07  |  12.2 KB  |  276 lines
  1. This is the distribution of Supercite 2.3, released January 1993, It is an
  2. elisp utility to do fancy citing of reply messages for various mail and
  3. news reading subsystems for GNU emacs.  This version fixes bugs that arose
  4. when porting supercite to Lucid Emacs 19.x. See the file ChangeLog for
  5. more details.
  6.  
  7. LCD Entry:
  8. supercite|Barry A. Warsaw|bwarsaw@cen.com
  9. |Citation package for various mail and news readers
  10. |07-Jan-1993|2.3|
  11.  
  12. The only substantive change between version 2.2, originally released in
  13. May 1991, and this version is that this version should work with both GNU
  14. emacs 18.59 and Lucid Emacs 19.3.  The only thing that doesn't quite work
  15. in lemacs is the doc-string spoogification in the reply buffer; the
  16. supercite keybindings don't show up when doing a describe-mode.  I suspect
  17. this is no big deal for most people. I'll be looking into this for version
  18. 3.0 which is still in development.
  19.  
  20. One important change is that sc-electric.el has been renamed to sc-elec.el
  21. to avoid problems with 14-char-max filename Un*x's.  This should be a
  22. transparent change.
  23.  
  24. The rest of this README covers changes from version 2.1 to 2.2.
  25.  
  26. Things removed:
  27.  
  28.     * Cheapcite. Consider this a failed experiment ;-}. I conducted a
  29.       poll of the supercite listers and it turns out nobody was really
  30.       using it anyway (at least no one who responded).  Plus it was
  31.       just too hard to maintain 2 versions of the same code, and
  32.       cheapcite didn't really appear to improve the benefit/size
  33.       costs. If you still want cheapcite, get it from the 2.1
  34.       distribution.
  35.  
  36.     * MH-E overloading. This version of supercite is based on emacs
  37.       18.57 and the mh-e.el mode distributed with emacs 18.57 now
  38.       supports the necessary hooks. Nothing prohibits you from using
  39.       supercite 2.3 with emacs versions before 18.57, but if you use
  40.       MH-E mode with these earlier versions, either save the
  41.       overloading routines from version 2.1 sc-oloads.el, or grab
  42.       mh-e.el from 18.57.  I understand its drop-in compatible (but I
  43.       don't use MH-E so I don't know for sure that this is the case).
  44.  
  45. Things added:
  46.  
  47.     * sc.texinfo. Yes, I actually got motivated to write a texinfo
  48.       manual for this beast. I think it beats the hell out of
  49.       sc-describe and so I've chopped all that sc-describe stuff out.
  50.  
  51.     * nicknames. A new variable sc-nickname-alist for matching names
  52.       to nicknames on a one to many basis.  Nicknames can't currently
  53.       be automatically used for attribution strings, but will always
  54.       be presented in attribution completions.
  55.  
  56.     * GNEWS overloads.
  57.  
  58.     * new variable sc-header-nuke-list for easier user defining mail
  59.       headers which get zapped.
  60.  
  61.     * new variable sc-spacify-name-chars for converting certain funny
  62.       characters which can be found in names to spaces.
  63.  
  64.     * new variable sc-all-but-cite-p for setting up all supercite
  65.       info, but not citing included text. Good for manually citing
  66.       portions of large messages.
  67.  
  68.     * new variable sc-auto-fill-query-each-paragraph-p for really fine
  69.       control of auto filling.
  70.  
  71.     * new command sc-view-field (C-c f), similar to, but different
  72.       than, sc-modify-information.
  73.  
  74.     * new info keys (for use with sc-field): "sc-reply-address" and
  75.       "sc-from-address".
  76.  
  77. Things fixed or changed:
  78.  
  79.     * electric reference mode has been improved slightly so that you
  80.       shouldn't ever encounter a catastrophic error, where your keymap
  81.       is fried.  it now works slightly differently and some of the
  82.       redundant keybindings were removed.
  83.  
  84.     * changed sc-run-hook to sc-post-hook and added sc-pre-hook. You
  85.       might want to use these for pre- and post- processing (i.e.
  86.       changing the header rewrite style based on replying or following
  87.       up).
  88.  
  89.     * sc-cite-original no longer binds sc-electric-p to nil so you
  90.       can be automatically dropped into electric referencing mode in
  91.       the first yank of the message.
  92.  
  93.     * renamed all files to begin with sc for consistency (and popular
  94.       demand).
  95.  
  96.     * sc-cite-regexp was enhanced to help with inconsistent citation
  97.       warnings.
  98.  
  99.     * sc-version takes a numeric argument for inserting into a buffer.
  100.  
  101.     * massive rewrite of built-in header rewrite functions. they now
  102.       are more intelligent about what they insert. No more "mumble"
  103.       strings! Also, changed sc-header-regarding-writes to
  104.       sc-header-regarding-adds, and put back sc-header-verbose due to
  105.       popular demand.  Finally, added sc-no-blank-line-or-header. 
  106.  
  107.     * many bug fixes and optimizations.
  108.  
  109.  
  110. -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
  111. This package should contain the following files:
  112.  
  113.     sc-alist.el     Association list utilities
  114.     sc-elec.el      Electric insert mode
  115.     sc-oloads.el    Overloading functions
  116.     sc.el           Supercite version 2.3 main file
  117.     sc.texinfo      Texinfo manual for supercite version 2.3
  118.     README          Introduction to supercite version 2.3 (this file)
  119.     ChangeLog       Differences from version 2.1
  120.  
  121. Supercite 2.3 has been tested and is known to work with VM 4.37+, VM 5.x
  122. and MH-E 3.7 (distributed with emacs 18.57) out of the box. It is
  123. compatible with GNU emacs 18.58+, and Lucid Emacs 19.3+. Supercite will
  124. work with GNUS 3.12+, RMAIL, RNEWS, GNEWS, PCMAIL, and other packages,
  125. once the proper functions have been overloaded (see below).
  126.  
  127. To learn more about linking to and using supercite, see the associated
  128. texinfo manual.  For those who aren't familiar with GNU's standard
  129. method of distributing documentation manuals, texinfo files can be
  130. used to generate both an on-line and hard copy version of a manual
  131. from a single ascii file.  Texinfo files can be processed by the TeX
  132. typesetting system (not written by GNU, but freely available from many
  133. ftp sites) and converted into PostScript or other printer ready
  134. formats.  Also, the same texinfo file can be processed within emacs to
  135. generate an "info" file, suitable for emacs' on-line info browser.
  136.  
  137. I believe the emacs distribution comes with an info node called
  138. Texinfo which describes how to generate both hardcopy and on-line
  139. manuals from a given texinfo file (such as sc.texinfo), as well as how
  140. to write such manuals yourself.  To find out more about texinfo files,
  141. while in emacs, type "C-h i" to get you into the info browser, then
  142. type "mTexinfo <RET>" to enter the Texinfo branch. If you have
  143. problems, or for more information, contact the various emacs mailing
  144. lists or news groups.  If you have problems specific to sc.texinfo,
  145. you can naturally contact the supercite mailing list for help.
  146.  
  147. What follows below is a quick guide to connecting supercite to your
  148. favorite news/mail reader.  It is excerpted from the texinfo file.
  149.  
  150. -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
  151. Getting Connected
  152. *****************
  153. Early in supercite's development, the supercite author, many of the
  154. major reader subsystem authors, and some supercite users got together
  155. and agreed upon a standard interface between all readers and any
  156. supercite-like package (of which supercite is the only known one :-).
  157. *Note Hints to Reader Authors:: for more information on the details of
  158. this interface.  You may want to also *Note Thanks and History:: for
  159. details on how this interface was proposed and adopted.
  160.  
  161. Suffice to say that at the time of this writing (May 1991), only VM
  162. 4.37+ and MH-E 3.7 (as distributed with emacs 18.57) conform to this
  163. interface "out of the box."  If you are connecting supercite to one of
  164. these two packages, you do not need overloading. All other reader
  165. packages must be modified to provide this interface.  The file
  166. `sc-oloads.el' contains "overloading" routines which will allow
  167. you to connect supercite with any of the known major readers currently
  168. in existence (*Note Overloading for Selected Readers::).  This includes:
  169. GNUS 3.12+, GNEWS, RMAIL 18.55+, RNEWS 18.55+ and PCMAIL.  If you are
  170. using a reader package other than one of those mentioned above, contact
  171. the supercite mailing list about getting or writing overloading
  172. functions for that package (*Note The Supercite Mailing List::).
  173.  
  174. Quick Guide for All Readers
  175. ===========================
  176. For any reader package except MH-E, you will need to connect supercite
  177. to the standard hook variable `mail-yank-hooks'.  MH-E users will
  178. need to connect supercite to `mh-yank-hooks'. The supercite
  179. function `sc-cite-original' is intended to be run from a hook. It
  180. not only cites the text, also does much pre- and post-processing on the
  181. reply buffer (*Note Replying and Yanking::) so it should be the first
  182. supercite function to be called on a raw reply buffer. Thus, you will
  183. need one of the following two lines in your `.emacs' file:
  184.  
  185.      (setq mail-yank-hooks 'sc-cite-original) ; for all but MH-E
  186.      (setq mh-yank-hooks   'sc-cite-original) ; for MH-E only
  187.  
  188. Also, if supercite is not compiled into your emacs image, you will need
  189. to set up the following autoload, also in your `.emacs' file:
  190.  
  191.      (autoload 'sc-cite-original "sc" "Supercite 2.3" t)
  192.  
  193. Supercite will run the user definable hook `sc-load-hook' after
  194. loading. Default value for this variable is `nil'.
  195.  
  196. Overloading for Selected Readers
  197. ================================
  198.  
  199. Most readers contain hardwired citing styles (often unpopular!) which
  200. cannot be changed. For these readers, you are required to overload the
  201. necessary functions so that they call a hook (i.e., `mail-yank-hooks')
  202. after inserting the original text into the buffer.  This hook can then
  203. be set to call `sc-cite-original' at the appropriate time.
  204.  
  205. Once again, note that if you are connecting supercite to either MH-E 3.7
  206. or VM 4.37+, you do not need overloading and can skip this section.
  207.  
  208. Quick Guide to Overloading
  209. --------------------------
  210.  
  211. Since supercite's overloading routines are usually not loaded into your
  212. emacs session until they are needed, you should add the following small
  213. function to your `.emacs' file.  This will load (via the `require') the
  214. supercite overloading package, and then actually overload the functions
  215. for the particular reader your are using.  Only those original reader
  216. functions already bound will be overloaded, and they will only be
  217. overloaded once per session.
  218.  
  219.      (defun my-sc-overload-hook ()
  220.        (require 'sc-oloads)     ; be sure this file is on your load-path
  221.        (sc-overload-functions))
  222.  
  223. Next, you will need to find a hook in the reader which will be called at
  224. an appropriate time to execute `my-sc-overload-hook'. It can be
  225. something of a guessing game to find the right hook, but fortunately
  226. that's already been done for all the readers supercite currently knows
  227. about. You should put one of these two lines in your `.emacs' file:
  228.  
  229.      (setq news-reply-mode-hook 'my-sc-overload-hook) ; for RNEWS,GNEWS,GNUS
  230.      (setq mail-setup-hook      'my-sc-overload-hook) ; for RMAIL,PCMAIL,GNUS
  231.  
  232. Note that if you have `sc-oloads.el' compiled into your emacs image, you
  233. do not need `my-sc-overload-hook'. Instead just use one of the following
  234. code fragments:
  235.  
  236.      (setq news-reply-mode-hook 'sc-overload-functions) ; for RNEWS,GNEWS,GNUS
  237.      (setq mail-setup-hook      'sc-overload-functions) ; for RMAIL,PCMAIL,GNUS
  238.  
  239. -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
  240. Enjoy, and please send the author your questions, suggestions,
  241. patches, enhancements and bug reports.  Don't forget, if you're
  242. interested in discussing supercite, join the mailing list by sending
  243. mail to the supercite-request address below.
  244.  
  245. If you do send bug reports, please indicate the version of supercite
  246. and emacs that you are using and the name and version number of the
  247. reader package you're trying to interface with. This will help you in
  248. getting your problem resolved. There are many very helpful people on
  249. the mailing list, representing probably every supported reader
  250. subsystem.  But no one person uses them all (well, definitely *not*
  251. the supercite author :-), and you want to be able to draw the
  252. attention of the right people.
  253.  
  254. NAME: Barry A. Warsaw      USMAIL: Century Computing, Inc.
  255. TELE: (301) 593-3330               1014 West Street
  256. INET: bwarsaw@cen.com              Laurel, Md 20707
  257. UUCP: uunet!cen.com!bwarsaw
  258.  
  259. Want to be on the Supercite mailing list?
  260.  
  261. Send articles to:
  262.     Internet: supercite@anthem.nlm.nih.gov
  263.         UUCP: uunet!anthem.nlm.nih.gov!supercite
  264.  
  265. Send administrivia (additions/deletions to list, etc) to:
  266.     Internet: supercite-request@anthem.nlm.nih.gov
  267.         UUCP: uunet!anthem.nlm.nih.gov!supercite-request
  268.  
  269. Local Variables:
  270. mode: indented-text
  271. tab-width: 4
  272. left-margin: 8
  273. fill-column: 74
  274. version-control: never
  275. End:
  276.