Re: ⟨ vs < in hostname man page of hostname

[Alejandro Colomar <alx@kernel.org>]

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

Hi Jonny,

On 2023-08-07 15:47, Jonny Grant wrote:
> Hi Alejhandro
> 
> Just looking at the COLOPHON
> https://man7.org/linux/man-pages/man1/hostname.1.html

```
COLOPHON         top

       This page is part of the net-tools (networking utilities)
       project.  Information about the project can be found at 
       ⟨http://net-tools.sourceforge.net/⟩.  If you have a bug report for
       this manual page, see ⟨http://net-tools.sourceforge.net/⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨git://git.code.sf.net/p/net-tools/code⟩ on 2023-06-23.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2021-12-12.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org
```

> 
> 
> 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

>  Or even just no angle brackets at all, it's not that common to enclose links in <>

I'm sorry, but that's not an option.  Links /must/ be enclosed in
some other pair of unambiguous quoting, such as <> or "".  See uri(7):

   Writing a URI
       When written, URIs should be placed inside double quotes (e.g.,
       "http://www.kernel.org"), enclosed  in  angle  brackets  (e.g.,
       <http://lwn.net>),  or placed on a line by themselves.  A warn‐
       ing for those who  use  double‐quotes:  never  move  extraneous
       punctuation  (such as the period ending a sentence or the comma
       in a list) inside a URI, since this will change  the  value  of
       the  URI.   Instead, use angle brackets instead, or switch to a
       quoting system that never includes extraneous characters inside
       quotation marks.  This latter system, called the ’new’ or ’log‐
       ical’ quoting system by "Hart’s Rules" and the "Oxford  Dictio‐
       nary  for  Writers and Editors", is preferred practice in Great
       Britain and in various  European  languages.   Older  documents
       suggested  inserting the prefix "URL:" just before the URI, but
       this form has never caught on.

       The URI syntax was designed to  be  unambiguous.   However,  as
       URIs  have  become  commonplace, traditional media (television,
       radio, newspapers, billboards, etc.) have increasingly used ab‐
       breviated URI references consisting of only the  authority  and
       path portions of the identified resource (e.g., <www.w3.org/Ad‐
       dressing>).   Such  references are primarily intended for human
       interpretation rather than machine, with  the  assumption  that
       context‐based  heuristics  are  sufficient  to complete the URI
       (e.g., hostnames beginning with "www" are likely to have a  URI
       prefix  of  "http://" and hostnames beginning with "ftp" likely
       to have a prefix of  "ftp://").   Many  client  implementations
       heuristically  resolve  these  references.  Such heuristics may
       change over time, particularly when new schemes are introduced.
       Since an abbreviated URI has the same syntax as a relative  URL
       path,  abbreviated URI references cannot be used where relative
       URIs are permitted, and can be used only when there is  no  de‐
       fined  base  (such  as in dialog boxes).  Don’t use abbreviated
       URIs as hypertext links inside a  document;  use  the  standard
       format as described here.

Cheers,
Alex

> 
> https://man7.org/linux/man-pages/man1/hostname.1.html
> 
> Kind regards, Jonny

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

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