Re: ⟨ vs < in hostname man page of hostname

Re: ⟨ vs < in hostname man page of hostname

[Alejandro Colomar]

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

Re: ⟨ vs < in hostname man page of hostname

[Jonny Grant]

On 07/08/2023 16:13, Alejandro Colomar wrote:
> 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


Fair enough. Some pages even have both. I saw sometime <> is used, as I expected, other times '⟨⟩' . "SEE ALSO"

https://man7.org/linux/man-pages/man1/cp.1.html

But though "COLOPHON" looks like it was appended by a man7 website script with the '⟨⟩' instead, so I thought maybe that could be changed for consistency to <>. There are so many different characters that could be used, but <> is on every keyboard :)
Kind regards, Jonny

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

Re: ⟨ vs < in hostname man page of hostname

[Alejandro Colomar]

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

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

Re: ⟨ vs < in hostname man page of hostname

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1552 bytes --]

Hi Alex & Jonny,

At 2023-08-09T12:16:12+0200, Alejandro Colomar wrote:
> > 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?).

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.23.0#n1121

At present, mdoc(7) hyperlinks don't render similarly, but I plan to
make them do so for groff 1.24.

Here's an example.

$ cat EXPERIMENTS/use-Lk.mdoc
.Dd 2023-08-09
.Dt use\-Lk 1
.Os
.Sh Name
.Nm use\-Lk
.Nd demonstrate a hyperlink
.Sh Description
What do man pages look like with
.Lk http://example.com hyperlinks ?

use-Lk(1)                   General Commands Manual                  use-Lk(1)

Name
     use-Lk — demonstrate a hyperlink

Description
     What do man pages look like with hyperlinks: http://example.com?

GNU                               2023‐08‐09                         use-Lk(1)

Except for font styling differences, mandoc(1) renders it the same.

At 2023-08-09T11:39:32+0100, Jonny Grant wrote:
> 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 :)

You can express your preference in groff man(7)'s site-local
configuration.  Its installation location for your system is documented
in groff_man(7).

On my Debian system, it's in /etc/groff/man.local.

Adding the following should do the trick:

.if '\*[.T]'utf8' \{\
.  char \[la] <
.  char \[ra] >
.\}

Regards,
Branden

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

Re: ⟨ vs < in hostname man page of hostname

[Jonny Grant]

On 10/08/2023 04:25, G. Branden Robinson wrote:
> Hi Alex & Jonny,
> 
> At 2023-08-09T12:16:12+0200, Alejandro Colomar wrote:
>>> 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?).
> 
> https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.23.0#n1121
> 
> At present, mdoc(7) hyperlinks don't render similarly, but I plan to
> make them do so for groff 1.24.
> 
> Here's an example.
> 
> $ cat EXPERIMENTS/use-Lk.mdoc
> .Dd 2023-08-09
> .Dt use\-Lk 1
> .Os
> .Sh Name
> .Nm use\-Lk
> .Nd demonstrate a hyperlink
> .Sh Description
> What do man pages look like with
> .Lk http://example.com hyperlinks ?
> 
> use-Lk(1)                   General Commands Manual                  use-Lk(1)
> 
> Name
>      use-Lk — demonstrate a hyperlink
> 
> Description
>      What do man pages look like with hyperlinks: http://example.com?
> 
> GNU                               2023‐08‐09                         use-Lk(1)
> 
> Except for font styling differences, mandoc(1) renders it the same.
> 
> At 2023-08-09T11:39:32+0100, Jonny Grant wrote:
>> 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 :)
> 
> You can express your preference in groff man(7)'s site-local
> configuration.  Its installation location for your system is documented
> in groff_man(7).
> 
> On my Debian system, it's in /etc/groff/man.local.
> 
> Adding the following should do the trick:
> 
> .if '\*[.T]'utf8' \{\
> .  char \[la] <
> .  char \[ra] >
> .\}
> 
> Regards,
> Branden

Many thanks for your reply with the steps to follow

With kind regards
Jonny