sandbox/dkuhlman/Docs/rstpythonlatex_intro.txt

   1
   2 :author: Dave Kuhlman
   3 :revision: 1.0a
   4 :date: July 1, 2003
   5
   6 :copyright: Copyright (c) 2003 Dave Kuhlman
   7     Permission is hereby granted, free of charge, to any person
   8     obtaining a copy of this software and associated documentation
   9     files (the "Software"), to deal in the Software without
  10     restriction, including without limitation the rights to use, copy,
  11     modify, merge, publish, distribute, sublicense, and/or sell copies
  12     of the Software, and to permit persons to whom the Software is
  13     furnished to do so, subject to the following conditions:
  14     The above copyright notice and this permission notice shall be
  15     included in all copies or substantial portions of the Software.
  16     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  20     HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  21     WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  23     DEALINGS IN THE SOFTWARE.
  24
  25 :abstract: This document describes a Docutils writer for use with
  26     Python LaTeX and the Python project's documentation tools.
  27
  28
  29 ==============================================
  30 Introduction to the Documenting Python Writer
  31 ==============================================
  32
  33
  34 -------------
  35 What It Does
  36 -------------
  37
  38 This writer for Docutils generates LaTeX suitable for
  39 input to the documentation system described in `Documenting
  40 Python`_
  41
  42 .. _`Documenting Python`: http://www.python.org/dev/doc/devel/doc/doc.html
  43
  44
  45 ---------------
  46 Where to Get It
  47 ---------------
  48
  49 This writer is not yet part of the Docutils distribution.  Until
  50 it is, you can find it at
  51 `"A Docutils writer for the Documenting Python system"`_.
  52
  53 .. _`"A Docutils writer for the Documenting Python system"`:
  54     http://www.rexx.com/~dkuhlman/#docutils_pythonlatex
  55
  56
  57 --------------
  58 How to Use It
  59 --------------
  60
  61 Conversion has several steps:
  62
  63 1.  Run the writer -- Run *documenting_python.py* in
  64     *docutils/tools*, for example::
  65
  66        $ docutils/tools/python_latex.py --documentclass=howto rstpythonlatex_intro.txt
  67
  68     There is one option:
  69
  70
  71     --documentclass=class
  72
  73         Selects the template type from Doc/templates in the Python
  74         source distribution. Possible values are ``howto``,
  75         ``manual``, and ``module``. The ``module`` document type is
  76         not yet implemented. See the Doc/templates subdirectory in the
  77         Python Source code distribution for samples of these document
  78         types.
  79
  80     .. ("module" too, according to the writer's settings_spec.  Or should
  81        "module" be removed from the writer?)
  82
  83 2.  Run the "Documenting Python" document processor.
  84
  85
  86 Here is a Makefile that performs these two steps.  It was used to
  87 convert the document that you are currently reading::
  88
  89     # Makefile to process a file LaTeX with the Python LaTeX system.
  90     #  Optionally processes reStructuredText files.
  91
  92     #
  93     # Change the following to point to your Python source code.
  94     #
  95     PYTHON_SRC = /w1/Python/Python-2.3b2
  96     DOCUTILS_DIR = /w1/Python/DocUtils/docutils
  97
  98     #
  99     # Change the following to point to your Docutils installation.
 100     #
 101     DOCUTILSTOOLS_DIR = $(DOCUTILS_DIR)/tools
 102     TRANSFORMDOCPY = $(DOCUTILSTOOLS_DIR)/python_latex.py \
 103         --documentclass=howto
 104
 105     #
 106     # Change these flags for your purposes.
 107     #
 108     #HTMLFLAGS= --image-type png --html -s 1 --favicon ../icons/pyfav.gif
 109     HTMLFLAGS= --iconserver ../icons --html -s 1 --favicon ../icons/pyfav.gif
 110
 111     MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto
 112
 113     PAPER = a4
 114
 115     #
 116     # Change this to the name of your source file (without extension).
 117     #
 118     #SRC_NAME=zip-ls
 119     ifndef SRC_NAME
 120     $(error Must define SRC_NAME (no extension), e.g. make SRC_NAME=mysourcefile)
 121     endif
 122
 123     TARGETS = $(SRC_NAME)/$(SRC_NAME).html
 124
 125     FIGURES =
 126
 127     all:        html
 128
 129     html:       $(TARGETS) $(FIGURES)
 130
 131     $(SRC_NAME)/$(SRC_NAME).html: $(SRC_NAME).tex
 132         $(MKHOWTO) $(HTMLFLAGS) $(SRC_NAME).tex
 133
 134     #
 135     # Remove or Comment out the following lines if your source file
 136     #   is a LaTeX file not a reST file.
 137     #
 138     $(SRC_NAME).tex: $(SRC_NAME).txt
 139         $(TRANSFORMDOCPY) $(SRC_NAME).txt > $(SRC_NAME).tex
 140
 141     clean:
 142         rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \
 143     *.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi
 144         -rm -f $(SRC_NAME).tex
 145         -rm -f $(SRC_NAME)/*
 146         -rmdir $(SRC_NAME)
 147         -rm -f $(SRC_NAME).tex
 148
 149
 150 Run this Makefile with the following commands::
 151
 152     $ make SRC_NAME=rstpythonlatex_intro clean
 153     $ make SRC_NAME=rstpythonlatex_intro
 154
 155
 156
 157
 158 ------------------------------
 159 Special Formatting Constructs
 160 ------------------------------
 161
 162 See the companion document 'Quick reStructuredText for
 163 "Documenting Python"' for additional mark-up that can be used when
 164 generating LaTeX for "Documenting Python".  It is included in the
 165 distribution file for this writer.
 166
 167 The first section of that document has information specific to the
 168 generation of LaTeX for Documenting Python.
 169
 170 In addition, that document also adds another column to the
 171 specification tables.  This additional column describes the LaTeX
 172 commands generated by this writer.
 173
 174
 175 -----------------
 176 Acknowledgements
 177 -----------------
 178
 179 Thanks to the Docutils project members for Docutils.  In
 180 particular, thanks to project coordinator David Goodger.
 181
 182 Thanks to Engelbert Gruber for the implementation of the LaTeX
 183 writer.  That implementation formed the starting point for this
 184 writer.  He should get much of the credit for this writer also,
 185 however, any bugs were likely introduced by me.
 186
 187 Thanks to Fred Drake (and many more I'm sure) for the Python
 188 documentation tools, the Python documentation project, and the
 189 Python documentation itself.
 190
 191 ---------
 192 See Also
 193 ---------
 194
 195 `The Docutils Home Page`_
 196
 197 .. _`The Docutils Home Page`: http://docutils.sourceforge.net/
 198
 199
 200 `The Python home page`_
 201
 202 .. _`The Python home page`: http://www.python.org/
 203
 204
 205 `The documentation on the Documenting Python system`_
 206
 207 .. _`The documentation on the Documenting Python system`:
 208     http://www.python.org/dev/doc/devel/doc/doc.html
 209
 210 `"A Docutils writer for the Documenting Python system"`_
 211
 212 .. _`"A Docutils writer for the Documenting Python system"`:
 213     http://www.rexx.com/~dkuhlman/#docutils_pythonlatex
 214
 215