Hi Drew,

There is a subtle bug in the man pages produces by scdoc. This afffects
the man pages of aerc, wayland, and any other projects that depend on
it.

roff's syntax has a peculiar requirement. It *enforces* semantic
line-breaks [1].

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 corresponding documentation for groff and mandoc can be found at

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

This is a *hard requirement* because for tty output, nroff and mandoc
both use *2 spaces* for sentence spaces, and 1 space for *normal
spaces*. This makes the spacing in aerc(1) very inconsistent:

    save [-fp] <path>
       Saves the current message part to the given path.  If the path is
       not an absolute path, general.default-save-path will be prepended
       to the path given.  If path ends in a trailing slash or if a folder
       exists on disc, aerc assumes it to be a directory.  When passed a
       directory :save infers the filename from the mail part if possible,
       or if that fails, uses "aerc_$DATE".
    ^ 2 spaces

    mark [-atv]
       Marks messages. Commands will execute on all marked messages in‐
       stead of the highlighted one if applicable. The flags below can be
       combined as needed.
    ^ 1 spaces

The source code of this snippet can be found at [2]. You can use '/\.  '
and '/\. [^ ]' in less and Vim to identify these.

I will not debate on the rationale of this behavior. There are plenty of
discussions out there [3,4]. The problem is that there doesn't seem to
be an option to turn this off, at least for mandoc and plan9 nroff.

The default end-of-sentence (EOS) character is `.!?` for both groff and
mandoc. For groff, this is controlled by cflags, but for mandoc, this
seems to be hardcoded.

One possible solution is to avoid sentence spacing entirely using `\&`

    $ nroff << EOF
    This is a sentence.\&
    This is another sentence.\&
    1.\&0 i\&.e.\& test!\&
    EOF
    This is a sentence. This is another sentence. 1.0 i.e. test!

Compare with

    $ nroff << EOF
    This is a sentence.
    This is another sentence.
    1.0 i.e. test!
    EOF
    This is a sentence.  This is another sentence.  1.0 i.e. test!

However, I have no idea if this will cause any unexpected behaviors.

The other solution is to enforce line-breaking by adding a line break to
every EOS character. This conforms to the standard roff syntax. However,
we need to have some kind of escaping mechanism. Consider the following
paragraph from OpenBSD's roff(7)

    The RUNOFF typesetting system, whose input forms the basis for roff,
    was written in MAD and FAP for the CTSS operating system by Jerome
    E. Saltzer in 1964? Doug McIlroy rewrote it in BCPL in 1969,
    renaming it roff. Dennis M. Ritchie rewrote McIlroy's roff in PDP-11
    assembly for Version 1 AT&T UNIX, Joseph F. Ossanna improved roff
    and renamed it nroff for Version 2 AT&T UNIX, then ported nroff to C
    as troff, which Brian W. Kernighan released with Version 7 AT&T
    UNIX. In 1989, James Clarke re-implemented troff in C++, naming it
    groff.

How should we deal with the abbreviation dot in names? This is the
strategy in Pandoc, but it has problem dealing with abbreviation dot.

Related issues
--------------

1. asciidoc: https://github.com/asciidoc/asciidoc-py3/issues/137
2. Pandoc: https://github.com/jgm/pandoc/issues/6613
3. plan9port: https://github.com/9fans/plan9port/issues/441

[1]: https://sembr.org/
[2]: https://git.sr.ht/~sircmpwn/aerc/tree/f1a0fd20/doc/aerc.1.scd#L284
[3]: https://lists.gnu.org/archive/html/groff/2014-01/msg00077.html
[4]: https://practicaltypography.com/one-space-between-sentences.html

I suppose "pretend this problem doesn't exist" isn't a valid answer?

On Wed Aug 12, 2020 at 11:58 PM EDT, k.st wrote:
> One possible solution is to avoid sentence spacing entirely using `\&`
>
> $ nroff << EOF
> This is a sentence.\&
> This is another sentence.\&
> 1.\&0 i\&.e.\& test!\&
> EOF
> This is a sentence. This is another sentence. 1.0 i.e. test!

This is my preference.

> However, I have no idea if this will cause any unexpected behaviors.

Could always roll it back if we start getting annoyed users reporting
in.