docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

thanks Dmitry 
your are (mostly, I did not care about multiple tables) right
thanks for thinking for me :-)


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Sun Nov 19, 2023 05:07 PM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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] [docutils:feature-requests] Re: #91 Include directive path argument should support a configurable root.

[Karl O. P. <ko...@ka...>]

On Mon, 20 Nov 2023 07:56:06 -0000
"Günter Milde" via Docutils-develop
<doc...@li...> wrote:

> We are here at the Docutils (not Sphinx) where there is no `conf.py`
> nor a "project directory". So the "natural" and backwards compatible
> default for the new "include_root" setting is the filesystem root.

Thanks very much.  Apologies for my confusion.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

[Docutils-develop] [docutils:feature-requests] Re: #91 Include directive path argument should support a configurable root.

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

We are here at the Docutils (not Sphinx) where there is no `conf.py` nor a "project directory". So the "natural" and backwards compatible default for the new "include_root" setting is the filesystem root. 
In docutils there is only *one* primary input file (which may include other files via rST directives). Users are free to include files from anywhere in the file system. 
The new setting should help users to organize the to-be-included files and use simpler paths inside the rST source.


---

**[feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** pending
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Sun Nov 19, 2023 09:39 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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.

Re: [Docutils-develop] [docutils:feature-requests] #91 Include directive path argument should support a configurable root.

[Karl O. P. <ko...@ka...>]

I guess the full development of my thoughts leads to this
observation (which might not be true because I'm not steeped
in Sphinx):

If "root path" declarations take absolute paths in config.py
then a single config.py is not (in the general
case) reusable in sphinx-build invocations which
use different "sourcedir" paths, because if the sourcedir
is different there's likely different image dirs/etc.

There seem to be multiple solutions.  

1) Allow absolute file system
paths, relative to the overall root of the system's filesystem
hierarchy, as values for the various "root path" declarations,
and have sphinx-build take new arguments, each of which
would set a "root path" value similar to the way "sourcedir"
works.  ("imageroot" "staticroot", etc.)

2) Have the values of the various "root path" declarations
be relative to a well-known filesystem path, like the directory
containing the config.py file.

3) Do nothing.  Different invocations of sphinx-build may
need to use different configuration files, each of which
would correspond with a different "sourcedir" value.
Perhaps there would be a common config file "included"
by each top-level config file, the top-level config file
being the one that sets the various "root paths".  But
this would be up to the Sphinx user to construct.

4) Do something else.  Magic that completely reworks the
expected sphinx directory structure, to not only accommodate
multiple sorts of root directories but also to naturally
and simply separate sphinx supplied files from user-supplied
files.  There would then magically be zero level of effort
involved in starting to use Sphinx in a way that cleanly
works with revision control and with multiple RST source
directories (each of which may be expected to produce
output formats which differ from each other, given that
various output formats sometimes require different image
file formats, etc.).  Huzzah!

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Re: [Docutils-develop] [docutils:feature-requests] #91 Include directive path argument should support a configurable root.

[Karl O. P. <ko...@ka...>]

On Sun, 19 Nov 2023 21:39:11 -0000
"Günter Milde" via Docutils-develop
<doc...@li...> wrote:

> Waiting for a consensus about behaviour of image file reading (see
> comment above) …

I have not read and understood the entire thread, so apologies
if my comment here is not helpful.

When I think of a "root directory" for Sphinx I think
in terms of a webserver's "Document Root" -- the uppermost
part of the filesystem hierarchy to which the webserver
(symlinks, etc., aside) has access.

The sphinx-quickstart tool seems to make "document root" be
the directory containing the RST source directory.
The "images" and "_static" directories used by Sphinx
are placed in the same directory as the RST source directory.
(If I'm right, it's been a while since I used sphinx-build.)
So the directory containing the RST source plays the role
of "topmost part of the filesystem hierarchy" that is of
interest to Sphinx.

