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

[Schimon J. <sc...@fe...>]

Günter. Good day.

Thank you for your elaboration on this concern.

I have responded further.

On Sun, 27 Jul 2025 18:57:56 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

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

Yes. I can so that. I can process it again afterwards.

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

Yes. I suppose, because I attach the output to an XSLT stylesheet, ass
a part of customizing XSLT stylesheets and make them as usuable as so
called "template engines" (e.g. Jinja2).

This is the raw code of the XSLT stylesheet.

<nav id="xslt-navigation-bottom"/>

This is the processed code of the XSLT stylesheet.

<nav id="xslt-navigation-bottom">
  <p>
    <a class="reference external" href="/about" rel="noopener noreferrer">About</a>
    <a class="reference external" href="/about/rss" rel="noopener noreferrer">Atom</a>
    <a class="reference external" href="/v" rel="noopener noreferrer">V</a>
    <a class="reference external" href="/about/xmpp" rel="noopener noreferrer">XMPP</a>
    <a class="reference external" href="/help" rel="noopener noreferrer">Help</a>
  </p>
</nav>

The element "p" is not intended to be included.

https://journal.woodpeckersnest.eu/

So, I resorted to create a CSS rule.

nav p {
  all: unset;
}

https://journal.woodpeckersnest.eu/css/stylesheet.css

As you suggested, post-processing would be a good solution.

> 
> >> 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?
> 

Yes. Precisely, as I have detailed.

> 
> >> 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/
> 

Until recently, I have utilized "html".

I will try "xhtml10" also.

I only need a valid XML output.

> 
> Regards,
> 
> Günter
> 
> 

Thank you,
Schimon