help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: o@krj.st
Cc: discuss@mandoc.bsd.lv
Subject: Re: Option to disable sentence spacing in tty output?
Date: Fri, 14 Aug 2020 01:22:07 +0200	[thread overview]
Message-ID: <20200813232207.GB46177@athene.usta.de> (raw)
In-Reply-To: <C4W7PRAXX6VJ.2ONUP0D5K7A4K@szk>


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?


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

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

 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2020-08-13 23:22 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-13 22:12 k.st
2020-08-13 23:22 ` Ingo Schwarze [this message]
2020-08-14  3:50   ` k.st

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200813232207.GB46177@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=o@krj.st \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).