Re: [Groff] It is time to modernise "groff"

[G. Branden Robinson]

At 2017-08-31T20:54:10+0000, Bjarni Ingi Gislason wrote:
> Introduction:
> 
> A) There are about 1400 lines in the code in the "groff" repository that
> contains the backquote, grave (`) as a directional quote, but it is output
> exactly as itself, as it is not processed as an input to "groff" to be
> formatted and typeset.

No argument here.  A grave accent is not a directional quote; it's not
1968, and nobody is using a 7-bit display system nor a paper teletype
where the semantics of backspacing in the output data stream to compose
characters are respected.

Stuff like `this' should be burned with fire and extreme prejudice.
It's been ugly for over 20 years and is indefensible.

If LC_MESSAGES matches .*\.UTF-8 then people who love directional quotes
can write po files for them to their heart's content.

> B) There are too many manuals (man pages) that contain a syntax error that is
> not seen because
> 
> a) The user does not use '-ww'
> 
> b) Programs, that use "groff", like "man" (from "man-db"), suppress most
> warnings by default, so the user must himself arrange for the permission to
> see the warnings.

I agree with others in the thread that making groff's default behavior
into an extremely rigorous validator will exasperate our users.

However, there should exist an easy-to-use knob to turn this on, and
people like us who are trying to develop groff and/or improve man pages
and other *roff documents should be using it.

Bjarni, your efforts to make groff's own documentation reflect best
current practice are extremely laudable and we should make it easier for
others to help you out in this area.  You have stomped on many of the
problems that annoyed me, and noticed many others I had no idea about.
So before I get back to your proposal, THANK YOU!

> Changes:
> 
> case A:
>   Instead of changing these '`' to "'", it is time to modernize "groff" and
> get rid of Americanism, old, obsolete, deprecated, bad, and worse decisions.

This is too broadly and vaguely phrased to make for a mission statement.
(I would say something about too susceptible to subjective
interpretation, but what mission statement _isn't_?) Further,
occasionally, Americans do set good precedents.  I'd be happy to cite an
example if I could think of one.  ;-)

>   Suggestions:
> 
> a) Change command substitution `...` to a modern form, $(...) or equivalent

Yes.  As Tom Duff pointed out, the escaping required on ` within ` is
exponential in the nesting depth.  Almost no one will get this right.
Moreover, almost every Bourne-family shell user these days is using a
shell that is mostly POSIX-compliant, and $() is not one of the
less-well-respected parts of the standard.  I hear even Solaris came
around several years ago.

foo=`bar` is a fine shortcut for lazy typists but horrible pedagogy.

> b) Change backquote (`), that is used as a quote mark, to ' (single quote)

Iff proper directional quotes are not available, yes.

[skipping a few points that I think might cause legacy documents to
become ugly]

>   I have seen too many man pages, where a warning from "groff" is seen, if
> the user allows it.
> 
>   Programs like "man" (from "man-db") suppress most warnings if the user
> does not turn on an environmental variable (which too many users and
> maintainers do not know of, or ignore).

A few things can be done here.

1) man-db's own man(1) page should document this environment variable.
All I see is the -w option which points me to the dang groff info page
for a list of its recognized arguments.

2) groff(7) and groff_man(7) should tell document writers and
maintainers how to turn warnings on.  Right now groff_man(7) says
nothing and groff(7) gives terse tabular descriptions of some
warning-related requests that I frankly mostly don't understand.
Tutorial material is needed.

3) man-pages's man(7) should also tell man page writers and maintainers
how to perform validity checking of their documents.

Best practices exist; let's get them written down and spread the news.

>   Writers, maintainers (up- and downstreams) should not be allowed to misuse
> "*roff" to produce, maintain or distribute faulty products!

That runs afoul of the FSF's Freedom Zero[1].  There are limits to how
much we can solve social problems with technology.

What we can and should do is make Doing Right easy, and Doing Wrong
tedious or discouraging.  Let Groff be a nice quiet Unix tool that emits
no spew to stderr when all is well.  But only then.

> h) Make the default page size be A4 (a4).
> 
> i) Adjust default sizes to the metric system.
> 
> j) Use a metric point as default.  1 such point is then 375 micrometres
> (15 x 250 um) or about 1 didot-point (0.376 mm).

The above items should be determined by consulting the locale, surely?

> k) Add a warning (error) to some macros, when they are misused.
> 
>   Example: macros for two fonts (like .BR, .IR) but have only one argument.

Yes, these should warn because man page writers often screw this up
thanks to careless use of cut and paste.

Relatedly,  I've seen grief caused by attempts at cross-referencing the
titles of section headings:

.SH Description
The foobar frobnicates.
Some diagnostics are fatal; see
.BR Exit status ,
below.
.\" ...
.SH Exit status
.\" ...

But that sort of problem is a lot harder to catch with logic.

> l) Remove some compatibility of "groff" with Unix troff, example:
> 
>   preproc/tbl/table.cpp:// The only point of this is to make `\a' ``work'' as 
> in Unix tbl.  Grrr.
> 
> m) Change ``...'' to "...".  Directional quotation mark are not useful in
> comments, output to the standard error, or output that is not processed by
> "groff" itself.  Applies also to "groff".
> 
>   Such writing of quotes is a good example of how people get brainwashed.
> 
> n) Let \[en] output '--' (en-dash) when glyph is missing
> Let \[em] output '---' (em-dash) when glyph is missing

