home *** CD-ROM | disk | FTP | other *** search
/ Big Green CD 8 / BGCD_8_Dev.iso / OPENSTEP / Languages / Python / python-14-src / Doc / README < prev    next >
Encoding:
Text File  |  1997-01-17  |  4.2 KB  |  105 lines
  1. Python main documentation -- in LaTeX
  2. -------------------------------------
  3.  
  4. This directory contains the LaTeX sources to the Python documentation
  5. and a published article about Python.
  6.  
  7. The Python Reference Manual is no longer maintained in LaTeX.  It is
  8. now a FrameMaker document.  The FrameMaker 5.0 files (ref.book,
  9. ref*.doc) as well as PostScript generated (ref.ps) from it are in the
  10. subdirectory ref/.
  11.  
  12. If you don't have LaTeX, you can ftp a tar file containing PostScript
  13. of the 3 main documents.  It should be in the same place where you
  14. fetched the main Python distribution, in a file named
  15. "pythondoc-ps<version>.tar.gz".  (See "../Misc/FAQ" for more
  16. information about ftp-ing Python files.)
  17.  
  18. The following are the LaTeX source files:
  19.  
  20.     tut.tex                The tutorial
  21.     lib.tex, lib*.tex        The library reference
  22.     ext.tex                How to extend Python
  23.     qua.tex, quabib.bib        Article published in CWI Quarterly
  24.  
  25. All except qua.tex (which isn't built by the default target) use the
  26. style option file "myformat.sty".  This contains some macro
  27. definitions and sets some style parameters.
  28.  
  29. You need the makeindex utility to produce the index for lib.tex; you
  30. need bibtex to produce the references list for qua.tex.
  31.  
  32. There's a Makefile to call LaTeX and the other utilities in the right
  33. order and the right number of times.  This will produce DVI files for
  34. each document made; to preview them, use xdvi.  PostScript is produced
  35. by the same Makefile target that produces the DVI files.  This uses
  36. the dvips tool.  Printing depends on local conventions; at my site, I
  37. use lp.  For example:
  38.  
  39.     make lib            # create lib.dvi and lib.ps
  40.     xdvi lib            # preview lib.dvi
  41.     lp lib.ps            # print on default printer
  42.  
  43.  
  44. Making HTML files
  45. -----------------
  46.  
  47. The Tutorial and Extensions manual can be converted to HTML using
  48. Nikos Drakos' LaTeX2HTML converter.  See the Makefile; after some
  49. twiddling, "make l2h" should do the trick.
  50.  
  51. The Library manual doesn't work well with LaTeX2HTML; instead, there's
  52. a Python script texi2html.py in this directory that can be run on the
  53. texinfo generated as an intermediate step for generating the INFO
  54. files as described in the next section.  The command "make libwww"
  55. should do this.
  56.  
  57.  
  58. Making the INFO version of the Library Reference
  59. ------------------------------------------------
  60.  
  61. The Library Reference can also be read in hypertext form using the
  62. Emacs INFO system.  This uses Texinfo format as an intermediate step.
  63. It requires texinfo version 2 (we have used 2.14).
  64.  
  65. To build the info files (python-lib.info*), say "make lib.info".  This
  66. takes a while, even on a machine with a 100 MHz clock and 64 Mbytes of
  67. RAM :-).  Please ignore the output, which appears like error messages
  68. but really is debugging output only.
  69.  
  70. You may have to change a site dependency in fix.el: if texinfo 2.xx
  71. isn't installed by default at your site, you'll have to install it
  72. (use archie to locate a version and ftp to fetch it).  If you can't
  73. install it in the standard Emacs load path, uncomment the line
  74. containing a "(setq load-path ...)" statement, and fill in the path
  75. where you put it.
  76.  
  77. The files used by the conversion process are:
  78.  
  79. partparse.py            Python script that converts LaTeX sources to
  80.             texi files.
  81.  
  82. texi{pre,post}.dat      Files placed before and after the result.
  83.  
  84. fix.el                  Elisp file executed by Emacs. Two calls to
  85.                         'texinfo-all-menus-update are necessary in
  86.             some cases.
  87.  
  88. fix_hack        Shell script to fix the results of the
  89.                         "underscore hack". {\ptt \char'137} is
  90.                         back-translated to a simple underscore.  This
  91.                         is needed for the texindex program.
  92.  
  93. whichlibs        Shell script to print a list of lib*.tex files
  94.             to be processed.
  95.  
  96. Thanks for Jan-Hein B\"uhrman for writing and debugging the convertor
  97. and related scripts, and for fixing the LaTeX sources and writing new
  98. macros for myformat.sty!  More thanks to Dave Ascher for adapting
  99. myformat.sty to the new LaTeX release, to Fred Drake for revamping the
  100. partparse.py and texi2html.py scripts, to the many anonymous authors
  101. of library manual sections and corrections (too many to mention).
  102.  
  103. Many thanks to Robin Friedrich for the conversion of the Reference
  104. Manual to FrameMaker and his work on its index.
  105.