path: root/sandbox/grubert/test/README.txt.tex.ref

\documentclass[a4paper]{article}
% generated by Docutils <http://docutils.sourceforge.net/>
\usepackage{fixltx2e} % LaTeX patches, \textsubscript
\usepackage{cmap} % fix search and cut-and-paste in Acrobat
\usepackage{ifthen}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\setcounter{secnumdepth}{0}
\usepackage{tabularx}

%%% Custom LaTeX preamble
% PDF Standard Fonts
\usepackage{mathptmx} % Times
\usepackage[scaled=.90]{helvet}
\usepackage{courier}

%%% User specified packages and stylesheets

%%% Fallback definitions for Docutils-specific commands

% providelength (provide a length variable and set default, if it is new)
\providecommand*{\DUprovidelength}[2]{
  \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
}

% docinfo (width of docinfo table)
\DUprovidelength{\DUdocinfowidth}{0.9\linewidth}
% numeric or symbol footnotes with hyperlinks
\providecommand*{\DUfootnotemark}[3]{%
  \raisebox{1em}{\hypertarget{#1}{}}%
  \hyperlink{#2}{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
  \begingroup%
  \renewcommand{\thefootnote}{%
    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
    \protect\hyperlink{#2}{#3}}%
  \footnotetext{#4}%
  \endgroup%
}

% hyperlinks:
\ifthenelse{\isundefined{\hypersetup}}{
  \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
}{}
\hypersetup{
  pdftitle={README: Docutils},
  pdfauthor={David Goodger}
}

%%% Title Data
\title{\phantomsection%
  README: Docutils%
  \label{readme-docutils}}
\author{}
\date{}

%%% Body
\begin{document}
\maketitle

% Docinfo
\begin{center}
\begin{tabularx}{\DUdocinfowidth}{lX}
\textbf{Author}: &
	David Goodger \\
\textbf{Contact}: &
	\href{mailto:goodger@users.sourceforge.net}{goodger@users.sourceforge.net} \\
\textbf{Date}: &
	2003-08-16 \\
\textbf{Web site}: &
\url{http://docutils.sourceforge.net/}
\\
\textbf{Copyright}: &
	This document has been placed in the public domain. \\
\end{tabularx}
\end{center}

\phantomsection\label{contents}
\pdfbookmark[1]{Contents}{contents}
\tableofcontents


Thank you for downloading the Python Docutils project archive.  As
this is a work in progress, please check the project website for
updated working files (snapshots).  This project should be considered
highly experimental; APIs are subject to change at any time.


\section{Quick-Start%
  \label{quick-start}%
}

This is for those who want to get up \& running quickly.  Read on for
complete details.
\newcounter{listcnt0}
\begin{list}{\arabic{listcnt0}.}
{
\usecounter{listcnt0}
\setlength{\rightmargin}{\leftmargin}
}

\item Get and install the latest release of Python, available from
%
\begin{quote}

\url{http://www.python.org/}

\end{quote}

Python 2.2 or later\DUfootnotemark{id1}{py21}{1} is required; Python 2.2.2 or later is
recommended.

\item Use the latest Docutils code.  Get the code from CVS or from the
snapshot:
%
\begin{quote}

\url{http://docutils.sf.net/docutils-snapshot.tgz}

\end{quote}

See \hyperref[releases-snapshots]{Releases \& Snapshots} below for details.

\item Unpack the tarball in a temporary directory (\textbf{not} directly in
Python's \texttt{site-packages}) and install with the standard
%
\begin{quote}{\ttfamily \raggedright \noindent
python~setup.py~install
}
\end{quote}

See \hyperref[installation]{Installation} below for details.

\item Use a front-end tool from the \textquotedbl{}tools\textquotedbl{} subdirectory of the same
directory as in step 3.  For example:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~tools\\
html.py~test.txt~test.html
}
\end{quote}

See \hyperref[usage]{Usage} below for details.
\end{list}


\section{Purpose%
  \label{purpose}%
}

The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX.  Support for the following sources has been implemented:
%
\begin{itemize}

\item Standalone files.

\item \href{http://www.python.org/peps/pep-0012.html}{PEPs (Python Enhancement Proposals)}.

\end{itemize}

Support for the following sources is planned:
%
\begin{itemize}

\item Inline documentation from Python modules and packages, extracted
with namespace context.  \textbf{This is the focus of the current
development effort.}

\item Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).

\item Wikis, with global reference lookups of \textquotedbl{}wiki links\textquotedbl{}.

\item Compound documents, such as multiple chapter files merged into a
book.

\item And others as discovered.

\end{itemize}


\section{Releases \& Snapshots%
  \label{releases-snapshots}%
}

Putting together an official \textquotedbl{}Release\textquotedbl{} of Docutils is a significant
effort, so it isn't done that often.  In the meantime, the CVS
snapshots always contain the latest code and documentation, usually
updated within an hour of changes being committed to the repository,
and usually bug-free:
%
\begin{itemize}

\item Snapshot of Docutils code, front-end tools, tests, documentation,
and specifications: \url{http://docutils.sf.net/docutils-snapshot.tgz}

\item Snapshot of the Sandbox (experimental, contributed code):
\url{http://docutils.sf.net/docutils-sandbox-snapshot.tgz}

\item Snapshot of web files (the files that generate the web site):
\url{http://docutils.sf.net/docutils-web-snapshot.tgz}

\end{itemize}

To keep up to date on the latest developments, download fresh copies
of the snapshots regularly.  New functionality is being added weekly,
sometimes daily.  (There's also the CVS repository, and a mailing list
for CVS messages.  See the web site {[}address above{]} or spec/notes.txt
for details.)


\section{Requirements%
  \label{requirements}%
}

To run the code, Python 2.2 or later\DUfootnotemark{id2}{py21}{1} must already be
installed.  The latest release is recommended (2.2.2 as of this
writing).  Python is available from \url{http://www.python.org/}.
%
\DUfootnotetext{py21}{id1}{1}{\phantomsection\label{py21}%
Python 2.1 may be used providing the compiler package is
installed.  The compiler package can be found in the Tools/
directory of Python 2.1's source distribution.
}


\section{Project Files \& Directories%
  \label{project-files-directories}%
}
%
\begin{itemize}

\item README.txt: You're reading it.

\item COPYING.txt: Public Domain Dedication and copyright details for
non-public-domain files (most are PD).

\item FAQ.txt: Docutils Frequently Asked Questions.

\item HISTORY.txt: Release notes for the current and previous project
releases.

\item setup.py: Installation script.  See \textquotedbl{}Installation\textquotedbl{} below.

\item install.py: Quick \& dirty installation script.  Just run it.

\item docutils: The project source directory, installed as a Python
package.

\item extras: Directory for third-party modules that Docutils depends on.
These are only installed if they're not already present.

\item docs: The project user documentation directory.  Contains the
following documents:
%
\begin{itemize}

\item docs/tools.txt: Docutils Front-End Tools

\item docs/latex.txt: Docutils LaTeX Writer

\item docs/rst/quickstart.txt: A ReStructuredText Primer

\item docs/rst/quickref.html: Quick reStructuredText (HTML only)

\end{itemize}

\item licenses: Directory containing copies of license files for
non-public-domain files.

\item spec: The project specification directory.  Contains PEPs (Python
Enhancement Proposals), XML DTDs (document type definitions), and
other documents.  The \texttt{spec/rst} directory contains the
reStructuredText specification.  The \texttt{spec/howto} directory
contains How-To documents for developers.

\item tools: Directory for Docutils front-end tools.  See docs/tools.txt
for documentation.

\item test: Unit tests.  Not required to use the software, but very useful
if you're planning to modify it.  See \hyperref[running-the-test-suite]{Running the Test Suite}
below.

\end{itemize}


\section{Installation%
  \label{installation}%
}

The first step is to expand the \texttt{.tar.gz} or \texttt{.tgz} archive in a
temporary directory (\textbf{not} directly in Python's \texttt{site-packages}).
It contains a distutils setup file \textquotedbl{}setup.py\textquotedbl{}.  OS-specific
installation instructions follow.


\subsection{GNU/Linux, BSDs, Unix, Mac OS X, etc.%
  \label{gnu-linux-bsds-unix-mac-os-x-etc}%
}
\setcounter{listcnt0}{0}
\begin{list}{\arabic{listcnt0}.}
{
\usecounter{listcnt0}
\setlength{\rightmargin}{\leftmargin}
}

\item Open a shell.

\item Go to the directory created by expanding the archive:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~<archive\_directory\_path>
}
\end{quote}

\item Install the package:
%
\begin{quote}{\ttfamily \raggedright \noindent
python~setup.py~install
}
\end{quote}

If the python executable isn't on your path, you'll have to specify
the complete path, such as /usr/local/bin/python.  You may need
root permissions to complete this step.
\end{list}

You can also just run install.py; it does the same thing.


\subsection{Windows%
  \label{windows}%
}
\setcounter{listcnt0}{0}
\begin{list}{\arabic{listcnt0}.}
{
\usecounter{listcnt0}
\setlength{\rightmargin}{\leftmargin}
}

\item Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
calling it these days).

\item Go to the directory created by expanding the archive:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~<archive\_directory\_path>
}
\end{quote}

\item Install the package:
%
\begin{quote}{\ttfamily \raggedright \noindent
<path\_to\_python.exe>\textbackslash{}python~setup.py~install
}
\end{quote}
\end{list}

If your system is set up to run Python when you double-click on .py
files, you can run install.py to do the same as the above.


\subsection{Mac OS 8/9%
  \label{mac-os-8-9}%
}
\setcounter{listcnt0}{0}
\begin{list}{\arabic{listcnt0}.}
{
\usecounter{listcnt0}
\setlength{\rightmargin}{\leftmargin}
}

\item Open the folder containing the expanded archive.

\item Double-click on the file \textquotedbl{}setup.py\textquotedbl{}, which should be a \textquotedbl{}Python
module\textquotedbl{} file.

If the file isn't a \textquotedbl{}Python module\textquotedbl{}, the line endings are probably
also wrong, and you will need to set up your system to recognize
\textquotedbl{}.py\textquotedbl{} file extensions as Python files.  See
\url{http://gotools.sourceforge.net/mac/python.html} for detailed
instructions.  Once set up, it's easiest to start over by expanding
the archive again.

\item The distutils options window will appear.  From the \textquotedbl{}Command\textquotedbl{} popup
list choose \textquotedbl{}install\textquotedbl{}, click \textquotedbl{}Add\textquotedbl{}, then click \textquotedbl{}OK\textquotedbl{}.
\end{list}

If install.py is a \textquotedbl{}Python module\textquotedbl{} (see step 2 above if it isn't), you
can run it (double-click) instead of the above.  The distutils options
window will not appear.


\section{Usage%
  \label{usage}%
}

After unpacking and installing the Docutils package, the following
shell commands will generate HTML for all included documentation:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~<archive\_directory\_path>/tools\\
buildhtml.py~../
}
\end{quote}

The final directory name of the \texttt{<archive\_directory\_path>} is
\textquotedbl{}docutils\textquotedbl{} for snapshots.  For official releases, the directory may be
called \textquotedbl{}docutils-X.Y\textquotedbl{}, where \textquotedbl{}X.Y\textquotedbl{} is the release version.
Alternatively:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~<archive\_directory\_path>\\
tools/buildhtml.py~-{}-config=tools/docutils.conf
}
\end{quote}

Some files may generate system messages (warnings and errors).  The
\texttt{tools/test.txt} file (under the archive directory) contains 5
intentional errors.  (They test the error reporting mechanism!)

There are many front-end tools in the unpacked \textquotedbl{}tools\textquotedbl{} subdirectory.
You may want to begin with the \textquotedbl{}html.py\textquotedbl{} front-end tool.  Most tools
take up to two arguments, the source path and destination path, with
STDIN and STDOUT being the defaults.  Use the \textquotedbl{}-{}-help\textquotedbl{} option to the
front-end tools for details on options and arguments.  See \href{docs/tools.html}{Docutils
Front-End Tools} (\texttt{docs/tools.txt}) for full documentation.

The package modules are continually growing and evolving.  The
\texttt{docutils.statemachine} module is usable independently.  It contains
extensive inline documentation (in reStructuredText format of course).

Contributions are welcome!


\section{Running the Test Suite%
  \label{running-the-test-suite}%
}

To run the entire test suite, after \hyperref[installation]{installation} open a shell and use
the following commands:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~<archive\_directory\_path>/test\\
./alltests.py
}
\end{quote}

You should see a long line of periods, one for each test, and then a
summary like this:
%
\begin{quote}{\ttfamily \raggedright \noindent
Ran~518~tests~in~24.653s\\
~\\
OK\\
Elapsed~time:~26.189~seconds
}
\end{quote}

The number of tests will grow over time, and the times reported will
depend on the computer running the tests.  The difference between the
two times represents the time required to set up the tests (import
modules, create data structures, etc.).

If any of the tests fail, please \href{http://sourceforge.net/tracker/?group_id=38414&atid=422030}{open a bug report} or \href{mailto:docutils-users@lists.sourceforge.net?subject=Docutils\%20test\%20suite\%20failure}{send
email}.  Please include all relevant output, information about your
operating system, Python version, and Docutils version.  To see the
Docutils version, use these commands:
%
\begin{quote}{\ttfamily \raggedright \noindent
cd~../tools\\
./quicktest.py~-{}-version
}
\end{quote}


\section{Getting Help%
  \label{getting-help}%
}

If you have questions or need assistance with Docutils or
reStructuredText, please \href{mailto:docutils-users@lists.sourceforge.net}{post a message} to the \href{http://lists.sourceforge.net/lists/listinfo/docutils-users}{Docutils-Users
mailing list}.

% Local Variables:
% mode: indented-text
% indent-tabs-mode: nil
% sentence-end-double-space: t
% fill-column: 70
% End:

\end{document}