docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:patches] #209 manpage writer: Update manpage.txt.

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

---

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

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

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

But you don't need to use `'` to call `UR` and `UE` to get an inline hyperlink.   Just use them with the `.` control character like any other _man_ macro.


---

**[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:** Mon Nov 20, 2023 06:12 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] release 0.21rc1 on tuesday march 26

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

Hei everyone,

Release 0.21 is planned for tuesday april 9 ... probably

all the best
 e

Change since 0.20
================

* General

  - Drop support for Python 3.7 and 3.8.
  - Updated build system to use Flit_ (patch #186 by Adam Turner).
    Removed ``setup.py``.
  - Provide ``rst2*`` "console_scripts" `entry points`_
    (without the ``.py`` extension) instead of installing the
    ``rst2*.py`` front end tools in the binary PATH.

  .. _Flit: https://github.com/pypa/flit/

* docs/ref/docutils.dtd

  - The <image> element accepts a new attribute "loading".

  - Fix definitions (no change to actual behaviour):

    * The <math_block> element uses the attribute "xml:space".
    * The <raw> element may contain text only (no inline elements).

* docutils/frontend.py

  - Allow `validate_*()` functions to be called with just the "value"
    argument but keep the legacy interface for use with optparse.
  - New function `frontend.validate_math_output()`.

* docutils/io.py

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

    .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
    .. _input encoding: docs/api/publisher.html#encodings

  - Auto-close `FileInput.source` in case of reading/decoding errors.

* docutils/languages/, docutils/parsers/rst/languages/

  - Mark/Fix mistranslated localizations of the "admonition" directive
    name. In Docutils, "admonition" is used as a generic term for
    "advice"/"advisory"/"remark", not a reprimand.
  - Add support for Georgian language (patch #204 by Temuri Doghonadze).
  - Update/complete Catalan translations (patch #203 by Antoni Bella Pérez).

* docutils/nodes.py

  - Remove compatibility hacks `nodes.reprunicode` and `nodes.ensure_str()`.

* docutils/parsers/rst/directives/images.py

  - New "image" directive option "loading".

* docutils/parsers/rst/directives/tables.py

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

  - Move `parsers.rst.directives.Table.process_header_option()` method
    to `parsers.rst.directives.CSVTable`.

* docutils/parsers/rst/states.py

  - Don't split inside "< >" when parsing "option groups" (fixes bug #474).

* docutils/parsers/rst/directives/misc.py,
  docutils/parsers/rst/directives/tables.py

  - Consider the new root_prefix_ setting when including files with
    "include", "raw", or "csv-table" directives.

* docutils/utils/math/*

  - Use custom exception `utils.math.MathError` instead of
    abusing `SyntaxError` for LaTeX math syntax errors.
  - Unify interface of LaTeX -> MathML conversion functions.
    Improve error reporting.
  - Sort ℏ (`\hslash`) as "mathord", not "mathalpha".

* docutils/utils/math/latex2mathml.py

  - Generate "MathML Core" to fix rendering with Chromium/Android.

    Use CSS rules instead of the deprecated "columnalign" attribute
    to style <mtable> as "align" environment.

    Use Mathematical Alphanumeric Symbols instead of <mstyle> with
    "mathvariant" attribute.

  - Use <mi> instead of <mo> for character class "mathord".

  - Support "aligned" environment.

  - Eliminate side-effect on later import of "tex2unichar".

* docutils/utils/math/mathml_elements.py

  - New module defining MathML element classes
    (outsourced from latex2mathml.py).
  - Base MathML element classes on `xml.etree.ElementTree`.

* docutils/utils/roman.py

  - Update to version `1.4 <https://pypi.org/project/roman/4.1/>`__.
    Fixes feature-request #95 (license is now ZPL 2.1).

