SF.net SVN: docutils:[10060 ] trunk/docutils/docs
milde--- via Docutils-checkins <[email protected]> Sun, 30 Mar 2025 18:21:03 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10060
http://sourceforge.net/p/docutils/code/10060
Author: milde
Date: 2025-03-30 18:21:02 +0000 (Sun, 30 Mar 2025)
Log Message:
-----------
Documentation update and fixes.
Fix/update links.
The <author> element's DocBook analogon is not <author> but <personname>.
Clarify description of bibliographic fields (docinfo) in the rST specification.
Use the term "settings" instead of "options" for configuration settings in the
LaTeX writer documentation.
Modified Paths:
--------------
trunk/docutils/docs/api/transforms.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/latex.rst
Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst 2025-03-23 19:49:49 UTC (rev 10059)
+++ trunk/docutils/docs/api/transforms.rst 2025-03-30 18:21:02 UTC (rev 10060)
@@ -545,8 +545,6 @@
.. _doctitle_xform: ../user/config.html#doctitle-xform
.. _sectsubtitle_xform: ../user/config.html#sectsubtitle-xform
-.. _directive:
-.. _directives: ../ref/rst/directives.html
.. _"class": ../ref/rst/directives.html#class
.. _"contents": ../ref/rst/directives.html#table-of-contents
.. _"default-role": ../ref/rst/directives.html#default-role
@@ -577,10 +575,11 @@
.. reStructuredText Markup Specification
.. _bibliographic field:
-.. _bibliographic fields:
- ../ref/rst/restructuredtext.html#bibliographic-fields
+.. _bibliographic fields: ../ref/rst/restructuredtext.html#bibliographic-fields
.. _comments: ../ref/rst/restructuredtext.html#comments
-.. _document title: ../ref/rst/restructuredtext.html#document-title
+.. _directive:
+.. _directives: ../ref/rst/restructuredtext.html#directives
+.. _document title: ../ref/rst/restructuredtext.html#document-title
.. _hyperlink targets: ../ref/rst/restructuredtext.html#hyperlink-targets
.. _interpreted text: ../ref/rst/restructuredtext.html#interpreted-text
.. _registered bibliographic field names:
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2025-03-23 19:49:49 UTC (rev 10059)
+++ trunk/docutils/docs/ref/doctree.rst 2025-03-30 18:21:02 UTC (rev 10060)
@@ -558,7 +558,7 @@
of the document.
:Category: `Bibliographic Elements`_
-:Analogues: <author> is analogous to the DocBook_ <author> element.
+:Analogues: <author> is analogous to the DocBook_ <personname> element.
:Processing: see `\<docinfo>`_
:Parents: `\<docinfo>`_, `\<authors>`_
:Children: text data plus `inline elements`_ (`%text.model`_)
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-03-23 19:49:49 UTC (rev 10059)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-03-30 18:21:02 UTC (rev 10060)
@@ -381,10 +381,9 @@
r"""This is a raw docstring. Backslashes (\) are not touched."""
-.. [#uri-context] In contexts where Docutils expects a `URI-reference`_
+.. [#uri-context] In contexts where the parser expects a `URI-reference`_
(the link block of `external hyperlink targets`_ or the argument of an
- `"image"`_
- or `"figure"`_ directive), whitespace is ignored by default.
+ `"image"`_ or `"figure"`_ directive), whitespace is ignored by default.
.. [#literal-context]
In *literal context* (`literal blocks`_, `inline literals`_,
@@ -650,6 +649,8 @@
Body Elements
=============
+.. _paragraph:
+
Paragraphs
----------
@@ -673,6 +674,8 @@
+------------------------------+
+.. _bullet list:
+
Bullet Lists
------------
@@ -959,7 +962,8 @@
`\<status>`_, `\<topic>`_, `\<version>`_
When a field list is the document body's first element [#PreBibliographic]_,
-it may have its fields transformed__ to bibliographic data.
+it may have its fields transformed to bibliographic data
+by the `DocInfo transform`_.
This bibliographic data corresponds to the front matter of a book,
such as the title page and copyright page.
@@ -968,8 +972,6 @@
do not show up in the output before the bibliographic fields don't
count. See `PreBibliographic Elements`_ for details.
-__ `DocInfo transform`_
-
Certain registered field names (listed below) are recognized and
transformed to the corresponding doctree elements, most becoming child
elements of the `\<docinfo>`_ element. No ordering is required of these
@@ -986,7 +988,7 @@
doctree elements are as follows:
=================== ================
- Field name [#i18n]_ doctree element
+ field name [#i18n]_ doctree element
=================== ================
Abstract `\<topic>`_
Address `\<address>`_
@@ -1003,37 +1005,48 @@
=================== ================
.. compound::
- The "_`Authors`" field may contain
+ :name: authors
- * a single paragraph consisting of a list of authors, separated by
- ``;`` or ``,`` (``;`` is checked first, so ``Doe, Jane; Doe,
- John`` will work), [#i18n]_
- * multiple paragraphs (one per author), or
- * a bullet list whose elements each contain a single paragraph per author.
+ The **Authors** field may contain
+ * a single paragraph_ consisting of a list of authors, separated by
+ ``;`` or ``,`` [#i18n]_ (the semicolon is checked first, so
+ ``Doe, Jane; Doe, John`` will work),
+ * multiple paragraphs_ (one per author), or
+ * a `bullet list`_ whose elements each contain a single paragraph
+ per author.
+
+ .. attention:: Extracting author names from a single paragraph drops
+ inline markup! To keep, e.g., footnotes or emphasized name parts,
+ use multiple paragraphs or a bullet list.
+
+ As a convention, use an "Authors" field for authors with common
+ affiliation and separate "Author" fields (each followed by the
+ respective "Organization", "Address", and/or "Contact" fields) for
+ authors with distinct affiliations.
+ There is currently no way to represent the organization or
+ contact info of an individual author in an "Authors" field.
+
In some languages (e.g. Swedish), there is no singular/plural distinction
between "Author" and "Authors", so only an "Authors" field is provided,
and a single name is interpreted as an "Author". If a single name
- contains a comma, end it with a semicolon to disambiguate:
- ``:Författare: Doe, Jane;``.
+ contains a comma, end it with a semicolon or use a one-item
+ `bullet list`_ to disambiguate::
- There is currently no way to represent an individual author's
- organization or contact info in a reStructuredText "Authors" field.
- However, you may use an "Author" field followed by
- "Organization", "Address", and/or "Contact" for each author.
+ :Författare: * Larsson, Lars
-The "Address" field is for a multi-line surface mailing address.
-Newlines and whitespace will be preserved.
+The **Address** field is for a multi-line surface mailing address.
+Newlines will be preserved.
-The "Dedication" and "Abstract" fields may contain arbitrary body
-elements. Only one of each is allowed. They become topic elements
-with "Dedication" or "Abstract" titles (or language equivalents)
-immediately following the docinfo element.
+The **Dedication** and **Abstract** fields may contain arbitrary body
+elements. Only one of each is allowed. They become `\<topic>`_ elements
+with "Dedication" or "Abstract" titles (or language equivalents) [#i18n]_
+immediately following the `\<docinfo>`_ element.
-Unregistered/generic fields may contain one or more paragraphs or
+**Unregistered/generic fields** may contain one or more paragraphs or
arbitrary body elements. To support custom styling, the field name is
-also added to the `"classes" attribute`_ value after being converted
-into a valid identifier form.
+also added to the `"classes" attribute`_ value after an `identifier
+normalization`_.
.. [#i18n] Docutils supports localised bibliographic field names and
author separators. See the language_code_ setting and, for details,
@@ -2470,7 +2483,7 @@
See "Error Handling" in `PEP 258`_.
The parser must return a set of *unique* hyperlink targets. The
-calling software (such as the Docutils_) can warn of unresolvable
+calling software (such as Docutils_) can warn of unresolvable
links, giving reasons for the messages.
@@ -3200,6 +3213,7 @@
.. _"date": directives.html#date
.. _"default-role": directives.html#default-role
.. _"figure": directives.html#figure
+.. _identifier normalization: directives.html#identifier-normalization
.. _"image": directives.html#image
.. _"list-table": directives.html#list-table
.. _"math": directives.html#math
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-03-23 19:49:49 UTC (rev 10059)
+++ trunk/docutils/docs/user/config.rst 2025-03-30 18:21:02 UTC (rev 10060)
@@ -1020,8 +1020,7 @@
docinfo_xform
~~~~~~~~~~~~~
-Enable the `bibliographic field list`_ transform
-(docutils.transforms.frontmatter.DocInfo).
+Enable the DocInfo_ transform for `bibliographic fields`_.
*Default*: True. *Options*: ``--no-doc-info``.
@@ -1028,8 +1027,8 @@
doctitle_xform
~~~~~~~~~~~~~~
Enable the promotion of a lone top-level section title
-to `document title`_ (and subsequent section title to document
-subtitle promotion; docutils.transforms.frontmatter.DocTitle).
+to the `document title`_ (and subsequent section title
+to document subtitle) by the DocTitle_ transform.
*Default*: True. *Options*: ``--no-doc-title``.
@@ -1036,7 +1035,7 @@
sectsubtitle_xform
~~~~~~~~~~~~~~~~~~
Enable the promotion of the title of a lone subsection
-to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
+to a subtitle by the SectSubTitle_ transform.
:Default: False.
:Options: ``--section-subtitles``, ``--no-section-subtitles``.
@@ -1999,7 +1998,9 @@
use_latex_docinfo
~~~~~~~~~~~~~~~~~
-Attach date and author information to the `document title`__.
+Attach the content of the `bibliographic fields`_ "Author", "Authors",
+"Address", "Contact", "Organization", and "Date" to the `document
+title`__.
:Default: False (keep date and author info in the `document info`__ table).
:Options: ``--use-latex-docinfo``, ``--use-docutils-docinfo``.
@@ -2330,8 +2331,8 @@
[docutils application]
--------------------------
-Docutils' `generic front end`_ tool allows combining “reader”, “parser”,
-and “writer” components from the Docutils package or 3rd party plug-ins.
+Docutils' `generic front end`_ tool allows combining "reader", "parser",
+and "writer" components from the Docutils package or 3rd party plug-ins.
| New in 0.17. Config file support added in 0.18. Renamed in 0.19
(the old section name "docutils-cli application" is kept as alias).
@@ -2590,6 +2591,9 @@
.. _publish_from_doctree(): ../api/publisher.html#publish-from-doctree
.. _transform: ../api/transforms.html
+.. _DocInfo: ../api/transforms.html#docinfo
+.. _DocTitle: ../api/transforms.html#doctitle
+.. _SectSubTitle: ../api/transforms.html#sectsubtitle
.. _severity level: ../peps/pep-0258.html#error-handling
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2025-03-23 19:49:49 UTC (rev 10059)
+++ trunk/docutils/docs/user/latex.rst 2025-03-30 18:21:02 UTC (rev 10060)
@@ -46,7 +46,7 @@
libraries) provide means to extend or modify the LaTeX language by
redefining macros or providing new ones.
-Using the `document class`_ and `style sheet`_ configuration options, you
+Using the `document class`_ and `style sheet`_ configuration settings, you
can select from a *huge* selection of classes and packages (standard as well
as user contributed) coming with your TeX distribution or available at
CTAN_ as well as custom style sheets.
@@ -151,7 +151,6 @@
You may need to call the respective command two or three times
to get internal references correct.
-.. _documentoptions: config.html#documentoptions
.. _xetex: https://tug.org/xetex/
.. _luatex: https://www.luatex.org/
.. _rst2latex: tools.html#rst2latex
@@ -172,11 +171,13 @@
.. contents:: :local:
.. _option:
+.. _setting:
+.. _settings:
Options/Settings
----------------
-Options can be specified as
+Docutils configuration settings can be specified as
* command-line options, or
@@ -302,7 +303,7 @@
`LaTeX packages`_ (see the clsguide_ for an introduction on LaTeX
package writing).
-Options:
+Setting:
stylesheet_
It is possible to specify multiple style sheets and mix `LaTeX
@@ -351,7 +352,7 @@
options or commands re-defined without the need to create a separate
file (new in Docutils 0.7).
-Option:
+Setting:
latex-preamble_
Default:
@@ -379,7 +380,7 @@
documentation`_ for a description of the `document parts`_ available in a
template file.
-Option:
+Setting:
template_
In addition to the 'default.tex' template, the latex writer directory
@@ -590,17 +591,20 @@
document class
--------------
-There are hundreds of LaTeX document classes installed by modern
+There are hundreds of `LaTeX document classes`_ installed by modern
LaTeX distributions, provided by publishers, or available at CTAN_.
+Setting:
+ documentclass_
+
Popular document classes:
- * article, report, book: standard document classes
- * scrartcl, scrrprt, scrbook: KOMA-script_ classes
- * memoir_: highly configurable class for larger documents
+ * `Standard document classes`_: article, report, book
+ * KOMA-script_ classes: scrartcl, scrrprt, scrbook
+ * memoir_: a highly configurable document class for larger documents
-Option:
- documentclass_
-
+.. _LaTeX document classes: https://texfaq.org/FAQ-clsvpkg
+.. _standard document classes:
+ http://mirrors.ctan.org/macros/latex/base/classes.pdf
.. _KOMA-script: https://ctan.org/pkg/koma-script
.. _memoir: https://ctan.org/pkg/memoir
.. _documentclass: config.html#documentclass
@@ -609,22 +613,28 @@
document info
-------------
-Content of the `bibliographic fields`_ at the top of a document.
-By default, docinfo items are typeset as a table.
-If use-latex-docinfo_ is True, the "Author/s", "Address", "Contact",
-"Organization", and "Date" fields are attached to the `document title`_.
+The `bibliographic fields`_ at the top of a document specify
+document information like author name(s) and copyright info.
+By default, they are typeset as a table.
-Options:
+Settings:
use-latex-docinfo_, use-latex-abstract_
+ If use-latex-docinfo_ is True, the content of the "Author", "Authors",
+ "Address", "Contact", "Organization", and "Date" fields is attached to
+ the `document title`_ (see below).
+
+ If use-latex-abstract_ is True, the "Abstract" field content is placed
+ in an "abstract" environment. The "abstract" environment can be
+ customized or `set up`__ (for the "book" documentclass) with the
+ "abstract_" LaTeX package.
+
Length:
- ``\DUdocinfowidth``: the width for the `docinfo` table.
+ | ``\DUdocinfowidth`` (width of the `docinfo` table).
+ | Default: ``0.9\textwidth`` (90 % of text width)
-Default:
- 90 % of text width: ``0.9\textwidth``
-
Example:
- set to 70 % of text width::
+ Change the width of the docinfo table to 70 % of text width::
\newlength{\DUdocinfowidth}
\setlength{\DUdocinfowidth}{0.7\textwidth}
@@ -632,6 +642,8 @@
.. _bibliographic fields: ../ref/rst/restructuredtext.html#bibliographic-fields
.. _use-latex-docinfo: config.html#use-latex-docinfo
.. _use-latex-abstract: config.html#use-latex-abstract
+__ https://tex.stackexchange.com/a/539606/288060
+.. _abstract: https://ctan.org/pkg/abstract
document title
@@ -640,24 +652,22 @@
A lone top-level section title is (usually) transformed to the document title
(see `section structure`_).
-The format of the document title is defined by the `document class`_. The
-"article" document class uses an in-page title and the "report" and "book"
-classes write a separate title page. See the `TeX FAQ`_ on how to customize
-the `style of document titles`_.
+Settings:
+ doctitle_xform_, documentclass_, use-latex-docinfo_, template_
-The default title page shows only title and subtitle, date and author
-are shown in the `document info`_ table.
+The format of the document title is defined by the `document class`_
+and can be modified by `latex packages`_.
+The "article" document class uses an in-page title while the "report"
+and "book" classes use a separate title page.
+See section Templates_ and the `TeX FAQ`_ on how to customize the
+`style of document titles`_.
-Options:
- use-latex-docinfo_
-
- ``--template=titlepage.tex`` Put docinfo and abstract into the title page.
- A separate title page is used also with the "abstract" document class.
-
.. _section structure: rst/quickref.html#section-structure
+.. _doctitle_xform: config.html#doctitle-xform
.. _TeX FAQ: https://texfaq.org/
.. _style of document titles: https://texfaq.org/FAQ-titlsty
+
field lists
-----------
@@ -783,7 +793,7 @@
pdflatex_
a) specifying the corresponding LaTeX package(s) as argument to the
- stylesheet_ option_ or with the ``\usepackage`` LaTeX command.
+ stylesheet_ setting or with the ``\usepackage`` LaTeX command.
* packages can be combined,
* passing options to a package is only possible in a `style sheet`_
@@ -811,7 +821,7 @@
\usepackage{courier} % Courier for teletype (mono-space)
Since Docutils 0.7, this is the default value of the
- `latex-preamble`_ option.
+ `latex-preamble`_ setting.
.. [#] When generating PDF-files from LaTeX, the `PDF standard
fonts`_ do not need to be embedded in the document. While this
@@ -992,7 +1002,7 @@
LaTeX font encodings are described in detail in the encguide_ which is
part of the LaTeX base documentation.
-Option:
+Setting:
font-encoding_
Default:
@@ -1115,7 +1125,7 @@
hyperlinks
----------
-Options:
+Settings:
hyperlink-color_, hyperref-options_
Hyperlinks are realized using the hyperref_ package. As it re-defines many
@@ -1160,8 +1170,8 @@
or load the "nohyperref" package that comes with the "hyperref"
bundle.
-Option:
- ``--hyperref-options=draft``
+Setting:
+ hyperref-options_
`LaTeX code`_::
@@ -1231,7 +1241,7 @@
No markup processing is done within a `literal block`__. It is left as-is,
and is typically rendered in a monospaced typeface
-Option:
+Setting:
literal-block-env_
Example:
@@ -1449,7 +1459,7 @@
paper size
----------
-Paper geometry can be changed using ``--documentoptions`` or with the
+Paper geometry can be changed using documentoptions_ or with the
`geometry`_ package.
`LaTeX code`_::
@@ -1535,7 +1545,7 @@
section headings
----------------
-Options: documentclass_, use-part-section_
+Settings: documentclass_, use-part-section_
Section headings are converted into LaTeX macros according to their level,
the document class and the value of the use-part-section_ setting:
@@ -1563,8 +1573,7 @@
Sections are numbered if there is a `sectnum directive`_ in the document.
-Option: sectnum_xform_
- ``--section-numbering``, ``--no-section-numbering``
+Setting: sectnum_xform_
If sectnum_xform_ is False, section numbers are generated by LaTeX. In this
case the "prefix" and "suffix" arguments of the `sectnum directive`_ are
@@ -1678,8 +1687,7 @@
A `contents directive`_ is replaced by a table of contents (ToC).
-Option: use-latex-toc_
- ``--use-latex-toc``, ``--use-docutils-toc``
+Setting:: use-latex-toc_
With use-latex-toc (default since release 0.6):
@@ -1778,8 +1786,7 @@
The encoding of the LaTeX source file is Docutils' *output* encoding
but LaTeX' *input* encoding.
-Option: output_encoding_
- ``--output-encoding=OUTPUT-ENCODING``
+Setting: output_encoding_
Default:
"utf-8" (LaTeX's default input encoding)
@@ -1791,7 +1798,7 @@
--output-encoding=latin-1
Note:
- 8-bit LaTeX comes with two options for UTF-8 support,
+ 8-bit LaTeX comes with two packages for UTF-8 support,
.. class:: field-indent-4em
@@ -1891,7 +1898,7 @@
There is `Latin Modern`_ if you like the look of the standard font on paper,
but want nice pdf. Or select something else like Times, Palatino, ... via
-configuration `options/settings`_. See font_ and font-encoding_.
+configuration settings_. See font_ and font-encoding_.
footnote mark and text at different pages
@@ -2114,7 +2121,7 @@
page foot.
Workaround:
- Select citation handling with the use_latex_citations_ option.
+ Select citation handling with the use_latex_citations_ setting.
If ``use-latex-citations`` is used, a bibliography is inserted right at
the end of the document. *This should be customizable*.
@@ -2132,7 +2139,7 @@
* Too wide tables (cf. `bug #422`_):
- Try the new_column_widths_ algorithm or use the `"widths" option`_ to
+ Try the new_column_widths_ setting or use the `"widths" option`_ to
manually set the table column widths.
* Table cells with both multirow and multicolumn are currently not possible.
@@ -2161,8 +2168,3 @@
* Hyperlinks are not hyphenated; this leads to bad spacing. See
docs/user/rst/demo.rst 2.14 directives.
-
-* Pagestyle headings does not work, when sections are starred. Use LaTeX for
- the section numbering with the `options/settings`_
- ``--no-section-numbers`` (command line) or ``sectnum_xform: False``
- (config file).
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins