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