Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8932] trunk/docutils
|
From: <mi...@us...> - 2022-01-05 14:59:34
|
Revision: 8932
http://sourceforge.net/p/docutils/code/8932
Author: milde
Date: 2022-01-05 14:59:31 +0000 (Wed, 05 Jan 2022)
Log Message:
-----------
Front-end documentation update and small fix.
Revise/fix front-end tool documentation.
Add support for -h and --help options to rst2odt_prepstyles.py
in order to unify behaviour.
Modified Paths:
--------------
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/tools/rst2odt_prepstyles.py
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2022-01-04 23:33:59 UTC (rev 8931)
+++ trunk/docutils/docs/user/config.txt 2022-01-05 14:59:31 UTC (rev 8932)
@@ -20,10 +20,12 @@
Configuration Files
-------------------
-Configuration files are used for persistent customization; they can be
-set once and take effect every time you use a front-end tool.
+Configuration files are used for persistent customization;
+they can be set once and take effect every time you use a component,
+e.g., via a `front-end tool`_.
Configuration file settings override the built-in defaults, and
command-line options override all.
+For the technicalities, see `Docutils Runtime Settings`_.
By default, Docutils checks the following places for configuration
files, in the following order:
@@ -63,7 +65,9 @@
``DOCUTILSCONFIG`` environment variable), and its entries will have
priority.
+.. _Docutils Runtime Settings: ../api/runtime-settings.html
+
-------------------------
Configuration File Syntax
-------------------------
@@ -192,6 +196,7 @@
http://www.python.org/doc/current/lib/module-ConfigParser.html
.. _Python: http://www.python.org/
.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
+.. _front-end tool:
.. _Docutils application: tools.html
@@ -2313,5 +2318,4 @@
.. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
.. _option lists: ../ref/rst/restructuredtext.html#option-lists
.. _tables: ../ref/rst/restructuredtext.html#tables
-
.. _table of contents: ../ref/rst/directives.html#contents
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2022-01-04 23:33:59 UTC (rev 8931)
+++ trunk/docutils/docs/user/tools.txt 2022-01-05 14:59:31 UTC (rev 8932)
@@ -24,16 +24,15 @@
understands the syntax of the text), and a "Writer" (which knows how
to generate a specific data format).
-Most front ends have common options and the same command-line usage
+Most [#]_ front ends have common options and the same command-line usage
pattern::
toolname [options] [<source> [<destination>]]
-(The exceptions are buildhtml.py_ and rstpep2html.py_.) See
-rst2html.py_ for concrete examples. Each tool has a "``--help``"
-option which lists the `command-line options`_ and arguments it
-supports. Processing can also be customized with `configuration
-files`_.
+See rst2html4.py_ for examples.
+Each tool has a "``--help``" option which lists the
+`command-line options`_ and arguments it supports.
+Processing can also be customized with `configuration files`_.
The two arguments, "source" and "destination", are optional. If only
one argument (source) is specified, the standard output (stdout) is
@@ -40,7 +39,13 @@
used for the destination. If no arguments are specified, the standard
input (stdin) is used for the source.
+.. note::
+ Docutils front-end tool support is currently under discussion.
+ Tool names, install details and the set of auto-installed tools
+ may change in future Docutils versions.
+.. [#] The exceptions are buildhtml.py_ and rst2odt_prepstyles.py_.
+
Getting Help
============
@@ -70,6 +75,7 @@
:Parser: reStructuredText, Markdown (reCommonMark)
:Writers: html_, html4css1_, html5_, latex__, manpage_,
odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
+:Config_: See `[docutils-cli application]`_
The ``docutils-cli.py`` front allows combining reader, parser, and
writer components.
@@ -77,13 +83,22 @@
For example, to process a Markdown_ file "``test.md``" into
Pseudo-XML_ ::
- docutils_.py --parser=markdown --writer=pseudoxml test.md test.txt
+ docutils-cli.py --parser=markdown --writer=pseudoxml\
+ test.md test.txt
-__ `Generating LaTeX with Docutils`_
+Use the "--help" option together with the component-selection options
+to get the correct list of supported command-line options. Example::
+
+ docutils-cli.py --parser=markdown --writer=xml --help
+
+__
+.. _latex2e:
.. _Generating LaTeX with Docutils: latex.html
.. _manpage: manpage.html
.. _Markdown: https://www.markdownguide.org/
+.. _[docutils-cli application]: config.html#docutils-cli-application
+
HTML-Generating Tools
=====================
@@ -93,6 +108,7 @@
:Readers: Standalone, PEP
:Parser: reStructuredText
:Writers: html_, html5_, pep_html_
+:Config_: `[buildhtml application]`_
Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
(including PEPs) in each <directory> given, and their subdirectories
@@ -123,6 +139,7 @@
automatically). Command-line options may be used to override config
file settings or replace them altogether.
+.. _[buildhtml application]: config.html#buildhtml-application
.. _configuration file: configuration files
@@ -137,11 +154,14 @@
The default writer may change with the development of HTML, browsers,
Docutils, and the web. Currently, it is html4css1_.
-* Use `rst2html.py`, if you want the output to be up-to-date automatically.
+.. caution::
+ Use docutils-cli.py_ with the `"writer" option`__ or
+ a specific front end like rst2html4.py_ or rst2html5.py_,
+ if you depend on stability of the generated HTML code
+ (e.g., because you use a custom style sheet or post-processing
+ that may break otherwise).
-* Use a specific front end, if you depend on stability of the
- generated HTML code, e.g. because you use a custom style sheet or
- post-processing that may break otherwise.
+ __ config.html#writer-docutils-cli-application
rst2html4.py
@@ -346,7 +366,7 @@
:Reader: Standalone
:Parser: reStructuredText
-:Writer: latex2e
+:Writer: latex2e_
The ``rst2latex.py`` front end reads standalone reStructuredText
source files and produces LaTeX_ output. For example, to process a
@@ -368,7 +388,7 @@
:Writer: _`xelatex`
The ``rst2xetex.py`` front end reads standalone reStructuredText source
-files and produces `LaTeX` output for processing with unicode-aware
+files and produces `LaTeX` output for processing with Unicode-aware
TeX engines (`LuaTeX`_ or `XeTeX`_). For example, to process a
reStructuredText file "``test.txt``" into LaTeX::
@@ -409,21 +429,34 @@
:Reader: Standalone
:Parser: reStructuredText
-:Writer: ODF/odt
+:Writer: odt_
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.
-(http://www.openoffice.org/). A stylesheet file is required. A
+printed, etc with OpenOffice_ ``oowriter`` or LibreOffice_ ``lowriter``.
+A stylesheet file is required. A
stylesheet file is an OpenOffice .odt file containing definitions
-of the styles required for ``rst2odt.py``. You can learn more
-about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
-etc from `Odt Writer for Docutils`_.
+of the styles required for ``rst2odt.py``.
+For details, see `Odt Writer for Docutils`_.
-.. _Odt Writer for Docutils:
-.. _odt: odt.html
+.. _OpenOffice: https://www.openoffice.org/
+.. _LibreOffice: https://www.libreoffice.org/
+.. _odt:
+.. _Odt Writer for Docutils: odt.html
+rst2odt_prepstyles.py
+`````````````````````
+A helper tool to fix a word-processor-generated STYLE_FILE.odt for
+odtwriter use::
+
+ rst2odt_prepstyles STYLE_FILE.odt
+
+See `Odt Writer for Docutils`__ for details.
+
+__ odt.html#page-size
+
+
reStructuredText-Generating Tools
=================================
@@ -480,19 +513,29 @@
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
the parser directly. No transforms are applied to the parsed
-document. Various forms output are possible:
+document. Possible output forms output include:
-- Pretty-printed pseudo-XML (default)
-- Test data (Python list of input and pseudo-XML output strings;
- useful for creating new test cases)
-- Pretty-printed native XML
-- Raw native XML (with or without a stylesheet reference)
+--pretty Pretty-printed pseudo-XML (default)
+--test Test data (Python list of input and pseudo-XML output strings;
+ useful for creating new test cases)
+--xml Pretty-printed native XML
+--rawxml Raw native XML (with or without a stylesheet reference)
+--help Usage hint and complete list of supported options.
+
---------------
Customization
---------------
+Most front-end tools support the options/settings from the generic
+`configuration file sections`_ plus the sections of their components
+(reader, writer, parser). [#]_
+Some front-end tools also add application-specific settings.
+
+.. [#] The exceptions are quicktest.py_ and rst2odt_prepstyles.py_.
+
+
Command-Line Options
====================
@@ -513,6 +556,9 @@
names are listed in the `Docutils Configuration`_ document.
.. _Docutils Configuration: config.html
+.. _Config:
+.. _configuration file sections:
+ config.html#configuration-file-sections-entries
..
Modified: trunk/docutils/tools/rst2odt_prepstyles.py
===================================================================
--- trunk/docutils/tools/rst2odt_prepstyles.py 2022-01-04 23:33:59 UTC (rev 8931)
+++ trunk/docutils/tools/rst2odt_prepstyles.py 2022-01-05 14:59:31 UTC (rev 8932)
@@ -53,7 +53,7 @@
def main():
args = sys.argv[1:]
- if len(args) != 1:
+ if len(args) != 1 or args[0] in ('-h', '--help'):
print(__doc__, file=sys.stderr)
print("Usage: %s STYLE_FILE.odt\n" % sys.argv[0], file=sys.stderr)
sys.exit(1)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
