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: 2022-07-08 --- README.txt | 21 +++++++++++++++++++-- docs/user/tools.txt | 43 ++++++++++++++++++++++++++++++++++++------- 2 files changed, 55 insertions(+), 9 deletions(-) diff --git a/README.txt b/README.txt index 12c3c0a..dac46fa 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/python3-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. @@ -229,6 +240,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`_ 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 f19f7f0..3187a5c 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -40,6 +40,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. + .. note:: Docutils front-end tool support is currently under discussion. Tool names, install details and the set of auto-installed tools @@ -115,13 +119,15 @@ buildhtml.py :Writers: html_, html5_, pep_html_ :Config_: `[buildhtml application]`_ +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:: @@ -155,6 +161,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. @@ -176,6 +184,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 @@ -185,13 +195,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 @@ -224,6 +234,8 @@ rst2html5.py :Parser: reStructuredText :Writer: html5_ +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 @@ -239,6 +251,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 @@ -249,7 +263,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 @@ -260,6 +274,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 @@ -269,7 +285,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. @@ -287,7 +303,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. @@ -376,11 +392,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 @@ -395,6 +413,8 @@ rst2xetex.py :Parser: reStructuredText :Writer: _`xelatex` +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 @@ -439,6 +459,8 @@ rst2odt.py :Parser: reStructuredText :Writer: 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`` or LibreOffice_ ``lowriter``. @@ -485,6 +507,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 @@ -503,6 +527,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). @@ -517,6 +543,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