docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] Mass edit changes by Günter Milde

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

Mass edit changing:

- **Status**: closed-fixed


ticket: bugs:#153 Image directive URI handled incorrectly in ODT output

- **Status**: open-fixed --> closed-fixed

[Docutils-develop] Release 0.21

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

Hello to everyone,

Release 0.21 is out on pypi
  most of the work done by günter, kudos kudos kudos
  most of the fails on me

Release 0.21 (2024-04-09)
=========================

* General:

  - Drop support for Python 3.7 and 3.8.

  - Provide ``rst2*`` "console_scripts" `entry points`_
    (without the ``.py`` extension) instead of installing the
    ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_

    Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:

    - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
    - Use ``python -m docutils.writers.odf_odt.prepstyles``
      to `strip the page size`__ from an ODT writer stylesheet.

    __ docs/user/odt.html#page-size

  .. [#] Some Linux distributions already use the short names.
  .. [#] The final rendering is done by a Sphinx-based build system
         (cf. :PEP:`676`).

* reStructuredText:

  - Use the same CSV format for the ``:header:`` option and the main data
    of the "csv-table_" directive.

  - New option "loading" for the `"image" directive`_.
    Sets the new attribute loading__ of the <image> doctree element.

  __ docs/ref/doctree.html#loading

* Configuration changes:

  - New configuration setting root_prefix_.
    Configurable root directory for included files.

  - New configuration setting sources_ for the "buildhtml.py" application.

  - Simpler and more secure `input encoding`_ default behaviour:

    Do not use the locale encoding as fallback if Python is started in
    `UTF-8 mode`_. Stop using "latin1" as second fallback.

    Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
    configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
    Do not remove other ZWNBSPs.

* Output changes:

  HTML5:
    Stop setting the "footnote-reference" class value for footnote
    references. Use the CSS selector ``[role="doc-noteref"]``
    (works since Docutils 0.18, see minimal.css for examples).

    Fix MathML rendering problems in Chrome/Chromium based browsers.

    Embed SVG images as ``<svg>`` instead of data-URI.

  manpage:
    Use .EE/.EX macros for literal blocks.

    Render URI references (do not use .UR/.UE).

    Use box option for tables.

* Removed objects:

  `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
    Python 2 compatibility hacks
  `docutils.utils.Reporter.set_conditions()`
    obsolete
  `docutils.core.Publisher.setup_option_parser()`
    internal, obsolete

* New files:

  ``docutils/writers/html5_polyglot/italic-field-names.css``
    Alternative style for Docutils field-lists.

* Removed files:

  ``install.py``, ``setup.py``
    Metadata is now stored in ``pyproject.toml``,
    supported by pip_ since version 19.0 (2019-01-22).
    See README__ for installation alternatives.

  __ README.html#installation

* Bugfixes and improvements (see HISTORY_).

.. _input encoding: docs/api/publisher.html#encodings
.. _csv-table: docs/ref/rst/directives.html#csv-table
.. _"image" directive: docs/ref/rst/directives.html#image
.. _root_prefix: docs/user/config.html#root-prefix
.. _sources: docs/user/config.html#sources

[Docutils-develop] [docutils:bugs] Re: #427 Inconsistent sentence spacing in man pages using rst2man.py

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

Thank you for the explanation. We will close this bug as "fixed" (via the new documentation) once 0.21 is out.


---

**[bugs:#427] Inconsistent sentence spacing in man pages using rst2man.py**

**Status:** pending-works-for-me
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Wed Mar 20, 2024 07:35 PM UTC
**Owner:** nobody


## Operating system info

I'm running Docutils 0.18b2.dev r8848 with Python 3.9.

## Description of bug

The roff language has a very subtle requirement. It enforces semantic line breaks. That is, any roff document must end a sentence with a line break.

For example, this is incorrect:

~~~
This is a sentence. This is another sentence.
~~~

We have to insert a line break after each sentence:

~~~
This is a sentence.
This is another sentence.
~~~

The semantic line breaks are used to add optional sentence spacing. It uses the line breaks to detect when a period (or question or exclamation mark) represents the end of a sentence and then adds an optional extra space when displaying it. The relevant documentation for groff(1) and mandoc(1) is at

- https://www.gnu.org/software/groff/manual/groff.html#Sentences
- https://mandoc.bsd.lv/man/roff.7.html#Sentence_Spacing

## Minimal example

Here is a minimal example that shows how the reST man page writer has this bug:

~~~rst
###
mwe
###
a minimal example
#################
:Date: October 13, 2021
:Manual section: 1
:Manual group: Testing Docutils
:Version: mwe 0.1.0

Synopsis
========
| mwe [**-aq**] [**-b** *file*] [**\--long-long** *which*] *file \...*

Description
===========
To find the common attributes of a variety of objects, it is necessary
to begin, by surveying the *objects* themselves in the concrete. Let us
therefore advert successively to the various modes of action, and
arrangements of human affairs, which are classed, by universal or widely
spread opinion, as Just or as Unjust. The things well known to excite
the sentiments associated with those names, are of a very multifarious
character. I shall pass them rapidly in review, without studying any
particular arrangement.
The previous line will have been spaced with two spaces.

Options
=======
Its arguments are as follows:

-a                         Do all.
-q                         Be quiet.
-b file                    Do everything to *file*.
--long-meme which          Chooses the long named *which*.

Environment
===========
mwe is not affected by environment variables.

Exit status
===========
mwe exits 0 on success.
~~~

If you convert this with `rst2man.py mwe.rst mwe.1` and view it with `man ./mwe.1` you will notice the issue easily: some sentences in the DESCRIPTION section end with 1 space and some sentences end with 2 spaces.

## Possible solutions

The most complete solution would be to automatically detect where sentences end in the input and add line breaks as required in the man page output. This is what Pandoc does. However, it requires keeping a list of abbreviations for every language so as to not have false positives: you don't want to add a line break when someone uses "e.g.".

Another solution would be to use the `.ss` macro to remove the extra space at the end of any sentences. Then Docutils wouldn't have to conform to roff syntax. However, this would not work with mandoc(1) as the developer of that program has decided not to support `.ss`. This is what Asciidoctor does.

Please let me know if you have any questions.


---

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:feature-requests] #105 manpage: would like more informative document comments

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

Ticket moved from /p/docutils/bugs/480/


---

**[feature-requests:#105] manpage: would like more informative document comments**

**Status:** open
**Group:** None
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Sun Apr 07, 2024 05:09 PM UTC
**Owner:** engelbert gruber


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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] #102 Image height/width attributes

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

Specifying the aspect-ratio via unitless "width" and "hight" is by now a valid use case.  Users  get a way to prevent layout shifts (e.g. specifying `:scale: 100`) while we retain the possibilty to overwrite document wide image dimension rules in a CSS stylesheet for a particular image in the "image" directive. 
As this is a backwards-incompatible change with the potential to break existing documents, it must be announced. See [r9617].


---

**[feature-requests:#102] Image height/width attributes**

**Status:** pending
**Group:** Default
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Tue Mar 12, 2024 10:00 AM UTC
**Owner:** nobody


When setting `:width:` or `:height:` on an image, the output is a `<image style="width: $W; height: $H">`. This isn’t the expected out put as there are & have been `width` & `height` attributes for the `<img>` tag for a long time. One might assume this is the same affect, but there are some important problems & why I think this is a bug for incorrect implementation.

1. Tools like Lighthouse, et al. show users to have width/height as a optimization so the browser can calculate & the image size properly without having to do a layout shift which is great
2. A good CSP (Content Security Policy) should never include `unsafe-inline` as this can be an attack surface but the output of `:width:` & `:height:` do just this.

The way to solve this to keep out unneeded inline style practice for good CSP but still have the width/height is to just use `<img width="$W" height="$H">` (at least when units are not specified).

What I may not be accounting for: units. `12px` is not the same as `12rem` or `12ex` or `12vw`. However, what I had input in my image was just plain ol’ integers got back something I didn’t expect: a) something using `px` (I‘m exclusively using relative unit like `em`, `rem`, etc.) and b) not using the attributes since the number I gave had no units.


---

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] Update CSS class identifier normalization

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

Dear Sarah,

On 2024-03-25, Sarah Johnson wrote:

> Hi! Thank you all for your work on docutils!

> I've recently started using Plausible for analytics tracking. Unfortunately
> their naming schema for custom events is incompatible with docutils CSS
> class normalization, since Plausible relies on either "=" or "--" for
> naming custom events (plausible docs
><https://plausible.io/docs/custom-event-goals#you-can-also-add-class-names-directly-in-html>
> ).

> Reading through the rationale for the chosen normalization
><https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization>,
> why is "=" excluded? Would an update ever be considered where "=" was
> allowed in class names for docutils?

I see your case. There is a similar request regarding the element identifiers
https://sourceforge.net/p/docutils/feature-requests/66/,
I added your use case there.

Thanks for asking,
Günter

[Docutils-develop] [docutils:feature-requests] #66 allow more characters when transforming "names" to "ids".

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

On 2024-03-25, a user posted a request to [docutils-develop](http://sourceforge.net/mailarchive/forum.php?forum_name=docutils-develop) with a use case where the identifier-normalization  of class names stands in the way:

> I've recently started using Plausible for analytics tracking. Unfortunately
their naming schema for custom events is incompatible with docutils CSS
class normalization, since Plausible relies on either "=" or "--" for
naming custom events ([plausible docs](https://plausible.io/docs/custom-event-goals#you-can-also-add-class-names-directly-in-html)).
>
>Reading through the rationale for the chosen [normalization](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization),
why is "=" excluded? Would an update ever be considered where "=" was
allowed in class names for docutils?



---

**[feature-requests:#66] allow more characters when transforming "names" to "ids".**

**Status:** pending
**Group:** Default
**Created:** Mon Sep 30, 2019 05:30 PM UTC by Roland Puntaier
**Last Updated:** Mon Aug 24, 2020 08:37 PM UTC
**Owner:** David Goodger


    `` encloses a role. There is a default role, else :<role>:`text`

    _ in front, is the special target role. For one word the backtick can be dropped.

    _`__init__` should produce a target named "__init__".

But instead the produced target is "init".
The backtick avoids ambiguity. There is no need for this behavior.



---

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] #104 Relax class name normalization.

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

---

**[feature-requests:#104] Relax class name normalization.**

**Status:** open
**Group:** Default
**Created:** Thu Mar 28, 2024 08:22 PM UTC by Günter Milde
**Last Updated:** Thu Mar 28, 2024 08:22 PM UTC
**Owner:** nobody


The current rules for class name normalization are [motivated by compatibility to CSS1 and the restrictions on identifiers in HTML4](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
20 years later, they restrict class names that will work in 99% of browsers used.

On 2024-03-25, a user posted a request to [docutils-develop](http://sourceforge.net/mailarchive/forum.php?forum_name=docutils-develop) with a use case where this outdated normalization stands in the way:
> I've recently started using Plausible for analytics tracking. Unfortunately
their naming schema for custom events is incompatible with docutils CSS
class normalization, since Plausible relies on either "=" or "--" for
naming custom events ([plausible docs](https://plausible.io/docs/custom-event-goals#you-can-also-add-class-names-directly-in-html)).
>
>Reading through the rationale for the chosen [normalization](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization),
why is "=" excluded? Would an update ever be considered where "=" was
allowed in class names for docutils?




---

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] #481 manpage: please stop converting text to full capitals

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

- **labels**:  --> manpage writer
- **assigned_to**: engelbert gruber



---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:12 AM UTC
**Owner:** engelbert gruber


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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] #482 manpage: section numbers wrongly in boldface in "See also" section

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

- **labels**:  --> manpage writer
- **assigned_to**: engelbert gruber



---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:29 AM UTC
**Owner:** engelbert gruber


The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.

This appears to be an unintentional defect in the manpage writer.  Here's a snippet of _rst2man_ output.

~~~
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
~~~

It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros.  (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)

Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.

~~~
.TP
.B \fIgroff_man_style\fP\R(7)\fP
~~~

If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder.

Here's my rST input for the foregoing.

~~~
See also
========

*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.

*mandoc*\(1)
  is a non-*roff*-based system for formatting man pages.
~~~

It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document.  I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire.  In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way.


---

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] #480 manpage: would like more informative document comments

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

- **labels**:  --> manpage writer
- **assigned_to**: engelbert gruber



---

**[bugs:#480] manpage: would like more informative document comments**

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 09:49 AM UTC
**Owner:** engelbert gruber


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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: #481 manpage: please stop converting text to full capitals

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

but .TH and .SH parameters are uppercase still ?

On Wed, 27 Mar 2024 at 02:12, G. Branden Robinson
<br...@us...> wrote:
>
> ________________________________
>
> [bugs:#481] manpage: please stop converting text to full capitals
>
> Status: open
> Created: Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
> Last Updated: Wed Mar 27, 2024 01:12 AM UTC
> Owner: nobody
>
> mandoc maintainer Ingo Schwarze and I (groff lead developer) reached a consensus a few years ago that man pages should stop shouting. This is a historical artifact of practices at Bell Labs in the 1970s.
>
> It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words. (The KDE screen reader I tried with a PDF didn't do this.)
>
> In groff 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time. With man-db, these options can be passed in via the MANROFFOPT environment variable.
>
>      -rCS=1   Set section headings (the argument(s) to .SH) in full
>               capitals.  This transformation is off by default because
>               it discards case distinction information.
>
>      -rCT=1   Set the man page identifier (the first argument to .TH) in
>               full capitals in headers and footers.  This transformation
>               is off by default because it discards case distinction
>               information.
>
> ________________________________
>
> Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/docutils/bugs/481/
>
> To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/


---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** open
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:12 AM UTC
**Owner:** nobody


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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: #481 manpage: please stop converting text to full capitals

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

sorry mandoc_man had uppercase titles

groff_man is lowercase already ... looks will require some time to
getting used to


On Wed, 27 Mar 2024 at 10:56, engelbert gruber
<gr...@us...> wrote:
>
> but .TH and .SH parameters are uppercase still ?
>
> On Wed, 27 Mar 2024 at 02:12, G. Branden Robinson
> <br...@us...> wrote:
> >
> > ________________________________
> >
> > [bugs:#481] manpage: please stop converting text to full capitals
> >
> > Status: open
> > Created: Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
> > Last Updated: Wed Mar 27, 2024 01:12 AM UTC
> > Owner: nobody
> >
> > mandoc maintainer Ingo Schwarze and I (groff lead developer) reached a consensus a few years ago that man pages should stop shouting. This is a historical artifact of practices at Bell Labs in the 1970s.
> >
> > It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words. (The KDE screen reader I tried with a PDF didn't do this.)
> >
> > In groff 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time. With man-db, these options can be passed in via the MANROFFOPT environment variable.
> >
> >      -rCS=1   Set section headings (the argument(s) to .SH) in full
> >               capitals.  This transformation is off by default because
> >               it discards case distinction information.
> >
> >      -rCT=1   Set the man page identifier (the first argument to .TH) in
> >               full capitals in headers and footers.  This transformation
> >               is off by default because it discards case distinction
> >               information.
> >
> > ________________________________
> >
> > Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/docutils/bugs/481/
> >
> > To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/


---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** open
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:12 AM UTC
**Owner:** nobody


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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: #482 manpage: section numbers wrongly in boldface in "See also" section

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

this is disruptive

a manpage is not a webpage , getting fonts uniform helps (just like
uppercase titles)
but from rST-source point it is clearer if the importance is marked there ...

might require a lot of changes in rST files ...

till after 0.21

On Wed, 27 Mar 2024 at 02:29, G. Branden Robinson
<br...@us...> wrote:
>
> Here's a message from 2022 where Ingo mentions that he'll be changing mandoc(1) to no longer warn about mixed case. Note that it only produces these warnings with the -Tlint option in the first place; using mixed case for man page identifiers and section headings will not cause any formatter known to me to produce diagnostic messages.
>
> https://lists.gnu.org/archive/html/groff/2022-08/msg00014.html
>
> ________________________________
>
> [bugs:#482] manpage: section numbers wrongly in boldface in "See also" section
>
> Status: open
> Created: Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
> Last Updated: Wed Mar 27, 2024 01:22 AM UTC
> Owner: nobody
>
> The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.
>
> This appears to be an unintentional defect in the manpage writer. Here's a snippet of rst2man output.
>
> .SH SEE ALSO
> .INDENT 0.0
> .TP
> .B \fIgroff_man_style\fP(7)
> is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
> for document authors.
> .TP
> .B \fImandoc\fP(1)
> is a non\-\fIroff\fP\-based system for formatting man pages.
> .UNINDENT
>
> It's pretty confusing to humans to mix font selection escape sequences with man font macros. (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)
>
> Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.
>
> .TP
> .B \fIgroff_man_style\fP\R(7)\fP
>
> If you're not doing pattern matching to detect man page cross references, the problem may be harder.
>
> Here's my rST input for the foregoing.
>
> See also
> ========
>
> *groff_man_style*\(7)
>   is a reference to the *groff* *man* macro language, with much advice
>   for document authors.
>
> *mandoc*\(1)
>   is a non-*roff*-based system for formatting man pages.
>
> It appears to me that the decision to set the paragraph tag (definition list headword) in bold was rst2man's; it was not derived from any formatting in the rST source document. I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire. In fact it appears to be that they can already do so, so the B call may just be getting in the way.
>
> ________________________________
>
> Sent from sourceforge.net because you indicated interest in https://sourceforge.net/p/docutils/bugs/482/
>
> To unsubscribe from further messages, please visit https://sourceforge.net/auth/subscriptions/


---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:29 AM UTC
**Owner:** nobody


The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.

This appears to be an unintentional defect in the manpage writer.  Here's a snippet of _rst2man_ output.

~~~
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
~~~

It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros.  (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)

Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.

~~~
.TP
.B \fIgroff_man_style\fP\R(7)\fP
~~~

If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder.

Here's my rST input for the foregoing.

~~~
See also
========

*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.

*mandoc*\(1)
  is a non-*roff*-based system for formatting man pages.
~~~

It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document.  I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire.  In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way.


---

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] #480 manpage: would like more informative document comments

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

... maybe
docutils was command line tools : rst2something
but is also used as a library ... so it might not be rst2man, maybe a sphinx pipeline
but how do i know this 
but you are correct , this would be interesting


---

**[bugs:#480] manpage: would like more informative document comments**

**Status:** open
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:07 AM UTC
**Owner:** nobody


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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] #482 manpage: section numbers wrongly in boldface in "See also" section

[G. B. R. <br...@us...>]

Here's a message from 2022 where Ingo mentions that he'll be changing _mandoc_(1) to no longer warn about mixed case.  Note that it only produces these warnings with the ``-Tlint`` option in the first place; using mixed case for man page identifiers and section headings will not cause any formatter known to me to produce diagnostic messages.

https://lists.gnu.org/archive/html/groff/2022-08/msg00014.html


---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:22 AM UTC
**Owner:** nobody


The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.

This appears to be an unintentional defect in the manpage writer.  Here's a snippet of _rst2man_ output.

~~~
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
~~~

It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros.  (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)

Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.

~~~
.TP
.B \fIgroff_man_style\fP\R(7)\fP
~~~

If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder.

Here's my rST input for the foregoing.

~~~
See also
========

*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.

*mandoc*\(1)
  is a non-*roff*-based system for formatting man pages.
~~~

It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document.  I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire.  In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way.


---

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] #482 manpage: section numbers wrongly in boldface in "See also" section

[G. B. R. <br...@us...>]

---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:22 AM UTC
**Owner:** nobody


The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.

This appears to be an unintentional defect in the manpage writer.  Here's a snippet of _rst2man_ output.

~~~
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
~~~

It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros.  (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)

Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.

~~~
.TP
.B \fIgroff_man_style\fP\R(7)\fP
~~~

If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder.

Here's my rST input for the foregoing.

~~~
See also
========

*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.

*mandoc*\(1)
  is a non-*roff*-based system for formatting man pages.
~~~

It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document.  I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire.  In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way.


---

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] #481 manpage: please stop converting text to full capitals

[G. B. R. <br...@us...>]

---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** open
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:12 AM UTC
**Owner:** nobody


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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] #480 manpage: would like more informative document comments

[G. B. R. <br...@us...>]

---

**[bugs:#480] manpage: would like more informative document comments**

**Status:** open
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 01:07 AM UTC
**Owner:** nobody


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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] release 0.21rc1

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

Hei everyone

0.21rc1 is out, a prerelease
to try out in an python environment install with the --pre argument

  python3 -m venv du3
  cd du3
  bin/activate
  pip install --pre docutils

0.21 final is due in two weeks.

Release 0.21.rc1 (2024-03-26)
=============================

* General:

  - Drop support for Python 3.7 and 3.8.

  - Provide ``rst2*`` "console_scripts" `entry points`_
    (without the ``.py`` extension) instead of installing the
    ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_

    Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:

    - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
    - Use ``python -m docutils.writers.odf_odt.prepstyles``
      to `strip the page size`__ from an ODT writer stylesheet.

    __ docs/user/odt.html#page-size

  .. [#] Some Linux distributions already use the short names.
  .. [#] The final rendering is done by a Sphinx-based build system
         (cf. :PEP:`676`).

* reStructuredText:

  - Use the same CSV format for the ``:header:`` option and the main data
    of the "csv-table_" directive.

  - New option "loading" for the `"image" directive`_.
    Sets the new attribute loading__ of the <image> doctree element.

  __ docs/ref/doctree.html#loading

* Configuration changes:

  - New configuration setting root_prefix_.
    Configurable root directory for included files.

  - New configuration setting sources_ for the "buildhtml.py" application.

  - Simpler and more secure `input encoding`_ default behaviour:

    Do not use the locale encoding as fallback if Python is started in
    `UTF-8 mode`_. Stop using "latin1" as second fallback.

    Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
    configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
    Do not remove other ZWNBSPs.

* Output changes:

  HTML5:
    Stop setting the "footnote-reference" class value for footnote
    references. Use the CSS selector ``[role="doc-noteref"]``
    (works since Docutils 0.18, see minimal.css for examples).

    Fix MathML rendering problems in Chrome/Chromium based browsers.

    Embed SVG images as ``<svg>`` instead of data-URI.

    Support video inclusion via ``<video>``.

  manpage:
    Use .EE/.EX macros for literal blocks.

    Render URI references (do not use .UR/.UE).

    Use box option for tables.

* Removed objects:

  `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
    Python 2 compatibility hacks
  `docutils.utils.Reporter.set_conditions()`
    obsolete
  `docutils.core.Publisher.setup_option_parser()`
    internal, obsolete

* New files:

  ``docutils/writers/html5_polyglot/italic-field-names.css``
    Alternative style for Docutils field-lists.

* Removed files:

  ``install.py``, ``setup.py``
    Metadata is now stored in ``pyproject.toml``,
    supported by pip_ since version 19.0 (2019-01-22).
    See README__ for installation alternatives.

  __ README.html#installation

* Bugfixes and improvements (see HISTORY_).

.. _input encoding: docs/api/publisher.html#encodings
.. _csv-table: docs/ref/rst/directives.html#csv-table
.. _"image" directive: docs/ref/rst/directives.html#image
.. _root_prefix: docs/user/config.html#root-prefix
.. _sources: docs/user/config.html#sources

For details see https://docutils.sourceforge.io/HISTORY.html

cheers
 e

[Docutils-develop] Update CSS class identifier normalization

[Sarah J. <sa...@co...>]

Hi! Thank you all for your work on docutils!

I've recently started using Plausible for analytics tracking. Unfortunately
their naming schema for custom events is incompatible with docutils CSS
class normalization, since Plausible relies on either "=" or "--" for
naming custom events (plausible docs
<https://plausible.io/docs/custom-event-goals#you-can-also-add-class-names-directly-in-html>
).

Reading through the rationale for the chosen normalization
<https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization>,
why is "=" excluded? Would an update ever be considered where "=" was
allowed in class names for docutils?

Thanks!

- Sarah

[Docutils-develop] [docutils:bugs] #479 scripts install with broken shebang

[Jason R. C. <ja...@us...>]

The upstream pipx issue is https://github.com/pypa/pipx/issues/1198.


---

**[bugs:#479] scripts install with broken shebang**

**Status:** closed-invalid
**Created:** Mon Feb 19, 2024 07:25 AM UTC by Jason R. Coombs
**Last Updated:** Mon Mar 25, 2024 01:57 PM UTC
**Owner:** nobody


The way docutils presents its executable scripts is broken on macOS.

Today, I installed docutils using pipx.

```
 @ pipx install docutils
  installed package docutils 0.20.1, installed using Python 3.12.2
  These apps are now globally available
    - docutils
    - rst2html.py
    - rst2html4.py
    - rst2html5.py
    - rst2latex.py
    - rst2man.py
    - rst2odt.py
    - rst2odt_prepstyles.py
    - rst2pseudoxml.py
    - rst2s5.py
    - rst2xetex.py
    - rst2xml.py
    - rstpep2html.py
done! ✨ 🌟 ✨
```

Quick aside, it would be nice if these executables didn't have the .py extension.

After installing, the scripts failed with this error:

```
 @ rst2html.py docs/*
xonsh: subprocess mode: command not found: '/Users/jaraco/Library/Application'
```

The problem is that pipx, by default, installs its data into the "Application Support" directory:

```
 @ pipx environment | grep HOME
PIPX_HOME=
PIPX_HOME=/Users/jaraco/Library/Application Support/pipx
```

And when it does, the scripts get installed with an invalid shebang because [Unix doesn't support spaces in shebangs](https://blog.jaraco.com/unix-doesnt-support-spaces-in-filenames/):

```
 @ head -n 1 $(which rst2html.py)
#!/Users/jaraco/Library/Application Support/pipx/venvs/docutils/bin/python
```




---

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] #479 scripts install with broken shebang

[Jason R. C. <ja...@us...>]

Yes, using the `docutils` app does work, so `rst.*` should also work once converted to console entry points. Thanks!

I agree the "macOS workaround" could work around the issue, but it's not a very robust workaround, as it requires repairing every shebang on every installation, and moreover, the bug doesn't exist just in macOS or just with pipx. Here's the same bug manifest in Ubuntu using just pip:

```
docker run -it jaraco/multipy-tox bash
root@6b1625414874:/# mkdir /foo\ bar
root@6b1625414874:/# py -m venv /foo\ bar/env
root@6b1625414874:/# /foo\ bar/env/bin/pip install -q docutils

[notice] A new release of pip is available: 23.2.1 -> 24.0
[notice] To update, run: python3.12 -m pip install --upgrade pip
root@6b1625414874:/# /foo\ bar/env/bin/rst2html.py
bash: /foo bar/env/bin/rst2html.py: /foo: bad interpreter: No such file or directory

```

The root problem is that Unix doesn't support paths with spaces in a shebang.




---

**[bugs:#479] scripts install with broken shebang**

**Status:** closed-invalid
**Created:** Mon Feb 19, 2024 07:25 AM UTC by Jason R. Coombs
**Last Updated:** Mon Mar 11, 2024 07:25 PM UTC
**Owner:** nobody


The way docutils presents its executable scripts is broken on macOS.

Today, I installed docutils using pipx.

```
 @ pipx install docutils
  installed package docutils 0.20.1, installed using Python 3.12.2
  These apps are now globally available
    - docutils
    - rst2html.py
    - rst2html4.py
    - rst2html5.py
    - rst2latex.py
    - rst2man.py
    - rst2odt.py
    - rst2odt_prepstyles.py
    - rst2pseudoxml.py
    - rst2s5.py
    - rst2xetex.py
    - rst2xml.py
    - rstpep2html.py
done! ✨ 🌟 ✨
```

Quick aside, it would be nice if these executables didn't have the .py extension.

After installing, the scripts failed with this error:

```
 @ rst2html.py docs/*
xonsh: subprocess mode: command not found: '/Users/jaraco/Library/Application'
```

The problem is that pipx, by default, installs its data into the "Application Support" directory:

```
 @ pipx environment | grep HOME
PIPX_HOME=
PIPX_HOME=/Users/jaraco/Library/Application Support/pipx
```

And when it does, the scripts get installed with an invalid shebang because [Unix doesn't support spaces in shebangs](https://blog.jaraco.com/unix-doesnt-support-spaces-in-filenames/):

```
 @ head -n 1 $(which rst2html.py)
#!/Users/jaraco/Library/Application Support/pipx/venvs/docutils/bin/python
```




---

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] #209 manpage writer: Update manpage.txt.

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

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

thanks a lot ... applied



---

**[patches:#209] manpage writer: Update manpage.txt.**

**Status:** open-fixed
**Group:** None
**Created:** Sun Mar 24, 2024 10:09 PM UTC by G. Branden Robinson
**Last Updated:** Mon Mar 25, 2024 01:20 PM UTC
**Owner:** nobody
**Attachments:**

- [gbr.diff](https://sourceforge.net/p/docutils/patches/209/attachment/gbr.diff) (11.1 kB; text/x-patch)


Here's a patch updating "manpage.txt" in many respects.  I wasn't able to address all of the open issues at the end because I either don't understand exactly what's being asked or I need an exhibit of failing input, but I think I clarified some of them.


---

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] #209 manpage writer: Update manpage.txt.

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

thanks a lot, applied.
I moved the open issue list at the end, 
This was intended for discussion when I started the writer ... no one ever read up to now.


---

**[patches:#209] manpage writer: Update manpage.txt.**

**Status:** open
**Group:** None
**Created:** Sun Mar 24, 2024 10:09 PM UTC by G. Branden Robinson
**Last Updated:** Sun Mar 24, 2024 10:09 PM UTC
**Owner:** nobody
**Attachments:**

- [gbr.diff](https://sourceforge.net/p/docutils/patches/209/attachment/gbr.diff) (11.1 kB; text/x-patch)


Here's a patch updating "manpage.txt" in many respects.  I wasn't able to address all of the open issues at the end because I either don't understand exactly what's being asked or I need an exhibit of failing input, but I think I clarified some of them.


---

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.