[Python-modules-commits] [python-docutils] 03/14: change paths in documentation to match Debian's
Dmitry Shachnev
mitya57 at moszumanska.debian.org
Sat Dec 10 10:40:51 UTC 2016
This is an automated email from the git hooks/post-receive script.
mitya57 pushed a commit to branch master
in repository python-docutils.
commit 03baf7716ddfceb839d714cae7dfad360c1aaee8
Author: Simon McVittie <smcv at debian.org>
Date: Thu Oct 8 11:57:03 2015 -0700
change paths in documentation to match Debian's
Change paths in documentation to match Debian's. Debian policy recommends not
having extensions like .py on script names, and buildhtml seems too generic a
name.
Forwarded: not-needed
Last-Update: 2016-12-10
Patch-Name: doc-debian-paths.diff
---
README.txt | 21 +++++++++++++++++++--
docs/user/tools.txt | 43 ++++++++++++++++++++++++++++++++++++-------
2 files changed, 55 insertions(+), 9 deletions(-)
diff --git a/README.txt b/README.txt
index 854fe34..a5ea488 100644
--- a/README.txt
+++ b/README.txt
@@ -11,8 +11,19 @@
.. contents::
-Quick-Start
-===========
+Quick-Start on Debian systems
+=============================
+
+The reStructuredText tools are installed in the normal system path by the
+Debian ``python-docutils`` package. To convert reStructuredText to another
+format, use a shell command like::
+
+ rst2html /usr/share/doc/python-docutils/FAQ.txt ./FAQ.html
+
+See Usage_ below for details.
+
+Quick-Start on other systems
+============================
This is for those who want to get up & running quickly.
@@ -283,6 +294,12 @@ with STDIN and STDOUT being the defaults. Use the "--help" option to
the front-end tools for details on options and arguments. See
Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
+On a Debian system the included tools (with the exception of quicktest.py
+and the development tools in the dev/ directory) are installed into the
+normal system path, so you can run ``rst2html.py`` with a command like::
+
+ rst2html example.txt example.html
+
The package modules are continually growing and evolving. The
``docutils.statemachine`` module is usable independently. It contains
extensive inline documentation (in reStructuredText format of course).
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index e95cf36..c90d6a9 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -39,6 +39,10 @@ one argument (source) is specified, the standard output (stdout) is
used for the destination. If no arguments are specified, the standard
input (stdin) is used for the source.
+In Debian these tools are installed in the normal system path, without the
+``.py`` extension, according to Debian policy.
+buildhtml.py_ is installed as rst-buildhtml.
+
Getting Help
============
@@ -66,13 +70,15 @@ buildhtml.py
:Parser: reStructuredText
:Writers: html_, pep_html_
+In Debian this tool is installed under the name rst-buildhtml.
+
Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
(including PEPs) in each <directory> given, and their subdirectories
too. (Use the ``--local`` option to skip subdirectories.)
Usage::
- buildhtml.py [options] [<directory> ...]
+ rst-buildhtml [options] [<directory> ...]
After unpacking the Docutils package, the following shell commands
will generate HTML for all included documentation::
@@ -103,6 +109,8 @@ rst2html.py
:Parser: reStructuredText
:Writer: html_
+In Debian this front end is installed as rst2html.
+
`rst2html.py` is the front-end for the default Docutils HTML writer.
The default writer may change with the development of HTML, browsers,
Docutils, and the web. Currently, it is html4css1_.
@@ -121,6 +129,8 @@ rst2html4.py
:Parser: reStructuredText
:Writer: html4css1_
+In Debian this front end is installed as rst2html4.
+
The ``rst2html.py`` front end reads standalone reStructuredText source
files and produces `XHTML 1.0 Transitional`_ output.
A CSS stylesheet is required for proper rendering; a simple but
@@ -130,13 +140,13 @@ below).
For example, to process a reStructuredText file "``test.txt``" into
HTML::
- rst2html.py test.txt test.html
+ rst2html test.txt test.html
Now open the "``test.html``" file in your favorite browser to see the
results. To get a footer with a link to the source file, date & time
of processing, and links to the Docutils project, add some options::
- rst2html.py -stg test.txt test.html
+ rst2html -stg test.txt test.html
Stylesheets
@@ -166,6 +176,8 @@ rst2html5.py
:Parser: reStructuredText
:Writer: html5 (html5_polyglot_)
+In Debian this front end is installed as rst2html5.
+
The ``rst2html5.py`` front end reads standalone reStructuredText source
files and produces `HTML 5`_ output.
Correct rendering of elements not directly supported by HTML depends on a
@@ -181,6 +193,8 @@ rstpep2html.py
:Parser: reStructuredText
:Writer: pep_html_
+In Debian this front end is installed as rstpep2html.
+
``rstpep2html.py`` reads a new-style PEP (marked up with reStructuredText)
and produces `XHTML 1.0 Transitional`_. It requires a template file and a
stylesheet. By default, it makes use of a "``pep-html-template``" file and
@@ -191,7 +205,7 @@ configuration files.
For example, to process a PEP into HTML::
cd <path-to-docutils>/docs/peps
- rstpep2html.py pep-0287.txt pep-0287.html
+ rstpep2html pep-0287.txt pep-0287.html
.. _pep_html: html.html#pep-html
@@ -202,6 +216,8 @@ rst2s5.py
:Parser: reStructuredText
:Writer: s5_html_
+In Debian this is installed as rst2s5.
+
The ``rst2s5.py`` front end reads standalone reStructuredText source
files and produces (X)HTML output compatible with S5_, the "Simple
Standards-based Slide Show System" by Eric Meyer. A theme is required
@@ -211,7 +227,7 @@ are available; see Themes_ below.
For example, to process a reStructuredText file "``slides.txt``" into
S5/HTML::
- rst2s5.py slides.txt slides.html
+ rst2s5 slides.txt slides.html
Now open the "``slides.html``" file in your favorite browser, switch
to full-screen mode, and enjoy the results.
@@ -229,7 +245,7 @@ using the "``--theme``" option (for themes that come with Docutils) or
the "``--theme-url``" option (for themes anywhere). For example, the
"medium-black" theme can be specified as follows::
- rst2s5.py --theme medium-black slides.txt slides.html
+ rst2s5 --theme medium-black slides.txt slides.html
The theme will be copied to the ``ui/medium-black`` directory.
@@ -318,11 +334,13 @@ rst2latex.py
:Parser: reStructuredText
:Writer: latex2e
+In Debian this is installed as rst2latex.
+
The ``rst2latex.py`` front end reads standalone reStructuredText
source files and produces LaTeX_ output. For example, to process a
reStructuredText file "``test.txt``" into LaTeX::
- rst2latex.py test.txt test.tex
+ rst2latex test.txt test.tex
The output file "``test.tex``" should then be processed with ``latex``
or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
@@ -337,6 +355,8 @@ rst2xetex.py
:Parser: reStructuredText
:Writer: xetex
+On Debian this front end is installed as rst2xetex.
+
The ``rst2xetex.py`` front end reads standalone reStructuredText source
files and produces `LaTeX` output for processing with unicode-aware
TeX engines (`LuaTeX`_ or `XeTeX`_). For example, to process a
@@ -365,6 +385,8 @@ rst2xml.py
:Parser: reStructuredText
:Writer: XML (Docutils native)
+In Debian this is installed as rst2xml.
+
The ``rst2xml.py`` front end produces Docutils-native XML output.
This can be transformed with standard XML tools such as XSLT
processors into arbitrary final forms. An example is the xml2rst_ processor
@@ -383,6 +405,8 @@ rst2odt.py
:Parser: reStructuredText
:Writer: ODF/.odt
+In Debian this front end is installed as rst2odt.
+
The ``rst2odt.py`` front end reads standalone reStructuredText
source files and produces ODF/.odt files that can be read, edited,
printed, etc with OpenOffice ``oowriter``
@@ -413,6 +437,8 @@ rst2pseudoxml.py
:Parser: reStructuredText
:Writer: Pseudo-XML
+In Debian this is installed as rst2pseudoxml.
+
``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
Transform to Writer" pipeline. It produces a compact pretty-printed
"pseudo-XML", where nesting is indicated by indentation (no end-tags).
@@ -427,6 +453,9 @@ quicktest.py
:Parser: reStructuredText
:Writer: N/A
+This tool is not currently installed by the Debian package;
+``apt-get source python-docutils`` if you need it.
+
The ``quicktest.py`` tool is used for testing the reStructuredText
parser. It does not use a Docutils Reader or Writer or the standard
Docutils command-line options. Rather, it does its own I/O and calls
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-docutils.git
More information about the Python-modules-commits
mailing list