Docutils: Documentation Utilities Code

move manpage image TODO into test_writers/test_manpage

ODT writer: Fix handling of `*.xml` stylesheets.

According to the ODT writer documentation, the "stylesheet" setting
should work with either "styles.odt" or "styles.xml" files.

Fix errors with "*.xml" style files [bugs:#494].
Thanks to Paul Kishimoto for report and analysis.

image enhancement

Document, that type hints use Python 3.10 syntax.

Allow transient elements `<target>` and `<pending>` before a figure `<caption>`.

In rST, the "figure" directive's content must start with a paragraph (that
becomes the caption) or an empty comment (to get a legend without caption).

The change allows passing a "classes" or "names" attribute value to the
figure caption via the "class" directive rsp. an internal hyperlink target.

Change the `references.PropagateTargets` transform to remove a `<target>`
element followed by a `<caption>` (after propagating ids and names)
to keep the doctree valid.

Fix the HTML5 writer, to apply the attributes to the `<figcaption>` element,
(instead of the included `<p>`).

Fix LaTeX writer to handle "classes" and "ids" attributes of a `<caption>`
element.

Add test cases.
Remove misleading test case. Figures without caption are invalid and won't get
a "Figure 1."-style caption with the Docutils writers.

Add internal source and line attributes to more nodes.

The rST parser now also adds internal source and line attributes to
`<compound>`, `<container>`, `<sidebar>`, `<topic>`, `<line_block>`,
and `<line>` nodes.

Based on a pull request by Rob Taylor (on the github mirror) but adding
source and line info instead of the "raw" line number to account for
source parts included with the "include" directive,
also fixing line blocks (both directive and via line-block syntax),
and adding a test case.

See also [feature-requests:#41].

Downgrade "duplicate ID" message from "serious" to "error".

A duplicate ID is not a critical error where the output will
inevitably contain severe errors but rather "a major issue that should
adressed. If ignored, the output will contain unpredictable errors."
(cf. :PEP:`0258` Error Handling).

Re-use `nodes.document.set_id()` in the XML parser, but
only for registering an existing ID, do not generate IDs.

"include" directive: handle duplicate names and IDs in sub-documents

When the :parser: option is specified, the included file is parsed
into a dummy `<document>` and children are appended.
Let internal bookkeeping attributes reference the main document
equivalents, so that element names and IDs share a namespace
with the including document.

Use UNIX-style (LF) line endings

Use custom TypeAlias `StrPath` for `str`-based file system path vars.

Define TypeAlias for "str or os.PathLike" in docutils.nodes
(as this module does not depend on other docutils modules).
Import and use in all places where ``str | os.PathLike`` is expected.

Align formatting, use f-strings where it helps clarity.