* docutils/utils/smartquotes.py

  - Pre-compile regexps once, not with every call of `educateQuotes()`
    (patch #206 by Chris Sewell).
  - Simplify regexps; skip replacement rules if there is nothing to replace.

* docutils/writers/html4css1/__init__.py

  - Support video inclusion via ``<object>`` tags.

* docutils/writers/html5_polyglot/\*.css

  - Move MathML styles to "minimal.css" (required for correct rendering).
  - Highlight heading of target section also with explicit hyperlink target.

* docutils/writers/_html_base.py

  - Stop setting the "footnote-reference" class value for footnote references.
    Since 0.18, you can use the CSS selector ``[role="doc-noteref"]``.
  - Support reading/embedding images also with "file:" URI.
  - Warn, if image scaling fails because the image file cannot be read.
  - Support video inclusion via ``<video>`` tags
    (moved here from writers/html5_polyglot/__init__.py).
  - New auxiliary method `HTMLTranslator.uri2imagepath()` ensures the
    image file can also be read when CWD and output directory differ.
  - Consider the root_prefix_ setting when converting an image URI
    to a local filesystem path.
  - New `\<image>`_ attribute "loading" overrides image_loading_ setting.
  - Embed SVG images as ``<svg>`` instead of data-URI.
    Fixes feature-request #100.
  - Generate system messages for errors/warnings during the writing stage
    (image transformations, math content conversion, ...).
  - Close ``<dt>`` element in `depart_term()` to allow a
    "definition_list_item" with multiple "terms" (cf. feature-request #60).
  - Link to the document "#top" from the ToC heading
    (unless toc_backlinks_ is False).

* docutils/writers/latex2e/__init__.py

  - Fix placement of hyperlink target (label) for tables (bug #440).
  - More compact LaTeX source for option-lists and description-lists
    (no change in output).

* docutils/writers/manpage.py

  - Skip footer to avoid the link to document source in the manpage.
  - Add multiple definition list term support, see feature #60.
  - Use ``.UR`` and ``.UE`` macros for reference markup.
  - Add preprocessor hinting tbl first line, see bug #477.
  - Change tbl-Tables using box option, see bug #475.
  - Apply literal block patch #205. Use ``.EE`` and ``.EX`` macros.
    Thanks to G. Branden Robinson.

* docutils/writers/odf_odt/__init__.py

  - Use context manager for image reading operations.
    Catch `URLError` when `urllib.request.urlopen()` fails.

  - Convert image URI to path if accessing a local file. Fixes bug #153.

* docutils/writers/s5_html/__init__.py

  - Warn if the S5 writer cannot copy the theme files.
  - Programmatic customization of theme_url_ setting no longer
    overridden by the default for theme_.

* tools/buildhtml.py

  - New configuration setting `sources`_.
  - Match `prune`_ values with `fnmatch.fnmatch()`.

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

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

- **status**: open --> pending-works-for-me



---

**[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 05: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:bugs] Re: #427 Inconsistent sentence spacing in man pages using rst2man.py

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

Hi Günter,

> While \[using the _roff_ `ss` macro to assign an amount of inter-sentence space in man pages generated by _docutils_ ] is reasonable for locales that have the tradition of extra large inter-sentence space, it makes live hard for document authors from locales where "frenchspacing" is the norm (and alsways was) like German. Writing a German text, I usually don't care about sentence spacing and any additional space after a full stop at the end of a line comes as an unwelcome surprise.

In _groff_, this is already taken care of for you.  Its localization files for Czech, German, Spanish (forthcoming in 1.24), French, Italian, Russian (forthcoming in 1.24) and Swedish all use what TeX calls "frenchspacing".

See:

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/cs.tmac?h=1.23.0#n158
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/de.tmac?h=1.23.0#n158
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/fr.tmac?h=1.23.0#n158

...and so forth.

> An option for "frenchspacing" would come handy for authors that don't know about (or object to) the extra space after sentences. It would be, however, an additional feature, not a bugfix.

I don't think this is necessary for the _man_(7) output of _docutils_.  _groff_ will produce the locally-correct amount of inter-sentence space regardless, and if the user has a different preference, the _man.local_ mechanism for overriding it has been in place for over 30 years, since before _groff_ 1.06 in 1992 (which is as far back as our Git repository has history).

I do not want _groff_ to impose English-specific typographical practices on people while denying the opportunity for configuration, and I do not think it does in this respect.

Regards,
Branden


---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Wed Mar 20, 2024 05:17 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:bugs] #427 Inconsistent sentence spacing in man pages using rst2man.py

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

>>    Another solution would be to use the .ss macro to remove the extra space at the end of any sentences.

> I object to this proposal because the amount of inter-sentence space is a matter of taste/preference--that of the reader, not the man page author. The groff_man_style(7) page includes advice for customizing the man.local file to apply single-spacing after sentences. I ask that man(7) generators not override the user's preference in this matter. 

While this is reasonable for locales that have the tradition of extra large inter-sentence space, 
it makes live hard for document authors from locales where "frenchspacing" is the norm (and alsways was) like German. Writing a German text,  I usually don't care about sentence spacing and any additional space after a full stop at the end of a line comes as an unwelcome surprise.

An option for "frenchspacing" would come handy for authors that don't know about (or object to) the extra space after sentences. It would be, however, an additional feature, not a bugfix.


---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Fri Mar 15, 2024 03:23 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:bugs] #427 Inconsistent sentence spacing in man pages using rst2man.py

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

Hi Günter & Engelbert,

Your suggested language looks good to me.  I don't claim a full understanding of how Python docutils converts rST to _man_(7), but from what I do grasp, the new advice in _docs/user/manpage.txt_ looks like it should keep users out of trouble (that is, prevent surprise about where the sentences end).  ☺

Please consider me and the _groff_ mailing list a resource for any further questions about \*roff or _man_.

Regards,
Branden




---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Fri Mar 15, 2024 03:02 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:bugs] Re: #427 Inconsistent sentence spacing in man pages using rst2man.py

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