I don't agree with this.  This is an aping of TeX's input conventions
and not standard English orthography.

In typewriter-like environments, there simply is no distinction between
the hyphen, the minus, and the en-dash in English, and an em-dash is
written as "--".

I think a far better solution is to identify and fix fonts that are
missing these extremely important glyphs.

At the risk of blaspheming, coverage of the Windows-1252 character
set[2] not only pays off immensely in terms of actually-encountered
character repetoire in English-language text (which is what most[?]
*roff documents and especially man pages are), but most fonts that are
either commercial or designed to replace commercial fonts have to have
glyphs for its codepoints.

(For that matter, any FLOSS font intended for text rendering has little
business not matching or exceeding Windows-1252's coverage.  It's only
an 8-bit encoding, and no glyphs are defined for the C0 controls, in
distinction to the Mulligan stew that the older IBM code pages crammed
in there.)

> o) Use the .ig request for longer (4-5 lines) comments, like
> .de comment
> ..
> .ig comment
> <Comments>
> .comment

1) Why is ".de comment" necessary?  .ig with no arguments is already
terminated by "..".

Some quick experimentation shows that .ig does actually call its
argument, _and_ ignores everything until .argument is seen, kind of
like a shell here document.

In any case,

.ig
multi-line comment
multi-line comment
multi-line comment
multi-line comment
..

is all that is required.

2) This is a good tip; Vim's autoindenter is too dumb to handle *roff
comments.  It happily flows .\" right into your paragraphs as if it were
an English word.  Sigh.  On the bright side, its syntax highlighter
recognizes .ig and handles it correctly, but only in the no-argument
case.

>   Issue an error if there are more the (4-5) consecutive lines that begin
> with the comment request.

Disagree here.  Instead we should promote knowledge of the .ig request.

Though I suppose there is the perenially damnable question of its
portability in man pages.  As a rule I hate to see font escapes and
non-macro requests in man pages.  I mean REALLY hate.

> p) Remove the '-a' option (the ASCII approximation output).

I didn't even know this existed.  Looking at what it spits out, I find
myself wondering what good it is.  Is this for Unix troff compatibility?
For people who didn't even have glass TTYs and needed to imagine what
the typeset output would look like?

I see that SUS has not standardized the troff command at all, so I
suppose there is no specification requiring us to keep it.  Maybe warn
of its deprecation in the groff 1.22.4 release notes, and remove it for
groff 2.0[3]?

[1] https://www.gnu.org/philosophy/free-sw.en.html
[2] https://en.wikipedia.org/wiki/Windows-1252
[3] I'm a believer in semantic versioning. http://semver.org/

-- 
Regards,
Branden

signature.asc
Description: PGP signature