[groff] 03/09: Adapt to the fact that \: reënables hyphenation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ab53bf101d9a6e66478346b6a31ae3af130b798d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 15 23:38:38 2020 +1000

    Adapt to the fact that \: reënables hyphenation.
    
    ...and rename "hyphenless [discretionary] break" to "non-printing break
    point" in documentation.
    
    In spite of my discomfort at learning this fact, I decided not to try to
    change groff's behavior because (1) frankly, doing so looked challenging
    in the implementation and (2) it occurred to me that, for those
    circumstances in which the present behavior is desired by the user, the
    mechanism of recovering it would be _even more_ challenging.  Keeping in
    mind that requests and escapes are "assembly language for typesetting",
    I'm leaving the language alone and adapting to it.  The pattern '\:\%'
    will be unambiguous to locate and easy to change later if someone has a
    brighter idea.
    
    * doc/groff.texi (Manipulating Hyphenation): Rename "hyphenless break"
      to "non-printing break point".  Clarify that it is the soft hyphen
      glyph, not necessarily a hyphen, that is ordinarily written to the
      output on hyphenation breaks.  Note that the remainder of a word after
      \: is subject to hyphenation as normal.  Note (new) '\:\%' idiom for
      getting what people will want at least some of the time.  Update
      example to use it.
    
    * makevarescape.sed: Insert \% after we insert \: to rewrite slashes in
      filenames, to protect later portions of the filename from hyphenation.
    
    * man/groff.7.man (Escape Sequences/Escape short reference): Rename
      "hyphenless break" to "non-printing break point".
    
    * man/groff_diff.7.man (Language/Escape sequences): Resync with our
      Texinfo manual.
    
    * tmac/groff_man.7.man.in (Description/Hyperlink and email macros):
      Rename "hyphenless break" to "non-printing break point".  (The
      examples did not need updating because the macros already disable
      hyphenation--too aggressively as it turns out, but that's a different
      change set...)
---
 ChangeLog               | 24 ++++++++++++++++++++++++
 doc/groff.texi          | 14 ++++++++++----
 makevarescape.sed       |  2 +-
 man/groff.7.man         |  4 +++-
 man/groff_diff.7.man    | 33 +++++++++++++++++++++++++++++----
 tmac/groff_man.7.man.in |  6 +++---
 6 files changed, 70 insertions(+), 13 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4feca13..0e7a374 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,29 @@
 2020-08-15  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       Adapt to the fact that \: reënables hyphenation.  Rename
+       "hyphenless [discretionary] break" to "non-printing break point"
+       in documentation.
+
+       * doc/groff.texi (Manipulating Hyphenation): Rename "hyphenless
+       break" to "non-printing break point".  Clarify that it is the
+       soft hyphen glyph, not necessarily a hyphen, that is ordinarily
+       written to the output on hyphenation breaks.  Note that the
+       remainder of a word after \: is subject to hyphenation as
+       normal.  Note (new) '\:\%' idiom for getting what people will
+       want at least some of the time.  Update example to use it.
+       * makevarescape.sed: Insert \% after we insert \: to rewrite
+       slashes in filenames, to protect later portions of the filename
+       from hyphenation.
+       * man/groff.7.man (Escape Sequences/Escape short reference):
+       Rename "hyphenless break" to "non-printing break point".
+       * man/groff_diff.7.man (Language/Escape sequences): Resync with
+       our Texinfo manual.
+       * tmac/groff_man.7.man.in (Description/Hyperlink and email
+       macros): Rename "hyphenless break" to "non-printing break
+       point".
+
+2020-08-15  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        documentation: Re-christen 'ESCAPE_AMPERSAND'.
 
        s/zero[- ]width space character/non-printing input break/
diff --git a/doc/groff.texi b/doc/groff.texi
index 1cb776c..317d94d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6660,17 +6660,23 @@ Note that the escapes @code{\X} and @code{\Y} start a 
word; that is, the
 hyphenation point at the beginning of @samp{foobar}; most likely this
 isn't what you want to do.  @xref{Postprocessor Access}.
 
-@cindex hyphenless breaks (@code{\:})
+@cindex non-printing break points (@code{\:})
 @cindex breaking without hyphens (@code{\:})
 @cindex file names, breaking (@code{\:})
 @cindex breaking file names (@code{\:})
 @cindex URLs, breaking (@code{\:})
 @cindex breaking URLs (@code{\:})
-The @code{\:} escape inserts a zero-width break point; that is, the word
-can break there, but no hyphen is written to the output if it does.
+The @code{\:} escape inserts a non-printing break point; that is, the
+word can break there, but the soft hyphen glyph is not written to the
+output if it does.  Note that breaks are word boundaries, so if a break
+is inserted, the remainder of the (input) word is subject to hyphenation
+as normal.
+
+You can use @code{\:} and @code{\%} in combination to control breaking
+of a filename or URL.
 
 @Example
-@dots{} check the /var/log/\:httpd/\:access_log file @dots{}
+@dots{} check the \%/var/log/\:\%httpd/\:\%access_log file @dots{}
 @endExample
 @endDefesc
 
diff --git a/makevarescape.sed b/makevarescape.sed
index 8ece3e8..8356264 100644
--- a/makevarescape.sed
+++ b/makevarescape.sed
@@ -6,4 +6,4 @@ s/-/\\\\&/g
 s/\^/\\\\(ha/g
 s/`/\\\\(ga/g
 s/~/\\\\(ti/g
-s|[^ ]/\+|&\\\\:|g
+s|[^ ]/\+|&\\\\:\\%|g
diff --git a/man/groff.7.man b/man/groff.7.man
index 92293d4..cbdadf2 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3122,10 +3122,12 @@ line is adjusted.
 .
 .TP
 .ESC :
-Inserts a zero-width break point (similar to
+Insert a non-printing break point
+(similar to
 .esc %
 but without a soft hyphen character).
 .
+.
 .TP
 .ESC "" newline
 Ignored newline, for continuation lines.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 7aa9dbb..c52083d 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -816,12 +816,37 @@ intervening space.
 .
 .TP
 .B \[rs]:
-Insert a zero-width break point.
+Insert a non-printing break point.
 .
-This resembles
+That is,
+the word can break there,
+but the soft hyphen glyph is not written to the output if it does
+(in contrast to
+.RB \[lq] \[rs]% \[rq]).
+.
+Note that breaks are word boundaries,
+so if a break is inserted,
+the remainder of the (input) word is subject to hyphenation as normal.
+.
+.
+.IP
+You can use
+.B \[rs]:
+and
 .B \[rs]%
-within a word but does not output the soft hyphen glyph prior to the
-break.
+in combination to control breaking of a filename or URL.
+.
+.
+.RS
+.RS
+.IP
+.EX
+\&.\|.\|.\& check the \%/var/log/\:httpd/\:access_log file \
+\&.\|.\|.\&
+.EE
+.RE
+.RE
+.
 .
 .TP
 .BI \[rs]? anything \[rs]?
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 6796b8c..bd1ac49 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1154,8 +1154,8 @@ more information.\(rq.
 .IP
 The use of
 .B \e:
-to insert hyphenless discretionary breaks is a
-GNU extension and can be omitted.
+to insert non-printing break points is a GNU extension and can be
+omitted.
 .
 .
 _endif()dnl
@@ -1212,7 +1212,7 @@ the groff home page
 .IP
 The use of
 .B \e:
-to insert hyphenless discretionary breaks is a GNU extension and can be
+to insert non-printing break points is a GNU extension and can be
 omitted.
 .
 .