So, to me, it makes sense for the Sphinx "document root" to default
to the directory containing the "sourcedir" argument that is
supplied to the sphinx-build command.  This gives consistency
to the directory structures used whether it is sphinx-build
or sphinx-quickstart (and it's Makefile) that is used to
build the docs.

The question of defaults is orthogonal to the question of whether
there should be configuration directives controlling what
the "root directory" should be for various kinds of documentation
elements, images, static files, etc.  But I think it does
impact how the various root directories are specified.
It seems to me that the specification of the root directory
in the configuration file should be relative to some default
location.  To be specific, without having put in a lot of thought,
it seems that being relative to the "sourcedir" argument to
"sphinx-build" would be a good choice.  That way a single configuration
file can be re-used in different "sphinx-build" invocations
each of which has a different "sourcedir" argument.

tldr; you can stop reading now.

As an aside, I've never been comfortable with the directory
layout created by sphinx-quickstart.  I don't like the way
it mixes sphinx-quickstart created content with content
supplied by the sphinx user.  (Or that's how it feels to me.)
Of course, everything setup by sphinx-quickstart can be changed
by frobbing config.py, but I'm talking about defaults -- which
is likely the directory structure most people use.  I would love
to see a "better" default directory layout.  (And I seem to recall
that there's some single knob/argument that does something
to better separate sphinx-quickstart supplied files from
user supplied files from build directories, etc.  I think.)
What you get when you type just "sphinx-quickstart", I'm guessing
from what I've seen, seems to result in a lot of projects
putting the stuff sphinx-quickstart creates under revision
control.  Because it's simpler to put the whole directory
created by sphinx-quickstart under revision control than
to tease out what files are sphinx's and which are user-created.
Or to take the time to figure out how to use sphinx-build
or tweak the sphinx-quickstart invocation. Especially when first
using sphinx.  Putting sphinx-supplied stuff under revision
control makes it harder to use newer versions of sphinx/newer
sphinx features as they are released.  (I bit the bullet
and figured out how to use sphinx-build and am using that
instead of sphinx-quickstart and its Makefile, in my
Makefiles/whatever.) I wanted to write this paragraph to inject
some off-topic-but-related-to-directory-layout
feedback and don't expect anything to change.  Thanks for
listening and feel free to ignore this digression.

Hoping at least some of the above is useful,

Karl

> ---
> 
> **[feature-requests:#91] Include directive path argument should
> support a configurable root.**
> 
> **Status:** pending
> **Group:** Default
> **Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
> **Last Updated:** Sun Jun 25, 2023 07:01 PM UTC
> **Owner:** nobody
> 
> 
> I'm building a static website using restructuredtext and I'm really
> annoyed by the lack of support for root-relative paths.
> 
> I have already implemented multiple directive plugins for my website
> build process, some of which use external files in a different
> format. They use the convention that if a path begins with /, they
> are relative to the root directory of the project.
> 
> IMO the requirement for relative paths is very limiting - I could
> have a directory with files intended for inclusion but:
> 
> - I would need to use `../../` which is very ugly
> - relative paths are different depending on the current file path -
> this is very fragile and limits 
> 
> An additional argument is that C and C++ have been using #include for
> like 40 years and relative paths (while sometimes useful) are only
> for specific cases. The leading convention is to use root-relative
> paths.
> 
> I could implement another plugin for it but ... copy-pasting docutils
> own code only to change few lines is definitely smelly.
> 
> 
> ---
> 
> 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.



Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

[Docutils-develop] [docutils:feature-requests] #91 Include directive path argument should support a configurable root.

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

- **status**: open --> pending
- **Comment**:

Waiting for a consensus about behaviour of image file reading (see comment above) …



---

**[feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** pending
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Sun Jun 25, 2023 07:01 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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:patches] #206 Improve SmartQuote performance

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

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

Applied in [r9479]. More optimizations in [r9480] and  [r9481]



---

**[patches:#206] Improve SmartQuote performance**

**Status:** open-fixed
**Group:** None
**Created:** Wed Aug 16, 2023 04:37 PM UTC by Chris Sewell
**Last Updated:** Sun Nov 19, 2023 09:32 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Pre-compile-smartquote-regexes.patch](https://sourceforge.net/p/docutils/patches/206/attachment/0001-Pre-compile-smartquote-regexes.patch) (8.3 kB; application/octet-stream)
- [sphinx-build-after.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-after.svg) (199.1 kB; image/svg+xml)
- [sphinx-build-before.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-before.svg) (282.1 kB; image/svg+xml)


Performing a representative sphinx-build (10 x docutils/docs/ref/rst/restructuredtext.txt, dummy builder), and analysing with py-spy, you can see from the attached flamegraph that the smartquote transform accouts for over 22% of the build time!

This PR attempts to improve that situation (at least down to 18%) by caching regex compilation 


---

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] Re: #206 Improve SmartQuote performance

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

It turned out that actually "smartquotes" mostly used pre-compiled regexes already but re-did the recompilation with every call to `educateQuotes()`. Replacing these pre-compilations with direct calls allowed Python's caching to kick in and improve performance a bit. Pre-compiling at module import (as proposed in the patch) turned out to further improve, as did simplifying the regular expressions and introducing a preliminary thest for quotes to "educate". 
After theres optimizations, time spent on "smartquotes" went down from 20% of the time "buildhtml.py" requires to build the Docutils documentation to 10%. (Tested with py-spy before the changes, after the changes and with option `--smart-quotes=no`.)


---

**[patches:#206] Improve SmartQuote performance**

**Status:** open
**Group:** None
**Created:** Wed Aug 16, 2023 04:37 PM UTC by Chris Sewell
**Last Updated:** Fri Aug 18, 2023 12:31 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Pre-compile-smartquote-regexes.patch](https://sourceforge.net/p/docutils/patches/206/attachment/0001-Pre-compile-smartquote-regexes.patch) (8.3 kB; application/octet-stream)
- [sphinx-build-after.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-after.svg) (199.1 kB; image/svg+xml)
- [sphinx-build-before.svg](https://sourceforge.net/p/docutils/patches/206/attachment/sphinx-build-before.svg) (282.1 kB; image/svg+xml)


Performing a representative sphinx-build (10 x docutils/docs/ref/rst/restructuredtext.txt, dummy builder), and analysing with py-spy, you can see from the attached flamegraph that the smartquote transform accouts for over 22% of the build time!

This PR attempts to improve that situation (at least down to 18%) by caching regex compilation 


---

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] #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

[Dmitry S. <man...@us...>]

Hi Engelbert!

I think your fix is not fully correct. It adds this fragment:
```python
self._has_a_table = True
if self._has_a_table:
    # the comment to hint that preprocessor tbl should be called
    self.head.insert(0, "'\\\" t\n")
```

Here, the condition in `if` statement will be always true. So every time we encounter a table, we will add a new line to `self.head`.

Maybe you meant something like this instead?

```python
if not self._has_a_table:
    self._has_a_table = True
    # the comment to hint that preprocessor tbl should be called
    self.head.insert(0, "'\\\" t\n") 
    # single apostrophe, backslash, double apostroph, blank, character-t
```


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Sun Nov 19, 2023 09:47 AM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

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

Reclassifying as "open-fixed" so long the fix is only in the repository.
Will be closed when the next release is out.



---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Sat Nov 18, 2023 09:49 PM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

- **status**: open --> closed-fixed



---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Nov 15, 2023 07:32 PM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

> They are not the same, as noted in the first URL above. However, a
> portable man(7) document is unlikely to ever rely on the distinction
> between them 

you mean i should not use it in the manpage-writer ... for example inline UR/UE is easy with ' ...


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Nov 15, 2023 07:23 PM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

the problem is 
* missing hint in the generated manpage to include preprocessing by tbl ... that would be a reasonable title, especially when someone hacked the man-system to not include tbl.
* less cryptic might be '\" tbl ... which might not force me to add a comment for humans
* acchording to the man page , tbl is detected automatically
* and the nit picking if something is a command or a request or a macro is hackish ... i meant cleaning up the documentation 

clearer now ... :-) cheers and thanks


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Tue Nov 14, 2023 09:19 AM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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] [docutils:bugs] #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

[G. B. R. <g.b...@gm...>]

At 2023-11-13T04:43:40-0000, engelbert gruber via Docutils-develop wrote:
> the title is misleading and the solution looks like something was
> dropped on the keyboard

You mean `'\" t`?

Yes, that is pretty ugly.  But it is a convention that dates back to the
1980s and approximately every man(1) program in the world supports it.

We can dissect the splat to better understand what it is.

1.  the *roff no-break control character

https://www.gnu.org/software/groff/manual/groff.html.node/Control-Characters.html

2.  the *roff comment escape sequence

https://www.gnu.org/software/groff/manual/groff.html.node/Comments.html

3.  a space

4.  the letter "t" which tells man(1) to run tbl(1)

> on my system "man 7 man" says
> ~~~
>    Title line
>        The  first command in a man page (after comment lines, that is, lines that start
>        with .\") should be
> 
>               .TH title section date source manual

Yes, that's the man(7) page from the Linux man-pages project.  It was
largely written by people without a mastery of the *roff language or
man(7) macro package history.  It's not terrible but it has gaps.

> ~~~
> I had to move a lot of lines before .TH because indexers had problems

Yes.  groff_man(7) tries to warn about this too.

> and I will add this droplet too,

> BUT please is there anyone considering
> the fact that a manual-system should be less cryptic
> 
> and the page might be in need of a cleanup, it also says
> ~~~
>        Many  man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed.  For  portability’s  sake  to  non-troff  translators we recommend that you avoid using anything other than tbl(1),
>        and Linux can detect that automatically.
> ~~~

In the next release, the Linux man-pages project is dropping its own
man(7) page in favor of a redirect to groff's (groff_man(7)).  I've
spent a significant part of the past 6 years rewriting that page. It was
much improved for groff 1.22.4 (December 2018) and even more so for
groff 1.23.0 (July 2023).  I am also trying to reach more people with
the new page groff_man_style(7), and trying to steer people to it.

groff_man(7):

Description
       The GNU implementation of the man macro package is part of the
       groff document formatting system.  It is used to produce manual
       pages (“man pages”) like the one you are reading.

       This document presents the macros thematically; for those needing
       only a quick reference, the following table lists them
       alphabetically, with cross references to appropriate subsections
       below.

       Man page authors and maintainers who are not already experienced
       groff users should consult groff_man_style(7), an expanded
       version of this document, for additional explanations and advice.
       It covers only those concepts required for man page document
       maintenance, and not the full breadth of the groff typesetting
       system.

> then the fact that the apostrophe and the dot are the same comes up at
> sometime ...

They are not the same, as noted in the first URL above.  However, a
portable man(7) document is unlikely to ever rely on the distinction
between them and, except for the splat that gives man(1) a hint which
preprocessors to run, a man(7) document should use the normal control
character (the dot .) exclusively.

I've never seen any commentary on the issue, but my guess is that the
no-break control character was drafted into use for the man(1) hint to
avoid confusion arising from the following input.

$ cat > myprog.1
.\" this is my first man page!

Regards,
Branden

[Docutils-develop] [docutils:feature-requests] #100 Support SVG hyperlinks and event handling

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

[r9468] updates and extends the functional test with SVG images. Now you can compare inclusion with `<object>` tags (by the "html4" writer) https://docutils.sourceforge.io/test/functional/expected/standalone_rst_html5.html#svg-images
and with `<img>` tags (by the "html5" writer) https://docutils.sourceforge.io/test/functional/expected/standalone_rst_html4css1.html#svg-images.
The source is https://docutils.sourceforge.io/test/functional/input/data/svg_images.txt

It turns out that `<img>` is the most failprove, privacy-friendly and safe method to include SVGs, while `<object>` provides interactivity for included images but may fail under some circumstances. Fortunately, the ratio of SVGs  "in the wild"  without a `viewBox` seems to be decreasing over the last years.

You may experiment with the `<object>` method using `rst2html4` or selecting the "html4" writer in Sphinx, to see whether it may work four your use cases.
(The method was initially devised as a workaround for older browsers requiring a plug-in to display SVG images.) If it works satisfactory, we may consider using it in the "html5" writer as an alternative.

Direct embedding is currently only available via "raw" (see the examples in `svg_images.txt`).
As SVG images only work with  HTML, this is no major limitation.

For native support of embedding SVG, we still have to solve the issue on how to handle size and scaling options, (wrap in `<div>`, wrap in ´<svg>` with ViewPort, ...).

I don't think the "rewriting method" will be implemented in Docutils: it is too complicated and error-prone. However, if we get direct embedding of SVG, users may create re-usable images if they want to go this way. You may try with "raw" to embedding two  SVG files with one defining something to use and the second using it.




---

**[feature-requests:#100] Support SVG hyperlinks and event handling**

**Status:** open
**Group:** Default
**Created:** Wed Nov 01, 2023 09:15 PM UTC by Karl O. Pinc
**Last Updated:** Wed Nov 01, 2023 09:19 PM UTC
**Owner:** nobody


SVG supports embedded hyperlinks, and the ability to trigger scripts on keyboard, mouse, and document events.  But docutils does not, because SVG files are referenced by HTML "img" elements instead of "svg" elements.

Might be best to use the SVG "image" element, nested in a HTML "svg" element, to reference the underlying SVG file.


---

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: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

> I would just include it unconditionally, because that would not
> increase the complexity level of docutils codebase.

If noone is ever looking at the generated "troff" source, this is fine.
Otherwise, the complexity may be better "hidden" in the manpage writer.

(For comparison, the "latex" writer uses an elaborated framework for adding
preamble code (loading packages...) only if actually required in the document
in order to keep the "noise level" in the generated *.tex file smaller.)


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Tue Nov 14, 2023 09:19 AM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

[Dmitry S. <man...@us...>]

Hi @branden!

> You _could_ just include the `'\" t` unconditionally, since tbl(1) will
> not do any damage to a well-formed man page that doesn't use tables, and
> the time tbl(1) takes to run has not been noticeable for decades.

I would just include it unconditionally, because that would not increase the complexity level of docutils codebase.

Of course, Engelbert or Günter may have other opinions, but I don't mind going the other way too.

Thank you!

--
Dmitry Shachnev


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Tue Nov 14, 2023 09:16 AM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

[Dmitry S. <man...@us...>]

Hi Engelbert!

> the title is misleading

Okay, maybe it should have been more specific: Generated man page leads to groff warning "TE macro called with TW register undefined" with `MANROFFSEQ=''` env variable passed. Or you meant something else?

> on my system "man 7 man" says…

I agree, that manpage is a bit misleading. Probably it should say: …lines that start with `.\"` or `'\"`.

> BUT please is there anyone considering the fact that a manual-system should be less cryptic

I think it's too late to try to fix it without breaking the compatibility with legacy of the last decades.


---

**[bugs:#477] Generated man page leads to groff warning "TE macro called with TW register undefined"**

**Status:** open
**Labels:** manpage writer 
**Created:** Sun Nov 12, 2023 06:15 PM UTC by Dmitry Shachnev
**Last Updated:** Mon Nov 13, 2023 04:43 AM UTC
**Owner:** engelbert gruber


In Debian, we have a `lintian` tool which runs various checks on the built packages. Among other things, it makes sure that man pages explicitly require all preprocessors that they need.

I have received a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053355) about an error reported by that tool. It looks like that if a document contains a table, `rst2man` generates macros `.TS` and `.TE` which are recognized by [tbl](https://manpages.debian.org/testing/groff-base/tbl.1.en.html) preprocessor, but does not generate a dependency on it.

Here is a minimal reproducing example:
```
$ cat table.rst
.. list-table::

   * - Foo
     - Bar
$ rst2man table.rst | MANROFFSEQ='' man -l -Z - >/dev/null
an.tmac:<standard input>:43: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
```

According to [this email](https://lists.debian.org/debian-devel/2023/08/msg00220.html), to fix this error, `rst2man` should add this line on top of the generated man page:

    '\" t

Cc @branden — I think you are interested in all manpage-related issues.


---

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] [PATCH 0/9] Allow literal tabs in reStructuredText

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

Dear Jarret, dear Docutils developers,

thank you for the TAB patch set. A review/test is on my TODO list.

On 2023-10-31, Jarret "Jax" Renker via Docutils-develop wrote:
> On Tuesday, October 31st, 2023 at 1:49 PM, engelbert gruber <eng...@gm...> wrote:

>> * python discourages usage hardtabs and space mixing, because becomes
>>   painful (IMHO)

> Sure, but other languages, e.g. Makefile, mandate tabs and so do some
> styleguides.

I agree that there is a case for preserving TAB characters in literal
blocks and code blocks (in extension to what is already possible with
included files). 

>> * python philosophy : explicit is better then implicit ... would an
>>   option :hard-tabs: keep be more in line ?

> I'm fine with that.  I planned (re)using the tab_width option of
> docutils.conf (setting it to -1 preserves tabs, like its cousin does
> for the include directive) but introducing a new option is also ok.

The "tab-width" setting is also important to tell the "visible
indentation" of lines that start between tab stops:

"""\
* bullet list

\tThe nesting of this paragraph depends on the ``tab-width`` setting:
\tSecond paragraph of the first item with ``--tab-width 2``,
\tblock quote nested in first item with ``--tab-width`` > 2, but
\tblock quote following the list with ``--tab-width 1``.
"""
      
So we have the choice of

a)  tab-width: <positive integer>
    expand-tabs: <boolean>
    
b)  tab-width: <integer>  
       Negative values preserve TAB characters in "code"
       and "literal" blocks. Other TABs are expanded to abs(tab_width).
       
I prefer b), because it does not increase the number of settings 
and is compatible with the "include" directive's ``:tab-width:`` option.

Günter

[Docutils-develop] [docutils:feature-requests] #96 <abbr> abbreviations tag

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

- **status**: open --> pending



---

**[feature-requests:#96] <abbr> abbreviations tag**

**Status:** pending
**Group:** Default
**Created:** Wed Jul 12, 2023 06:19 AM UTC by toastal
**Last Updated:** Thu Nov 09, 2023 04:55 PM UTC
**Owner:** nobody


I would like to see inline support for `<abbr>` tags.

> The `abbr` element represents an abbreviation or acronym, optionally with its expansion. The `title` attribute may be used to provide an expansion of the abbreviation. The attribute, if specified, must contain an expansion of the abbreviation, and nothing else.

https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-abbr-element

These are useful for jargon-heavy content like documentation and can help with accessibility.


---

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:patches] #159 issue a warning when an image file does not exist

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

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



---

**[patches:#159] issue a warning when an image file does not exist**

**Status:** closed-rejected
**Group:** None
**Created:** Wed Jul 24, 2019 08:45 PM UTC by Nathaniel Beaver
**Last Updated:** Wed Aug 26, 2020 12:21 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Issue-warning-if-image-file-does-not-exist.patch](https://sourceforge.net/p/docutils/patches/159/attachment/0001-Issue-warning-if-image-file-does-not-exist.patch) (1.5 kB; text/x-patch)


rst2html does not issue a warning when an image file does not exist. For example, this will not produce a warning if the file "this-does-no-exist.png" does not exist:

~~~
.. image:: this-does-not-exist.png
~~~

I have attached a patch that issues a warning when file insertion is enabled and the image URI is a file URL or a path.


---

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:feature-requests] #41 Not all Node instances have the source and line attributes set

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

[r9475] adds source/line info to `<admonition>` and `<definition_list>` nodes.
See https://docutils.sourceforge.io/test/test_parsers/test_rst/test_source_line.py for the state of the art.



---

**[feature-requests:#41] Not all Node instances have the source and line attributes set**

**Status:** open
**Group:** sandbox
**Created:** Sun Jan 12, 2014 07:21 PM UTC by Brecht Machiels
**Last Updated:** Wed Jun 01, 2022 09:59 PM UTC
**Owner:** nobody


The source and line attributes of Node elements are not set for all types of elements. For example, these attributes never get set on bulleted or enumerated list nodes. Other elements (such as literal block) don't have source set depending on the context.


---

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:patches] #202 RST parser: Add source lines to admonitions and definitionlists

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

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

Thank you for the feature proposal.
With some testing, it could be modified to work as intended.
See [r9475].



---

**[patches:#202] RST parser: Add source lines to admonitions and definitionlists**

**Status:** open-fixed
**Group:** None
**Created:** Mon Jan 23, 2023 07:44 PM UTC by Hood Chatham
**Last Updated:** Tue Apr 18, 2023 12:04 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Add-source-lines-to-admonitions-and-definitionlists.patch](https://sourceforge.net/p/docutils/patches/202/attachment/0001-Add-source-lines-to-admonitions-and-definitionlists.patch) (1.8 kB; text/x-patch)


Work on bug #465


---

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] #186 Modernise packaging

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

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

setup.py is replaced by pyproject.toml in [r9448], packaging the next version will be done with flit.
Thank you for the patches, collaboration, and patience.



---

**[patches:#186] Modernise packaging**

**Status:** open-fixed
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Wed Sep 06, 2023 12:04 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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] #474 IndexError while parsing specially crafted option arguments

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

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

The underlying problem (splitting the "option marker" inside < >) is fixed in [r9473].
This also solves the `IndexError`.
Thank you for reporting.



---

**[bugs:#474] IndexError while parsing specially crafted option arguments**

**Status:** open-fixed
**Created:** Tue Sep 12, 2023 07:05 PM UTC by Andrew Pan
**Last Updated:** Tue Sep 12, 2023 07:13 PM UTC
**Owner:** nobody
**Attachments:**

- [reproducer.py](https://sourceforge.net/p/docutils/bugs/474/attachment/reproducer.py) (88 Bytes; text/x-python-script)


When rendering arbitrary input with the RST parser, I expect docutils to either return successfully or raise a `MarkupError`. However, the following input causes docutils to raise an `IndexError`:

`-a<, , >`

docutils tries to render this as an option group. It splits the group into individual options:

<small>docutils/parsers/rst/states.py:1555:</small>
```python
optionstrings = match.group().rstrip().split(', ')
```

Which yields the following array (note the empty string):

```
(Pdb) optionstrings
['-a<', '', ' >']
```

Which is then tokenized with `split()`. When processing an empty "option", `split()` yields an empty array, causing this statement to raise an `IndexError`:


<small>docutils/parsers/rst/states.py:1559:</small>
```python
firstopt = tokens[0].split('=', 1)
```


I checked [the documentation](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) and it appears that angle brackets are usually used to denote option arguments. I'm not sure if docutils should parse and render this kind of input. If it shouldn't, it would be nice to get a `MarkupError`.

Here's the output from `docutils -V`:
`docutils (Docutils 0.20.1, Python 3.11.3, on darwin)`

I've reproduced this on macOS `13.5.2 (22G91)` and Ubuntu 22.04 with the attached reproducer.


---

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.