From: Simon McVittie Date: Thu, 8 Oct 2015 11:57:03 -0700 Subject: 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: 2017-09-19 --- README.txt | 21 +++++++++++++++++++-- docs/user/tools.txt | 43 ++++++++++++++++++++++++++++++++++++------- 2 files changed, 55 insertions(+), 9 deletions(-) diff --git a/README.txt b/README.txt index 33ee605..3e9abda 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. @@ -281,6 +292,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 9f06816..665dc80 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 given, and their subdirectories too. (Use the ``--local`` option to skip subdirectories.) Usage:: - buildhtml.py [options] [ ...] + rst-buildhtml [options] [ ...] 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 ``rst2html4.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 /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