groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.


From: G. Branden Robinson
Subject: Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.
Date: Sun, 1 Nov 2020 00:27:36 +1100
User-agent: NeoMutt/20180716

At 2020-10-31T13:55:08+0100, Ingo Schwarze wrote:
> Please take man.local out of the equation.  Such a thing simply
> doesn't exist on FreeBSD, OpenBSD, NetBSD, or Dragonfly, and it
> won't be created on OpenBSD.

groff ships it.  What do you do with it?

> If the change isn't reverted in groff upstream, we may have to patch
> groff/tmac/an-old.tmac outright in the groff port to restore
> acceptable behaviour.
> 
> > 3. Restore the remappings to tmac/an-old.tmac, but make them
> >    conditional on a register that defaults off.
> > 4. Restore the remappings to tmac/an-old.tmac, but make them
> >    conditional on a register that defaults on.
> 
> OS-local changes solve little in the first place.

What's OS-local about

.if r SOMEREG \
.   if \n[SOMEREG] \{\
.     char ... ...
.     char ... ...
.   \}

?

You have baffled me.

> Manual pages are supposed to be as operating-system independent as
> possible, such that pages from one system can also be read on another,
> and such that authors of portable software know what to do.  You seem
> to be advocating ecosystem fragmentation, making manual pages
> non-portable, which astonishes me.

That argument is precisely equally true of supporting a configurable LL
register.  The world has shattered into N pieces, where N is every
terminal width in use.  Do you yearn for the days of 110 baud Teletypes
with nroff grinding out the reference pages at 65n width?

> I have no preference among options 1 to 4.
> They are all equally bad.

This is an absurd claim.  I don't think you have understood what options
3 and 4 entail.

> > 5. Revert the change[3] entirely.
> 
> That seems to be the only reasonable course of action to me.
> And not just for now, but for good.

It also happens to be the most frequent prescription that comes off your
pad, so it somewhat loses its force through repetition.

> > 6. Revert the change an un-fix the misuses of ` and ' in code
> >    specimens that I've been repairing for the past few years.
> 
> That is not needed.  There is nothing wrong with the few people who
> know and want to  using the escape sequences that are required for
> general-purpose roff typesetting even in manual pages.

No?  Then stop trying to keep us chained to the divergent semantics that
were hacked into groff_{man,mdoc} in 2009.

Option 4 proposes an opt-in approach for developers concerned about good
typopgraphy, like me, yet you have evaluated it as thoroughly, maximally
objectionable, in precise parity with 3 other options.  Do you struggle
with IRV ballots that require a total ordering of candidates?

With the above, you are, in fact, saying something that there _is_
something deeply wrong, _with me_, for wanting good typography in man
pages and wanting a way to manifest it on my terminal screen without
forking groff.

> By the way, the problem is not only changing thousands of existing
> manual pages - which can't be automated; every single instance of '
> and ` would have to be checked manually.  Here is a list of *a few
> examples* of affected manual pages from OpenBSD base alone.  The
> list is definitely far from comprehensive, these are just some
> examples:
> 
>   section 1: bc, csplit, expr, find, flex, getopt, grep, ksh, ldap,
>     less, mandoc, more, paste, pax, shar, ssh, su, tar, tmux, vi,
>     xargs
> 
>   section 3: BIO_f_ssl, EVP_PKEY_keygen, RMD160Init, SHA256Init,
>     SSL_CTX_set_alpn_select_cb, SSL_CTX_set_default_passwd_cb,
>     cgetent, fgetln, fgets, getopt, getopt_long, malloc, stpcpy,
>     strchr, strcspn, strncat, strncpy, strrchr, strsep, strtol,
>     strtoul, va_start, wcslcpy, wcsrchr, wprintf
> 
>   section 5: ifstated.conf, nsd.conf, pf.conf, pf.os, relayd.conf
> 
>   section 7: ascii, ports, roff

You haven't shared your search method, so I can't infer very much from
this.  Backticks and apostrophes used as quote characters tend to abut
whitespace; backticks are unknown in prose, and apostrophes are
invariably within word boundaries in English except in dialect registers
that are unheard of in man pages.

        Don' go messin' 'roun' wit' the -r and -f flag on rm if'n ya
        knows what's good fer ya.

This sort of thing is not seen.

I don't doubt that there are a lot of wrongly-encoded "quotes" in
OpenBSD man pages, however.

> The problem is that manual pages are written by software developers,
> not by typesetters, who are used to typing programming languages
> and who are used to the fact, from the past, that these five
> characters do not need escaping.

They did in 2008, and every year before that, for people using -Tutf8.

> So new problems will continuously creep in.  Theoretically, i might be
> possible to educate *BSD base system developers, which are maybe a
> thousand people all told, alienating part of them, as Anthony
> explained.  I explained in my first mail why this massive education
> effort is not worthwhile because it provides little benefit: the
> current rules are simpler than the proposed ones and they are adequate
> for the particular needs of software documentation.

So was -Tascii.  Unless you were an APL programmer.  :)

> For GNU/Linux and for portable software, i see no chance for such an
> education project even if it were desired.

I don't share your cynicism regarding the educability of programmers.
If I did, I likely wouldn't be contributing to groff's documentation at
all, and thus not to the rest of it, because it is only through close
study of the documentation that I have managed to learn anything about
the system.

Regards,
Branden

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]