Option to disable sentence spacing in tty output?

Option to disable sentence spacing in tty output?

[k.st]

Hi Ingo,

Is there currently an option in mandoc to disable sentence spacing, i.e.
2 spaces after end-of-sentence character, in tty outputs?

I noticed that many man page authors either do not follow semantic
line-breaking or convert man pages from other formats such as asciidoc,
pandoc, and scdoc. All of them has some problems handling sentence
spaces and lead to inconsistent spacing in man pages.

For example, in git-push(1),

  --prune
     Remove remote branches that don’t have a local counterpart. For
     example a remote branch tmp will be removed if a local branch with
     the same name doesn’t exist any more. This also respects refspecs,
     e.g.  git push --prune remote refs/heads/*:refs/tmp/* would make
     sure that remote refs/tmp/foo will be removed if refs/heads/foo
     doesn’t exist.

it uses 1 space after period, but 2 spaces after 'e.g.'. Git uses
asciidoc to convert man pages, which does not handle sentence spacing
very well.

Since sentence spacing can lead to inconsistent spacings, I think it is
reasonable to have an option to disable sentence spacing entirely and
let user choose which convention to use.

groff uses `.ss` request to control it, but in mandoc this seems to be
hardcoded in `term.c`:

    if ((p->flags & TERMP_NOSPACE) == 0) {
      if ((p->flags & TERMP_KEEP) == 0) {
        bufferc(p, ' ');
        if (p->flags & TERMP_SENTENCE)
          bufferc(p, ' ');
      } else
        bufferc(p, ASCII_NBRSP);
    }

We essentially only need to add a check before printing the second
space. Since mandoc deals with man pages only, maybe it would make sense
to implement this as a command-line argument, similar to --nj and --nh
flags from man-db's man(1)?

Best,
kst
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Option to disable sentence spacing in tty output?

[Ingo Schwarze]

Hello,

k.st wrote on Thu, Aug 13, 2020 at 10:12:44PM +0000:

> Is there currently an option in mandoc to disable sentence spacing,
> i.e. 2 spaces after end-of-sentence character, in tty outputs?

No.

See also:  https://man.openbsd.org/roff.7#ss

> I noticed that many man page authors either do not follow semantic
> line-breaking or convert man pages from other formats such as asciidoc,
> pandoc, and scdoc. All of them has some problems handling sentence
> spaces and lead to inconsistent spacing in man pages.

My philosophy is "garbage in, garbage out".

Encourage authors to write correct source code.

Encourage software developers of man(7) generators to produce
better quality in their generators - though admittedly, pod2man(1)
is already good enough and all others are basically unmaintained,
hopeless crap, with DocBook by far the worst of all, markdown also
quite bad, scdoc a very sloppy niche product, and pandoc virtually
unused by any real-world software.  Rest and ASCIIdoc aren't really
good either.  None of that seems likely to change.

Sometimes, when really serious problems are very widespread and
have devastating consequences, implementing fully automatic workarounds
that fix stuff up without needing any user intervention can help
users, but workarounds for issues of little to no importance just
encourage laziness and bad practice for no relevant benefit.

> Since sentence spacing can lead to inconsistent spacings, I think
> it is reasonable to have an option to disable sentence spacing
> entirely

I don't agree.  I don't believe in low-importance options.
To warrant an option, something must be *really* of major
importance, or the downside of making the documentation longer
outweighs the utility of the new feature.

Dealing with minor glitches in the output of broken man(7) generators
is clearly very far from being a sufficient reason for adding an
option.  Heck, the whole man(7) language has been obsolete for more
than two decades, so anything related to the man(7) language, even
if much more important, is not a good enough reason for adding an
option.

> and let user choose which convention to use.

That seems pretty irrelevant to me: bells and whistles...

> groff uses `.ss` request to control it, but in mandoc this seems to be
> hardcoded in `term.c`:
> 
>     if ((p->flags & TERMP_NOSPACE) == 0) {
>       if ((p->flags & TERMP_KEEP) == 0) {
>         bufferc(p, ' ');
>         if (p->flags & TERMP_SENTENCE)
>           bufferc(p, ' ');
>       } else
>         bufferc(p, ASCII_NBRSP);
>     }
> 
> We essentially only need to add a check before printing the second
> space.

Respecting .ss would be easy indeed, but that would amount to letting
the *author* choose rather than the user, which would likely result
in less rather than in more consistency, and which would provide
no benefit whatsoever.

> Since mandoc deals with man pages only, maybe it would make sense
> to implement this as a command-line argument, similar to --nj and --nh
> flags from man-db's man(1)?

getopt_long?  Over my dead body.

But i don't think there is the slightest chance for building a
sufficiently good argument for -O frenchspacing either.

Configurability is not a goal for manual page display.  Instead,
what matters is a consistent style that people can get used to.
Gratuitiously changing the existing style also isn't something i
like to do.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Option to disable sentence spacing in tty output?

[k.st]

Sorry, I forgot to cc the list.

---

"Ingo Schwarze" <schwarze@usta.de> wrote:

> Though admittedly, pod2man(1) is already good enough and all others
> are basically unmaintained, hopeless crap.

Now that you mentioned pod2man(1), I noticed that it also has trouble
handling sentence breaks.

  $ cat test.pod
  =head1 Test

  This is a line. This is another line.
  $ pod2man test.pod | mandoc
  TEST(1)               User Contributed Perl Documentation              TEST(1)




  Test
         This is a line. This is another line.



  perl v5.32.0                      2020-08-14                           TEST(1)

> but workarounds for issues of little to no importance just
> encourage laziness and bad practice for no relevant benefit.

I agree that this issue is very minor. It should be handled by man(7)
generators, but as far as I know, the only generator that handles this
properly is Pandoc. This is quite difficult without enforcing the same
line-breaking style as roff. Pandoc uses an abbreviation list to handle
ambiguity, but there can be false positives.

I have addressed this issue to developers of multiple man(7) generators.
For asciidoc, it is tied to docbook, which hasn't been updated for years
and mostly deprecated in favor of a new format, so fixing it might be
hopeless [1].

> Respecting .ss would be easy indeed, but that would amount to letting
> the *author* choose rather than the user.

groff happens to have a man.local file that is loaded before processing
any man pages, but mandoc's workflow is quite different, so yes, I don't
think implementing this option would matter a lot to users.

> getopt_long? Over my dead body.
>
> But i don't think there is the slightest chance for building a
> sufficiently good argument for -O frenchspacing either.

Of course, I mean similar in functionality, not similar option names.

As an alternative to option flags, If anyone would like to disable
this behavior. The following patch should do the trick:

    For revision 1.281.
    --- a/term.c
    +++ b/term.c
    @@ -535,8 +535,6 @@ term_word(struct termp *p, const char *word)
        if ((p->flags & TERMP_NOSPACE) == 0) {
          if ((p->flags & TERMP_KEEP) == 0) {
            bufferc(p, ' ');
    -				if (p->flags & TERMP_SENTENCE)
    -					bufferc(p, ' ');
          } else
            bufferc(p, ASCII_NBRSP);
        }

- kst

[1]: https://github.com/asciidoc/asciidoc-py3/issues/137
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv