[groff] 08/16: Improve documentation of URL breaking.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d41ab19ae2a3f10c3c99410f004a0e2f685bde73
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 17 06:11:44 2020 +1100

    Improve documentation of URL breaking.
    
    * tmac/groff_man.7.man.in (Description/Hyperlink and email macros)
      [style] <.MT,.UR>: Add non-printing break points before periods in
      URLs.  Explain why.
    
    * tmac/groff_www.7.man: Same.  However, I'm noticing some things in this
      page that disturb me.
---
 tmac/groff_man.7.man.in | 27 ++++++++++++++++++++-------
 tmac/groff_www.7.man    | 29 +++++++++++++++--------------
 2 files changed, 35 insertions(+), 21 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 830a33a..9a1ac9d 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1131,7 +1131,7 @@ to a terminal or PostScript device,
 .IP
 .EX
 Contact
-\&.MT fred.foonly@\e:fubar.net
+\&.MT fred\e:.foonly@\e:fubar\e:.net
 Fred Foonly
 \&.ME
 for more information.
@@ -1140,8 +1140,8 @@ for more information.
 .
 .
 .IP
-displays as \(lqContact Fred Foonly \(lafred.foonly@\:fubar.net\(ra for
-more information.\(rq.
+displays as \(lqContact Fred Foonly \(lafred\:.foonly@\:fubar\:.net\(ra
+for more information.\(rq.
 .
 .
 .IP
@@ -1150,6 +1150,11 @@ The use of
 to insert non-printing break points is a GNU extension and can be
 omitted.
 .
+We place them
+.I before
+each period so that the reader does not mistake them for sentence
+endings.
+.
 .
 _endif()dnl
 .TP
@@ -1189,8 +1194,9 @@ to a terminal or PostScript device,
 .EX
 The GNU Project of the Free Software Foundation
 hosts the
-\&.UR https://\e:www.gnu.org/\e:software/\e:groff/
-groff home page
+\&.UR https://\e:www\e:.gnu\e:.org/\e:software/\e:groff/
+\&.I groff
+home page
 \&.UE .
 .EE
 .RE
@@ -1198,8 +1204,10 @@ groff home page
 .
 .IP
 displays as \(lqThe GNU Project of the Free Software Foundation hosts
-the groff home page
-\(lahttps://\:www.gnu.org/\:software/\:groff/\(ra.\(rq.
+the
+.I groff
+home page
+\(lahttps://\:www\:.gnu\:.org/\:software/\:groff/\(ra.\(rq.
 .
 .
 .IP
@@ -1208,6 +1216,11 @@ The use of
 to insert non-printing break points is a GNU extension and can be
 omitted.
 .
+We place them
+.I before
+each period so that the reader does not mistake them for sentence
+endings.
+.
 .
 _endif()dnl
 .\" ====================================================================
diff --git a/tmac/groff_www.7.man b/tmac/groff_www.7.man
index b40fffc..b4084ae 100644
--- a/tmac/groff_www.7.man
+++ b/tmac/groff_www.7.man
@@ -222,12 +222,12 @@ explicit breakpoints should be inserted with the
 escape.
 .
 Here is how to encode
-.UR http://\:foo.\:org/
+.UR http://\:foo\:.org/
 foo
 .UE :
 .RS
 .IP
-.B .URL http://\[rs]:foo.\[rs]:org/ "foo" :
+.B .URL http://\[rs]:foo\[rs]:.org/ "foo" :
 .RE
 .
 .IP
@@ -238,18 +238,21 @@ or
 it appears as:
 .RS
 .IP
-foo \[la]\f[CR]http://foo.org\f[]\[ra]:
+foo \[la]\f[CR]http://\:foo\:.org\f[]\[ra]:
 .RE
 .
 .IP
-The URL macro can be of any type; for example we can reference
-.UR pic.html
-Eric Raymond's pic guide
+The URL macro can be of any type;
+for example, we can reference
+.UR pic\:.html
+Eric Raymond's
+.I pic
+guide
 .UE
 by:
 .RS
 .IP
-.B .URL pic.html \[dq]Eric Raymond's pic guide\[dq]
+.B .URL pic\[rs]:.html \[dq]Eric Raymond's pic guide\[dq]
 .RE
 .
 .TP
@@ -306,14 +309,14 @@ The second and the third parameter are optional.
 Hyphenation is disabled while printing the actual URL.
 .
 As an example, here is the location of the
-.UR ftp://\:ftp.gnu.org/
+.UR ftp://\:ftp\:.gnu\:.org/
 GNU FTP server
 .UE .
 .
 The macro example above can be specified as:
 .RS
 .IP
-.B .FTP ftp://\[rs]:ftp.gnu.org/ \[dq]GNU FTP server\[dq] .
+.B .FTP ftp://\[rs]:ftp\[rs]:.gnu\[rs]:.org/ \[dq]GNU FTP server\[dq] .
 .RE
 .
 .TP
@@ -475,12 +478,10 @@ Example:
 \&.HnS 1
 \&.HR
 GNU Troff
-\&.URL http://groff.ffii.org (Groff)
-\&\(em a
-\&.URL http://www.gnu.org/ GNU
+\&.URL https://\[rs]:www\[rs]:.gnu\[rs]:.org/\[rs]:software/\[rs]:groff/
+\&\[rs][em]a
+\&.URL http://www\[rs]:.gnu\[rs]:.org/ GNU
 \&project.
-\&Hosted by
-\&.URL http://ffii.org/ FFII .
 \&.HR
 \&.HnE
 .ft P