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