Re: groff 1.23.0.rc2 available for testing

[G. Branden Robinson]

At 2023-02-05T13:29:11+0000, Ralph Corderoy wrote:
> Some drive-by comments from a quick skim.

Consider getting out of the car and taking the air next time, perhaps...

> > o New requests `soquiet` and `msoquiet` are available.  They operate
> >   as `so` and `mso`, respectively, except that they do not emit a
> >   warning diagnostic if the file named in their argument does not
> >   exist.
> 
> Given the ‘file’ warning also controls this, AIUI, I wonder if it
> would have been more orthogonal to have a new command to alter the
> warnings for just what follows.
> 
>     .warn -file so might-be-missing
>     .warn -el historicalmacro foo bar

Possibly, but (1) the `*quiet` requests are for cases where no strong
dependency on the sourced file is present and (2) redesigning the `warn`
interface as you suggest was beyond my ambition at the time (April 2021)
and would furthermore seem to warrant reconsideration of the warning
category structure, also beyond my ambition at the time.  As I recall,
Ingo had much to complain about there.

Here is the syntax summary of the `warn` request from groff(7).  It (the
feature, not the exact wording below) has looked this way for 30+ years.
(Warning categories seem to have been implemented prior to groff 0.6.)

       .warn     Enable all warning categories.
       .warn 0   Disable all warning categories.
       .warn n   Enable warnings in categories whose codes sum to n; see
                 troff(1).

I don't infer the complete meaning of your proposal, either.

> > o nroff now supports spaces and tabs between option flag letters and
> >   option arguments, like groff and troff themselves.
> 
> I think that's trying to say
> 
>     nroff -o 3,1,4
> 
> is now okay, i.e. the option's value can be a separate argument to the
> option,

Yes.

> but it reads to me that
> 
>     nroff -o' 3,1,4'
> 
> will ignore the space.  Having to mention spaces and tabs smells wrong.

The file says that nroff "supports" them, not that it "ignores" them, so
I don't know how you arrived at this reading.

[...]
> >     .am pdfpic@error
> >     .  ab
> >     ..
[...]
> >     .am pspic@error-hook
> >     .  ab
> >     ..
> 
> Were those ‘.ab’ written with the lack of a default message in mind?

tmac/pdfpic.tmac says:

.\" A user may wish to append an 'ab' to this macro using 'am'.  That
.\" is why we don't 'return X' from here to return from two scopes.
.de pdfpic@error
.  tm pdfpic.tmac:\\n[.F]:\\n[.c]: error: \\$*
..

pspic emits no diagnostics whatsoever.  Would anyone like to write some?

> > o The new rfc1345 macro package, contributed by Dorai Sitaram, defines
> >   special character identifiers implementing RFC 1345 mnemonics (plus
> >   some additions from Vim, which itself uses RFC 1345 for its digraphs).
> >   It is documented in the groff_rfc1345(7) man page.
> 
> Mention ‘digraphs’ earlier and more prominently as that's their common
> name.

The contents of RFC 1345 and of rfc1345.tmac reveal a problem with this
claim.

