Re: [PATCH] posix.py: ffix: Correctly format URIs

Hi Branden,

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

Hi Alex,

I've noticed you've started formatting your emails like recommended
*roff input.  ;-)

Yes.  Before I filled until the margin, but when I edited something at
the begining (especially when writing on the editor and not directly on
Thunderbird), I had to fix all the lines to fit the margin.

So to solve it, I decided to cut the lines at meaningful point, much
before the margin, as when writing manual pages, so that if I edit text
at the begining I don't have to edit every line.

That habit extended to what you can see :)

I have, however, taken the liberty of reformatting them conventionally
for brevity.

No problem.  Just a nitpick: when reading the mail from the phone, it
wraps around col 70 (more or less; it's not monospace, so it's an
experimental approximation), so many of the lines you compacted, expand
to a line and a word or so, effectively occupying 2 lines each, and
therefore occupying even more space than originally.

That's also the reason when I render a manual page and copy it's
contents to an email, I tend to use 68-col (or less) terminals, so that
text is nicely formatted on phones too.

At 2021-01-09T22:07:09+0100, Alejandro Colomar (man-pages) wrote:

quoted

Hi Michael, Branden,
On 1/9/21 8:58 PM, Alejandro Colomar wrote:

[...]

quoted

quoted

Enclose URIs in <>.  It is especially important in this case, as the
URIs are followed by '.'.  From "" or <>, I prefer <>, as they are
less used in other contexts, so they are more easily read as URIs.

[...]

quoted

quoted

Also enclose them in [.UR/.UE].

I was wondering if, instead of hardcoding <>, it would be possible to
make .UR/.UE embed those characters.  It would make the code more
generic, but I don't know if it is feasible or desirable.

Not only is it possible, but the groff_man(7) .UR/.UE extension macros
have been doing this automatically since they were introduced in January
2007.

They use left and right angle bracket special character escapes (Unicode
U+2039 and U+203A)[1]; the output drivers degrade these to less-than and
greater-than signs if the former glyphs are unavailable, or if the
formatter is not groff[2].

Here are some of the relevant portions of tmac/an-ext.tmac.

[...]
  .\" groff has glyph entities for angle brackets.
  .ie \n(.g \{\
  .  ds la \(la\"
  .  ds ra \(ra\"
  .\}
  .el \{\
  .  ds la <\"
  .  ds ra >\"
  .  \" groff's man macros control hyphenation with this register.
  .  nr HY 1
  .\}
[...]
  .\" End URL.
  .de UE
[...]
  .    nh
  \\*(la\\*(m1\\*(ra\c
  .    ie \n(.g \&\\$*\"
  .    el \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
  .    hy \\n(HY
[...]
  ..

The macro has a lot of conditional logic to support multiple formatters,
include non-groff ones--it attempts to be usable even with old AT&T
troff.  For the same reason, the register and string names used are
short and unfriendly.  It also does special things when formatting for
groff's HTML output device, which I do not show above.  But the heart of
the matter for terminal output is the line

  \\*(la\\*(m1\\*(ra\c

which uses the left and right angle bracket strings defined previously.

Let me know if you could use the above in annotated form.

If something in your test environment is preventing the angle brackets
from being rendered, maybe I could help you troubleshoot it?

Regards,
Branden

Hmm, I might have read a few URLs that didn't use .UR/.UE to think that
they didn't render a character; I don't know.  After your email, I
checked, and yes, it renders some character (the character depends on
the terminal: on tty I've seen a diamond, and on the xfce terminal
something similar (but slightly different) to a parenthesis).

So I'll send a v2 patch removing the <>.

Thanks!

Alex

[1] https://man7.org/linux/man-pages/man7/groff_char.7.html#Glyph_tables
[2] Technically, if the formatter does not claim groff compatibility by
    setting the .g register to a positive value.

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/