Re: ⟨ vs < in hostname man page of hostname

[Jonny Grant]

On 09/08/2023 11:16, Alejandro Colomar wrote:
> 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.
>
Ok I agree. If UR was used consistently it would be better. Thank you for your 
reply.

I'd change the groff configuration to generate the web version of those UR on 
man7.org to be <>. Maybe that's just my preference :)

Kind regards, Jonny