.char \[U:-] \[u01D5]    \" LATIN CAPITAL LETTER U WITH DIAERESIS AND MACRON
.char \[u:-] \[u01D6]    \" LATIN SMALL LETTER U WITH DIAERESIS AND MACRON
.char \[U:'] \[u01D7]    \" LATIN CAPITAL LETTER U WITH DIAERESIS AND ACUTE
.char \[u:'] \[u01D8]    \" LATIN SMALL LETTER U WITH DIAERESIS AND ACUTE
.char \[U:<] \[u01D9]    \" LATIN CAPITAL LETTER U WITH DIAERESIS AND CARON
.char \[u:<] \[u01DA]    \" LATIN SMALL LETTER U WITH DIAERESIS AND CARON
.char \[U:!] \[u01DB]    \" LATIN CAPITAL LETTER U WITH DIAERESIS AND GRAVE
.char \[u:!] \[u01DC]    \" LATIN SMALL LETTER U WITH DIAERESIS AND GRAVE
[...]
.char \[AA'] \[u01FA]    \" LATIN CAPITAL LETTER A WITH RING ABOVE AND ACUTE
.char \[aa'] \[u01FB]    \" LATIN SMALL LETTER A WITH RING ABOVE AND ACUTE
.char \[AE'] \[u01FC]    \" LATIN CAPITAL LETTER AE WITH ACUTE
.char \[ae'] \[u01FD]    \" LATIN SMALL LETTER AE WITH ACUTE
.char \[O/'] \[u01FE]    \" LATIN CAPITAL LETTER O WITH STROKE AND ACUTE
.char \[o/'] \[u01FF]    \" LATIN SMALL LETTER O WITH STROKE AND ACUTE
[...]
.char \[L--.] \[u1E38]    \" LATIN CAPITAL LETTER L WITH DOT BELOW AND MACRON
.char \[l--.] \[u1E39]    \" LATIN SMALL LETTER L WITH DOT BELOW AND MACRON
[...]
.char \[50r] \[u217C]    \" SMALL ROMAN NUMERAL FIFTY
.char \[100r] \[u217D]    \" SMALL ROMAN NUMERAL ONE HUNDRED
.char \[500r] \[u217E]    \" SMALL ROMAN NUMERAL FIVE HUNDRED
.char \[1000r] \[u217F]    \" SMALL ROMAN NUMERAL ONE THOUSAND
[...]
.char \[5000R] \[u2181]    \" ROMAN NUMERAL FIVE THOUSAND
.char \[10000R] \[u2182]    \" ROMAN NUMERAL TEN THOUSAND
[...]
.char \[1000RCD] \[u2180]    \" ROMAN NUMERAL ONE THOUSAND C D

One can perceive the progressively stretching cardinality of "digraph".

> >   you should now write
> >     .MR ls 1 .
> 
> Is text to include in one's man-page preamble given which tests if .MR
> is available and if not defines it?  This would encourage .MR to be
> used.

https://git.savannah.gnu.org/cgit/groff.git/commit/?id=18d708e489758636ff9e168eee2592591755eb61

> >   The default is "b" (adjust lines to both margins) as has been
> >   the Unix man(7) default since 1979.
> 
> Probably just because it was showing off, similar to UNIX with small
> caps.  :-)

We have testimony that Room 1137 people (McIlroy, McRoberts) had a
preference *against* spelling Unix in shouting capitals, but were
overridden by AT&T's legal department.  I have seen no account that
adjustment mode "b" was also externally imposed against resistance.
Further, groff is typesetting software.  Professionally typeset
literature continues to perform this adjustment, and its popularity does
not seem to be flagging.  Looking at a few recently published titles in
my collection, all of

  _The Elements of Typographic Style_, fourth edition, Bringhurst;
  _Code_, second edition, Petzold;
  _UNIX [sic!]: A History and Memoir_, Kernighan; and
  _A Hitch in Time_, Hitchens;

set text this way.

> It looks ugly.

The very item you are quoting tells you how to configure this behavior
so that it no longer repels you.

> > o On output devices using the Latin-1 character encoding ("groff -T
> >   latin1" and the X11 devices) the special character escape sequence
> >   \[oq] (opening quote) is now rendered as code point 0x27
> >   (apostrophe) instead of 0x60 (grave accent).  The ISO 8859/ECMA-94
> >   Latin character sets do not define any glyphs for directional
> >   ("typographer's") quotation marks, but the apostrophe is depicted
> >   in the defining standard as a neutral (vertical) glyph, whereas
> >   the grave accent 0x60 and acute accent 0xB4 are mirror-symmetric
> >   diacritical marks.
> >
> >   This change has no effect on _input_ conventions for roff source
> >   documents.  You can still get directional single quotes on UTF-8,
> >   PostScript, PDF, and other output devices supporting them by
> >   typing sequences like `this' in the input (character remapping
> >   with 'char' requests and similar notwithstanding).
> 
> -Tascii could do with a mention to place it in the Latin-1 or UTF-8
> camp.

US-ASCII was ambiguous regarding the shape of the apostrophe.  This was
discussed at some length about 4 years ago.

commit 2e2d302aa7bce88bad9b05f24db22b4727957f69
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jun 28 03:26:57 2019 +1000

    devlatin1: Map \(oq to ' on output.

[snip: pretty much the text of the NEWS item]

    Patch and idea from Ingo Schwarze, who originally proposed it for
    ASCII as well, and included Latin-1 for parallelism.  The groff
    developers could reach no consensus about the wisdom of such a
    change for ASCII (which was designed to support ambiguity for some
    code points, requiring the development of supplementary
    interpretation conventions between parties).  ECMA-94/ISO-8559 is
    more strongly prescriptive.

    See https://savannah.gnu.org/bugs/?55616 and the groff mailing list
    archives for 31 January to 23 February 2019 at
    https://lists.gnu.org/archive/html/groff for lengthy discussion.

That "8559" up there should have been "8859".  It is correct in the
ChangeLog, but commit messages are effectively immutable.

> What's producing those funky ‘o’ bullet points?

Tradition.  It's what the NEWS file (whence these items came) has used
going all the way back.  I declined--in this instance--to, shall we say,
"deviate".

> And the `hip` backticks?

These are my innovation and, I admit, kind of Markdownish.  With the
hastening demise of the horrendously ugly `quotation' convention, I find
I now have 3 sorts of quotation at my disposal (in plain text
documents), so I use backticks for "language elements" (the sorts of
things that might have index entries or tagged paragraphs devoted to
them), double quotes for file names and ordinary quotation, and single
quotes for miscellaneous literals.

I don't hate Markdown; I merely believe that its place in the domain of
technical writing is more limited than do its many proponents who
suggest that it can and should replace everything else, immediately.  I
find this view most commonly expressed by engineers who strive to
suggest their own superlative brilliance and resent writing
documentation at all.  ("Use the source, Luke," their fathers grunted to
each other.)  Little wonder that for them, Markdown is a solution finely
tuned to getting a manager's box ticked quickly so that they can get
back to the serious, well-compensated business of writing code that
other people aren't expected to understand.  Those other people, the
ones who want proper documentation, are not as brilliant, you see.

> Could UTF-8 be produced instead with • and ‘elegant’?

It could, but at the cost of reducing the readability of the file on
limited environments like legacy Unix systems, to which I hope groff
remains portable.

Regards,
Branden

signature.asc
Description: PGP signature