Re: [Docutils-users] Setting element "span" instead of element "p"

[Guenter M. <mi...@us...>]

Dear Schimon,

On 2025-07-26, Schimon Jehudah via Docutils-users wrote:
> On Sat, 26 Jul 2025 08:06:50 -0000 (UTC)
> Guenter Milde > wrote:
>> On 2025-07-25, Schimon Jehudah via Docutils-users wrote:

>> > Is it feasible to set the routine (i.e. default) element to "span",
>> > or any other element, instead of element "p"?  

>> Isn't this what XSLT is made for?

> I meant, that the produced output of docutils utilizes the tag "p".

The Docutils HTML writers use the HTML tag <p> for native <pararagraph>
elements, because both are the basic block-level elements.
https://docutils.sourceforge.io/docs/ref/doctree.html#paragraph

Using a HTML <span> instead would mean using a HTML inline element for a
native block element and prevent paragraph separation.
This is something you may do in a custom HTML writer or as a
post-processing with an XSLT stylesheet rule but it seems wrong for
standard HTML output.

What is your problem with paragraphs? Is it about <p> in table cells, list
items etc.?


>> When processing Docutils output with XSLT, you may consider using
>> Docutils native XML format as starting point. HTML is missing several
>> features of Docutils documents (e.g. footnotes) that must be
>> emulated. Starting from Docutils XML saves you from reverse
>> engineering.

>> See https://docutils.sourceforge.io/docs/ref/docutils.dtd
>> and https://docutils.sourceforge.io/docs/ref/doctree.html.

>> ::

>>   from docutils.core import publish_string
>>   publish_string(source="Text with link: https://example.org", 
>>   		 writer_name="xml",
>> 		 settings_overrides={"indents": True, 
>> 		 		     "output_encoding": "unicode"})

>> With the upcoming Docutils 0.22, you will be able to re-read the
>> processed Docutils XML with the "xml" parser and export to all
>> supported formats.


> This is done separately.

> Docutils is utilized to convert reStructuredText to XHTML, and then
> LXML is utilized to incorporate that output to XSLT.

Does this mean you don't transform docutils output *with* some XSLT
stylesheet but transform it *into* an XSLT template?


>> If you want HTML output from Docutils, you may consider the more
>> modern "html5" writer.  Both, the "xhtml" writer and the "html5"
>> writer emit HTML that is also valid XML. However the "xhtml" writer
>> (an alias for "html4css1") is less semantic in its output. 
>> (On the other hand, the "xhtml" writer is more stable, because it is
>> mainly kept for backwards compatibility.)

> I will try the option of XHTML.

Mind, that "xhtml" and "html5" are both aliases for the "html5_polyglot"
writer. It produces HTML5 that is also valid XML.
https://docutils.sourceforge.io/docs/user/html.html#html5

For clarity and brevity, I prefer to call this writer "html5" and its
output "HTML" or "HTML5".

The term "XHTML" is a bit ambiguous, because the legacy `"html4css1" writer`__
(with aliases "html", "html4" and "xhtml10") produces 
`XHTML 1 Transitional`__.

__ https://docutils.sourceforge.io/docs/user/html.html#html4css1
__ https://www.w3.org/TR/xhtml1/


Regards,

Günter