Re: ⟨ vs < in hostname man page of hostname

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 3846 bytes --]

Hi Jinny,

On 2023-08-07 17:36, Jonny Grant wrote:
>>>
>>> Noticed that sometimes the '⟨' doesn't render, perhaps it is not in all fonts, would it be possible to use consider using regular '<' and '>' character in the man page?
>>
>> That is implemented using man(7)'s UR, which is for URIs.  The source
>> code of the manual page doesn't know about the glyph that will be
>> produced in your system.  In your system, groff(1) will try to find
>> the most appropriate one.  You (or your distributor) can also tweak
>> that.  You can for example change it to use ASCII '<' and '>'.
>>
>> In man7.org, I guess that you read it correctly from any machine.
>> In your systems' pages there's no COLOPHON anymore (I removed it
>> in man-pages-6.01).  If you're on an old system, you can tweak it.
>>
>> But you'll still see that character in pages that have URIs in them.
>> For example, let's consider hier(7):
>>
>>     $ grep -n '^\.UR ' man7/hier.7;
>>     640:.UR https://refspecs.linuxfoundation.org/fhs.shtml
>>
>> which renders as (including the whole section):
>>
>> STANDARDS
>>        The   Filesystem   Hierarchy   Standard   (FHS),   Version  3.0
>>        ⟨https://refspecs.linuxfoundation.org/fhs.shtml⟩,     published
>>        March 19, 2015
> 
> 
> Fair enough. Some pages even have both.

Pages that use both are bad.  That means that in some places they used
the correct UR man(7) macro, and in some others they hardcoded <>, which
is wrong.  It may happen in <man7.org>, because the COLOPHON was added
by Michael, while the page was written by a different author.  In other
places, it means that the page is badly written.

I know of uri.7, where this happens, and some day I'll fix it.

> I saw sometime <> is used, as I expected,

Those pages are wrongly written.  I expect that most of those pages are
not written in man(7), but rather translated from some other source
language by a program, which usually produce crap man(7) source.

> other times '⟨⟩' .

When you see that, the page was written properly in man(7) (or
mdoc(7)? I expect both produce the same glyph; Branden?).

> "SEE ALSO"
> 
> https://man7.org/linux/man-pages/man1/cp.1.html

I think GNU coreutils is one of those projects that don't write man(7)
source, but rather translate it from a different language.

alx@debian:~/src/gnu/coreutils$ find | grep 'cp\.1'
alx@debian:~/src/gnu/coreutils$

> 
> But though "COLOPHON" looks like it was appended by a man7 website script with the '⟨⟩' instead,

Yes, Michael uses a script to generate the COLOPHON.  That script uses
the proper method for writing URIs: the UR man(7) macro.  He used a
similar script for releasing man-pages until 5.13, as you'll find our
pages in versions <=5.13 had a COLOPHON in them.

I temporarily added a script that did the same thing:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts/append_COLOPHON.sh?h=cd34c839d3c9878db9105714b1e460f30057e7f2>

You can expect that Michael's script will be similar.

However, shortly after I decided to just remove the COLOPHON section,
and thus the script:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?h=8c3052b0322580eba62de91f04ba657f7dfe360e>

> so I thought maybe that could be changed for consistency to <>.

No.  It should be <> that are fixed to use the UR man(7) macro.

> There are so many different characters that could be used, but <> is on every keyboard :)

But nobody types ⟨⟩.  It's generated by groff(1).  When you write
an email or anything similar, you can use <>, but for manual pages,
those symbols are fine, I guess.

> Kind regards, Jonny

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]