New XHTML 1.1. writer in Docutils

[Guenter Milde]

Dear Sphinx developers,

since start of the week, Docutils 0.13 [repository] has a
new HTML writer that outputs XHTML 1.1 styled with CSS2.
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/xhtml11

This writer started as `HTML-strict writer` in the docutils sandbox__.

__ http://docutils.sourceforge.net/sandbox/

It complements the current standard HTML writer "html4css1" with its
hacks around problems of IE6 (at the time of its writing the most-used
internet browser with a market share around 90%) and "hardcoded"
formatting due to the limitations of CSS1.

Changes to and and advantages over the html4css1 writer are discussed in
the README__

__ http://docutils.sourceforge.net/sandbox/html4strict/


As Sphinx subclasses the Docutils HTML writer, it would be interesting to
see it cooperate with the xhtml11 writer. A configuration setting to
choose the writer would be good.

There may be the need for further adaption to changed methods in the
HTMLTranslator as well as to the new default stylesheet
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/xhtml11/xhtml11.css


Günter

[Takayuki Shimizukawa]

Hi Günter,

Thanks for the introduction!

As you mentioned, a configuration settings would be good.

I'm looking forward to using new docutils :)

OTOH, recently we are requested a HTML5 writer/translator too.

I think the docutils new HTML writer would be base class for HTML5 writer or its implementation would be a useful reference for HTML5 writer.

 

Günter

Regards,

--

Takayuki SHIMIZUKAWA

http://about.me/shimizukawa 

[Guenter Milde]

On 2015-02-27, Takayuki Shimizukawa wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

There is a HTML5 compatible writer in Docutils (repository) now as well.

http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/
docutils/docutils/writers/html_base/

This can become the basis of an additional HTML5 writer, if there is need
for more specific HTML 5 support.

The "html-base" writer will keep compatibility with HTML4.1/XHTML1 and it
is planned to make it the new default "html" writer in one of the next
releases.

Günter

[Tony Narlock]

Günter,

Nice to see you here. It's a small world.  I'm look forward to seeing your HTMLWriter in the next docutils release. The output is much better!

[anatoly techtonik]

Yes, please. Absense of HTML5 makes Sphinx customization pretty limited.

Also, is it possible to make markup of parent elements independent on their

child? While styling it gives a headache when markup starts depend on the

content.

Here is one case http://permalink.gmane.org/gmane.text.docutils.devel/5982

[Guenter Milde]

On 2015-05-26, anatoly techtonik wrote:
> On Tuesday, March 17, 2015 at 10:07:25 AM UTC+3, Guenter Milde wrote:
>> On 2015-02-27, Takayuki Shimizukawa wrote:
>> > On Wed Feb 25 2015 at 17:57:58 Guenter Milde <mi...@users.sf.net wrote:

>> >> Dear Sphinx developers,

>> >> since start of the week, Docutils 0.13 [repository] has a
>> >> new HTML writer that outputs XHTML 1.1 styled with CSS2.
>> >> http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/
>> >> docutils/docutils/writers/xhtml11

...

>> >> As Sphinx subclasses the Docutils HTML writer, it would be
>> >> interesting to see it cooperate with the xhtml11 writer. A
>> >> configuration setting to choose the writer would be good.

...

>> > OTOH, recently we are requested a HTML5 writer/translator too.

...

>> There is a HTML5 compatible writer in Docutils (repository) now as well.

>> http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/
>> docutils/docutils/writers/html_base/

BTW: the directory name of this writer will change.
However, it would be good if to-be-implemented Sphinx config setting
used the "get_writer_by_name" method provided by Docutils - the
alias names "html5" and "xhtml" will probabely stay.

>> This can become the basis of an additional HTML5 writer, if there is need
>> for more specific HTML 5 support.

> Yes, please. Absense of HTML5 makes Sphinx customization pretty limited.

Can you be more specific, please? Where would HTML5 be better configurable
than XHTML1.1?

> Also, is it possible to make markup of parent elements independent on their
> child? While styling it gives a headache when markup starts depend on the
> content.

> Here is one case http://permalink.gmane.org/gmane.text.docutils.devel/5982

The new html writer(s) do not change the basic behaviour: just like the
current writer there is an option to style a list differently depending
on "compactness".

However, this is fully configurable (also with the current html writer)
via a Docutils configuration setting or via custom CSS. This is why the
referenced bug report is closed as invalid. For details see my reply to
the bug report.

One problem is, that the Sphinx documentation does not reveal how to set
Docutils configuration settings.

Relevant settings in `Docutils configuration files`__ are fully
considered by the Docutils parser, transforms and writer(s) used by
Sphinx "under the hood".

__ http://docutils.sourceforge.net/docs/user/config.html#configuration-files


Regards

Günter

[anatoly techtonik]

