On 2020-02-24, Jan 'oglop' Gazda wrote:
> Hello,
> I've been playing around with a html5 translator for my pelican page and I
> noticed that html5 translator
> (docutils.writers.html5_polyglot.HTMLTranslator) is missing override
> of visit_footnote_reference which adds brackets around the numbers like
> this "Note [1]".
> This looks like a major change (maybe not intentional) but I could not find
> any reference in issues/bug or docs.
It is part of a major change, documented in
https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot
There is no hard-coded formatting information in the HTML document.
Correct rendering of elements not directly supported by HTML depends on
a CSS style sheet.
> So I have a few questions:
> 1) What is the reason for dropping the brackets? (Bug or feature)
The "footnote-references" setting is translated to a class argument by
the "html5_polyglot" writer. The appearance of footnote reference markers
is defined using CSS. The default rules in "minimal.css" define::
a.footnote-reference.brackets:before,
dt.label > span.brackets:before { content: "["; }
a.footnote-reference.brackets:after,
dt.label > span.brackets:after { content: "]"; }
> 2) Would you recommend to use html5 translator or not yet?
This depends on your needs. The html5 writer is supported and ready to be
used but less "road tested". Also, it may still evolve so it may be
necessary to adapt custom style-sheets or define some configuration
setting for full backwards compatibility. For example, we may make use of
the more liberal rules of ID values in HTMTL5 to allow more sensible IDs
of sections with Greek or Russian headings or headings starting with
numbers (https://sourceforge.net/p/docutils/feature-requests/66/).
An overview of the various HTML export options is given in
https://docutils.sourceforge.io/docs/user/html.html
More details and background around the differences between the html4 and
html5 writers can be seen in the commented source
https://docutils.sourceforge.io/docutils/writers/html5_polyglot/__init__.py
> 3) Are there any plans or would devs consider a change or docs website
> style
There are currently no plans for a major revamp. The documentation is
intentionally also a *showcase of Docutil's default output*.
This means that many aspects (fonts, font size, colours) are left at the
browser default settings and comfortable site navigation a la `Sphinx`__ is
not implemented.
OTOH, we are, of course, interested in a good user experience and open
for suggestions to improve.
> - it's really difficult to navigate
> and especially hard to read for people with dyslexia (me)?
Could you elaborate?
You may also consider generating local HTML documentation from the sources
shipped with the Docutils package. This allows using the HTML5 writer as
well as experimenting with the configuration settings or CSS styles.
Thanks,
Günter
__ https://www.sphinx-doc.org
|
