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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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:
>> Hi Michael, Branden,
>> On 1/9/21 8:58 PM, Alejandro Colomar wrote:
> [...]
>>> 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.
> [...]
>>> 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/