On Thu, May 28, 2015 at 4:05 PM, Guenter Milde <mi...@users.sf.net> wrote:
>
>>> This can become the basis of an additional HTML5 writer, if there is need
>>> for more specific HTML 5 support.
>
>> Yes, please. Absense of HTML5 makes Sphinx customization pretty limited.
>
> Can you be more specific, please? Where would HTML5 be better configurable
> than XHTML1.1?

Configurable? HTML5 is for humans. Designers and journalists are being
taught web design and markup in HTML5. You need to read the first 200
pages of the book about XML to understand what the XHTML doctype really
mean. HTML5 is more simple - it is just about markup for the web.

http://www.dummies.com/how-to/content/the-relationship-between-html5-and-xhtml.html

You don't want t XSLT stylesheets for the doctools output, do you? Then
why do you need XHTML?

>> Also, is it possible to make markup of parent elements independent on their
>> child? While styling it gives a headache when markup starts depend on the
>> content.
>
>> Here is one case http://permalink.gmane.org/gmane.text.docutils.devel/5982
>
> The new html writer(s) do not change the basic behaviour: just like the
> current writer there is an option to style a list differently depending
> on "compactness".
>
> However, this is fully configurable (also with the current html writer)
> via a Docutils configuration setting or via custom CSS. This is why the
> referenced bug report is closed as invalid. For details see my reply to
> the bug report.
>
> One problem is, that the Sphinx documentation does not reveal how to set
> Docutils configuration settings.
>
> Relevant settings in `Docutils configuration files`__ are fully
> considered by the Docutils parser, transforms and writer(s) used by
> Sphinx "under the hood".
>
> __ http://docutils.sourceforge.net/docs/user/config.html#configuration-files

The problem is that rare people understand where docutils configuration is,
what is needed to be set to get consistent markup, and there is usually no
time to grok on that.

It will really help people (especially those without rich Python/docutils/reST
background) who are asked to do styles for the docs if the output from Sphinx
html5 is predictable 1:1 mapping of elements that don't try to be too smart
and leave the hard job of styling what is got there to CSS + JS.

--
anatoly t.

[Guenter Milde]

On 2015-05-28, anatoly techtonik wrote:
> On Thu, May 28, 2015 at 4:05 PM, Guenter Milde <mi...@users.sf.net> wrote:

>>>> This can become the basis of an additional HTML5 writer, if there is need
>>>> for more specific HTML 5 support.

>>> Yes, please. Absense of HTML5 makes Sphinx customization pretty limited.

>> Can you be more specific, please? Where would HTML5 be better configurable
>> than XHTML1.1?

> Configurable?

Customizable, to use the term you introduced. However, I cannot see the
connection between (X)HTML version and Sphinx customization.

> HTML5 is for humans.

... but Docutils/Sphinx is a program that can easily translate a markup
language that is even more suited for input by humans (rST) into both,
valid HTML and XHTML.

> http://www.dummies.com/how-to/content/the-relationship-between-html5-and-xhtml.html

The arguments in favour of HTML over XHTML don't hold if you generate the
document from another language.

The the new Docutils HTML writer implements the strict content/layout
separation for HTML as well as XHTML.

Customization/Layout/Styling is done via CSS and does not depend
on the HTML/XHTML version.

Easier parsing and machine-processing is the advantage of XML that comes at
no cost with Docutils.

> You don't want t XSLT stylesheets for the doctools output, do you?

Well, the only existing rst2rst converter uses XSLT and the native
DocutilsXML.

>>> Also, is it possible to make markup of parent elements independent on their
>>> child? While styling it gives a headache when markup starts depend on the
>>> content.

>>> Here is one case http://permalink.gmane.org/gmane.text.docutils.devel/5982

>> The new html writer(s) do not change the basic behaviour: just like the
>> current writer there is an option to style a list differently depending
>> on "compactness".

>> However, this is fully configurable (also with the current html writer)
>> via a Docutils configuration setting or via custom CSS. This is why the
>> referenced bug report is closed as invalid. For details see my reply to
>> the bug report.

>> One problem is, that the Sphinx documentation does not reveal how to set
>> Docutils configuration settings.

>> Relevant settings in `Docutils configuration files`__ are fully
>> considered by the Docutils parser, transforms and writer(s) used by
>> Sphinx "under the hood".

>> __ http://docutils.sourceforge.net/docs/user/config.html#configuration-files

> The problem is that rare people understand where docutils configuration is,
> what is needed to be set to get consistent markup, and there is usually no
> time to grok on that.

This is a pity and a problem of Sphinx: it uses a complex tool under the
hood and adds more complexity in the

> It will really help people (especially those without rich
> Python/docutils/reST background) who are asked to do styles for the
> docs if the output from Sphinx html5 is predictable 1:1 mapping of
> elements that don't try to be too smart and leave the hard job of
> styling what is got there to CSS + JS.

Also the new writer (both xhtml and html5) will have different spacing
for compact and open lists but this is implemented via a class argument
and the default CSS rules. So it can be configured just as easy and maybe a
bit more straigthforward by just looking into the CSS style sheet.

Günter