[Docutils-checkins] sandbox/dkuhlman/Docs rstpythonlatex_intro.txt,NONE,1.1 pythonlatex_intro.rst,1.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Update of /cvsroot/docutils/sandbox/dkuhlman/Docs
In directory sc8-pr-cvs1:/tmp/cvs-serv15806/Docs

Added Files:
	rstpythonlatex_intro.txt 
Removed Files:
	pythonlatex_intro.rst 
Log Message:
Replaced and added python_latex intro doc

--- NEW FILE: rstpythonlatex_intro.txt ---

:author: Dave Kuhlman
:revision: 1.0a
:date: July 1, 2003

:copyright: Copyright (c) 2003 Dave Kuhlman 
    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the "Software"), to deal in the Software without
    restriction, including without limitation the rights to use, copy,
    modify, merge, publish, distribute, sublicense, and/or sell copies
    of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions: 
    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software. 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE. 

:abstract: This document describes a Docutils writer for use with
    Python LaTeX and the Python project's documentation tools.

==============================================
Introduction to the Documenting Python Writer
==============================================

-------------
What It Does
-------------

This writer for Docutils generates LaTeX suitable for
input to the documentation system described in `Documenting
Python`_

.. _`Documenting Python`: http://www.python.org/dev/doc/devel/doc/doc.html

---------------
Where to Get It
---------------

This writer is not yet part of the Docutils distribution.  Until
it is, you can find it at
`"A Docutils writer for the Documenting Python system"`_.

.. _`"A Docutils writer for the Documenting Python system"`:
    http://www.rexx.com/~dkuhlman/#docutils_pythonlatex

--------------
How to Use It
--------------

Conversion has several steps:

1.  Run the writer -- Run *documenting_python.py* in
    *docutils/tools*, for example::

       $ docutils/tools/python_latex.py --documentclass=howto rstpythonlatex_intro.txt

    There is one option:

    --documentclass=class 

        Selects the template type from Doc/templates in the Python
        source distribution. Possible values are ``howto``,
        ``manual``, and ``module``. The ``module`` document type is
        not yet implemented. See the Doc/templates subdirectory in the
        Python Source code distribution for samples of these document
        types.  

    .. ("module" too, according to the writer's settings_spec.  Or should
       "module" be removed from the writer?)

2.  Run the "Documenting Python" document processor.

Here is a Makefile that performs these two steps.  It was used to
convert the document that you are currently reading::

    # Makefile to process a file LaTeX with the Python LaTeX system.
    #  Optionally processes reStructuredText files.

    #
    # Change the following to point to your Python source code.
    #
    PYTHON_SRC = /w1/Python/Python-2.3b2
    DOCUTILS_DIR = /w1/Python/DocUtils/docutils

    #
    # Change the following to point to your Docutils installation.
    #
    DOCUTILSTOOLS_DIR = $(DOCUTILS_DIR)/tools
    TRANSFORMDOCPY = $(DOCUTILSTOOLS_DIR)/python_latex.py \
    	--documentclass=howto

    #
    # Change these flags for your purposes.
    #
    #HTMLFLAGS= --image-type png --html -s 1 --favicon ../icons/pyfav.gif
    HTMLFLAGS= --iconserver ../icons --html -s 1 --favicon ../icons/pyfav.gif

    MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto

    PAPER = a4

    #
    # Change this to the name of your source file (without extension).
    #
    #SRC_NAME=zip-ls
    ifndef SRC_NAME
    $(error Must define SRC_NAME (no extension), e.g. make SRC_NAME=mysourcefile)
    endif

    TARGETS = $(SRC_NAME)/$(SRC_NAME).html

    FIGURES = 

    all:	html

    html:	$(TARGETS) $(FIGURES)

    $(SRC_NAME)/$(SRC_NAME).html: $(SRC_NAME).tex
    	$(MKHOWTO) $(HTMLFLAGS) $(SRC_NAME).tex

    #
    # Remove or Comment out the following lines if your source file
    #   is a LaTeX file not a reST file.
    #
    $(SRC_NAME).tex: $(SRC_NAME).txt
    	$(TRANSFORMDOCPY) $(SRC_NAME).txt > $(SRC_NAME).tex

    clean:
    	rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \
    *.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi
    	-rm -f $(SRC_NAME).tex
    	-rm -f $(SRC_NAME)/*
    	-rmdir $(SRC_NAME)
    	-rm -f $(SRC_NAME).tex

Run this Makefile with the following commands::

    $ make SRC_NAME=rstpythonlatex_intro clean
    $ make SRC_NAME=rstpythonlatex_intro

------------------------------
Special Formatting Constructs
------------------------------

See the companion document 'Quick reStructuredText for
"Documenting Python"' for additional mark-up that can be used when
generating LaTeX for "Documenting Python".  It is included in the
distribution file for this writer.

The first section of that document has information specific to the
generation of LaTeX for Documenting Python.

In addition, that document also adds another column to the
specification tables.  This additional column describes the LaTeX
commands generated by this writer.

-----------------
Acknowledgements
-----------------

Thanks to the Docutils project members for Docutils.  In
particular, thanks to project coordinator David Goodger.

Thanks to Engelbert Gruber for the implementation of the LaTeX
writer.  That implementation formed the starting point for this
writer.  He should get much of the credit for this writer also,
however, any bugs were likely introduced by me.

Thanks to Fred Drake (and many more I'm sure) for the Python
documentation tools, the Python documentation project, and the
Python documentation itself.

---------
See Also
---------

`The Docutils Home Page`_

.. _`The Docutils Home Page`: http://docutils.sourceforge.net/

`The Python home page`_

.. _`The Python home page`: http://www.python.org/ 

`The documentation on the Documenting Python system`_

.. _`The documentation on the Documenting Python system`:
    http://www.python.org/dev/doc/devel/doc/doc.html

`"A Docutils writer for the Documenting Python system"`_

.. _`"A Docutils writer for the Documenting Python system"`:
    http://www.rexx.com/~dkuhlman/#docutils_pythonlatex

--- pythonlatex_intro.rst DELETED ---

[Docutils-checkins] sandbox/dkuhlman/Docs rstpythonlatex_intro.txt,NONE,1.1 pythonlatex_intro.rst,1.

[Docutils-checkins] sandbox/dkuhlman/Docs rstpythonlatex_intro.txt,NONE,1.1 pythonlatex_intro.rst,1.1,NONE