Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8713] trunk/docutils
|
From: <mi...@us...> - 2021-04-19 11:29:37
|
Revision: 8713
http://sourceforge.net/p/docutils/code/8713
Author: milde
Date: 2021-04-19 11:29:36 +0000 (Mon, 19 Apr 2021)
Log Message:
-----------
Documentation fixes.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/ref/doctree.txt
trunk/docutils/docs/ref/rst/directives.txt
trunk/docutils/docs/user/config.txt
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2021-04-17 14:58:28 UTC (rev 8712)
+++ trunk/docutils/RELEASE-NOTES.txt 2021-04-19 11:29:36 UTC (rev 8713)
@@ -88,6 +88,9 @@
stability of the generated HTML code, e.g. because you use a custom
style sheet or post-processing that may break otherwise.
+* The html_writer_ option of the ``buildhtml.py`` application is
+ obsoleted by ``--writer`` and will be removed in future.
+
.. _id_prefix: docs/user/config.html#id-prefix
.. _auto_id_prefix: docs/user/config.html#auto-id-prefix
.. _rst2html.py: docs/user/tools.html#rst2html-py
@@ -94,6 +97,7 @@
.. _reference name: docs/ref/rst/restructuredtext.html#reference-names
.. _identifier normalization:
docs/ref/rst/directives.html#identifier-normalization
+.. _html_writer: docs/user/config.html#html-writer
Release 0.17.1 (2021-04-16)
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2021-04-17 14:58:28 UTC (rev 8712)
+++ trunk/docutils/docs/ref/doctree.txt 2021-04-19 11:29:36 UTC (rev 8713)
@@ -4537,9 +4537,8 @@
_`number`
The attribute value must be a number. Resolves to ``NMTOKEN``.
- Used in the `start`_ and `scale`_ attributes.
+ Used in the `level`_, `morecols`_, `scale`_, and `start`_ attributes.
- .. also ltrim, rtrim
_`measure`
A number which may be immediately followed by a unit or percent sign.
Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt 2021-04-17 14:58:28 UTC (rev 8712)
+++ trunk/docutils/docs/ref/rst/directives.txt 2021-04-19 11:29:36 UTC (rev 8713)
@@ -517,7 +517,7 @@
The following options are recognized:
-``number-lines`` : [start line number]
+``number-lines`` : [integer]
Precede every line with a line number.
The optional argument is the number of the first line (defaut 1).
@@ -784,7 +784,7 @@
The horizontal alignment of the table.
(New in Docutils 0.13)
-``widths`` : "auto", "grid" or a list of integers
+``widths`` : "auto", "grid", or a list of integers
A comma- or space-separated list of column widths.
The default is the width of the input columns (in characters).
@@ -793,7 +793,7 @@
(LaTeX, the HTML browser, ...).
See also the `table_style`_ configuration option.
-``width`` : `length`_ or `percentage`_ of the current line width
+``width`` : `length`_ or `percentage`_
Forces the width of the table to the specified length or percentage
of the line width. If omitted, the renderer determines the width
of the table based on its contents.
@@ -869,7 +869,7 @@
whether to delegate the determination of column widths to the backend
(LaTeX, the HTML browser, ...).
-``width`` : `length`_ or `percentage`_ of the current line width
+``width`` : `length`_ or `percentage`_
Forces the width of the table to the specified length or percentage
of the line width. If omitted, the renderer determines the width
of the table based on its contents.
@@ -893,7 +893,7 @@
``url`` : string (whitespace removed)
An Internet URL reference to a CSV data file.
-``encoding`` : name of text encoding
+``encoding`` : string
The text encoding of the external CSV data (file or URL).
Defaults to the document's encoding (if specified).
@@ -909,7 +909,7 @@
Unicode code point; see the unicode_ directive for syntax
details.
-``keepspace`` : flag
+``keepspace`` : flag (empty)
Treat whitespace immediately following the delimiter as
significant. The default is to ignore such whitespace.
@@ -1331,13 +1331,13 @@
The following options are recognized:
-``ltrim`` : flag
+``ltrim`` : flag (empty)
Whitespace to the left of the substitution reference is removed.
-``rtrim`` : flag
+``rtrim`` : flag (empty)
Whitespace to the right of the substitution reference is removed.
-``trim`` : flag
+``trim`` : flag (empty)
Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
of the substitution reference is removed.
@@ -1454,18 +1454,18 @@
The entire included text is inserted into the document as a single
literal block.
-``code`` : formal language (optional)
+``code`` : [string] (formal language)
The argument and the included content are passed to
the code_ directive (useful for program listings).
(New in Docutils 0.9)
-``number-lines`` : [start line number]
+``number-lines`` : [integer] (start line number)
Precede every code line with a line number.
The optional argument is the number of the first line (defaut 1).
Works only with ``code`` or ``literal``.
(New in Docutils 0.9)
-``encoding`` : name of text encoding
+``encoding`` : string
The text encoding of the external data file. Defaults to the
document's input_encoding_.
@@ -1559,7 +1559,7 @@
``url`` : string (whitespace removed)
An Internet URL reference to a raw data file to be included.
-``encoding`` : name of text encoding
+``encoding`` : string
The text encoding of the external raw data (file or URL).
Defaults to the document's encoding (if specified).
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2021-04-17 14:58:28 UTC (rev 8712)
+++ trunk/docutils/docs/user/config.txt 2021-04-19 11:29:36 UTC (rev 8713)
@@ -146,8 +146,8 @@
-------------------------------------
Below are the Docutils runtime settings, listed by config file
-section. Any setting may be specified in any section, but only
-settings from active sections will be used. Sections correspond to
+section. **Any setting may be specified in any section, but only
+settings from active sections will be used.** Sections correspond to
Docutils components (module name or alias; section names are always in
lowercase letters). Each `Docutils application`_ uses a specific set
of components; corresponding configuration file sections are applied
@@ -167,7 +167,7 @@
4. `[writers]`_, writer family ("[... writers]"; if applicable),
writer dependencies, and the section specific to the writer used
("[... writer]"). For example, `[pep_html writer]`_ depends
- on `[html4css1 writer]`_.
+ on `[html writers]`_ and `[html4css1 writer]`_.
5. `[applications]`_, application dependencies, and the section
specific to the Application (front-end tool) in use
@@ -211,7 +211,7 @@
A trailing "%" is replaced with the tag name (new in Docutils 0.16).
Default: "id" (`will change to "%" in future`__).
-Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
+Option: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
.. _identifier normalization:
../ref/rst/directives.html#identifier-normalization
@@ -256,7 +256,7 @@
document (``document.__dict__``) to stderr.
Default: don't (None).
-Options: ``--dump-internals`` (hidden, for development use only).
+Option: ``--dump-internals`` (hidden, for development use only).
dump_pseudo_xml
---------------
@@ -265,7 +265,7 @@
the document to stderr.
Default: don't (None).
-Options: ``--dump-pseudo-xml`` (hidden, for development use only).
+Option: ``--dump-pseudo-xml`` (hidden, for development use only).
dump_settings
-------------
@@ -273,7 +273,7 @@
At the end of processing, write all Docutils settings to stderr.
Default: don't (None).
-Options: ``--dump-settings`` (hidden, for development use only).
+Option: ``--dump-settings`` (hidden, for development use only).
dump_transforms
---------------
@@ -282,7 +282,7 @@
to the document to stderr.
Default: don't (None).
-Options: ``--dump-transforms`` (hidden, for development use only).
+Option: ``--dump-transforms`` (hidden, for development use only).
error_encoding
--------------
@@ -308,7 +308,7 @@
exit. Exit status is the maximum system message level plus 10 (11
for INFO, etc.).
-Default: disabled (5). Options: ``--exit-status``.
+Default: disabled (5). Option: ``--exit-status``.
expose_internals
----------------
@@ -319,7 +319,7 @@
line, the option may be used more than once.
Default: don't (None).
-Options: ``--expose-internal-attribute`` (hidden, for development use only).
+Option: ``--expose-internal-attribute`` (hidden, for development use only).
footnote_backlinks
------------------
@@ -355,7 +355,7 @@
See also auto_id_prefix_.
Default: "" (empty).
-Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
+Option: ``--id-prefix`` (hidden, intended mainly for programmatic use).
input_encoding
--------------
@@ -596,7 +596,7 @@
Path to a file for the output of system messages (warnings). [#pwd]_
-Default: stderr (None). Options: ``--warnings``.
+Default: stderr (None). Option: ``--warnings``.
[parsers]
@@ -678,7 +678,7 @@
Recognize and link to standalone PEP references (like "PEP 258").
Default: disabled (None); enabled (True) in PEP Reader.
-Options: ``--pep-references``.
+Option: ``--pep-references``.
pep_base_url
~~~~~~~~~~~~
@@ -701,7 +701,7 @@
Recognize and link to standalone RFC references (like "RFC 822").
Default: disabled (None); enabled (True) in PEP Reader.
-Options: ``--rfc-references``.
+Option: ``--rfc-references``.
rfc_base_url
~~~~~~~~~~~~
@@ -793,7 +793,7 @@
Number of spaces for hard tab expansion.
-Default: 8. Options: ``--tab-width``.
+Default: 8. Option: ``--tab-width``.
trim_footnote_reference_space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -845,8 +845,8 @@
Enable or disable the promotion of the title of a lone subsection
to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
-Default: disabled (False). Options: ``--section-subtitles,
---no-section-subtitles``.
+Default: disabled (False).
+Options: ``--section-subtitles, --no-section-subtitles``.
[pep reader]
@@ -908,7 +908,7 @@
Generate XML with an XML declaration.
See also `xml_declaration [html writers]`_.
-Default: do (True). Options: ``--no-xml-declaration``.
+Default: do (True). Option: ``--no-xml-declaration``.
[html writers]
@@ -923,7 +923,7 @@
prefix), "parentheses"/"parens", or "none".
See also `attribution [latex writers]`_.
-Default: "dash". Options: ``--attribution``.
+Default: "dash". Option: ``--attribution``.
cloak_email_addresses
@@ -981,8 +981,8 @@
accessible during processing.
See also `embed_stylesheet [latex writers]`_.
-Default: enabled. Options: ``--embed-stylesheet,
---link-stylesheet``.
+Default: enabled.
+Options: ``--embed-stylesheet, --link-stylesheet``.
.. _footnote_references setting:
@@ -1151,7 +1151,7 @@
Default: the working directory of the process at launch and the directory
with default stylesheet files (writer and installation specific).
Use the ``--help`` option to get the exact value.
-Option: ``--stylesheet-directories``.
+Option: ``--stylesheet-dirs``.
.. _stylesheet_path:
@@ -1172,7 +1172,7 @@
Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
`[pep_html writer]`_).
-Options: ``--stylesheet-path``.
+Option: ``--stylesheet-path``.
__ `embed_stylesheet [html writers]`_
__ `stylesheet_dirs [html writers]`_
@@ -1186,14 +1186,11 @@
Class value(s) added to all tables_.
See also `table_style [latex writers]`_.
-The default CSS sylesheet defines:
+The default CSS sylesheets define:
borderless
No borders around the table.
- booktabs
- Lines above and below the table and a thin line after the head.
-
align-left, align-center, align-right
Align the tables
@@ -1202,9 +1199,14 @@
(leave out the ``<colgroup>`` column specification).
See also the "widths" option of the `table directive`_.
+The HTML5 stylesheets also define:
+
+ booktabs
+ Only lines above and below the table and a thin line after the head.
+
captionbelow
Place the table caption below the table
- (only with the `HTML5 writer`_, new in 0.17).
+ (New in 0.17).
Default: "". Option: ``--table-style``.
@@ -1219,9 +1221,9 @@
Path to template file, which must be encoded in UTF-8. [#pwd]_
See also `template [latex writers]`_.
-Default: "template.txt" in the docutils/writers/html4css1/
-directory (installed automatically; for the exact machine-specific
-path, use the ``--help`` option). Options: ``--template``.
+Default: "template.txt" in the writer's directory (installed automatically;
+for the exact machine-specific path, use the ``--help`` option).
+Option: ``--template``.
.. _xml_declaration [html writers]:
@@ -1229,17 +1231,56 @@
xml_declaration
~~~~~~~~~~~~~~~
-Generate XML with an XML declaration.
+Prepend an XML declaration.
See also `xml_declaration [docutils_xml writer]`_.
.. Caution:: The XML declaration carries text encoding information. If the
encoding is not UTF-8 or ASCII and the XML declaration is missing,
- standard tools may be unable to read the generated XHTML.
+ standard XML tools may be unable to read the generated XHTML.
-Default: do (True). Options: ``--no-xml-declaration``.
+Default: writer dependent.
+Options: ``--xml-declaration``, ``--no-xml-declaration``.
+[html5 writer]
+~~~~~~~~~~~~~~
+The `HTML5 Writer`_ generates valid XML that is compatible with `HTML5`_.
+It shares all settings defined in the `[html writers]`_
+`configuration section`_.
+
+New in Docutils 0.13.
+
+__ https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
+.. _HTML5 Writer: html.html#html5-polyglot
+.. _HTML5: http://www.w3.org/TR/html5/
+
+
+Writer Specific Defaults
+""""""""""""""""""""""""
+
+`initial_header_level`_
+ 2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
+
+`stylesheet_path <stylesheet_path [html writers]_>`__:
+ "minimal.css,plain.css"
+
+embed_images
+""""""""""""
+
+Embed images in the output HTML file. If the image can be read from
+the local file system and its MIME type can be determined, it is
+base64_ encoded and included as a `data URI`_.
+
+Default: disabled (False).
+Options: ``--embed-images``, ``--link-images``.
+
+New in Docutils 0.17.
+
+.. _base64: https://en.wikipedia.org/wiki/Base64
+.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
+
+
[html4css1 writer]
~~~~~~~~~~~~~~~~~~
@@ -1249,7 +1290,8 @@
`configuration section`_.
-Writer specific defaults:
+Writer Specific Defaults
+""""""""""""""""""""""""
`initial_header_level`_
1 (for "<h1>")
@@ -1257,6 +1299,9 @@
`stylesheet_path <stylesheet_path [html writers]_>`__:
"html4css1.css"
+`xml_declaration <xml_declaration [html writers]_>`__
+ enabled (True)
+
.. _HTML4/CSS1 Writer: html.html#html4css1
.. _XHTML 1 Transitional: http://www.w3.org/TR/xhtml1/
@@ -1282,44 +1327,6 @@
Default: 14 (i.e. 14 characters). Option: ``--option-limit``.
-[html5 writer]
-~~~~~~~~~~~~~~
-
-The `HTML5 Writer`_ generates valid XML that is compatible with `HTML5`_.
-It shares all settings defined in the `[html writers]`_
-`configuration section`_.
-
-Writer specific defaults:
-
-`initial_header_level`_
- 2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
-
-`stylesheet_path <stylesheet_path [html writers]_>`__:
- "minimal.css,plain.css"
-
-New in Docutils 0.13.
-
-__ https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
-.. _HTML5 Writer: html.html#html5-polyglot
-.. _HTML5: http://www.w3.org/TR/html5/
-
-
-embed_images
-""""""""""""
-
-Embed images in the output HTML file. If the image can be read from
-the local file system and its MIME type can be determined, it is
-base64_ encoded and included as a `data URI`_.
-
-Default: disabled (False).
-Options: ``--embed-images``, ``--link-images``
-
-New in Docutils 0.17.
-
-.. _base64: https://en.wikipedia.org/wiki/Base64
-.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
-
-
[pep_html writer]
~~~~~~~~~~~~~~~~~
@@ -1327,7 +1334,8 @@
all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
`configuration sections`_.
-Writer specific defaults:
+Writer Specific Defaults
+""""""""""""""""""""""""
`initial_header_level`_
1 (for "<h1>")
@@ -1352,13 +1360,13 @@
Home URL prefix for PEPs.
-Default: current directory ("."). Options: ``--pep-home``.
+Default: current directory ("."). Option: ``--pep-home``.
python_home
"""""""""""
Python's home URL.
-Default: parent directory (".."). Options: ``--python-home``.
+Default: parent directory (".."). Option: ``--python-home``.
[s5_html writer]
@@ -1368,7 +1376,8 @@
all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
`configuration sections`_.
-Writer specific defaults:
+Writer Specific Defaults
+""""""""""""""""""""""""
compact_lists_:
disable compact lists.
@@ -1387,8 +1396,8 @@
Auto-hide the presentation controls in slideshow mode, or or keep
them visible at all times.
-Default: auto-hide (True). Options: ``--hidden-controls``,
-``--visible-controls``.
+Default: auto-hide (True).
+Options: ``--hidden-controls``, ``--visible-controls``.
current_slide
"""""""""""""
@@ -1395,8 +1404,8 @@
Enable or disable the current slide indicator ("1/15").
-Default: disabled (None). Options: ``--current-slide``,
-``--no-current-slide``.
+Default: disabled (None).
+Options: ``--current-slide``, ``--no-current-slide``.
overwrite_theme_files
"""""""""""""""""""""
@@ -1405,8 +1414,8 @@
``ui/<theme>`` directory. This has no effect if "theme_url_" is
used.
-Default: keep existing theme files (None). Options:
-``--keep-theme-files``, ``--overwrite-theme-files``.
+Default: keep existing theme files (None).
+Options: ``--keep-theme-files``, ``--overwrite-theme-files``.
theme
"""""
@@ -1601,6 +1610,7 @@
number or the page number.
Default: "" (use hyperreferences). Option: ``--reference-label``.
+
section_enumerator_separator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1673,7 +1683,7 @@
Default: the working directory of the process at launch and the directory
with default stylesheet files (writer and installation specific).
Use the ``--help`` option to get the exact value.
-Option: ``--stylesheet-directories``.
+Option: ``--stylesheet-dirs``.
.. _stylesheet_path [latex writers]:
@@ -1744,7 +1754,7 @@
See also `template [html writers]`_.
Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
-Options: ``--template``.
+Option: ``--template``.
use_bibtex
@@ -1999,7 +2009,7 @@
Pretty-print <#text> nodes.
-Default: False. Options: ``--detailled``.
+Default: False. Option: ``--detailled``.
[applications]
@@ -2013,18 +2023,24 @@
Do not process files, show files that would be processed.
-Default: False. Options: ``--dry-run``.
+Default: False. Option: ``--dry-run``.
-html_writer
-~~~~~~~~~~~
+.. _html_writer:
+.. _writer [buildhtml application]:
+writer
+~~~~~~
+
`HTML writer`_ version. One of "html", "html4", "html5".
Default: "html" (use Docutils' default HTML writer).
-Options: ``--html-writer``
+Option: ``--writer``
+New in 0.17. Obsoletes the ``html_writer`` option.
+
.. _HTML writer: html.html
+
ignore
~~~~~~
@@ -2033,7 +2049,7 @@
configuration files or on the command line); on the command line, the
option may also be used more than once.
-Default: None. Options: ``--ignore``.
+Default: None. Option: ``--ignore``.
prune
~~~~~
@@ -2043,7 +2059,7 @@
on the command line); on the command line, the option may also be
used more than once.
-Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
+Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Option:
``--prune``.
recurse
@@ -2059,7 +2075,7 @@
Work silently (no progress messages). Independent of
"report_level".
-Default: show progress (None). Options: ``--silent``.
+Default: show progress (None). Option: ``--silent``.
[docfactory application]
@@ -2089,7 +2105,7 @@
interpreted relative to the config file's location (*not* relative
to the current working directory).
-Default: None. Options: ``--config``.
+Default: None. Option: ``--config``.
Internal Settings
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
