home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / a / atav11.zip / ATAVACHR.INF (.txt) < prev    next >
GNU Info File  |  1993-01-19  |  47KB  |  914 lines
  1. This is Info file atavachron.info, produced by Makeinfo-1.49 from the
  2. input file atavachron.texi.
  3. File: atavachron.info,  Node: Top,  Next: Copying Conditions,  Prev: (dir),  Up: (dir)
  4.                             The Atavachron
  5.                by James E. Hetrick <hetrick@phys.uva.nl>
  6.    The *Atavachron* is an interface to the "Astro/Math/Physics"
  7. preprint archives from within the GNU Emacs editor. It gives the user a
  8. simple set of commands to get, store, process, and list papers with
  9. minimal effort.
  10.    This Texinfo file is current to Version 1.1 and was compiled        
  11.   by James Hetrick and Marcus Speh.
  12. * Menu:
  13. * Copying Conditions::
  14. * General Description::
  15. * Configuration::
  16. * Batteries Not Included::
  17. * Functions::
  18. * Paper Formats::
  19. * Example Sessions::
  20. * Things To Come::
  21. * Index::
  22.  -- The Detailed Node Listing --
  23. Configuration
  24. * Example .emacs File::
  25. * atv-main-ftp-site::
  26. * atv-download-dir::
  27. * atv-uufiles-dir::
  28. * atv-prompt-filename::
  29. * atv-interesting-file::
  30. * atv-auto-tex-paper::
  31. * atv-no-csh::
  32. Batteries Not Included
  33. * ange-ftp.el::
  34. * zcat.el::
  35. * .netrc::
  36. * .dvipsrc::
  37. Functions
  38. * Getting Papers::
  39. * Storing Papers::
  40. * Processing Functions::
  41. * Title Listings and Abstracts::
  42. * Utilities::
  43. File: atavachron.info,  Node: Copying Conditions,  Next: General Description,  Prev: Top,  Up: Top
  44. Copying Conditions
  45. ******************
  46.    This program is free software; you can redistribute it and/or modify
  47. it under the terms of the GNU General Public License as published by
  48. the Free Software Foundation.
  49.    This program is distributed in the hope that it will be useful, but
  50. *without any warranty*; without even the implied warranty of
  51. *merchantability* or *fitness for a particular purpose*. See the GNU
  52. General Public License for more details.
  53.    A copy of the GNU General Public License can be obtained from
  54.      Free Software Foundation, Inc.,
  55.      675 Mass Ave,
  56.      Cambridge, MA 02139, USA.
  57.    Permission is granted to copy and distribute modified versions of
  58. this manual under the conditions for verbatim copying, provided that the
  59. entire resulting derived work is distributed under the terms of a
  60. permission notice identical to this one.
  61. Obtaining This Package
  62. ======================
  63.    At the time of writing (January 1993), the `atavachron' package is
  64. intended to be placed in the `macros' directory of the supported
  65. archives. Thus it should hopefully be accessible by February 1993
  66. through anonymous ftp or by electronic mail from your favorite preprint
  67. site.
  68.    Copies will be submitted to `prep.ai.mit.edu' and
  69. `archive.cis.ohio-state.edu' for permenant archiving, and announcements
  70. will be made to the relevant Newsgroups (`gnu.emacs.source' and
  71. `sci.phys', at least).
  72.    Of course, the latest version can always be obtained from the author
  73. directly at the address given in *note General Description::..
  74. File: atavachron.info,  Node: General Description,  Next: Configuration,  Prev: Copying Conditions,  Up: Top
  75. General Description
  76. *******************
  77.    The *Atavachron* (pronounced: a . TAV'. a . kron) is an intelligent
  78. interface or "Front End" to the scientific preprint archives from
  79. within emacs. The preprint archives supported are only those running
  80. Paul Ginsparg's (<ginsparg@qfwfq.lanl.gov>) Preprint Bulletin Board
  81. software. At present the supported archives are:
  82.    `alg-geom:' Algebraic Geometry
  83.    `astro-ph:' Astrophysics
  84.    `cond-mat:' Condensed Matter Physics
  85.    `funct-an:' Functional Analysis
  86.    `gr-qc:   ' General Relativity and Quantum Cosmology
  87.    `hep-lat: ' High Energy Physics -- Lattice
  88.    `hep-ph:  ' High Energy Physics -- Phenomenology
  89.    `hep-th:  ' High Energy Physics -- Theory
  90.    `lc-om:   ' Liquid Crystals
  91.    `math-ph: ' Mathematical Physics (at babbage.sissa.it)
  92.    `nucl-th: ' Nuclear Theory
  93.    Should you wish to add another archive please contact the author (via
  94. `atavachron-mail' if you like *note Utilities::.). Supporting other
  95. disciplines which use TeX as their main typesetting format would be
  96. very simple and rewarding.
  97.    The *Atavachron* gives its user a simple set of commands to get,
  98. store, process, and list papers which can be called from the
  99. `mini-buffer' (the bottom most, one line window in Emacs used for
  100. command input and message output). The key strokes: `M-x' invoke Emacs
  101. functions; on most keyboards, `M' is `ESC'. The package is easily
  102. loaded via your `.emacs' file (*note Configuration::.) and then
  103. provides several functions which can be called at any time.
  104.    The *Atavachron*'s user functions are listed here and described
  105. below (*note Functions::.):
  106.      get-paper
  107.      get-paper-from-data
  108.      store-paper
  109.      store-paper-from-data
  110.      process-paper
  111.      slice-and-dice
  112.      shell-paper
  113.      get-listing-from-data
  114.      store-listing-from-data
  115.      get-abstract
  116.      get-abstract-from-data
  117.      interesting
  118.      atavachron-mail
  119.    You must go through *Note Configuration::, and *Note Batteries Not
  120. Included::, and set things appropriately for your system.  The variables
  121. to be set govern such things as where papers gotten with `get-paper'
  122. are put, whether they are renamed, and the address of your default
  123. archive.
  124.    Note that the documentation here is meant to be somewhat pedagogical
  125. for new users to Emacs. If you are such a user, your comments on the
  126. accessibility of this manual would be most appreciated.
  127.    `atavachron.el' requires `ange-ftp.el' for retrieving files across
  128. the network. In addition there are auxiliary files used by the
  129. *Atavachron* which greatly enhance its abilities. The purpose of these
  130. files is described in *Note Batteries Not Included::.
  131.    If you find bugs, please report them; this is very easy with the
  132. function `atavachron-mail'. You're welcome to use this function for
  133. other correspondence as well (*Note Utilities::).
  134. Why "Atavachron"?
  135. .................
  136.    This package was originally named `pp-tools.el' in its development
  137. stage, when a previously existing "pp-tools" package turned up in a
  138. network search. Thus the name had to be changed.
  139.    The name *Atavachron* comes from the original "Star Trek" series, in
  140. the episode "All Our Yesterdays". Kirk, Spock, and McCoy beam down to a
  141. planet with this wonderful library. Library users place disks into
  142. viewers which show images from periods of the planet's past. The
  143. library also has a portal through which users can travel backwards in
  144. time (for various reasons which probably included research).
  145.    All the disk viewers are interfaced to a machine called the
  146. *Atavachron* which senses which disk the user was viewing and
  147. configures the portal such that when the user steps through, he passes
  148. into the corresponding period of time.
  149.    Due to the similarities in functionality between the present package
  150. and the 23rd century's archive interface (at least to the imaginative
  151. mind), the name *Atavachron* seemed appropriate.
  152. Acknowledgements
  153. ................
  154.    Many thanks to Paul Ginsparg, Greg Kilcup, Marcus Speh, and Bas de
  155. Bakker for ongoing discussions, suggestions, and beta tests.
  156.    The text for the first edition of this document was taken from the
  157. text description distributed with version 1.3 of `pp-tools' and set
  158. into Texinfo by Marcus Speh (If you don't have Texinfo, you can obtain
  159. it from `prep.ai.mit.edu' via anonymous FTP).
  160.    The change over to the *Atavachron* package version 1.1 and
  161. documentation of subsequent additions to the source has been mostly
  162. done by Jim Hetrick.
  163. Author's address:
  164. .................
  165.      James E. Hetrick            Institute for Theoretical Physics
  166.      hetrick@phys.uva.nl                     -\|/-
  167.      University of Amsterdam
  168.      Valckenierstraat 65, 1018 XE Amsterdam
  169.      Telephone: +31 20 525 5772     Fax: +31 20 525 5788
  170. File: atavachron.info,  Node: Configuration,  Next: Batteries Not Included,  Prev: General Description,  Up: Top
  171. Configuration
  172. *************
  173.    This node describes the variables which configure the *Atavachron*
  174. within Emacs. "Configuring" means setting environment variables for
  175. Emacs.  These definitions are usually put into Emacs' initialization
  176. file `.emacs'. If you want to try them out, you may use any buffer in
  177. `Emacs-lisp' mode, then use `(M-x) eval-buffer', but remember that
  178. `atavachron.el' should really be reloaded everytime you change the
  179. configuration.
  180.    For users new to Emacs, there are two types of variables used below.
  181. Strings, which must be enclosed by "'s, are used for directories,
  182. archive sites, and so forth. The other kind is a logical variable which
  183. is either "t" (true or ON) or "nil" (false or OFF). Logical variables
  184. are *not* enclosed in quotations.
  185. * Menu:
  186. * Example .emacs File::
  187. * atv-main-ftp-site::
  188. * atv-download-dir::
  189. * atv-uufiles-dir::
  190. * atv-prompt-filename::
  191. * atv-interesting-file::
  192. * atv-auto-tex-paper::
  193. * atv-no-csh::
  194. File: atavachron.info,  Node: Example .emacs File,  Next: atv-main-ftp-site,  Up: Configuration
  195. Example `.emacs' File
  196. =====================
  197.    Below is an example `.emacs' file which loads `atavachron.el' and
  198. the batteries, then sets the `atv-'variables to their defaults.
  199. *Please* go through each variable and set it according to your own
  200. directory structure and preferences.
  201.    Regarding `ange-ftp.el', the simplest method of loading has been
  202. given here, for the case in which it has not been loaded previously in
  203. your `.emacs' file. If it is loaded previously be sure to delete the
  204. `(load-library '"ange-ftp")' line here, so as not to load it twice.
  205. Since `atavachron.el' contains the `require 'ange-ftp', users of more
  206. advanced auto-loading techniques may keep their mechanisms intact.
  207.    Although not discussed here, any *Atavachron* function can be bound
  208. to a key sequence or mouse button action. Such bindings should go here
  209. as well. See the Emacs manual on key rebinding and the documentation of
  210. your mouse interface for more details.
  211.      ; ====================.emacs stuff ========================
  212.      
  213.      (load-library '"ange-ftp")  ;see ange-ftp docs for more details
  214.      (setq ange-ftp-generate-anonymous-password t) ; sends email address
  215.                                                    ; for password
  216.      (load-library '"zcat")
  217.      (load-library '"atavachron")
  218.      
  219.      (setq atv-main-ftp-site "/anonymous\@babbage.sissa.it:") ;Europeans
  220.      ;;(setq atv-main-ftp-site "/anonymous\@xxx.lanl.gov:")  ;N+S Americans
  221.      
  222.      (setq atv-download-dir "~/tex/preprints/")   ;default download directory
  223.      (setq atv-uufiles-dir "~/tex/preprints/")    ;default place for uu output
  224.      (setq atv-prompt-filename t)              ;prompt to rename paper locally
  225.      (setq atv-interesting-file "~/interesting.atv") ;file for interesting abs.
  226.      (setq atv-auto-tex-paper nil)     ;run tex on paper grabbed automatically
  227.      (setq atv-auto-tex-command 'TeX-buffer)        ;command to run on buffer
  228.      (setq atv-no-csh nil)                     ;set to t if you don't have csh
  229.      
  230.      ; ==========================================================
  231. File: atavachron.info,  Node: atv-main-ftp-site,  Next: atv-download-dir,  Prev: Example .emacs File,  Up: Configuration
  232. `atv-main-ftp-site'
  233. ===================
  234.      ; ====================.emacs stuff =======================
  235.       (setq atv-main-ftp-site "/anonymous\@babbage\.sissa\.it:"); Europeans
  236.      ;; (setq atv-main-ftp-site "/anonymous\@xxx\.lanl\.gov:")  ; N+S Americans
  237.      ; ======================================================== ; Others chose one
  238.    Uncomment one of these as your main archive. Branches not supported
  239. at `xxx.lanl.gov', such as "cond-mat", are retrieved from
  240. `babbage.sissa.it'. Papers on "hep-lat", "alg-geom", etc. which are not
  241. mirrored at the above two sites are automatically gotten >from their
  242. respective archives at present.
  243. File: atavachron.info,  Node: atv-download-dir,  Next: atv-uufiles-dir,  Prev: atv-main-ftp-site,  Up: Configuration
  244. `atv-download-dir'
  245. ==================
  246.      ; ====================.emacs stuff =======================
  247.      (setq atv-download-dir "~/tex/preprints/")    ;default download directory
  248.      (setq atv-uufiles-dir "~/tex/preprints/")     ;default place for uu output
  249.      ; ========================================================
  250.    This is your local download workspace. Upon "getting" a paper, the
  251. default directory is reset to `atv-download-dir' so that saves put
  252. files there. In addition tarred papers (archived and compressed as
  253. .tar.Z files), and script papers (papers which are shell scripts to be
  254. executed) are processed in this directory so that any files unpacked end
  255. up there.
  256.    If you have branch directories  "hep-th", "hep-lat", "astro-ph", etc.
  257. below `atv-download-dir', papers, when saved, will automatically be put
  258. there, sorted by branch. For example, your `atv-download-dir' is set to
  259. `~/tex/preprints/' and you have the subdirs `~/tex/preprints/hep-th/'
  260. and `~/tex/preprints/cond-mat/'. Then getting "hep-th/91120013" will
  261. put the file in `tex/preprints/hep-th/'. Getting "cond-mat/920106" will
  262. put it in `tex/preprints/cond-mat/'. If these subdirs do not exist below
  263. `tex/preprints/', both papers would be put in `tex/preprints/'. The
  264. recognition of branched subdirectories is mainly provided for very
  265. heavy or library related use.
  266.    Be sure to put this directory (and branches) in your TEXINPUTS
  267. environment variable so that tex can get at your newly gotten files.
  268. File: atavachron.info,  Node: atv-uufiles-dir,  Next: atv-prompt-filename,  Prev: atv-download-dir,  Up: Configuration
  269. `atv-uufiles-dir'
  270. =================
  271.    This is where uuencoded files will be unpacked. It should usually be
  272. the same as `atv-download-dir', unless you have a good reason to put the
  273. figures elsewhere [your "dvi --> ps" processor can't get at them in
  274. `atv-download-dir', for instance. (in which case you should get
  275. `dvips')]. If it's the same as `atv-download-dir', it will adjust
  276. itself to the branched subdirectory structure following
  277. `atv-download-dir'.
  278. File: atavachron.info,  Node: atv-prompt-filename,  Next: atv-interesting-file,  Prev: atv-uufiles-dir,  Up: Configuration
  279. `atv-prompt-filename'
  280. =====================
  281.      ; ====================.emacs stuff =======================
  282.      (setq atv-prompt-filename t)        ; prompt to rename paper locally
  283.      ; ========================================================
  284.    This one toggles prompting for a local name for the grabbed paper or
  285. listing. When "t" (true), you are prompted to name the incoming archive
  286. file which is then appended with `.tex'. Hitting return at the prompt
  287. will accept the default given in parenthesis. If "nil" the paper is
  288. named by its paper number.
  289. File: atavachron.info,  Node: atv-interesting-file,  Next: atv-auto-tex-paper,  Prev: atv-prompt-filename,  Up: Configuration
  290. `atv-interesting-file'
  291. ======================
  292.      ; ===========================================
  293.      (setq atv-interesting-file "~/interesting.atv")  ; file for interesting
  294.      ; ===========================================  ; abstracts.
  295.    The default file to which abstracts stored with `interesting'
  296. function are appended (*note Utilities::.). You are prompted for a file
  297. name to append the interesting abstract to, and offered
  298. `atv-interesting-file' as the default.
  299.    I find it useful to put this file in a directory other than
  300. `atv-download-dir' since I regularly clean `atv-download-dir' with `rm
  301. File: atavachron.info,  Node: atv-auto-tex-paper,  Next: atv-no-csh,  Prev: atv-interesting-file,  Up: Configuration
  302. `atv-auto-tex-paper'
  303. ====================
  304.      ; ====================.emacs stuff =======================
  305.      (setq atv-auto-tex-paper nil)    ; run tex on paper grabbed automatically
  306.      (setq atv-auto-tex-command 'TeX-buffer)  ; command to run on buffer
  307.      ; ========================================================
  308.    Setting `atv-auto-tex-paper' to "t", automatically starts the tex
  309. processor as given by the function `atv-auto-tex-command' on the paper
  310. once it's loaded into a local buffer, provided no shell command signal
  311. is found. The default is that auto-texxing is OFF.
  312.    Note that adding auto-previewing is quite simple as well (e-mail for
  313. details), and will impress your friends if the paper texs, but is not
  314. really all that useful since many papers don't pass the texxing stage,
  315. as you probably know! As this changes, and authors submit standardized
  316. TeX, auto-tex/preview could become useful.
  317.    Originally provided as extra frill, these variables can actually be a
  318. powerful expansion slot. You can supply any function you like for
  319. `atv-auto-tex-command', in particular your own custom ones. Thus after
  320. processing all auxillary files and getting the primary TeX file,
  321. `atv-auto-tex-command' provides a final hook to execute custom
  322. processing.
  323. File: atavachron.info,  Node: atv-no-csh,  Prev: atv-auto-tex-paper,  Up: Configuration
  324. `atv-no-csh'
  325. ============
  326.      ; ====================.emacs stuff =======================
  327.      (setq atv-no-csh nil)            ; set to t if you don't have csh
  328.      ; ========================================================
  329.    Setting this variable to "t" will replace the `/bin/csh' in the
  330. grabbed uufile to `/bin/sh', making it possible to unpack the figure
  331. files even if you don't have `csh' on your machine. If you use this
  332. feature, please read the copyright *Note Copying Conditions:: now,
  333. especially where it says:
  334.    "This program is distributed in the hope that it will be useful, but
  335. *without any warranty*..."
  336. File: atavachron.info,  Node: Batteries Not Included,  Next: Functions,  Prev: Configuration,  Up: Top
  337. Batteries Not Included
  338. **********************
  339.    Here we discuss the other files needed or recommended for smooth
  340. operation of `atavachron.el'. The only one absolutely required is
  341. `ange-ftp.el', however you'll have to decipher a compressed binary file
  342. if you get a month old paper without `zcat.el'. The files `.netrc' and
  343. `.dvipsrc' eliminate the seams at the connections to the network and
  344.    Loading the elisp (`.el') files in your `.emacs' file is discussed
  345. in *Note Configuration::.
  346. * Menu:
  347. * ange-ftp.el::
  348. * zcat.el::
  349. * .netrc::
  350. * .dvipsrc::
  351. File: atavachron.info,  Node: ange-ftp.el,  Next: zcat.el,  Up: Batteries Not Included
  352. `ange-ftp.el'
  353. =============
  354.    * This file is available via anonymous FTP from
  355. `archive.cis.ohio-state.edu' in directory
  356. `/pub/gnu/emacs/elisp-archive/packages/'.
  357.    `atavachron.el' requires Andy Norman's essential ftp interface
  358. `ange-ftp.el' to do the remote file teleportation If you don't have
  359. this loaded in your `.emacs' file, you must get it. Check locally if
  360. you have it (perhaps in `/usr/local/emacs/lisp' or there abouts?), or
  361. convince your system administrator to install it (or do it yourself).
  362. File: atavachron.info,  Node: zcat.el,  Next: .netrc,  Prev: ange-ftp.el,  Up: Batteries Not Included
  363. `zcat.el'
  364. =========
  365.    * This file is included in the `atavachron' distribution package.
  366.    Another file needed is Graham Gough's `zcat.el' which uncompresses
  367. `.Z' files on the fly. This makes loading older papers which are
  368. compressed at the archive transparent. Since it's short it's included
  369. with the distribution package of `atavachron'.
  370. File: atavachron.info,  Node: .netrc,  Next: .dvipsrc,  Prev: zcat.el,  Up: Batteries Not Included
  371. `.netrc'
  372. ========
  373.    * You can easily write your own `.netrc' file, see example below.
  374.    Ange-ftp will work much smoother if you keep a `.netrc' file in your
  375. home directory, thus bypassing the need to send the "anonymous" login
  376. and email address when ftping into the archive. Simply clip out the
  377. following and name it `~/.netrc'. Remember to put your email address in
  378. for you@where.you.are).
  379. sample `.netrc'
  380. ...............
  381.      #   --------------------.netrc sample -----------------------
  382.      machine ftp.scri.fsu.edu login anonymous password you@where.you.are
  383.      machine xxx.lanl.gov login anonymous password you@where.you.are
  384.      machine babbage.sissa.it login anonymous password you@where.you.are
  385.      machine publications.math.duke.edu login anonymous password you@where.you.are
  386.      machine alcom-p.cwru.edu login anonymous password you@where.you.are
  387.      #   ---------------------------------------------------------
  388.    Furthermore, it must be a protected file. Run: `chmod go-rwx .netrc'
  389. on it once it has been created.
  390. File: atavachron.info,  Node: .dvipsrc,  Prev: .netrc,  Up: Batteries Not Included
  391. `.dvipsrc'
  392. ==========
  393.    * You can easily write your own `.dvipsrc' file, see example below.
  394.    Finally, if you use `dvips' as your ".dvi --> .ps" processor, put
  395. your `atv-download-dir' and `atv-uufiles-dir' (*note Configuration::.)
  396. in its path by keeping a `.dvipsrc' file in your home directory with
  397. the following lines:
  398. sample `.dvipsrc'
  399. .................
  400.      # -------------------.dvipsrc sample ---------------------
  401.      S ~/tex/preprints:
  402.      H ~/tex/preprints:
  403.      W "reading your .dvipsrc file"
  404.      # --------------------------------------------------------
  405.    The trailing `:''s above add the default paths to the path list. A
  406. line beginning with `W' echos the following string.
  407.    Having `atv-download-dir' and `atv-uufiles-dir' in both your `dvips'
  408. path and your TEXINPUTS environment variable (or whatever the path to
  409. TeX input and style files is named on your local machine) allows
  410. `dvips' and TeX to access your new figure files.
  411.    For more info, see your man pages on TeX and `dvips' or your system
  412. administrator, whichever is friendlier.
  413. File: atavachron.info,  Node: Functions,  Next: Paper Formats,  Prev: Batteries Not Included,  Up: Top
  414. Functions
  415. *********
  416.    This section describes the functions available to the user for
  417. interacting with the archive. In addition three example sessions are
  418. displayed in *Note Example Sessions::, where the reader can get a quick
  419. feel for the operation of the *Atavachron* on different types of papers.
  420. * Menu:
  421. * Getting Papers::
  422. * Storing Papers::
  423. * Processing Functions::
  424. * Title Listings and Abstracts::
  425. * Utilities::
  426. File: atavachron.info,  Node: Getting Papers,  Next: Storing Papers,  Up: Functions
  427. Getting Papers
  428. ==============
  429.    The following functions get an archive paper to an Emacs buffer (or
  430. buffers if it is distributed in several files). After the paper is in a
  431. local buffer, action appropriate to the format of the paper is taken.
  432. For instance, a tar file is uncompressed and unpacked, or uu encoded
  433. files are decoded, as described below in *Note Paper Formats::.
  434.    * Function: get-paper
  435.    When reading an abstract listing in emacs, either in one of the mail
  436. readers or as a previously saved file (output by Unix Mail perhaps),
  437. placing the point (cursor) anywhere in the abstract of choice (after the
  438. line beginning with `Paper'), and typing: `M-x get-paper' automatically
  439. opens an ftp socket into the right archive (via `ange-ftp.el'),
  440. transfers the paper, uncompresses it if necessary (via `zcat.el'), and
  441. loads it into a `tex-mode' buffer for [La]TeXing, previewing, and
  442. printing by the usual `tex-mode' facilities.
  443.    First though, the *Atavachron* performs a number of tests to
  444. determine the format in which the paper is stored at the archive. These
  445. steps are also performed by `process-paper' if it is called on a stored
  446. paper (See *Note Processing Functions::, *Note Storing Papers::.) Once
  447. its format is determined, appropriate action is taken based on the
  448. configuration variables (*note Configuration::.). The description of the
  449. paper formats supported in the present version (1.1) is given below (see
  450. *note Paper Formats::.).
  451.    If `atv-prompt-filename' is "t" (true), one is prompted to give a
  452. local name to the incoming paper, and the paper is renamed
  453. `localname.ext', where `.ext' depends on the format of the paper.
  454.    The buffer(s) containing the paper are marked as changed so that you
  455. will be prompted to save it if you try to delete it.
  456.    * Function: get-paper-from-data
  457.    This function works exactly like `get-paper' except that it promps
  458. the user to input the paper's data in the usual format:
  459.      cond-mat/9212003
  460.      hep-lat/9212005
  461.      etc.
  462. File: atavachron.info,  Node: Storing Papers,  Next: Processing Functions,  Prev: Getting Papers,  Up: Functions
  463. Storing Papers
  464. ==============
  465.    * Function: store-paper
  466.    * Function: store-paper-from-data
  467.    `Store-paper', and `store-paper-from-data', work the same as
  468. `get-paper' and `get-paper-from-data', except that the paper is stored
  469. directly to the user's default download directory (*note
  470. Configuration::.) for later processing. This is convenient when reading
  471. the abstracts remotely (on the weekend from home, say) when one wants
  472. to save processing and printing the tex file for later, or so that the
  473. file can be further downloaded via modem. (*note Example Sessions::.)
  474. File: atavachron.info,  Node: Processing Functions,  Next: Title Listings and Abstracts,  Prev: Storing Papers,  Up: Functions
  475. Processing Functions
  476. ====================
  477.    Three functions are presently provided for operating on preprint
  478. files individually. These are stand alone versions of functions which
  479. are called by `get-paper' and are useful for processing stored papers
  480. or individual buffers of a multifile paper.
  481.    In addition, the descriptions of the Emacs functions `buffer-menu'
  482. and `insert-buffer' are included for completeness; they are quite
  483. useful when a retrieved paper consists of several files which must be
  484. processed.
  485. Stand Alone Internal Functions
  486. ------------------------------
  487.    * Function: process-paper
  488.    Use this function on a paper that has been stored locally with
  489. `store-paper' (*note Storing Papers::.) to invoke the functions which
  490. determine the paper's format (*note Paper Formats::.) and execute
  491. processing accordingly.
  492.    For example, you have stored a particular paper with the local name
  493. `jones' earlier. `process-paper' will ask for the file name to be
  494. processed, `jones' in this case, then examine this file (or files) in
  495. `atv-download-dir' to determine its format. Having deduced this it
  496. takes appropriate action such as stripping appended PostScript figures,
  497. executing shell scripts, etc. For more details see *Note Paper
  498. Formats::, and *Note Example Sessions::.
  499.    * Function: slice-and-dice
  500.    `slice-and-dice' extracts appended PostScript figures from a file
  501. which is loaded in the current buffer. It will search for each occurance
  502. of `"^%!"' and strip the region between this line and the next `"^%!"'
  503. or the end of file. For each such region it pauses for the filename to
  504. be given to the figure, offering a default (in parenthesis) gathered
  505. from the comment area preceeding the PostScript signal.
  506.    * Function: shell-paper
  507.    This function is the one called when the retrieved paper is found to
  508. contain the regexp `"^#![ \t]*\\(.*/bin/.*\\)$"'. Everything below and
  509. including this line is extracted to a file `localname.sh' which is then
  510. executed by Emacs with `shell-command "(match) localname.sh"', where
  511. (match) is the executable shell name and path extracted from the file.
  512. Thus a variety of shells are supported, includng for instance, "Perl"
  513. scripts. A file `localname.rpt' is made which catches any standard
  514. output of the execution.
  515.    You can use this function on any buffer containing a non-interactive
  516. shell script, like a shar file sent to you in the mail. `shell-paper'
  517. strips the header and executes the shar file without leaving mail.
  518. Remember that the script is executed in `atv-download-dir'.
  519. Operating on Several Buffers in Emacs
  520. -------------------------------------
  521.    * Command: buffer-menu
  522.    See: *note Manipulating Several Buffers in Emacs: (emacs)Several
  523. Buffers.
  524.    The "buffer-menu" facility is like a "Dired for buffers"; it allows
  525. you to request operations on various Emacs buffers by editing an Emacs
  526. buffer containing a list of them.  You can save buffers, kill them
  527. (here called "deleting" them, for consistency with Dired), or display
  528. them.
  529.    Also the command `insert-buffer' is very useful for concatenating
  530. buffers of multifile papers.
  531.    * Command: insert-buffer FROM-BUFFER-OR-NAME
  532.    See: *note Inserting Whole Buffers: (elisp)Commands for Insertion.
  533. File: atavachron.info,  Node: Title Listings and Abstracts,  Next: Utilities,  Prev: Processing Functions,  Up: Functions
  534. Title Listings and Abstracts
  535. ============================
  536.    * Function: get-listing-from-data
  537.    * Function: store-listing-from-data
  538.    `get-listing-from-data' and `store-listing-from-data' work the same
  539. way, except on title listings. They prompt the user for the listing in
  540. the usual format: `hep-th/9204', then "get" (to a buffer), or "store"
  541. (to a file) the given month's listing.
  542.    Note that if the listing is gotten with `get-listing-from-data' into
  543. a buffer, then `get-paper' will work in that buffer as in the daily
  544. abstract list. Simply put the cursor on the paper of interest (*after*
  545. the line beginning with "Paper:" and type `(M-x:) get-paper'.
  546.    * Function: get-abstract
  547.    * Function: get-abstract-from-data
  548.    These two functions get abstracts to a new window and are useful in
  549. two situations mainly: use `get-abstract' when reading a monthly title
  550. listing where just the titles are given, to get the paper's abstract.
  551. `get-abstract-from-data' is handy to view the abstract of a reference
  552. for which you have the archive number.
  553. File: atavachron.info,  Node: Utilities,  Prev: Title Listings and Abstracts,  Up: Functions
  554. Utilities
  555. =========
  556.    * Function: interesting
  557.    This function is a tool for saving interesting abstracts to a file
  558. which can then be examined sometime later. It is used to avoid having
  559. to save the entire Mail abstract posting, and then later sifting
  560. through all abstracts. It can also be used to save abstracts to
  561. different files according to subject, etc.
  562.    When the point is placed in an abstract, type `M-x: interesting'.
  563. You are presented with the prompt to save the abstract to the default
  564. interesting file,
  565.      >>> Append to? (interesting.atv):
  566.    `[RETURN]' saves to the default, set by `atv-interesting-file'
  567. (*note atv-interesting-file::.), or you may enter another filename.
  568.    * Function: atavachron-mail
  569.    This handy function allows you to easily send a bug report, comment,
  570. or question to the author. It opens a mail buffer addressed to me ("Jim
  571. Hetrick)" and dumps the current values of all *Atavachron* variables,
  572. which can be used to reconstruct your situation. Please feel free to
  573. use this function any time you would like to contact me with questions,
  574. suggestions, or other correspondence.
  575. File: atavachron.info,  Node: Paper Formats,  Next: Example Sessions,  Prev: Functions,  Up: Top
  576. Paper Formats
  577. *************
  578.    The paper formats presently supported by the *Atavachron* version
  579. `1.1' are listed here with a brief desription of the action taken for
  580. each (see *Note Processing Functions::, for more). The paper's format
  581. is determined by listing all files which match the paper's number in
  582. the correct branch directory at the archive.
  583. Single TeX File
  584. ===============
  585.    If the paper is a single file and no "PostScript" signal or shell
  586. commands are found, the paper is renamed `localname.tex' upon transfer
  587. to a local buffer, and `tex-mode' is loaded. It is then ready for
  588. processing via the usual `tex-mode' facilities,
  589.      * `C-c C-b' for [La]TeXing,
  590.      * `C-c C-p' for printing,
  591.    or any other local tex or `auc-tex' features, such as previewing. If
  592. `atv-auto-tex-paper' is "t", [La]TeX is automatically started at this
  593. point.
  594. Single TeX File with Appended "PostScript" Figures
  595. ==================================================
  596.    A single paper file is first checked for any appended "PostScript"
  597. figures, which are then surgically removed to `.ps' files at the user's
  598. request (*note Processing Functions::.). The whole file is first saved
  599. though, with extension `.tpl'. The `slice-and-dice' function (which
  600. removes the figures) tries to find a name for the figure file from the
  601. comments near the top of the "PostScript" header.
  602.    With the advent of the bulletin board macro `uufiles' to package
  603. figures, data files, or other auxiliary files, the occurance of
  604. "all-in-one" papers will hopefully deminish.
  605. Shell Script
  606. ============
  607.    After checking for "PostScript" signs, the *Atavachron* checks for
  608. shell commands, in particular for `"#!.*/bin/"'. If this string is
  609. found, the region below `#!.*/bin/' is saved to a file `localname.sh'
  610. which is then executed (*note Processing Functions::.). A report of the
  611. execution (including any terminal output made by the script) is made
  612. and named `localname.rpt'.
  613. Tar File
  614. ========
  615.    If the archive paper is a tarfile, it is renamed `localname.tar.Z'
  616. and, upon confirmation, unpacked in `atv-download-dir'. A report of any
  617. output during the unpacking process is presented in the buffer
  618. `localname.rpt' which is then searched for a unique TeX file. If found
  619. this file is loaded to a buffer.
  620. Multiple Archive Files for a Paper
  621. ==================================
  622.    * UUENCODED Auxillary Files (Figures, Data, etc.)
  623.    When the *Atavachron* finds multiple files for a given paper, it
  624. first checks for the extention `.2' and if found, assumes sequential
  625. integer extensions for all files. The paper files `localname.2' through
  626. `localname.N' are copied and checked as to whether they are *uuencoded*
  627. files produced by Paul Ginsparg's preprint bulliten board macro
  628. `uufiles'. If so, they are *uudecoded*, ie.  their contents is unpacked
  629. in `atv-uufiles-dir'. The figure files should then be accessible to TeX
  630. and `dvips' via the paths specified in the environment variable
  631. TEXINPUTS and in the file `.dvipsrc' (see *note .dvipsrc::.). If `csh'
  632. is not available on your machine, you can set `atv-no-csh' to "t"
  633. (*note Configuration::.) and still unpack the uufiles.
  634.    A file named `localnameN.rpt' is produced in `atv-uufiles-dir' for
  635. each auxillary file, which records the output of the command `tar -xvf
  636. -' when unpacking (each of the N) uufiles. This file is then a manifest
  637. of figures/files included with this paper.
  638.    * NON-UUENCODED Files
  639.    If the extra archive files are not found to be *uufiles*, or they do
  640. not have sequential integer extensions, they are simply copied to
  641. separate Emacs buffers to be processed by hand. To facilitate this,
  642. `list-buffers' is called which lists all the buffers of the current
  643. session in "buffer-menu-mode" which makes working with several buffers
  644. much easier (*note Processing Functions::.).
  645.    Finally, `localname.1' is transfered and treated as the primary file
  646. of the paper. Thus it is assumed to be a TeX document (although tests
  647. for "PostScript" and shell commands are automatically done), and will
  648. either make use of the decoded uufiles, or hopefully contain
  649. instructions for manually processing the set of files displayed by
  650. `list-buffers'.
  651. Multiple Non-Integer Extensions
  652. ===============================
  653.    If multiple files with non-integer extensions are found or if the
  654. *Atavachron* is confused about the nature of the files on the remote
  655. archive, the files are stored directly on the user's system in
  656. `atv-download-dir'; these files will in general require conscious
  657. processing.
  658. File: atavachron.info,  Node: Example Sessions,  Next: Things To Come,  Prev: Paper Formats,  Up: Top
  659. Example Sessions
  660. ****************
  661.    This section shows some sample sessions of what should happen when
  662. getting specific papers of various formats. These are intended to
  663. illustrate the most common formats and certainly do not exaust the
  664. permutations of papers and functions. Below, `>>>' means that the
  665. following prompt or message appears in the mini-buffer.
  666. Example:  Single TeX File
  667. =========================
  668.    The point is located in the abstract of Witten's paper
  669. "hep-th/9204083". If `atv-prompt-filename' is "t", doing
  670.      M-x get-paper
  671.    asks:
  672.      >>>   Local name for paper? [.tex appended] (9204083):
  673.    Typing "witten", renames this paper to `witten.tex', while simply
  674. hitting `[RETURN]', preserves it's archive name and adds `.tex'
  675. yielding the buffer `9204083.tex'. Note that as an older paper it is
  676. compressed at the archive, so `9204083.Z' is transferred and
  677. uncompressed on the fly.
  678.    The file is gotten to a new window in `tex-mode'. Now typing `C-c
  679. C-b' ("Control and c" then "Control and b"), invokes TeX on the file,
  680. and `C-c C-p' prints it.
  681.    Thus in four simple of keystrokes, after reading the abstract in the
  682. mail, the paper is in the printer bin. This could even be reduced to a
  683. mouse click and the print command.
  684. Example:  TeX File with Appended "PostScript"
  685. =============================================
  686.    Reading a reference to the paper "hep-lat/9212017" we type:
  687.      M-x get-paper-from-data
  688.    the *Atavachron* asks:
  689.      >>>   Local name for paper? [.tex appended] (9212017):
  690.    We hit `[RETURN]' to accept the default name `9212017' and the paper
  691. is retrieved. We are notified of appended "PostScript" figures
  692.      >>>   Looks like there are appended PostScript figures...
  693.    then asked by the *Atavachron*
  694.      >>>   Shall I surgically remove the figures? (y or n)
  695.    Entering `y' gets the reply "`Entering slice and dice mode...'".
  696. First a backup is made called `9212017.tpl'. Then, upon demarking the
  697. first figure, the *Atavachron* asks
  698.      >>>   Name for figure file below this point? (bumpy-operator.ps):
  699.    Hitting `[RETURN]' accepts the default name `bumpy-operator.ps'
  700. which was found in the nearby comments. The "PostScript" figure
  701. `bumpy-operator.ps' is extracted; this process is repeated four times
  702. extracting each of the four appended figures. On the last figure the
  703. *Atavachron* asks:
  704.      >>>   Name for figure file below this point? (* NONE FOUND *):
  705.    Note the `* NONE FOUND *'; this is because of a typing error in the
  706. original paper file where the figure is labeled "binning-error.p", and
  707. the ".ps" search fails. In this case `binning-error.ps' (or some other
  708. name) *must* be entered at the above prompt by hand.
  709.    "Slice and dice" mode is now complete and the TeX portion of the
  710. original paper is returned, ready for `tex-mode' processing. In
  711. addition, a report of the figure extraction is made in the file
  712. `9212017.figs':
  713.       * -\|/- The Atavachron  (1.1) *
  714.      Below are the PostScript figures extracted from: 9212017.tex
  715.      -----------------------------------------------
  716.      bumpy-operator.ps
  717.      interpolation.ps
  718.      surface-energy.ps
  719.      binning-error.ps
  720. Example:  Storing and Processing a Paper (with *uuencoded* Figures)
  721. ===================================================================
  722.    While logged in from home, you read the abstract of Distler's paper
  723. "hep-th/9212062". You type:
  724.      M-x store-paper
  725.    with the point in the abstract. The *Atavachron* asks the usual:
  726.      >>>   Local name for paper? (9212062):
  727.    to which you enter `distler'. Two files are retrieved with the
  728. message: `Use "process-paper" on "distler" at your convenience..."'
  729.    The next morning you find the files `distler.1' and `distler.2'
  730. stored in your `atv-download-dir', thus you enter Emacs and do `M-x
  731. process-paper'. The response is
  732.      >>>   Name of stored paper? [without suffix]:
  733.    You enter `distler' and the *Atavachron* begins to process the
  734. paper. Since there are multiple files to this paper, the *Atavachron*
  735. checks for *uuencoded* figures. Finding them, it unpacks the figures
  736. into the `atv-uufiles-dir' where TeX and `dvips' can get at them.
  737. Finally it returns the TeX file of the paper in `tex-mode' and a
  738. manifest `distler2.rpt' of the uudecoding:
  739.       * -\|/- The Atavachron  (1.1) *
  740.      This is the output of: sh hep-th/9212062.2
  741.      Below should be a manifest of the enclosed files:
  742.      ------------------------------------------------
  743.      x grapha.eps, 3080 bytes, 7 media blocks.
  744.      x graphb.eps, 3080 bytes, 7 media blocks.
  745.      x fig.pro, 3089 bytes, 7 media blocks.
  746. File: atavachron.info,  Node: Things To Come,  Next: Index,  Prev: Example Sessions,  Up: Top
  747. Things To Come
  748. **************
  749.    * The first thing that should be done is clean the code a bit. *The
  750.      Atavachron* grew out of a 20 line `(defun get-paper ())' to teach
  751.      myself some Lisp, into the present package by Lamarkian evolution.
  752.      Certainly there are more efficient forms of various functions, and
  753.      many of the large modules could be broken down into reasonable
  754.      blocks.  Along these lines is a redefinition of the package as a
  755.      "semi-major mode" of some kind, instead of a non-linear collection
  756.      of functions.
  757.    * Improved error trapping; as `atavachron-mail' comes in, these will
  758.      be fixed. At present *The Atavachron* will crash if you don't give
  759.      an expected response, say `[RETURN]' when it really needs a string
  760.      input, however these seem to just abort without fatalities.
  761.    * At present the macro directories at the archives are ignored,
  762.      meaning you have to get macros via the usual routes of mail or
  763.      ftp.  A nice feature would be macro (ie. `\input' and
  764.      `\document{}') checking, by which *The Atavachron* would search
  765.      the gotten [La]TeX file for all auxillary files and macro packages
  766.      needed, check the path for these, then report and get the missing
  767.      macros.
  768.    * Finally, more consistent [La]TeX in preprint submissions will make
  769.      possible the assumption that the preprint will actually pass the
  770.      texxing stage, thereby making auto-previewing (at the click of the
  771.      mouse on an abstract), and similar futuristic fantasies possible.
  772.      This should be provided soon, along with auto-printing, as hook
  773.      functions for `atv-auto-tex-command' which sense the exit of the
  774.      TeX shell, and determine if it is safe to send the results to the
  775.      printer.
  776. File: atavachron.info,  Node: Index,  Prev: Things To Come,  Up: Top
  777. Concept Index
  778. *************
  779. * Menu:
  780. * atavachron.el:                        Top.
  781. * atavachron-mail:                      Utilities.
  782. * atv-download-dir:                     atv-download-dir.
  783. * atv-interesting-file:                 atv-interesting-file.
  784. * atv-main-ftp-site:                    atv-main-ftp-site.
  785. * atv-no-csh:                           atv-no-csh.
  786. * atv-prompt-filename:                  atv-prompt-filename.
  787. * atv-uufiles-dir:                      atv-uufiles-dir.
  788. * buffer-menu:                          Processing Functions.
  789. * dvips:                                atv-uufiles-dir.
  790. * get-abstract-from-data:               Title Listings and Abstracts.
  791. * get-abstract:                         Title Listings and Abstracts.
  792. * get-listing-from-data:                Title Listings and Abstracts.
  793. * get-paper-from-data:                  Getting Papers.
  794. * get-paper:                            Getting Papers.
  795. * insert-buffer:                        Processing Functions.
  796. * interesting:                          Utilities.
  797. * process-paper:                        Processing Functions.
  798. * shell-paper:                          Processing Functions.
  799. * slice-and-dice:                       Processing Functions.
  800. * store-listing-from-data:              Title Listings and Abstracts.
  801. * store-paper-from-data:                Storing Papers.
  802. * store-paper:                          Storing Papers.
  803. * Appended PostScript:                  Paper Formats.
  804. * Appended PostScript: Example:         Example Sessions.
  805. * archive.cis.ohio-state.edu:.../ange-ftp: ange-ftp.el.
  806. * Atavachron:                           General Description.
  807. * atv-auto-tex-paper:                   atv-auto-tex-paper.
  808. * Author's Address:                     General Description.
  809. * Auto-Previewing:                      Things To Come.
  810. * Auto-Previewing:                      atv-auto-tex-paper.
  811. * Bakker, Bas <bas@phys.uva.nl>:        General Description.
  812. * Bulletin Board Software:              General Description.
  813. * Configuration:                        Configuration.
  814. * Emacs Variables:                      Configuration.
  815. * Example .emacs File:                  Example .emacs File.
  816. * Example Sessions:                     Example Sessions.
  817. * Files Made by Macro uufiles:          Paper Formats.
  818. * Free Software Foundation:             Copying Conditions.
  819. * Functions:                            Functions.
  820. * General Description:                  General Description.
  821. * Getting Papers:                       Getting Papers.
  822. * Ginsparg, Paul <ginsparg@qfwfq.lanl.gov>: General Description.
  823. * GNU Emacs editor:                     Top.
  824. * GNU General Public License:           Copying Conditions.
  825. * Gough, Graham:                        zcat.el.
  826. * James Hetrick <hetrick@phys.uva.nl>:  Top.
  827. * Kilcup, Greg <kilcup@pacific.mps.ohio-state.edu>: General Description.
  828. * Loading atavachron.el:                Example .emacs File.
  829. * Local Branch Directories:             atv-download-dir.
  830. * Marcus Speh <marcus@x4u.desy.de>:     Top.
  831. * Mini-buffer:                          General Description.
  832. * Modem File Transfer:                  Storing Papers.
  833. * Multiple Files:                       Paper Formats.
  834. * Non-Integer Extensions:               Paper Formats.
  835. * Norman, Andy:                         ange-ftp.el.
  836. * Obtaining the *Atavachron* Package:   Copying Conditions.
  837. * Paper Formats:                        Paper Formats.
  838. * Paper in Multiple Files:              Processing Functions.
  839. * Primary File:                         Paper Formats.
  840. * Primary File:                         atv-auto-tex-paper.
  841. * Processing Functions:                 Processing Functions.
  842. * Processing Paper: Example:            Example Sessions.
  843. * Reading abstracts in Mail:            Getting Papers.
  844. * Several Buffers:                      Processing Functions.
  845. * Shell Scripts:                        Paper Formats.
  846. * Since TeX file:                       Paper Formats.
  847. * Single TeX file: Example:             Example Sessions.
  848. * Speh, Marcus <marcus@x4u.desy.de>:    General Description.
  849. * Star Trek:                            General Description.
  850. * Storing Paper: Example:               Example Sessions.
  851. * Storing Papers:                       Storing Papers.
  852. * Supported Archives:                   General Description.
  853. * Tar Files:                            Paper Formats.
  854. * Texinfo:                              General Description.
  855. * TEXINPUTS Environment Variable:       atv-download-dir.
  856. * Things to Come:                       Things To Come.
  857. * Title Listings and Abstracts:         Title Listings and Abstracts.
  858. * Utilities:                            Utilities.
  859. * UUfiles:                              Paper Formats.
  860. * UUfiles:                              Paper Formats.
  861. * UUfiles: Example:                     Example Sessions.
  862. * Wish List:                            Things To Come.
  863. Tag Table:
  864. Node: Top
  865. Node: Copying Conditions
  866. Node: General Description
  867. Node: Configuration
  868. Node: Example .emacs File
  869. Node: atv-main-ftp-site
  870. 10984
  871. Node: atv-download-dir
  872. 11756
  873. Node: atv-uufiles-dir
  874. 13365
  875. Node: atv-prompt-filename
  876. 13944
  877. Node: atv-interesting-file
  878. 14628
  879. Node: atv-auto-tex-paper
  880. 15370
  881. Node: atv-no-csh
  882. 16756
  883. Node: Batteries Not Included
  884. 17472
  885. Node: ange-ftp.el
  886. 18136
  887. Node: zcat.el
  888. 18735
  889. Node: .netrc
  890. 19184
  891. Node: .dvipsrc
  892. 20326
  893. Node: Functions
  894. 21480
  895. Node: Getting Papers
  896. 22008
  897. Node: Storing Papers
  898. 24087
  899. Node: Processing Functions
  900. 24776
  901. Node: Title Listings and Abstracts
  902. 28135
  903. Node: Utilities
  904. 29313
  905. Node: Paper Formats
  906. 30529
  907. Node: Example Sessions
  908. 35148
  909. Node: Things To Come
  910. 39842
  911. Node: Index
  912. 41698
  913. End Tag Table
  914.