i added it to docs/users/manpage.txt


---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Wed Mar 13, 2024 08:32 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:bugs] #427 Inconsistent sentence spacing in man pages using rst2man.py

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

Thanks, Branden, for the comprehensive explanation.
IMO, we can close this issue after adding something in the line of
~~~
   Comply with the `troff line break rules`__ after punctuation signs in
   the rST source.  Use a new line or two spaces to start a new sentence.
   
   Avoid linebreaks after punctuation signs that do not end a sentence.
   A linebreak can be escaped with a backslash.  In rST, escaped whitespace
   is removed, so precede the backslash by a space::
   
      We recommend the works of E. T. A. \
      Hoffman.
   
   __ https://www.gnu.org/software/groff/manual/groff.html#Sentences   
~~~
to the Manpage Writer documentation.


---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Sat Mar 09, 2024 07:14 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.

Re: [Docutils-develop] Proposal: removing the fallback alt-text for inline images

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

Dear James,

thank you for posting your suggestion and the rationale.

On 2024-03-09, James Addison via Docutils-develop wrote:
> Hi docutils developers,

> Before potentially submitting a patch, I'd like to sense-check a
> possible adjustment to the way that docutils handles alt-text for
> inline images[1] in rST documents.

> Currently, when an inline image (itself a substitution reference) that
> lacks a configured :alt: option is parsed, then the substitution's
> name - the text enclosed by pipe symbols - is included as the alt text
> on the resulting image node.

> This behaviour is demonstrated by corresponding parser test coverage[2].

It is in line with the general idea of reStructuredText markup:

  reStructuredText is plaintext that uses simple and intuitive constructs
  to indicate the structure of a document. These constructs are equally
  easy to read in raw and processed forms.

  -- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

The idea is that authors use reference names for hyperlinks and
substitutions that make the text easy to comprehend in raw form as well as
in output formats that do not support hyperlinks or images (e.g. man
pages).

> The change I'd like to suggest is that the alt-text be omitted from
> inline images in cases where it is not explicitly set as an option.
> In other words: to remove the fallback value of the substitution name.

