Docutils: Documentation Utilities Code

Revert [r9902] (right align code line numbers with CSS).

The change in [r9902] has the side-effect of a spurious space
before the first line of a code block without line nubers.

Right-aligning via CSS is not required, as line numbers are already
padded by the parser.

Revert.

LaTeX writer: stop requiring "ifthen.sty", fix Babel warning.

Replace use of ``\ifthenelse`` from "ifthen.sty" with the
eTeX primitive ``\ifdefined``.

Mark the main language when loading "babel" to prevent a warning
about another language being processed last. This happens when there
is more than one language in the document as we put the main language
also in the document options (for other packages to see).

Use `nodes.parse_measure()` in rST directive option conversion.

Simplify `parsers.rst.directives.get_measure()` by using
`nodes.parse_measure()`.

Sort the list of supported length units in the order used in the
rST specification (based on the CSS specification).

Update and extend the lenght value handling tests.
Clarify and test behaviour:

* case of length units is preserved (in contrast to CSS)
* the restriction of supported units is a rST feature
while the Docutils Doctree allows any run of ASCII letters + µ
or a percent sign as units on attributes with value type "measure".

Update documentation around length specifications.

ODT writer: report warnings with source line.

Add "base_node" argument to calls of `reporter.warning()` so
that the warning is completed with the source line to blame.

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].