docutils-users — General discussions, questions, help requests.

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

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

On 2025-07-28, Schimon Jehudah wrote:
> On Sun, 27 Jul 2025 Guenter Milde wrote:
>> On 2025-07-26, Schimon Jehudah wrote:
>> > On Sat, 26 Jul 2025 Guenter Milde wrote:  
>> >> On 2025-07-25, Schimon Jehudah wrote:  

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

...

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

This could be merged with the post processing to wrap text spans.
After all, the output of Docutils HTML writers is valid XML but no XSLT ;)

...

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

Using the Docutils writer name "html" or "xhtml10" will make no difference,
both refer to the legacy "html4css1" writer.

> I only need a valid XML output.

Using the writer names "html5" or "xhtml" will also result in valid XML
output. The difference is a more semantic output (more CSS styling
instead of hard-coded layout) and better support for advanced features
like SVG images, math formulas, and video images.


Regards,

Günter

[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

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

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

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

On Sat, 26 Jul 2025 08:06:50 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-07-25, Schimon Jehudah via Docutils-users wrote:
> > Good day.  
> 
> > 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".

> 
> >>>> from docutils.core import publish_parts
> >>>> publish_parts(source="This an XHTML text with a `link
> >>>> <https://movim.eu>`_ for XMPP PubSub",
> >>>> writer_name="xhtml")["fragment\  
> > "]
> > '<p>This an XHTML text with a <a class="reference external"
> > href="https://movim.eu">link</a> for XMPP PubSub</p>\n'  
> 
> 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.

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/interface/http.py
https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/rst.py
https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/parser/xml.py

Should XML output be utilized, would links be realized with the tag "a"?

> 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.)
> 
> Günter
> 

I will try the option of XHTML.

Thank you,
Schimon.

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

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

On 2025-07-25, Schimon Jehudah via Docutils-users wrote:
> Good day.

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


>>>> from docutils.core import publish_parts
>>>> publish_parts(source="This an XHTML text with a `link <https://movim.eu>`_ for XMPP PubSub", writer_name="xhtml")["fragment\
> "]
> '<p>This an XHTML text with a <a class="reference external" href="https://movim.eu">link</a> for XMPP PubSub</p>\n'

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.



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

Günter

Re: [Docutils-users] XSLT

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

Greetings.

I am answering to myself.

This code works, and the results are good, despite the lack of the
desired element </xsl:text>.

--- BEGIN PYTHON CODE ---

from docutils.core import publish_parts
import lxml.etree as ET

class UtilityRst:

    def convert_to_html(rst_content_str):
        html_content_str = publish_parts(source=rst_content_str,
                                         writer_name="html")
        return html_content_str["fragment"]

class ParserXml:

    def append_xhtml_to_xslt(filepath_xslt, filepath_rst):
        document_xslt = ET.parse(filepath_xslt)

        rst_content_str = open(filepath_rst, mode="r").read()
        xhtml_content_str = UtilityRst.convert_to_html(rst_content_str)
        lines = rst_content_str.split("\n")
        for line in lines:
            if line.startswith(".. xpath"):
                expression_xpath = line.split(": ")[1]
                break

        element_xml = document_xslt.xpath(expression_xpath)
        if element_xml:
            subelement = ET.fromstring(xhtml_content_str)
            element_xml[0].append(subelement)
        document_xslt.write(filepath_xslt, pretty_print=True)

--- END PYTHON CODE ---

This code will be featured in project Rivista (Vivista).

https://git.xmpp-it.net/sch/Rivista (Current brand)

https://git.xmpp-it.net/sch/Vivista (Future brand)

Kind regards,
Schimon


On Thu, 24 Jul 2025 04:22:15 +0300
Schimon Jehudah via Docutils-users
<doc...@li...> wrote:

> Greetings.
> 
> I am working to create a publishing system which is enntirely based on
> XML (Atom Syndication Format) with XSLT stylesheets to transform XML
> to XHTML.
> 
> 
> Preface
> -------
> 
> XSLT stylesheets are utilized instead of templating engines (e.g.
> Jinja2), in order to generalize theming systems for CMS and other
> types of publishing platforms.
> 
> However, modifying of XSLT for navigation links is essential for this
> idea to succeed.
> 
> 
> Concern
> -------
> 
> While adding plain text, as is, should be workable, I would rather
> enclose text within tag </xsl:text>, if possible.
> 
> <xsl:text>This an</xsl:text>
> <xsl:text> </xsl:text>
> <a href="?xml">Atom Syndication Format</a>
> <xsl:text> </xsl:text>
> <xsl:text>document which was transformed to HTML with</xsl:text>
> <xsl:text> </xsl:text>
> <a href="/about/xslt">XSLT stylesheets</a>
> 
> 
> Questions
> ---------
> 
> Is this possible to do with docutils?
> 
> Would it applicable to ask for such feature?
> 
> 
> Kind regards,
> Schimon
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

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

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

Good day.

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

>>> from docutils.core import publish_parts
>>> publish_parts(source="This an XHTML text with a `link <https://movim.eu>`_ for XMPP PubSub", writer_name="xhtml")["fragment\
"]
'<p>This an XHTML text with a <a class="reference external" href="https://movim.eu">link</a> for XMPP PubSub</p>\n'

Kind regards,
Schimon

[Docutils-users] XSLT

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

Greetings.

I am working to create a publishing system which is enntirely based on
XML (Atom Syndication Format) with XSLT stylesheets to transform XML to
XHTML.


Preface
-------

XSLT stylesheets are utilized instead of templating engines (e.g.
Jinja2), in order to generalize theming systems for CMS and other
types of publishing platforms.

However, modifying of XSLT for navigation links is essential for this
idea to succeed.


Concern
-------

While adding plain text, as is, should be workable, I would rather
enclose text withing tag </xsl:text>, if possible.

<xsl:text>This an</xsl:text>
<xsl:text> </xsl:text>
<a href="?xml">Atom Syndication Format</a>
<xsl:text> </xsl:text>
<xsl:text>document which was transformed to HTML with</xsl:text>
<xsl:text> </xsl:text>
<a href="/about/xslt">XSLT stylesheets</a>


Questions
---------

Is this possible to do with docutils?

Would it applicable to ask for such feature?


Kind regards,
Schimon

Re: [Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <vik...@gm...>]

Hello Guenter,

Am Mo., 21. Juli 2025 um 19:49 Uhr schrieb Guenter Milde via Docutils-users
<doc...@li...>:

> ...
> On 2025-06-30, Viktor Ransmayr wrote:
> ...
> >   test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name:
> "k4-l4mk7qa".
>
> > For me it is not clear, if the second mailarchive URI really does
> 'violate'
> > the reStructuredText Markup Specification - or - if it is a 'docutils'
> > issue.
>
> The parsing result conforms with the reStructuredText specification
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html.
>
> Why?
> ====
>
> Let us simplify the example to the two paragraphs::
>
>   works: https://example.org/msg/TljW9V_sIzQJ1PpO4axkKmiWCZI/
>
>   fails: https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/
>
> Each paragraph is parsed for *inline markup*.  According to the
> `recognition order`_ standalone hyperlinks are last to be recognised.
> I.e., before looking for an URI, the paragraph is checked for emphasis,
> literals, ..., hyperlink references, and interpreted text.
>
> The second URI contains inline markup consistent with the
> `hyperlink reference`_ "k4-l4mk7qa".
>
> Unfortunately, the `inline markup recognition rules`_ are rather complex.¹
>
> * A hyperlink reference has no start-string and the end-string "_".
>
> * end-strings must end the text block or be followed by whitespace or
>   punctuation (ASCII characters - : / ' " < ( [ { or similar non-ASCII
>   characters).
> ...
>
> Workarounds
> ===========
>
> escape_ the underscore:
>   https://example.org/msg/k4-L4mK7Qa\_-F3svmF6uFKKPZ6I/
>
> Mark up as hyperlink reference with `embedded URI`_::
>
>   `<https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/>`__
>
> Wrapping in angle brackets helps for standalone hyperlinks with trailing
> punctuation like <https://example.org/msg.> but does not help with
> underscores.
> ...


Thanks a lot for your detailled answer & the two workarounds !

With kind regards,

Viktor

Re: [Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

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

Dear Viktor,

welcome to the list and thanks for your feedback.

On 2025-06-30, Viktor Ransmayr wrote:

...
> I noted issues with certain IETF mailarchive URIs already a while ago - but
> - only now took the time to follow up & create a simple test file (see
> attachment) demonstrating the issue.

> This file contains two IETF mailarchive URI instances. - The first one is
> processed without an issue - and - the second one is processed with an
> error.

...

>   test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name: "k4-l4mk7qa".

> For me it is not clear, if the second mailarchive URI really does 'violate'
> the reStructuredText Markup Specification - or - if it is a 'docutils'
> issue.

The parsing result conforms with the reStructuredText specification
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html.


Why?
====

Let us simplify the example to the two paragraphs::

  works: https://example.org/msg/TljW9V_sIzQJ1PpO4axkKmiWCZI/

  fails: https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/

Each paragraph is parsed for *inline markup*.  According to the
`recognition order`_ standalone hyperlinks are last to be recognised.
I.e., before looking for an URI, the paragraph is checked for emphasis,
literals, ..., hyperlink references, and interpreted text.

The second URI contains inline markup consistent with the
`hyperlink reference`_ "k4-l4mk7qa".

Unfortunately, the `inline markup recognition rules`_ are rather complex.¹

* A hyperlink reference has no start-string and the end-string "_".

* end-strings must end the text block or be followed by whitespace or
  punctuation (ASCII characters - : / ' " < ( [ { or similar non-ASCII
  characters).

  In the working example, the underscore is followed by a letter, so it is
  not recognised as a hyperlink reference end-string.

  In the failing example, the underscore is followed by "-", so it is
  interpreted as end-string of a simple hyperlink reference.

  The text from "/" to "_" forms the `simple reference name`_ "k4-l4mk7qa".
  (The "violation" of proper rST syntax is, that there is no matching
  target_.)²

In the first URI, the "random" directory name ``TljW9V_sIzQJ1PpO4axkKmiWCZI/``
contains an underscore, too.
However, it is not recognised as inline markup end-string, because it
is followed by a letter.


Workarounds
===========

escape_ the underscore:
  https://example.org/msg/k4-L4mK7Qa\_-F3svmF6uFKKPZ6I/

Mark up as hyperlink reference with `embedded URI`_::

  `<https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/>`__

Wrapping in angle brackets helps for standalone hyperlinks with trailing
punctuation like <https://example.org/msg.> but does not help with
underscores.


I hope this helps to understand and work around the problem,

Günter



¹They were devised to allow 90% of non-markup uses of *, `, _, and |
without escaping.

²After parsing, the first paragraph contains:

 * the text "fails: ",
 * a reference to "https://example.org/",
 * the nonfunctional reference to the internal target "k4-l4mk7qa",
 * and the text "-F3svmF6uFKKPZ6I/".


.. _recognition order:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#recognition-order
.. _inline markup recognition rules:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules
.. _simple reference name:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-reference-names
.. _target:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets
.. _escape:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
.. _embedded URI:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Re: [Docutils-users] HTML only output

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

On 2025-07-14, Schimon Jehudah via Docutils-users wrote:
> Good day.

> I am interested to know whether it is possible to output an HTML code,
> preferably XHTML formatted, without elements "head" nor "body".

Yes, this is easily possible with the "publish_parts()" function.
https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts
(The "html_body" part is the <body> content.)

Both, the "html4css1" writer and the "html5" writer export valid XML.

Günter

Re: [Docutils-users] Audio tag

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

On 2025-07-18, Schimon Jehudah via Docutils-users wrote:
> Good afternoon.

> Is there any intention to add more tags, such as audio and video?

> I did read the object and video reference.

> https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-reference-1

> I do know that it is possible to add raw HTML code.

> https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through

> I think, that having these settled more explicitly would be best,
> especially for Atom/RSS attachments (i.e. enclosures).

> Please advise.

It seems you are looking at reStructuredText as a kind of 
"HTML-input-language".
However, the underlying document model differs from HTML in both, element
set and structure: https://docutils.sourceforge.io/docs/ref/doctree.html.
While reStructuredText documents can be converted to HTML, this is not the
only output format.

There is no plan to provide input methods for every HTML element/tag in
"stock rST".
Especially not for elements that do not have an analogon in other supported
output formats like LaTeX/PDF, ODT, or man pages (roff).

OTOH, there is this syntax construct called "directive"
(https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives)
whith a set of widely supported standard directives
(https://docutils.sourceforge.io/docs/ref/rst/directives.html).
These include a directive to include images into the output document, as
images are widely used to aide in documentation and supported by most output
formats (with limitations). For HTML, this includes moving images.

Directives are an extension mechanism, so applications can add their own
directives (see, e.g. Sphinx for a large set of additional directives).
The downside is, that documents using custom directives cannot be handled by
the "vanilla" Docutils tools.

Günter

Re: [Docutils-users] Enclosure directive for reStructuredText

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

Good evening.

Never mind. Please ignore my message.

I am attempting to create an Atom Syndication Format based content
management system (i.e. static site generator), and I have mixed RST
with XML.

Also, I can add attribute "class" to elements which I want to be of
enclosure or anything else.

This is a concern of software-level.

Regards,
Schimon

On Sat, 19 Jul 2025 16:40:53 +0200
Marc Rintsch <ma...@ri...> wrote:

> On 18.07.25 15:57, Schimon Jehudah via Docutils-users wrote:
> > Should reStructuredText have a directive for enclosures?
> > 
> > It is possible to scan HTML code for potential attachments (e.g.
> > torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an
> > explicit directive to indicate of a media which is intended to be
> > realized as an attachment.  
> 
> I'm a bit puzzled what is meant by the terms „enclosure“ and 
> „attachment“ here.  That's not really terminology used in 
> reStructuredText or HTML.
> 
> Ciao,
> 	Marc 'BlackJack' Rintsch

Re: [Docutils-users] Enclosure directive for reStructuredText

[Marc R. <ma...@ri...>]

On 18.07.25 15:57, Schimon Jehudah via Docutils-users wrote:
> Should reStructuredText have a directive for enclosures?
> 
> It is possible to scan HTML code for potential attachments (e.g.
> torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an
> explicit directive to indicate of a media which is intended to be
> realized as an attachment.

I'm a bit puzzled what is meant by the terms „enclosure“ and 
„attachment“ here.  That's not really terminology used in 
reStructuredText or HTML.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
Norton SystemWorks 2002 includes a file erasure program called
Wipe Info. In the manual (page 160), we learn that “Wipe Info uses
hexadecimal values to wipe files.  This provides more security than
wiping with decimal values.”  Who writes this stuff?
                                    -- Bruce Schneier in CRYPTO-GRAM

[Docutils-users] Enclosure directive for reStructuredText

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

Good afternoon.

Should reStructuredText have a directive for enclosures?

It is possible to scan HTML code for potential attachments (e.g.
torrent, ipfs, magnet, ogg, etc.), yet it might be better to have an
explicit directive to indicate of a media which is intended to be
realized as an attachment.

Perhaps a value for attribute "class" would be more appropriate.

Please advise.

Kind regards,
Schimon

[Docutils-users] Audio tag

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

Good afternoon.

Is there any intention to add more tags, such as audio and video?

I did read the object and video reference.

https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-reference-1

I do know that it is possible to add raw HTML code.

https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through

I think, that having these settled more explicitly would be best,
especially for Atom/RSS attachments (i.e. enclosures).

Please advise.

Kind regards,
Schimon

[Docutils-users] [SPAM] Re: HTML only output

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

Alan. Good evening.

Thank you very much!

https://git.xmpp-it.net/sch/Rivista/commit/9f422a8813e467db5ae62e850c660d02c0601e45

Respectfully,
Schimon

On Mon, 14 Jul 2025 09:28:14 -0400
Alan <ala...@gm...> wrote:

> Here is what (free) Copilot says.
> 
> [image: image.png]
> 
> On Mon, Jul 14, 2025 at 8:30 AM Schimon Jehudah via Docutils-users <
> doc...@li...> wrote:
> 
> > Good day.
> >
> > I am interested to know whether it is possible to output an HTML
> > code, preferably XHTML formatted, without elements "head" nor
> > "body".
> >
> > I am working with Atom Syndication Format and XSLT, and therefore,
> > I am not interested in creating elements "head" or "body", because
> > XSL Transformations already does the XHTML task.
> >
> > Kind regards,
> > Schimon
> >
> >

Re: [Docutils-users] HTML only output

[Alan <ala...@gm...>]

Here is what (free) Copilot says.

[image: image.png]

On Mon, Jul 14, 2025 at 8:30 AM Schimon Jehudah via Docutils-users <
doc...@li...> wrote:

> Good day.
>
> I am interested to know whether it is possible to output an HTML code,
> preferably XHTML formatted, without elements "head" nor "body".
>
> I am working with Atom Syndication Format and XSLT, and therefore, I am
> not interested in creating elements "head" or "body", because XSL
> Transformations already does the XHTML task.
>
> Kind regards,
> Schimon
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] HTML only output

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

Good day.

I am interested to know whether it is possible to output an HTML code,
preferably XHTML formatted, without elements "head" nor "body".

I am working with Atom Syndication Format and XSLT, and therefore, I am
not interested in creating elements "head" or "body", because XSL
Transformations already does the XHTML task.

Kind regards,
Schimon

Re: [Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <vik...@gm...>]

Hello Docutils Community,

Am Mo., 30. Juni 2025 um 13:44 Uhr schrieb Viktor Ransmayr <
vik...@gm...>:

> Hello Docutils Community,
>
> I use 'docutils' to organize my notes as HTML files - and - store links
> for later review.
>
> I noted issues with certain IETF mailarchive URIs already a while ago -
> but - only now took the time to follow up & create a simple test file (see
> attachment) demonstrating the issue.
>
> This file contains two IETF mailarchive URI instances. - The first one is
> processed without an issue - and - the second one is processed with an
> error. - That is, when I create the HTML file I receive the following
> 'Docutils System Message':
>
> ###
>
> [user@fedora-python-study-vm vransmayr]$
> [user@fedora-python-study-vm vransmayr]$ docutils test-IETF-URI-issue.rst
> test-IETF-URI-issue.html
> test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name: "k4-l4mk7qa".
> [user@fedora-python-study-vm vransmayr]$
>
> ###
>
> For me it is not clear, if the second mailarchive URI really does
> 'violate' the reStructuredText Markup Specification - or - if it is a
> 'docutils' issue.
>
> Looking forward to your feedback !
>
> With kind regards,
>
> Viktor
>
> PS: This issue occurs in docutils version 0.21.2 as well as 0.22rc5 ...
>

For easier access: Here's the created HTML file as well.

With kind regards,

Viktor

[Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <vik...@gm...>]

Hello Docutils Community,

I use 'docutils' to organize my notes as HTML files - and - store links for
later review.

I noted issues with certain IETF mailarchive URIs already a while ago - but
- only now took the time to follow up & create a simple test file (see
attachment) demonstrating the issue.

This file contains two IETF mailarchive URI instances. - The first one is
processed without an issue - and - the second one is processed with an
error. - That is, when I create the HTML file I receive the following
'Docutils System Message':

###

[user@fedora-python-study-vm vransmayr]$
[user@fedora-python-study-vm vransmayr]$ docutils test-IETF-URI-issue.rst
test-IETF-URI-issue.html
test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name: "k4-l4mk7qa".
[user@fedora-python-study-vm vransmayr]$

###

For me it is not clear, if the second mailarchive URI really does 'violate'
the reStructuredText Markup Specification - or - if it is a 'docutils'
issue.

Looking forward to your feedback !

With kind regards,

Viktor

PS: This issue occurs in docutils version 0.21.2 as well as 0.22rc5 ...

[Docutils-users] docutils 0.22rc5 release

[engelbert g. <eng...@gm...>]

Hei everyone,

only one change:

 Don't report an error for duplicate targets with identical refname

all the best
 e

[Docutils-users] release plan 0.22

[engelbert g. <eng...@gm...>]

Hei everyone,

today june 17th rc4 is out.

the final 0.22 is scheduled for end of july, start of august.

cheers
 e

[Docutils-users] docutils 0.22rc4

[engelbert g. <eng...@gm...>]

Hei everyone,

next pre-release,

This release often works in clarifying things, thanks to all the testers
and many thanks to Günter for the work.

Changes that should be run through pre-release

* Drop the "name" option of the "target-notes" directive. (Report an
  error instead of silently ignoring the value.)

* New alias "rst-class" for the "class" directive to improve the
  compatibility with Sphinx.

* "Downgrade" targets generated from hyperlink references with embedded
  URI or alias from explicit to implicit (i.e. similar to the targets for
  sections, see implicit hyperlink targets for details).

thanks for your patience and help
 e

[Docutils-users] docutils 0.22rc3 is out

[engelbert g. <eng...@gm...>]

Hei

minimal changes and fixes

manpage writer no longer drops the text of internal targets

0.22 in one week ... if ... :-)

cheers and thanks to günter
 e