NB This is an archive of Jesper Harder's dpans2texi script, available
under the GPLv2; the original site has disappeared.


                                 dpans2texi.el

   dpans2texi.el converts the TeX sources of the draft ANSI Common Lisp
   standard (dpANS) to the [2]Texinfo format.

   The purpose is to take advantage of the superior qualities of the Info
   reader in Emacs compared with other formats, viz.
     * Single-key index lookup with completion: i.
     * Single-key full text regexp search: s
     * Convenient symbol lookup from source code: C-h C-i

   There are [3]various existing ways to do the latter, though, by
   opening a web browser at the right spot in the [4]Common Lisp
   HyperSpec. But this means leaving Emacs ... a Bad Thing(TM).

   Some of the information conveyed by the selection of fonts in the
   hard-copy version is lost in the translation to Texinfo. I've also
   made frivolous use of Unicode characters to represent various glyphs
   -- you might need to [5]supplement your fontset to avoid empty boxes
   in Emacs.

   As a side effect of using Texinfo, you can in principle also
   produce a variety of other formats.  Unfortunately, the temp.texi
   file generated by dpans2texi.el is somewhat malformed and causes
   makeinfo to spit warnings and puke errors, which percolate down to
   cause, eg, texi2dvi to choke.

   I won't distribute the converted files, as the draft doesn't grant me
   permission to do so. So, you need to run the converter on the original
   TeX files yourself.

   Caveat: The translation may have introduced errors, please report
   discrepancies with the hard-copy version.  You can take a stab at
   fixing them yourself by removing the "--no-warn --force" flags in
   the Makefile, which will show quite a screenful of problems with
   the generated temp.texi.

   Q: Why didn't you just use Bill Schelter's [8]Texinfo rendition?
   A: Good question! I didn't learn about it until I had finished most of
   my converter, so I might as well do the rest. I think my version is a
   bit more polished (I also had the advantage of some handy new Texinfo
   commands introduced since 1994). Besides, having a converter means
   that it's fairly easy to customize aspects of the conversion to your
   preference.

  Installation

     * You need Texinfo 4.7 (released 10-04-2004) or later.  Some
       distributions may separate out makeinfo and install-info, you
       need those too.
     * A reasonably recent version of Emacs.
     * Get dpans2texi-1.03.tar.gz and unpack the tarball.
     * Run make wget to download the .tex files with wget (or download
       them directly from [10]web.archive.org/web/*/quimby.gnus.org/circus/cl/dpANS3
       and [11]web.archive.org/web/*/quimby.gnus.org/circus/cl/dpANS3R
       to the same directory).
     * Build the info files with make, and finally install them in your
       Info directory with make install (INFO_DIR may be set to install
       somewhere specific).
     * To use C-h C-i in Lisp mode to look up the symbol at point in the
       spec, add the following to your .emacs file:
   (require 'info-look)
   (info-lookup-add-help
    :mode 'lisp-mode
    :regexp "[^][()'\" \t\n]+"
    :ignore-case t
    :doc-spec '(("(ansicl)Symbol Index" nil nil nil)))
     * Run "FMT=foo make ansicl.foo" if you want a FOO version where
       foo ∈ (docbook, html, epub3, latex, plaintext, xml, dvi,
       dvipdf, ps, pdf).

  Problems

   Bugs in Texinfo and Emacs rather than the converter as such:
     * Backreferences from the list of figures are broken in Info.
     * makeinfo crashes on the XML, Docbook and HTML targets on Mac OS X.
     * makeinfo (7.0.3) on OpenSuse Tumbleweed crashes on HTML and
       Epub3 targets on with "realloc(): invalid next size".
     * Emacs on Mac OS X doesn't display all characters even though the
       font does contain them.
   Bugs in dpans2texi.el:
     * When not suppressed, makeinfo prints a LOT of warnings and
       three errors from temp.texi, which are likely the cause of
       broken backreferences and conversion failures.

References

   2. http://texinfo.org/
   3. http://www.cliki.net/CLHS
   4. http://www.lispworks.com/reference/HyperSpec/Front/index.htm
   5. http://www.gnu.org/software/emacs/manual/html_node/International.html
   8. ftp://ftp.ma.utexas.edu/pub/gcl/gcl-info+texi.tgz
  10. https://web.archive.org/web/20160603133923/http://quimby.gnus.org/circus/cl/dpANS3/
  11. https://web.archive.org/web/20160603133923/http://quimby.gnus.org/circus/cl/dpANS3R/