Re: groff 1.23.0.rc2 available for testing

[John Gardner]

>
> The an (man) macro package can now produce clickable hyperlinks within
> terminal emulators


It might be worth clarifying for macOS users that the hyperlinks use a
protocol incompatible with Apple's: “*man:printf(3)*” is used instead of “
*x-man-page://3/printf*” (the latter scheme is ancient and documented in
detail here
<https://github.com/donmccaughey/ManOpen/blob/master/Documentation/x-man-page_URL_Scheme.md>
).

If you agree, I can have a crack at documenting a workaround for macOS
users, but since it's essentially an opt-in feature, such a thing might be
overkill at this point. Let me know.

— John


On Mon, 6 Feb 2023 at 02:57, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

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