SF.net SVN: docutils:[9552 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9552
http://sourceforge.net/p/docutils/code/9552
Author: milde
Date: 2024-03-08 23:41:31 +0000 (Fri, 08 Mar 2024)
Log Message:
-----------
"Transforms" documentation revision.
Add cross-links.
Add description for DocInfo, DocTitle, and SectSubTitle transforms,
and their complex pre-conditions.
Fix/update transformation class docstrings.
Modified Paths:
--------------
trunk/docutils/docs/api/transforms.txt
trunk/docutils/docutils/transforms/frontmatter.py
Modified: trunk/docutils/docs/api/transforms.txt
===================================================================
--- trunk/docutils/docs/api/transforms.txt 2024-03-08 23:41:22 UTC (rev 9551)
+++ trunk/docutils/docs/api/transforms.txt 2024-03-08 23:41:31 UTC (rev 9552)
@@ -12,14 +12,18 @@
.. contents::
+ :depth: 2
-Transforms change the document tree in-place, add to the tree, or prune it.
-Transforms resolve references and footnote numbers, process interpreted
-text, and do other context-sensitive processing. Each transform is a
-subclass of ``docutils.transforms.Transform``.
+Introduction
+============
+Transforms change the `document tree`_ in-place, add to the tree, or prune it.
+Transforms resolve references and footnote numbers, process
+`interpreted text`_, and do other context-sensitive processing.
+Each transform is a subclass of `docutils.transforms.Transform`.
+
There are `transforms added by components`_, others (e.g.
-``parts.Contents``) are added by the parser, if a corresponding directive is
+``parts.Contents``) are added by the parser, if a corresponding directive_ is
found in the document.
To add a transform, components (objects inheriting from
@@ -35,90 +39,89 @@
258`_. (The ``default_transforms()`` attribute of component classes mentioned
there is deprecated. Use the ``get_transforms()`` method instead.)
-.. _PEP 258: ../peps/pep-0258.html#transformer
+.. _priority:
-
Transforms Listed in Priority Order
===================================
-Transform classes each have a default_priority attribute which is used by
+Transform classes each have a `default priority` attribute which is used by
the Transformer to apply transforms in order (low to high). The default
priority can be overridden when adding transforms to the Transformer object.
-============================== ============================ ========
-Transform: module.Class Added By Priority
-============================== ============================ ========
-misc.class "class" (d/p) 210
+================================== ============================ ========
+Transform: module.Class Added By Priority
+================================== ============================ ========
+misc_.ClassAttribute `"class"`_ (d/p) 210
-references.Substitutions standalone (r), pep (r) 220
+references_.Substitutions standalone (r), pep (r) 220
-references.PropagateTargets standalone (r), pep (r) 260
+references_.PropagateTargets standalone (r), pep (r) 260
-frontmatter.DocTitle standalone (r) 320
+frontmatter.\ DocTitle_ standalone (r) 320
-frontmatter.DocInfo standalone (r) 340
+frontmatter.\ DocInfo_ standalone (r) 340
-frontmatter.SectSubTitle standalone (r) 350
+frontmatter.\ SectSubTitle_ standalone (r) 350
-peps.Headers pep (r) 360
+peps_.Headers pep (r) 360
-peps.Contents pep (r) 380
+peps_.Contents pep (r) 380
-universal.StripClasses... Writer (w) 420
+universal_.StripClassesAndElements Writer (w) 420
-references.AnonymousHyperlinks standalone (r), pep (r) 440
+references_.AnonymousHyperlinks standalone (r), pep (r) 440
-references.IndirectHyperlinks standalone (r), pep (r) 460
+references_.IndirectHyperlinks standalone (r), pep (r) 460
-peps.TargetNotes pep (r) 520
+peps_.TargetNotes pep (r) 520
-references.TargetNotes peps.TargetNotes (t/p) 0
+references_.TargetNotes peps.TargetNotes (t/p) 0
-misc.CallBack peps.TargetNotes (t/p) 1
+misc_.CallBack peps.TargetNotes (t/p) 1
-references.TargetNotes "target-notes" (d/p) 540
+references_.TargetNotes `"target-notes"`_ (d/p) 540
-references.Footnotes standalone (r), pep (r) 620
+references_.Footnotes standalone (r), pep (r) 620
-references.ExternalTargets standalone (r), pep (r) 640
+references_.ExternalTargets standalone (r), pep (r) 640
-references.InternalTargets standalone (r), pep (r) 660
+references_.InternalTargets standalone (r), pep (r) 660
-parts.SectNum "sectnum" (d/p) 710
+parts_.SectNum `"sectnum"`_ (d/p) 710
-parts.Contents "contents" (d/p), 720
- peps.Contents (t/p)
+parts_.Contents `"contents"`_ (d/p), 720
+ peps.Contents (t/p)
-universal.StripComments Reader (r) 740
+universal_.StripComments Reader (r) 740
-peps.PEPZero peps.Headers (t/p) 760
+peps_.PEPZero peps.Headers (t/p) 760
-components.Filter *not used* 780
+components.Filter *not used* 780
-universal.Decorations Reader (r) 820
+universal_.Decorations Reader (r) 820
-misc.Transitions standalone (r), pep (r) 830
+misc_.Transitions standalone (r), pep (r) 830
-universal.ExposeInternals Reader (r) 840
+universal_.ExposeInternals Reader (r) 840
-references.DanglingReferences standalone (r), pep (r) 850
+references_.DanglingReferences standalone (r), pep (r) 850
-universal.SmartQuotes Parser 855
+universal_.SmartQuotes Parser 855
-universal.Messages Writer (w) 860
+universal_.Messages Writer (w) 860
-universal.FilterMessages Writer (w) 870
+universal_.FilterMessages Writer (w) 870
-universal.TestMessages DocutilsTestSupport 880
+universal_.TestMessages DocutilsTestSupport 880
-writer_aux.Compound *not used, to be removed* 910
+writer_aux_.Compound *not used, to be removed* 910
-writer_aux.Admonitions _html_base (w), 920
- latex2e (w)
+writer_aux_.Admonitions _html_base (w), 920
+ latex2e (w)
-misc.CallBack n/a 990
-============================== ============================ ========
+misc_.CallBack n/a 990
+================================== ============================ ========
Key:
@@ -130,7 +133,7 @@
Transform Priority Range Categories
-===================================
+-----------------------------------
==== ==== ================================================
Priority
@@ -151,7 +154,6 @@
Transforms added by components
===============================
-
readers.Reader:
| universal.Decorations,
| universal.ExposeInternals,
@@ -207,3 +209,395 @@
writers.odf_odt.Writer:
removes references.DanglingReferences
+
+
+Transforms Reference
+====================
+
+Incomplete. See also `Transforms Listed in Priority Order`_
+and the sources in `docutils/transforms`__.
+
+__ https://docutils.sourceforge.io/docutils/transforms/
+
+
+DocInfo
+-------
+
+.. class:: field-indent-12em
+
+:Module: frontmatter_
+:Added by: standalone Reader
+:Default priority_: 340
+:Configuration_ setting: docinfo_xform_ (default: True)
+
+Given a document starting [#pre-docinfo]_ with a field list, the DocInfo
+transform converts fields with registered `bibliographic field`_ names to
+the corresponding document tree elements becoming child elements of the
+`\<docinfo>`_ element (except for a "dedication" and "abstract", which
+become `\<topic>`_ elements after <docinfo>).
+
+.. [#pre-docinfo] A document title and subtitle, header and footer,
+ as well as body elements that do not show up in the output
+ before the field list don't prevent the DocInfo transformation.
+ See the `DocTitle examples`_ and `PreBibliographic Elements`_
+ in the Appendix for details.
+
+For example, this document fragment::
+
+ <document>
+ <title>
+ Document Title
+ <field_list>
+ <field>
+ <field_name>
+ Author
+ <field_body>
+ <paragraph>
+ A. Name
+ <field>
+ <field_name>
+ Status
+ <field_body>
+ <paragraph>
+ $RCSfile$
+ ...
+
+will be transformed to::
+
+ <document>
+ <title>
+ Document Title
+ <docinfo>
+ <author>
+ A. Name
+ <status>
+ frontmatter.py
+ ...
+
+
+DocTitle
+--------
+
+.. class:: field-indent-12em
+
+:Module: frontmatter_
+:Added by: standalone Reader
+:Default priority_: 320
+:Configuration_ setting: doctitle_xform_ (default: True)
+
+Under the conditions explained below, the DocTitle transform converts
+the document's first section title(s) to a document title and
+subtitle.
+
+1. If the document contains a single top-level section as its first body
+ element, [#pre-doctitle]_ the top-level section's title is used
+ as `document title`_ and default `metadata title`_. The top-level
+ section's contents become the document's immediate contents.
+
+ .. _step 2:
+
+2. If step 1 successfully determines the document title, the transform
+ checks for a subtitle:
+ If the lone top-level section itself contains a single second-level
+ section as its first element, [#pre-doctitle]_ that section's
+ title is promoted to the document's subtitle, and that section's
+ contents become the document's immediate contents.
+
+The transform can be disabled with the doctitle_xform_ configuration
+setting or the corresponding ``--no-doc-title`` command line option.
+
+.. [#pre-doctitle] Header and footer as well as body elements that
+ do not show up in the output before the section don't stop the
+ transformation of the section title to document title or subtitle.
+ See `PreBibliographic Elements`_ in the Appendix for details.
+
+.. _DocTitle examples:
+
+Examples
+~~~~~~~~
+
+The input text ::
+
+ Top-Level Title
+ ===============
+ A paragraph.
+
+is parsed to the following document tree::
+
+ <document>
+ <section names="top-level\ title">
+ <title>
+ Top-Level Title
+ <paragraph>
+ A paragraph.
+
+The DocTitle transform converts it to::
+
+ <document names="top-level\ title" title="Top-Level Title">
+ <title>
+ Top-Level Title
+ <paragraph>
+ A paragraph.
+
+Given this input with a lone section and sub-section::
+
+ Top-Level Title
+ ===============
+ Second-Level Title
+ ~~~~~~~~~~~~~~~~~~
+
+ A paragraph.
+
+the result after parsing and running the DocTitle transform is::
+
+ <document names="top-level\ title">
+ <title>
+ Top-Level Title
+ <subtitle names="second-level\ title">
+ Second-Level Title
+ <paragraph>
+ A paragraph.
+
+(Note that the implicit hyperlink target generated by the
+"Second-Level Title" is preserved on the "subtitle" element
+itself.)
+
+--------------
+
+The following examples do *not* comply with the conditions:
+
+i. More than one top-level section::
+
+ Top-Level Title
+ ===============
+ A paragraph.
+
+ Another Top-Level Title
+ =======================
+ Another paragraph.
+
+ The DocTitle transform will leave the document tree as-is.
+ The document has no title. It is recommended to set the
+ `metadata title`_ with the `"title"`_ directive.
+
+#. More than one second-level section::
+
+ Top-Level Title
+ ===============
+ Second-Level Title
+ ~~~~~~~~~~~~~~~~~~
+ A paragraph.
+
+ Another Second-Level Title
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Another paragraph.
+
+ Step 2 is skipped. "Top-Level Title" becomes the document title;
+ "Second-Level Title" and "Another Second-Level Title" become titles of
+ top-level sections.
+
+ This is what you normally want in a document with title but no
+ subtitle.
+
+#. Body elements before the first section: [#pre-doctitle]_ ::
+
+ .. note:: This element would not stop the transform, if it were
+ nested in a header.
+
+ Top-Level Title
+ ===============
+ A paragraph.
+
+ The DocTitle transform will leave the document tree as-is.
+ The document has no title.
+
+
+#. A `configuration file`_ entry "``doctitle_xform: False``"
+ or converting with the CLI command ::
+
+ docutils --no-doc-title example.rst > example.html
+
+ The DocTitle transform is skipped. The document has no title.
+
+
+SectSubTitle
+------------
+
+.. class:: field-indent-12em
+
+:Module: frontmatter_
+:Added by: standalone Reader
+:Default priority_: 350
+:Configuration_ setting: sectsubtitle_xform_ (default: False)
+
+The SectSubTitle transform works like `step 2`_ of the DocTitle_
+transform, but for sections.
+
+For example, ::
+
+ <section>
+ <title>
+ Title
+ <section>
+ <title>
+ Subtitle
+ ...
+
+is transformed into ::
+
+ <section>
+ <title>
+ Title
+ <subtitle>
+ Subtitle
+ ...
+
+This transform is disabled by default.
+
+
+Appendix
+========
+
+PreBibliographic Elements
+-------------------------
+
+The document tree elements `\<comment>`_, `\<decoration>`_,
+`\<footer>`_, `\<header>`_, `\<meta>`_, `\<pending>`_, `\<raw>`_,
+`\<substitution_definition>`_, `\<subtitle>`_, `\<system_message>`_,
+`\<target>`_, and `\<title>`_ are ignored when the DocTitle_ and DocInfo_
+transforms check for elements before frontmatter candidates.
+
+This means that in the reStructuredText source, comments_,
+`hyperlink targets`_, `substitution definitions`_, and the directives_
+`"class"`_, `"default-role"`_, `"footer"`_, `"header"`_, `"meta"`_,
+`"raw"`_, `"sectnum"`_, `"sectnum"`_, `"target-notes"`_, and `"title"`_
+may be placed before the `document title`_ or `bibliographic fields`_.
+
+The DocTitle_ transform inserts document title and subtitle before these
+elements. DocInfo_ inserts the bibliographic fields before
+`\<comment>`_, `\<raw>`_, `\<substitution_definition>`_, and `\<target>`_.
+
+For example, the document source::
+
+ .. a comment
+ .. |today| date::
+ .. _hypertarget: http://example.org
+ .. class:: spam
+ .. role:: ham
+ .. default-role:: ham
+ .. footer:: footer text
+ .. header:: header text
+ .. meta:: :test: value
+ .. raw:: html
+
+ raw html text
+ .. sectnum::
+ .. target-notes::
+ .. title:: metadata document title
+
+ Top-Level Title
+ ===============
+ Second-Level Title
+ ~~~~~~~~~~~~~~~~~~
+
+ :date: |today|
+
+is parsed and transformed to::
+
+ <document ids="top-level-title" names="top-level\ title"
+ title="metadata document title">
+ <title>
+ Top-Level Title
+ <subtitle ids="second-level-title" names="second-level\ title">
+ Second-Level Title
+ <meta content="value" name="test">
+ <decoration>
+ <header>
+ <paragraph>
+ header text
+ <footer>
+ <paragraph>
+ footer text
+ <docinfo>
+ <date>
+ 2024-03-01
+ <comment xml:space="preserve">
+ a comment
+ <substitution_definition names="today">
+ 2024-03-01
+ <target ids="hypertarget" names="hypertarget" refuri="http://example.org">
+ <raw classes="spam" format="html" xml:space="preserve">
+ raw html text
+
+
+
+.. References
+ ==========
+
+.. _PEP 258: ../peps/pep-0258.html#transformer
+
+.. _configuration:
+.. _configuration file:
+.. _configuration setting: ../user/config.html
+.. _docinfo_xform: ../user/config.html#docinfo-xform
+.. _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#contents
+.. _"default-role": ../ref/rst/directives.html#default-role
+.. _"footer": ../ref/rst/directives.html#footer
+.. _"header": ../ref/rst/directives.html#header
+.. _"meta": ../ref/rst/directives.html#meta
+.. _"raw": ../ref/rst/directives.html#raw
+.. _"sectnum": ../ref/rst/directives.html#sectnum
+.. _"target-notes": ../ref/rst/directives.html#target-notes
+.. _"title": ../ref/rst/directives.html#title
+
+.. _document tree: ../ref/doctree.html
+.. _`<comment>`: ../ref/doctree.html#comment
+.. _`<docinfo>`: ../ref/doctree.html#docinfo
+.. _`<decoration>`: ../ref/doctree.html#decoration
+.. _`<footer>`: ../ref/doctree.html#footer
+.. _`<header>`: ../ref/doctree.html#header
+.. _`<meta>`: ../ref/doctree.html#meta
+.. _`<pending>`: ../ref/doctree.html#pending
+.. _`<raw>`: ../ref/doctree.html#raw
+.. _`<substitution_definition>`: ../ref/doctree.html#substitution-definition
+.. _`<subtitle>`: ../ref/doctree.html#subtitle
+.. _`<system_message>`: ../ref/doctree.html#system-message
+.. _`<target>`: ../ref/doctree.html#target
+.. _`<title>`: ../ref/doctree.html#title
+.. _`<topic>`: ../ref/doctree.html#topic
+.. _metadata title: ../ref/doctree.html#title-attribute
+
+.. reStructuredText Markup Specification
+.. _bibliographic field:
+.. _bibliographic fields:
+ ../ref/rst/restructuredtext.html#bibliographic-fields
+.. _comments: ../ref/rst/restructuredtext.html#comments
+.. _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:
+ ../ref/rst/restructuredtext.html#bibliographic-field-names
+.. _substitution definitions:
+ ../ref/rst/restructuredtext.html#substitution-definitions
+
+.. transform class sources
+.. _frontmatter:
+ https://docutils.sourceforge.io/docutils/transforms/frontmatter.py
+.. _misc:
+ https://docutils.sourceforge.io/docutils/transforms/misc.py
+.. _parts:
+ https://docutils.sourceforge.io/docutils/transforms/parts.py
+.. _peps:
+ https://docutils.sourceforge.io/docutils/transforms/peps.py
+.. _references:
+ https://docutils.sourceforge.io/docutils/transforms/references.py
+.. _universal:
+ https://docutils.sourceforge.io/docutils/transforms/universal.py
+.. _writer_aux:
+ https://docutils.sourceforge.io/docutils/transforms/writer_aux.py
Modified: trunk/docutils/docutils/transforms/frontmatter.py
===================================================================
--- trunk/docutils/docutils/transforms/frontmatter.py 2024-03-08 23:41:22 UTC (rev 9551)
+++ trunk/docutils/docutils/transforms/frontmatter.py 2024-03-08 23:41:31 UTC (rev 9552)
@@ -3,7 +3,7 @@
# Copyright: This module has been placed in the public domain.
"""
-Transforms related to the front matter of a document or a section
+Transforms_ related to the front matter of a document or a section
(information found before the main text):
- `DocTitle`: Used to transform a lone top level section's title to
@@ -17,6 +17,8 @@
- `DocInfo`: Used to transform a bibliographic field list into docinfo
elements.
+
+.. _transforms: https://docutils.sourceforge.io/docs/api/transforms.html
"""
__docformat__ = 'reStructuredText'
@@ -145,47 +147,24 @@
two-step transform to "raise" or "promote" the title(s) (and their
corresponding section contents) to the document level.
- 1. If the document contains a single top-level section as its
- first non-comment element, the top-level section's title
- becomes the document's title, and the top-level section's
- contents become the document's immediate contents. The lone
- top-level section header must be the first non-comment element
- in the document.
+ 1. If the document contains a single top-level section as its first
+ element (instances of `nodes.PreBibliographic` are ignored),
+ the top-level section's title becomes the document's title, and
+ the top-level section's contents become the document's immediate
+ contents. The title is also used for the <document> element's
+ "title" attribute default value.
- For example, take this input text::
-
- =================
- Top-Level Title
- =================
-
- A paragraph.
-
- Once parsed, it looks like this::
-
- <document>
- <section names="top-level title">
- <title>
- Top-Level Title
- <paragraph>
- A paragraph.
-
- After running the DocTitle transform, we have::
-
- <document names="top-level title">
- <title>
- Top-Level Title
- <paragraph>
- A paragraph.
-
2. If step 1 successfully determines the document title, we
continue by checking for a subtitle.
- If the lone top-level section itself contains a single
- second-level section as its first non-comment element, that
- section's title is promoted to the document's subtitle, and
- that section's contents become the document's immediate
- contents. Given this input text::
+ If the lone top-level section itself contains a single second-level
+ section as its first "non-PreBibliographic" element, that section's
+ title is promoted to the document's subtitle, and that section's
+ contents become the document's immediate contents.
+ Example:
+ Given this input text::
+
=================
Top-Level Title
=================
@@ -195,8 +174,7 @@
A paragraph.
- After parsing and running the Section Promotion transform, the
- result is::
+ After parsing and running the DocTitle transform, the result is::
<document names="top-level title">
<title>
@@ -207,16 +185,13 @@
A paragraph.
(Note that the implicit hyperlink target generated by the
- "Second-Level Title" is preserved on the "subtitle" element
+ "Second-Level Title" is preserved on the <subtitle> element
itself.)
- Any comment elements occurring before the document title or
- subtitle are accumulated and inserted as the first body elements
- after the title(s).
+ Any `nodes.PreBibliographic` instances occurring before the
+ document title or subtitle are accumulated and inserted as
+ the first body elements after the title(s).
- This transform also sets the document's metadata title
- (document['title']).
-
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
"""
@@ -294,12 +269,12 @@
Specification`_ for a high-level description. This transform
should be run *after* the `DocTitle` transform.
- Given a field list as the first non-comment element after the
- document title and subtitle (if present), registered bibliographic
+ If the document contains a field list as the first element (instances
+ of `nodes.PreBibliographic` are ignored), registered bibliographic
field names are transformed to the corresponding DTD elements,
- becoming child elements of the "docinfo" element (except for a
- dedication and/or an abstract, which become "topic" elements after
- "docinfo").
+ becoming child elements of the <docinfo> element (except for a
+ dedication and/or an abstract, which become <topic> elements after
+ <docinfo>).
For example, given this document fragment after parsing::
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