docutils-develop Mailing List for Docutils: Documentation Utilities (Page 9)

your delay is no problem for me ... mine is


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Wed Mar 19, 2025 05:21 PM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Dear Günter, Engelbert, all,

[Engelbert]
> adam should get a invitaionfrom pypi.

Thank you! I have accepted the invitation. Please could you also add me to the Docutils project on Test PyPI? [1]

[Engelbert]
> maybe we might put out more betas, for users to try before a release, if they are not developers this might help.

I agree.

[Günter]
> Feel free to commit small, non-controversial changes right away
> (bit for bit, so that I can have a look) and discuss the complex and
> ambiguous ones either on this list, in private mail or the project tickets.

I have made a series of commits starting at [r10019] through to [r10048]. The most notable is [r10043], which removes type annotations for ``docutils.nodes.Node``, as I would like more time to research what the ideal type annotations are, and talk to some static typing experts. Other than that, the commits are mainly small clean-ups, test fixes, etc.

[Günter]
> What would be your proposed timeframe? (I will be offline next week.)

I think we could publish a beta/release candidate at any point, but I have no strong views. I'm also not in any hurry to do so.

[Günter]
> We should try to solve the deprecation warnings. There should be a
> documented way forward, if not, report back and well find a solution
> (as a last restort, we'll turn them into pending deprecation warnings).

You can inspect the deprecation warnings on GitHub [2] (expand the "test with pytest" tab). These are::

    DeprecationWarning: Argument "parser_name" will be removed in Docutils 2.0.
      Specify parser name in the "parser" argument.
      reader: Reader[DocTreeInput] = docutils.readers.doctree.Reader(

    DeprecationWarning: The auxiliary function roles.set_classes() is obsoleted by roles.normalize_options() and will be removed in Docutils 1.0
      set_classes(self.options)

The ``set_classes()`` function is somewhat frequently used [3] and the replacement is very new. Perhaps we should delay the deprecation and use a PendingDeprecationWarning? Likewise with the 'parser_name' argument, support for strings in 'parser' is not yet released, and removal is planned for 2.0, so perhaps we should start with a PendingDeprecationWarning?

[Günter]
> Could you also test building a typical Sphinx doctree with the new
> "validate__" parser setting set to True?
> There may be problems with the custom nodes added by Sphinx.
> (The setting was added due to a feature-request by a Sphinx-extension
> developer.)
>
> __ https://docutils.sourceforge.io/docs/user/config.html#validate

I haven't had time to do so yet, but I will try at some point.

Thanks,
Adam

[1] https://test.pypi.org/project/docutils/
[2] https://github.com/sphinx-doc/sphinx/actions/runs/13728707556/job/38401038459
[3] https://github.com/search?q=%2Fdocutils%5C..*set_classes%2F+language%3APython+NOT+is%3Aarchived++NOT+is%3Afork&type=code

Dear Adam, Engelbert, docutils developers,

back from the winter holidays...

On 2025-02-22, Adam Turner wrote:

>> how about releasing 0.22?

> Sounds good! I want to review the situation around type annotations
> before releasing, and I might revert some of the changes I have made.
> There are also a few updates to the packaging metadata we can take the
> opportunity to make before releasing.

Fine. Feel free to commit small, non-controversial changes right away
(bit for bit, so that I can have a look) and discuss the complex and
ambiguous ones either on this list, in private mail or the project tickets.
What would be your proposed timeframe? (I will be offline next week.)

>> IMO, we should start with a beta release, to give downstream users an easy
>> chance to test without breaking installations with `pip` auto-updates.

> Sphinx 8.2. (released last week) is fully compatible with Docutils
> master (although there are some deprecation warnings). 

We should try to solve the deprecation warnings. There should be a
documented way forward, if not, report back and well find a solution 
(as a last restort, we'll turn them into pending deprecation warnings).

Could you also test building a typical Sphinx doctree with the new
"validate__" parser setting set to True?
There may be problems with the custom nodes added by Sphinx.
(The setting was added due to a feature-request by a Sphinx-extension
developer.)

__ https://docutils.sourceforge.io/docs/user/config.html#validate

> I think we can request that other projects test a release candidate, as
> with previous releases.

I have no strong preference whether we call the next release 0.22rc1 or
0.22b1. (It depends on the probability of pending non-trivial changes.)

> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.

Could you co-ordinate this with Engelbert, please?

> I can probably also co-ordinate with the downstream projects, should
> this be useful.

Thanks for the offer. For projects where the contact is via github, this
may be helpfull.

sincerely,

Günter

not yet released you are correct

i did the processing with option --macro-references 
and get the attached file

the problem i have, aside from blanks and new lines, with this is

viewed with man uris are not shown and might be clickable on some systems
lost on others, like mine
that is why i did the rendering in the manpage-writer and set it as default.

on it, cheers


Attachments:

- [authors-urue.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/9b01/dc49/attachment/authors-urue.man) (1.7 kB; application/x-troff-man)


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Mon Feb 24, 2025 10:40 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

hei

adam should get a invitaionfrom pypi. you are only maintainer ... for now,
i did set felix back to maintainer, as i his off for a long time

maybe we might put out more betas, for users to try before a release, if
they are not developers this might help.

welcome


On Sat, 22 Feb 2025 at 20:01, Adam Turner <aat...@ou...>
wrote:

> Dear Günter, all,
>
> >  with a long list a fixes, improvements, and additions since
> release 0.21.2 (2024-04-23), how about releasing 0.22?
>
> Sounds good! I want to review the situation around type annotations before
> releasing, and I might revert some of the changes I have made. There are
> also a few updates to the packaging metadata we can take the opportunity to
> make before releasing.
>
> > IMO, we should start with a beta release, to give downstream users an
> easy
> > chance to test without breaking installations with `pip` auto-updates.
>
> Sphinx 8.2. (released last week) is fully compatible with Docutils master
> (although there are some deprecation warnings). I think we can request that
> other projects test a release candidate, as with previous releases.
>
> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.
>
> .. [1]: https://pypi.org/project/docutils/
> .. [2]: https://pypi.org/user/AA-Turner/
>
> I can probably also co-ordinate with the downstream projects, should this
> be useful.
>
> Best wishes,
> Adam
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

shouldn't the system recognize the mail-uris and render this way
`- Aaaaa (<mailto:aa...@bb...>), Bbb <" rel="nofollow">https://github.com/cc> (<mailto:dd...@gm...>),`

could you try rst2man with option --macro-references ?



---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Thu Feb 20, 2025 08:46 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Dear Günter, all,

>  with a long list a fixes, improvements, and additions since
release 0.21.2 (2024-04-23), how about releasing 0.22?

Sounds good! I want to review the situation around type annotations before releasing, and I might revert some of the changes I have made. There are also a few updates to the packaging metadata we can take the opportunity to make before releasing.

> IMO, we should start with a beta release, to give downstream users an easy
> chance to test without breaking installations with `pip` auto-updates.

Sphinx 8.2. (released last week) is fully compatible with Docutils master (although there are some deprecation warnings). I think we can request that other projects test a release candidate, as with previous releases.

I am happy to help with the release (perhaps publishing a release candidate), I think it might be useful to have more people who can do releases, to share the work and remove pressure on individuals. If this would be helpful, please could I be added to the Docutils PyPI project [1]_? My username on PyPI is ``AA-Turner`` [2]_.

.. [1]: https://pypi.org/project/docutils/
.. [2]: https://pypi.org/user/AA-Turner/

I can probably also co-ordinate with the downstream projects, should this be useful.

Best wishes,
Adam

thanks for the report.

pt1 is indentional. 
when adding refernce handling in this writer, i wanted this to be undisturbing.
not expanding some "email: ab...@de..." into "email: abc@def.g <mailto:ab...@de...>
No one recognized up to you, so i was successful ... will be removed

pt2 spaces are mostly random IMHO ... will try to improve
pt3 newlines are vertical spaces

references are tricky because

when viewed in a terminal, having them clickable is great.
this is done by most terminals by themselves, seam to parse the text

but there are also manpage macros for this UR/UE/MT/ME 
with these the manpage processor takes over and
produces clickables for terminals and pdf

on printouts clicking is hard and so the uris must be printed in the footer
which is done by lynx when dumping html pages, but maybe no one else.
which means the document is loosing something.

long uris should be broken, so that the long uris dont ruin the layout or go over borders, which might be physical on/off paper.
this my current problem: there are nonprinting breakpoints for roff

if your document is opensource send me a link
if not send me samples
if not report bugs, try latest source

all the best
  



---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Wed Feb 19, 2025 09:25 PM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: pending-remind --> closed-fixed
- **Comment**:

The "subject" keyword is implemented as well, so we can safely close this ticket.



---

**[patches:#122] Support Custom Meta in odf_odt writer**

**Status:** closed-fixed
**Group:** None
**Created:** Wed Feb 04, 2015 06:50 PM UTC by pifi
**Last Updated:** Sun Oct 31, 2021 10:08 AM UTC
**Owner:** nobody
**Attachments:**

- [docutils_custom_meta_odt_patches.tar.gz](https://sourceforge.net/p/docutils/patches/122/attachment/docutils_custom_meta_odt_patches.tar.gz) (33.8 kB; application/gzip)


This patch enhanced the ..meta directive in odt writer. Generic fields (anything except 'keywords' and 'description') are treated as Custom Properties in odt.

The archive contains 2 patches:

+ 'custom_meta_odt_doc.diff': patch on the documentation.
+ 'custom_meta_odt.diff': patch on the odf_odt writer code.

The archive also contains the 2 modified files.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **assigned_to**: engelbert gruber



---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Tue Feb 11, 2025 11:03 PM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: pending-remind --> closed-rejected
- **Comment**:

The use-case is too special to merit an additional option for the "image" directive and an additional attribute for the ´<image>` Doctree element.  
We may help if you are interested implementing it in a custom parser and writer.
    
Thank you for sharing your idea.



---

**[patches:#170] Patch proposal to parsers/rst/directives/images.py**

**Status:** closed-rejected
**Group:** None
**Created:** Mon Aug 24, 2020 02:55 PM UTC by Fernando Libonati
**Last Updated:** Wed Aug 26, 2020 09:33 AM UTC
**Owner:** nobody
**Attachments:**

- [images.patch](https://sourceforge.net/p/docutils/patches/170/attachment/images.patch) (988 Bytes; application/octet-stream)


There Docutils' team, I want to propose a patch to add a new "ascii" option to the image directive, to replace a "not-found" image file with an "ascii-art" image. This could be useful for make the documentation clearer, when using the image or figure directives, adding an 'ascii-art' representation of the final image.

Example of a docstring for a Cython extensión class, the :ascii: option could include any ascii-art version of the final image.

    """
    .. code:: python
     
       b = module.Math2d(name: str, function: str)
     
    .. _fig_NonLinear_Math2d:
     
    .. figure:: ./images/Math2d.png
       :align: center
       :alt: Non-Linear / Math2d block
       :ascii:
           Math2d
           +---------+
           > X       |
           |   f(X,Y)>
           > Y       |
           +---------+
    
       Non-Linear / Math2d

    Properties:

    - function: name of the function (read-only)

    .. warning::
        This block does not accept initial conditions propagation (yet).
    """

If the "./images/Math2d.png" is not available, it will be replaced with the text version of the image, that is not all, but something.




---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: pending-remind --> closed-fixed
- **Comment**:

Thank you for the patches.
The non-controversial parts of the patches are implemented. 
Closing now because of the long silence. If there are remaining issues, please open a new ticket.



---

**[patches:#183] Fix spacing around `code` and `raw` blocks in `compound` blocks**

**Status:** closed-fixed
**Group:** None
**Labels:** LaTeX 
**Created:** Mon Aug 16, 2021 08:17 PM UTC by Clément Pit-Claudel
**Last Updated:** Thu Aug 04, 2022 11:36 AM UTC
**Owner:** nobody
**Attachments:**

- [1-visit-inline.patch](https://sourceforge.net/p/docutils/patches/183/attachment/1-visit-inline.patch) (2.5 kB; text/x-patch)
- [2-compound-code.patch](https://sourceforge.net/p/docutils/patches/183/attachment/2-compound-code.patch) (2.1 kB; text/x-patch)
- [3-compound-raw.patch](https://sourceforge.net/p/docutils/patches/183/attachment/3-compound-raw.patch) (766 Bytes; text/x-patch)
- [compound.rst](https://sourceforge.net/p/docutils/patches/183/attachment/compound.rst) (629 Bytes; text/x-rst)


I have attached three patches and a test related to spaces before `raw` and `code` blocks.

- `1-visit-inline.patch`: This is a small code simplification
- `2-compound-code.patch`: This removes an unconditional newline added in compound blocks before code blocks that have a `:name:`
- `3-compound-raw.patch`: This removes an unconditional newline added in compound blocks before raw blocks.
- `compound.rst`: This is a test; I wasn't sure where to add it.  It shows how things are modified by 



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: pending-remind --> closed-rejected
- **Comment**:

Thank you for the feedback and patch.

Hower, IMO, the problem is better solved in the sphinx-argparse-cli extension.



---

**[patches:#208] On parse error, print text block when src=None**

**Status:** closed-rejected
**Group:** None
**Created:** Wed Jan 17, 2024 07:29 PM UTC by Colin Marquardt
**Last Updated:** Mon Apr 15, 2024 12:33 PM UTC
**Owner:** nobody


I am using https://github.com/tox-dev/sphinx-argparse-cli to document my Python app's command line options.
When I have a formatting error in the help text of such a command line option, I am getting an error like the following:

None:5: ERROR: Unexpected indentation

 With the patch below, I have a much better chance to find the offending piece of code by printing some context, like so:

None:5: ERROR: Unexpected indentation near text:
Foo
Bar
 
~~~

--- docutils/parsers/rst/states_orig.py     2024-01-04 14:46:37.402565000 +0100
+++ docutils/parsers/rst/states.py          2024-01-17 13:48:00.991420000 +0100
@@ -2793,8 +2793,16 @@
             block = self.state_machine.get_text_block(flush_left=True)
         except statemachine.UnexpectedIndentationError as err:
             block, src, srcline = err.args
-            msg = self.reporter.error('Unexpected indentation.',
-                                      source=src, line=srcline)
+            if src is None:
+                msg = self.reporter.error(
+                    'Unexpected indentation near text:\n' +
+                    ' '.join(list(context)) +
+                    '\n' +
+                    ' '.join(list(block)),
+                    source=src, line=srcline)
+            else:
+                msg = self.reporter.error('Unexpected indentation',
+                                          source=src, line=srcline)
         lines = context + list(block)
         paragraph, literalnext = self.paragraph(lines, startline)
         self.parent += paragraph
~~~



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Dear Docutils developers,

with a long list a fixes, improvements, and additions since
release 0.21.2 (2024-04-23), how about releasing 0.22?

IMO, we should start with a beta release, to give downstream users an easy
chance to test without breaking installations with `pip` auto-updates.

@Engelbert: would you take care of the release again?

@Adam: I remember you announced interest in collaborating. Is this still
       valid?

Best regards,
Günter

- **summary**: "title" option for the "image" directive --> title/tooltip option for the "image" directive
- **status**: pending-works-for-me --> pending



---

**[feature-requests:#108] title/tooltip option for the "image" directive**

**Status:** pending
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Mon Dec 30, 2024 03:51 PM UTC
**Owner:** nobody


Like `image`’s `:alt:` directive, allow `:title:` for creating titles on pointer hover. The use case here is different from alt as alt is for assistive technologies & titles are more to give a labels for images for those with pointer cursors.

Expected input

~~~
.. image:: /house.jxl
	:alt: Home
	:title: Navigate home
	:target: /

.. image:: /cat.jxl
	:alt: A Siamese cat on a chair
	:title: Chula says, “meow”
~~~

Expected HTML output

~~~
<a href="/"><img src="/house.jxl" alt="Home" title="Navigate home"></a>
<img src="/cat.jxl" alt="A Siamese cat on a chair" title="Chula says, “meow”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -7,3 +7,5 @@
 However, we are missing a framework for complex cases with competing
 alternatives and for documenting the internal processes at the Docutils
 project.
+
+Attached are a draft specification and a patch implementing EPs in the developer documentation.

~~~~




---

**[feature-requests:#111] Docutils Enhancement Proposals**

**Status:** open
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Fri Feb 14, 2025 12:50 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Set-up-enhancement-proposals-in-developer-documentat.patch](https://sourceforge.net/p/docutils/feature-requests/111/attachment/0001-Set-up-enhancement-proposals-in-developer-documentat.patch) (25.9 kB; text/x-patch)
- [ep-001.html](https://sourceforge.net/p/docutils/feature-requests/111/attachment/ep-001.html) (26.7 kB; text/html)


Set up a framework for *Docutils Enhancement Proposals*  as a mechanism for
  proposing major new features, collecting community input,
  and documenting important design decisions.
  
The *Docutils To Do List* and issue tickets on the project page are
sufficient for small changes or issues with an obvious solution.
However, we are missing a framework for complex cases with competing
alternatives and for documenting the internal processes at the Docutils
project.

Attached are a draft specification and a patch implementing EPs in the developer documentation.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -1 +1,2 @@
 0001-Set-up-enhancement-proposals-in-developer-documentat.patch (25.9 kB; text/x-patch)
+ep-001.html (26.7 kB; text/html)

~~~~

- **Comment**:

Attached a patch and a draft specification.



---

**[feature-requests:#111] Docutils Enhancement Proposals**

**Status:** open
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Fri Feb 14, 2025 12:47 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Set-up-enhancement-proposals-in-developer-documentat.patch](https://sourceforge.net/p/docutils/feature-requests/111/attachment/0001-Set-up-enhancement-proposals-in-developer-documentat.patch) (25.9 kB; text/x-patch)
- [ep-001.html](https://sourceforge.net/p/docutils/feature-requests/111/attachment/ep-001.html) (26.7 kB; text/html)


Set up a framework for *Docutils Enhancement Proposals*  as a mechanism for
  proposing major new features, collecting community input,
  and documenting important design decisions.
  
The *Docutils To Do List* and issue tickets on the project page are
sufficient for small changes or issues with an obvious solution.
However, we are missing a framework for complex cases with competing
alternatives and for documenting the internal processes at the Docutils
project.



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -0,0 +1 @@
+0001-Set-up-enhancement-proposals-in-developer-documentat.patch (25.9 kB; text/x-patch)

~~~~

- **Comment**:

Attached is a  patch that implements enhancement proposals in the developer documentation and provides a draft proposal for EP specification and purpose.



---

**[feature-requests:#111] Docutils Enhancement Proposals**

**Status:** open
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Thu Feb 13, 2025 10:05 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Set-up-enhancement-proposals-in-developer-documentat.patch](https://sourceforge.net/p/docutils/feature-requests/111/attachment/0001-Set-up-enhancement-proposals-in-developer-documentat.patch) (25.9 kB; text/x-patch)


Set up a framework for *Docutils Enhancement Proposals*  as a mechanism for
  proposing major new features, collecting community input,
  and documenting important design decisions.
  
The *Docutils To Do List* and issue tickets on the project page are
sufficient for small changes or issues with an obvious solution.
However, we are missing a framework for complex cases with competing
alternatives and for documenting the internal processes at the Docutils
project.



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

---

**[feature-requests:#111] Docutils Enhancement Proposals**

**Status:** open
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Thu Feb 13, 2025 10:05 PM UTC
**Owner:** nobody


Set up a framework for *Docutils Enhancement Proposals*  as a mechanism for
  proposing major new features, collecting community input,
  and documenting important design decisions.
  
The *Docutils To Do List* and issue tickets on the project page are
sufficient for small changes or issues with an obvious solution.
However, we are missing a framework for complex cases with competing
alternatives and for documenting the internal processes at the Docutils
project.



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

On 2025-02-02, Guenter Milde via Docutils-develop wrote:
> On 2025-01-31, Alan wrote:

>> Image paths are now changed from forward slashes to backslashes on Windows.
>> But that won't work with LaTeX writers, because backslashes start commands.
>> The LaTeX writers need to retain forward slashes in the image paths.

>> I've never needed docutils to mess with my paths, and this change is very
>> problematic.
>> I recommend returning to the status quo ex ante.

> A patch is ready and will be committed to the repo soon.

Done in r10008.

Günter

Dear Alan,

Thank you for the report. 

On 2025-01-31, Alan wrote:

> Image paths are now changed from forward slashes to backslashes on Windows.
> But that won't work with LaTeX writers, because backslashes start commands.
> The LaTeX writers need to retain forward slashes in the image paths.

> I've never needed docutils to mess with my paths, and this change is very
> problematic.
> I recommend returning to the status quo ex ante.

A patch is ready and will be committed to the repo soon.

Günter

Image paths are now changed from forward slashes to backslashes on Windows.
But that won't work with LaTeX writers, because backslashes start commands.
The LaTeX writers need to retain forward slashes in the image paths.

I've never needed docutils to mess with my paths, and this change is very
problematic.
I recommend returning to the status quo ex ante.

Alan Isaac

Hi Guenter,

OK, thanks. I can fix that at my end.
But I think there was another more problematic change:
image paths are now changed from forward slashes to backslashes on Windows.
But that won't work with LaTeX writers, because backslashes start commands.
Can you change this back, at least on Windows?

Thank you, Alan



On Tue, Jan 28, 2025 at 4:30 PM Guenter Milde via Docutils-develop <
doc...@li...> wrote:

> Dear Alan,
>
> On 2025-01-28, Alan wrote:
> > Has docutils.writers.latex2e.SortableDict rather recently been replaced
> > with an ordinary dict somewhere?
> > Thanks, Alan Isaac
>
> Actually, docutils.writers.latex2e.SortableDict is left unchanged (for
> backwards compatibility).
>
> However, `docutils.writers.latex2e.LaTeXTranslator.requirements` and
> `docutils.writers.latex2e.LaTeXTranslator.fallbacks` now use standard
> dicts (changed in r9942).
>
> sorry for the hassle,
>
> Günter
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Dear Alan,

On 2025-01-28, Alan wrote:
> Has docutils.writers.latex2e.SortableDict rather recently been replaced
> with an ordinary dict somewhere?
> Thanks, Alan Isaac

Actually, docutils.writers.latex2e.SortableDict is left unchanged (for
backwards compatibility).

However, `docutils.writers.latex2e.LaTeXTranslator.requirements` and
`docutils.writers.latex2e.LaTeXTranslator.fallbacks` now use standard
dicts (changed in r9942).

sorry for the hassle,

Günter