docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] Re: #497 manpage writer renders links incorrectly

[engelbert g. <gr...@us...>]

shouldn't the system recognize the mail-uris and render this way
`- Aaaaa (<mailto:aa...@bb...c>), Bbb <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...c),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <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...c> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <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...c), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <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.

Re: [Docutils-develop] time to release 0.22.b1 ?

[Adam T. <aat...@ou...>]

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] [docutils:bugs] #497 manpage writer renders links incorrectly

[engelbert g. <gr...@us...>]

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...c),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <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...c> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <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...c), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <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.

[Docutils-develop] [docutils:patches] #122 Support Custom Meta in odf_odt writer

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:bugs] #497 manpage writer renders links incorrectly

[engelbert g. <gr...@us...>]

- **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...c),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <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...c> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <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...c), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <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.

[Docutils-develop] [docutils:patches] #170 Patch proposal to parsers/rst/directives/images.py

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:patches] #183 Fix spacing around `code` and `raw` blocks in `compound` blocks

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:patches] #208 On parse error, print text block when src=None

[Günter M. <mi...@us...>]

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

[Docutils-develop] time to release 0.22.b1 ?

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

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

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

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:feature-requests] #111 Docutils Enhancement Proposals

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:feature-requests] #111 Docutils Enhancement Proposals

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:feature-requests] #111 Docutils Enhancement Proposals

[Günter M. <mi...@us...>]

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

[Docutils-develop] [docutils:feature-requests] #111 Docutils Enhancement Proposals

[Günter M. <mi...@us...>]

---

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

[Docutils-develop] (no subject)

[พล.อ ก. ท. <kon...@gm...>]

Re: [Docutils-develop] image paths

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

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

Re: [Docutils-develop] image paths

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

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

[Docutils-develop] image paths

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

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

Re: [Docutils-develop] error: 'dict' object has no attribute 'sortedvalues'

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

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

Re: [Docutils-develop] error: 'dict' object has no attribute 'sortedvalues'

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

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] error: 'dict' object has no attribute 'sortedvalues'

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

Has docutils.writers.latex2e.SortableDict rather recently been replaced
with an ordinary dict somewhere?
Thanks, Alan Isaac

[Docutils-develop] [docutils:feature-requests] #110 Move from "optparse" to "argparse".

[Günter M. <mi...@us...>]

- **assigned_to**: Günter Milde -->  nobody 
- **Group**:  --> Default



---

**[feature-requests:#110] Move from "optparse" to "argparse".**

**Status:** open
**Group:** Default
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Sat Oct 19, 2024 10:10 AM UTC
**Owner:** nobody


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

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.

[Docutils-develop] [docutils:feature-requests] #108 "title" option for the "image" directive

[Günter M. <mi...@us...>]

See also the proposal by Roman Suzi in "docutils-users" from 2003-07-07.
https://sourceforge.net/p/docutils/mailman/docutils-users/thread/Pine.LNX.4.44.0307070819150.2138-100000%40rnd.onego.ru/#msg4465479



---

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

**Status:** pending-works-for-me
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Thu Oct 17, 2024 08:23 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.

[Docutils-develop] [docutils:feature-requests] #83 Support SVG images in LaTeX

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

SVG support via the "svg" LaTeX package is implemented in [r9999].



---

**[feature-requests:#83] Support SVG images in LaTeX**

**Status:** open-fixed
**Group:** Default
**Created:** Sat Oct 09, 2021 12:05 AM UTC by Local State
**Last Updated:** Wed Jun 01, 2022 10:02 PM UTC
**Owner:** nobody


Hi there, this is Local State.

## Motivation
The current `Image` directive is not enough for svg files. Using `img` tag loses interactivities, and the width, and height can't be applied for svg files directly. It's better to use `style="width:50%"` instead. 

## 2 New Options
I'm hoping there could be 2 new options for `Image` directive.
    
   1. `tag`
        This would determine the html tag used to render the image. The default value would be `img`, and we could also use `object`, `iframe` and `embed` as alternatives. Currently, all images are rendered with `img` tag, which loses some interactivities (e.g., the text in svg file). We could avoid this by using `object` tag. I see there are some similar work in `html4css1` about `object_image_types`.  
        
        Example:
        ```
        <img src="a.png" width="50%" alt="alt msg">`
        <object data="a.png" style="width:50%">alt msg</object>
        <iframe src="a.png" width="50%" title="alt msg"></iframe>
        <embed src="a.png" width="50%">`
        ```
        
   2. `embed`
        If enabled, this option would embed the image into the html file using base64 encoding.  
        While I see there is already the if sentence in the `visit_image` function.
        ```
        if self.settings.embed_images or ('embed' in node):
        ```
        The `embed_images` could be set from command-line or setting, but I can't find how to satisfy the latter condition, since any node doesn't seem to have `embed` attribute. Could anyone tell me how to enable it? If we can't, then it's necessary to add the `embed` option, so that we could choose to embed one particular image or not. 
        Especially, I notice there exist a `todo` item for svg embedding. I'd like to implement it if possible. But the first option is still in demand, because most times we don't want our html files to be so large and need separate svg files.

##  Potential bugs
 
 svg files under `<img>` tag can't correctly render height and width if svg viewbox information is not contained in the file. It might be better to set the height and width in `style` indirectly.

##  Contribution
 I would like to fix and implement all these things if possible. But I'm not quite familiar with SourceForge and don't know how to submit a PR like what we do in github.


---

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.

[Docutils-develop] [docutils:bugs] Re: #493 Test failure on Windows with embedded images

[Günter M. <mi...@us...>]

A helper function that converts a URI-reference to a filesystem path for HTML and LaTeX writers based on this patch is introduced in [r9996]. The ODT writer will have to wait, as this is a backwards-incompatible change: : The ODT writer expects relative image paths to be relative to the *source* directory. 


---

**[bugs:#493] Test failure on Windows with embedded images**

**Status:** pending-works-for-me
**Created:** Wed Aug 07, 2024 02:25 AM UTC by Adam  Turner
**Last Updated:** Mon Nov 25, 2024 09:08 PM UTC
**Owner:** nobody


xref [r9785], [r9853], [r9855]

Dear @milde,

Thank you for the fix to my recent patch. It seems neither my patch nor the fix addressed the root cause of the test failures, as tests have resumed failing on Windows.

I believe the following demonstrates the problem:

```pycon
>>> import sys; print(sys.platform)
win32
>>> import urllib.parse, urllib.request
>>> urllib.request.url2pathname('test/data/circle-broken.svg')
'test\\data\\circle-broken.svg'
>>> urllib.parse.unquote('test/data/circle-broken.svg')
'test/data/circle-broken.svg'
```

Currently, we use `imagepath = urllib.request.url2pathname(uri_parts.path)`, which converts path separators to their platform-native format. On UNIX, `url2pathname` simply calls `unquote`, but on Windows it handles UNC paths (``\\host\path\``) and escaped drive letters (``///C|/users/``).

I don't know what led to using `url2pathname()`, as it is quite specialised (the docstring notes "not recommended for general use"). Is it possible to use the simpler `unquote()` here?  

For local file paths (e.g. without a ``file:///`` scheme), should we even be using URI parsing? Perhaps we should use proper path handling if there is no URI scheme (i.e. the user has provided a file-path).

A


---

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.