> The reasoning for the change is that although the substitution name
> _may_ in some cases provide a valuable, accessible alt-text, that
> positive outcome relies upon the documentation authors being aware of
> the alt text selection behaviour and adopting an appropriate
> substitution naming scheme.  Contrastingly, using the :alt: option
> directly is better-documented and more explicit.

In the general case, the fallback does not impair accessibility:

Authors that do not (need to) care about accessibility get an "alt" value
that is just as readable as the source.

Authors that care about accessibility but are not aware of the fallback
specify an :alt: value for all images.

"Caring experts" use the :alt: option directly for descriptions requiring
a phrase. In cases where a `simple reference name`_ can adequately
describe the image, the fallback saves these authors from duplicating the
substitution name as :alt: value. They will complain if the fallback
were removed.

.. _simple reference name:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-reference-name

...

> For anyone curious: my eventual objective here is one or two steps
> removed from docutils -- I would like Jupyter notebooks rendered using
> nbsphinx to be output deterministically. The internals of nbsphinx
> emit ephemeral (randomized) substitution names in the rST it produces
> when it encounters images in the input markdown it parses - and those
> ephemeral identifiers in turn produce nondeterminism (and likely poor
> accessibility) in the HTML output because docutils embeds them into img
> alt attribute values.
...
> [4] - https://github.com/spatialaudio/nbsphinx/pull/438

IMO, the particular use case of an auto-generated rST source with
pseudo-random substitution names does not merit dropping the :alt:
fallback.

I see several alternative solutions/workarounds for this problem, e.g.

* Use a deterministic substitution name (e.g. the image URI).

