Docutils: Documentation Utilities Code

Revise/fix handling of length specification in the ODT writer.

Use "px" as fallback unit for unitless image size attributes.

Fix conversion factor of "pc" (pica) to "cm".

Fix conversion of image width in "%" if the height is specified.

Adjust fallback DPI value (currently not used) to match CSS units.

Document that PIL/Pillow is always required if images are inserted
without specifying width and height, also if "scale" is not used.

Revise/fix handling of length specifications.

Don't use the generic number-formatter "g" to drop trailing zeroes
in `nodes.validate_measure()` to avoid writing large values in
scientific format (which is not supported in reStructuredText).
Instead, `nodes.parse_measure()` returns an `int` if possible so that
converting to `str` does not add a trailing zero in the first place.

Refactor `writers._html_base.HTMLTranslator.image_size()`.
(Using the "g"-formatter in the HTML writer is no problem, as the
scientific format is valid in CSS and "style" attribute values.)

Simplify `writers.latex2e.LaTeXTranslator.to_latex_length()`:
Use `nodes.parse_measure()`.
Move XeTeX-specific code to the "XeTeX" writer.
Drop trailing zeroes.
(Using "g" with percentage values is considered safe, as a "width"
value larger than 10 000 000 % leads to output problems anyway.)

HTML writers: Add "px" to unitless table "width" values.

The table "width" attribute is of type "length", with optional unit.
The writers must ensure there is a unit when converting a length to
a HTML "style" attribute rule.
For HTML writers, the default length unit is "px".

Use "unknown_reference_resolver" for LaTeX writer option "use-bibtex".

The "latex" writer provides the (provisional) setting "use_bibtex" to defer
the resolution of citation references to the backend (LaTeX/BibTeX/LaTeX).

Use the `unknown_reference_resolvers` hook of the `TransformSpec` to
mark citation references as resolved if BibTeX is used.

Advantages:

* replaces hard-coded special-case in
`transforms.references.DanglingReferencesVisitor` introduced in [r9312],
* provides a usage example,
* tests the hook with the Docutils test suite without additional overhead.

Update docstrings and comments.

Fix test_writers html4css when PIL is installed.

Fixup for [r9924].

HTML5: use "width" and "height" for unitless image size values.

Fixes [feature-requests:#102]

The HTML `<img>` element supports "width" and "height" attributes to
specify the size or ratio of an image. Values are restricted to
integers (size in pixels).

In Docutils, "width" and "hight" attributes also support a set of CSS
compatible units. Therefore, all size values were passed to HTML via
the common attribute "style".

Using HTML "width" and "hight" attributes for values without unit
provides a means to specify an image's *aspect ratio* without overriding
a size declaration in a CSS style sheet.

This change is not backported to the "html4css1" writer to keep
the output backwards compatible.

The provisional method `HTMLTranslator.image_size()` now returns a
dictionary of attribute values.

Fix test samples containing installation-specific path.

Use a relative path in the tests for external MathML converters
to make tests independent of the installation-specific
Docutils project root directory.

Fixes for "scale" attribute handling in ODT and LaTeX writer.

Remove redundant code in the ODT writer:
Scale is validated as "non-negative integer" by the parser.
No need to validate again.

Use the "generic" numeral format instead of "float"
in the LaTeX writer (%f -> %g).

late commit to rename .txt to .rst

FIX test_writers html4css when PIL is not installed