* Use a `3rd party markdown parser`__ to convert "markdown" input
  directly into a document tree
  (cf. https://github.com/spatialaudio/nbsphinx/issues/36).

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

with kind regards,

Günter

[Docutils-develop] [docutils:feature-requests] #102 Image height/width attributes

[flying s. <fly...@us...>]

I think attributes are the way to go since they’re [mapped to aspect-ratio](https://stackoverflow.com/a/12991496/247482).

Consider some theme adding `img { max-width: 100% }`: With the size set via CSS, this gives us a squished image. With the size set via attributes, it works perfectly. Demo: https://codepen.io/flying-sheep/pen/qBwNbOb



---

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

**Status:** pending
**Group:** Default
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Thu Feb 15, 2024 11:12 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.

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

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

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

This is a known issue with pipx under MacOS. See 
https://pipx.pypa.io/stable/troubleshooting/#macos-issues
for a workaround.
(It would still be interesting to know, whether the problem persists with "console entry points", i.e. with the `docutils` app.



---

**[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:** Sun Feb 25, 2024 01:51 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] Proposal: removing the fallback alt-text for inline images

[James A. <ja...@jp...>]

Hi docutils developers,

Before potentially submitting a patch, I'd like to sense-check a
possible adjustment to the way that docutils handles alt-text for
inline images[1] in rST documents.

Currently, when an inline image (itself a substitution reference) that
lacks a configured :alt: option is parsed, then the substitution's
name - the text enclosed by pipe symbols - is included as the alt text
on the resulting image node.

This behaviour is demonstrated by corresponding parser test coverage[2].

The change I'd like to suggest is that the alt-text be omitted from
inline images in cases where it is not explicitly set as an option.
In other words: to remove the fallback value of the substitution name.

The reasoning for the change is that although the substitution name
_may_ in some cases provide a valuable, accessible alt-text, that
positive outcome relies upon the documentation authors being aware of
the alt text selection behaviour and adopting an appropriate
substitution naming scheme.  Contrastingly, using the :alt: option
directly is better-documented and more explicit.

However: this could be a controversial or disruptive change, and I'd
be particularly glad to hear from anyone with accessibility-related
opinions, and anyone with thoughts about whether configuration/gradual
migration would make sense.


For anyone curious: my eventual objective here is one or two steps
removed from docutils -- I would like Jupyter notebooks rendered using
nbsphinx to be output deterministically.  The internals of nbsphinx
emit ephemeral (randomized) substitution names in the rST it produces
when it encounters images in the input markdown it parses - and those
ephemeral identifiers in turn produce nondeterminism (and likely poor
accessibility) in the HTML output because docutils embeds them into
img alt attribute values.  If further context is of interest, please
see the the Debian bugreport[3] where I discovered this behaviour, and
the followup discussion on a related GitHub nbsphinx issue thread[4].

Thank you and please let me know if I can clarify anything about the
suggestion and/or reasoning for it.

Regards,
James

[1] - https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

[2] - https://sourceforge.net/p/docutils/code/9553/tree/trunk/docutils/test/test_parsers/test_rst/test_substitutions.py#l52

[3] - https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064575

[4] - https://github.com/spatialaudio/nbsphinx/pull/438

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

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

Hi there.  I work on _groff_ upstream; Engelbert invited me to comment.

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

That's an AI-hard problem.

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

...for that reason, and even that can be defeated.  Consider the following input.

~~~
Many Linux distributions originate in the U.S. ls is the
most commonly used command.
~~~

As technical writing, the foregoing is poor, but it illustrates two points: sometimes sentences end with abbreviations, so you can't necessarily decide the opposite upon encountering one.  And in Unix documentation, because the system is case-sensitive, we often start sentences with lowercase letters.

Pattern matching is not powerful enough to decide sentence boundaries.

> Another solution would be to use the .ss macro to remove the extra space at the end of any sentences.

I object to this proposal because the amount of inter-sentence space is a matter of taste/preference--that of the _reader_, not the man page author.  The _groff_man_style_(7) page includes advice for customizing the _man.local_ file to apply single-spacing after sentences.  I ask that _man_(7) generators not override the user's preference in this matter. 

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

>From my conversations with _mandoc_(1)'s developer Ingo Schwarze, I believe he is of the opinion that _man_(7) (and _mdoc_(7)) should not permit much, if any, user customization along these lines.  So with that tool you'll likely get whichever amount of inter-sentence spacing the OpenBSD project decides you should have.

> This is what Asciidoctor does.

Would someone be so kind as to direct its developers to my comments here?

> From the troff manual, I assume that .cflags 0 .?! should do the trick.

I object to this as well, for the same reasons as injection of `ss` requests, and it's likely to meet the same fate when rendered by _mandoc_(1).

> A third solution/workaround is to comply with the troff line break rules after punctuation signs in the rST source. Use a new line to start a new sentence if you want double space after the full stop.

This is good advice, not because it's been a best _troff_ composition practice for about 50 years, but because it's the only truly reliable way of indicating to the machine where the sentence breaks are.

(Barring the injection of some sort of "start-sentence" and/or "end-sentence" tags, which I cannot imagine would survive first contact with ReStructured Text's design philosophy.)

> Avoid a new line after punctuation signs.

In _troff_ input you don't need this rule because following an end-of-sentence punctuation character with the `\&` dummy character escape sequence cancels detection of the end of a sentence.  I'm pretty sure you don't want to lift this syntax into Docutils; I mention it for completeness and in case it is useful to you when generating _man_(7) documents as output.

> Which might be the reason my man groff says nothing about sentences.
man 7 groff although states, without giving a reason: ... and ...

The language quoted here (which I elided with ellipses)  is from the _groff_ 1.22.4 version of the _groff_(7) page; _groff_ 1.23.0, released early last July, has _groff_(7) and _roff_(7) pages have much improved their explanations of basic _troff_ and _groff_ syntax.  (In my opinion, that is.  I wrote much of it.)

Regards,
Branden




---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Oct 13, 2021 07:00 PM UTC by jei23jkfd
**Last Updated:** Thu Apr 20, 2023 11:23 AM 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] #103 Add features from linuxdoc's "flat-table" to "list-table" directive.

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,5 +1,6 @@
 The *linuxdoc* Sphinx extension defines a new directive ["flat-table"](https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table) that is basically an extension of ["list-table"]() with the new roles "column-span", "row-span" and automatic filling up of missing cells at the end of a row.
 Also, comments and targets are allowed on *table-row* stage.
 
-These additional features can be implemented backwards-compatible by replacing the new option flag "fill-cells" with an option that allows 3 values ("no",, "fill", and "span").
+These additional features can be implemented backwards-compatible by replacing the new option flag "fill-cells" with an option "missing-cells" recognizing the keywords "strict",, "fill", and "span").
+The "missing-cells" option would also be useful for the "csv-table" directive.
 This would provide authors with a better choice of table generating rST constructs.

~~~~




---

**[feature-requests:#103] Add features from linuxdoc's "flat-table" to "list-table" directive.**

**Status:** open
**Group:** Default
**Created:** Tue Mar 05, 2024 04:33 PM UTC by Günter Milde
**Last Updated:** Tue Mar 05, 2024 04:33 PM UTC
**Owner:** nobody


The *linuxdoc* Sphinx extension defines a new directive ["flat-table"](https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table) that is basically an extension of ["list-table"]() with the new roles "column-span", "row-span" and automatic filling up of missing cells at the end of a row.
Also, comments and targets are allowed on *table-row* stage.

These additional features can be implemented backwards-compatible by replacing the new option flag "fill-cells" with an option "missing-cells" recognizing the keywords "strict",, "fill", and "span").
The "missing-cells" option would also be useful for the "csv-table" directive.
This would provide authors with a better choice of table generating rST constructs.


---

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] #90 Create a warning instead of an error for a missing "include" file?

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

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

A missing "literally" included file means missing data in the output. This should be an error, not just a warning.



---

**[feature-requests:#90] Create a warning instead of an error for a missing "include" file?**

**Status:** closed-rejected
**Group:** Default
**Created:** Tue Feb 01, 2022 09:25 AM UTC by Günter Milde
**Last Updated:** Tue Feb 01, 2022 09:25 AM UTC
**Owner:** nobody


The Python Developers Guide documents the Sphinx directive "literalinclude" and adds in a footnote
> There is a standard `include` directive, but it raises errors if the file is not found. This one only emits a warning.
> -- https://devguide.python.org/documenting/#id5

Should Docutils follow Sphinx and let the ["include" directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment) only warn?

* No, an error is the right [report level](https://docutils.sourceforge.io/docs/user/config.html#report-level).
* For literal inclusions (options "literal", "code", "raw", "parser"):  they have only local effect.
* For all inclusions: an included reST file may have effects later in the document (defining a role or substitution, setting the default role, establishing a new section level, ...).

It boils down to an assesment of the "seriosity" of a missing include file:
Both, *warning* and *error* indicate a  problem but do not normally  [halt](https://docutils.sourceforge.io/docs/user/config.html#halt-level) processing.
A *warning* is easier to silence (other *errors* will still pop up).




---

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] Re: #97 --disable-tab-expansion flag

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

Two minor points:

* You can add a class value to a literal block preceding it with a "class" directive ("rst-class" with Sphinx):
~~~
.. class:: testme

::

   a literal block
~~~
* TABs are converted to spaces in literal blocks, too :(


---

**[feature-requests:#97] --disable-tab-expansion flag**

**Status:** open
**Group:** Default
**Created:** Sun Jul 16, 2023 09:21 AM UTC by toastal
**Last Updated:** Tue Dec 12, 2023 04:14 PM UTC
**Owner:** nobody


> Spaces are recommended for indentation, but tabs may also be used. Tabs will be converted to spaces. Tab stops are at every 8th column (processing systems may make this value configurable).

Why tho? By converting tabs to spaces, we lose the accessibility aspect that tabs provide by letting the reader decide what’s comfortable to them as tab-width should be configurable on the reader’s side, not the writer’s. Some programming languages, like Go, tabs are overwhelmingly preferred & sometimes even required. Copying some code would not work.

I would like to see a `--disable-tab-expansion` flag that lets the author choose how they want their output to be output.


---

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] #103 Add features from linuxdoc's "flat-table" to "list-table" directive.

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

---

**[feature-requests:#103] Add features from linuxdoc's "flat-table" to "list-table" directive.**

**Status:** open
**Group:** Default
**Created:** Tue Mar 05, 2024 04:33 PM UTC by Günter Milde
**Last Updated:** Tue Mar 05, 2024 04:33 PM UTC
**Owner:** nobody


The *linuxdoc* Sphinx extension defines a new directive ["flat-table"](https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table) that is basically an extension of ["list-table"]() with the new roles "column-span", "row-span" and automatic filling up of missing cells at the end of a row.
Also, comments and targets are allowed on *table-row* stage.

These additional features can be implemented backwards-compatible by replacing the new option flag "fill-cells" with an option that allows 3 values ("no",, "fill", and "span").
This would provide authors with a better choice of table generating rST constructs.


---

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] #61 Support for :BCP: role, similar

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

The Sphinx extension [extlinks](https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html) is a generic solution to the common pattern of having many external links that point to URLs on one and the same site.


---

**[feature-requests:#61] Support for :BCP: role, similar**

**Status:** open
**Group:** Default
**Created:** Tue Apr 09, 2019 08:46 AM UTC by Roberto Polli
**Last Updated:** Wed Jan 12, 2022 11:45 PM UTC
**Owner:** nobody


## I wish

- support for referencing IETF Best Current Practices, eg:  :BCP:`47`role 
- the processing is similar to :RFC:

## Notes

- sphinx people suggests that goes in docutils. see  https://github.com/sphinx-doc/sphinx/issues/6255 


---

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

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

- **Comment**:

Thank you for reporting a problem with Docutils.

The problem seems caused by the installer `pipx` rather than Docutils:

In the repository and source tarball, the [front end tools](https://docutils.sourceforge.io/docs/user/tools.html) start with the line
~~~
#!/usr/bin/env python3
~~~
In the "wheel", the line is shortened to
~~~
#!python
~~~
The upcoming [release 0.21](https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-unpublished) will provide `rst2*` "console_scripts" *entry points* instead of installing the `rst2*.py` front end tools.
This change will provide the `rst2*` cli commands ("apps") also under Windows and solve the *quick aside*.

The [Generic Command Line Front End](https://docutils.sourceforge.io/docs/user/tools.html#generic-command-line-front-end) `docutils` already uses the new standard.
You may try, e.g, 

    docutils --help
    
to see, if this works on your system. If yes, the "rst2*" commands should work with Docutils 0.21, too.

**Attention**

The current usage is 

    <toolname> [options] [<source> [<destination>]]

In a directory with files `a.rst` and `b.rst`, the command

    rst2html.py docs/*
    
will happily **overwrite** `b.rst` with the output of converting `a.rst` **without warning**.
This is a [known problem](https://sourceforge.net/p/docutils/feature-requests/36/) and [will change in future releases](https://docutils.sourceforge.io/RELEASE-NOTES.html#command-line-interface).




---

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

**Status:** open
**Created:** Mon Feb 19, 2024 07:25 AM UTC by Jason R. Coombs
**Last Updated:** Mon Feb 19, 2024 07:25 AM 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:feature-requests] #102 Image height/width attributes

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

- **status**: open --> pending
- **Group**:  --> Default



---

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

**Status:** pending
**Group:** Default
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Wed Jan 03, 2024 01:36 PM 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] Fwd: [docutils:bugs] Re: #477 Generated man page leads to groff warning "TE macro called with TW register undefined"

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

Hi Engelbert,

I managed to miss this 3 months ago.

[regarding the ' and . control characters in *roff]

At 2023-11-15T13:32:00+0000, engelbert gruber wrote:
> > 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 ' ...

It makes no difference because the UR and UE macros don't break the line
anyway, and that is all the no-break control character ' is for.  Long
story short, you never need to call a man(7) macro with the no-break
control character, and groff man(7) will never do anything different if
you do.  I don't think any other man(7) implementation will either, but
I won't guarantee that.  (For a macro to even know which control
character was used to call it requires a GNU extension.)

Let me illustrate.  Here's a sample document.

$ cat ATTIC/UR-and-UE-demo.man
.TH foo 1 2024-02-13 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
For demonstration purposes,
the topic of discussion is
.UR https://\:sourceforge\:.net/\:p/\:docutils/\:bugs/\:477/
python-docutils bug #477
.UE .
Once again,
the topic of discussion is
'UR https://\:sourceforge\:.net/\:p/\:docutils/\:bugs/\:477/
python-docutils bug #477
'UE .

Now let's render it with and without explicit rendering of the URL
(groff man(7) will mark up the link text with OSC 8 escape sequences[1]
to make hyperlink text, but like font style changes, that won't show up
copy-and-pasted into an email).

$ nroff -man -Tascii ATTIC/UR-and-UE-demo.man
foo(1)                       General Commands Manual                      foo(1)

Name
     foo - frobnicate a bar

Description
     For  demonstration purposes, the topic of discussion is python-docutils bug
     #477.  Once again, the topic of discussion is python-docutils bug #477.

groff test suite                   2024-02-13                             foo(1)

$ nroff -rU0 -man -Tascii ATTIC/UR-and-UE-demo.man
foo(1)                       General Commands Manual                      foo(1)

Name
     foo - frobnicate a bar

Description
     For  demonstration purposes, the topic of discussion is python-docutils bug
     #477 <https://sourceforge.net/p/docutils/bugs/477/>.  Once again, the topic
     of  discussion  is  python-docutils  bug  #477  <https://sourceforge.net/p/
     docutils/bugs/477/>.

groff test suite                   2024-02-13                             foo(1)

Regards,
Branden

[1] https://github.com/Alhadis/OSC8-Adoption

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

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

Thank you for the suggestion and patch.
I downloaded and tested the "sphinx-argparse-cli" extension. With the patch and a deliberate rst syntax error in an argument description, running "make html" on a project printed, among a long list of warnings,
~~~
None:3: ERROR: Unexpected indentation near text:
output file, 
default:.
/usr/local/src/PyLit/doc/usage.txt:1: WARNING: Inline emphasis start-string without end-string.
/usr/local/src/PyLit/doc/usage.txt:81: ERROR: Unknown target name: "code".
/usr/local/src/PyLit/doc/build/html/examples/index.txt: WARNING: document isn't included in any toctree
~~~
I would still have to guess, that the offending input is from an argument description string of a program read in via the "sphinx-argparse" directive.

Other syntax problems are reported with the source file containing the "sphinx_argparse_cli" directive but an "arbitrary" wrong line number, e.g.,
~~~
/usr/local/src/PyLit/doc/usage.txt:1: WARNING: Inline emphasis start-string without end-string.
/usr/local/src/PyLit/doc/usage.txt:81: ERROR: Unknown target name: "code".
~~~

A real improvement would be if "sphinx_argparse_cli" could handle the exception and turn it into a helpful error message  that is both, reported on stderr and appended to the doctree at the place of occurence similar to what other directives do in case of syntax errors (i.e. return a "system_message" node). The "source" and line arguments for the reporter could be made the location of the `..  sphinx_argparse_cli::` or a source description like "{prog} cli description".

I suggest reporting the issue there.


---

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

**Status:** open
**Group:** None
**Created:** Wed Jan 17, 2024 07:29 PM UTC by Colin Marquardt
**Last Updated:** Wed Jan 17, 2024 07:29 PM UTC
**Owner:** nobody


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

None:5: ERROR: Unexpected indentation

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

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

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



---

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

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

[Docutils-develop] [docutils:feature-requests] #40 Option to embed images as data uri in rst2html

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

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

Direct SVG embedding is implemented in [r9597].



---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open-fixed
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Mon Jan 15, 2024 10:13 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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] Re: #40 Option to embed images as data uri in rst2html

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

The ODT writer may interpret "lazy loading" as "link in the flat XML format, embed in binary (zipped) ODT".


---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Sat Dec 16, 2023 10:42 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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.