[groff] 14/17: [docs]: Update "\/", "\," escape material.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 69af9c7c3df6137a0cafe408deecd934ce7532a2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 25 20:37:31 2021 +1000

    [docs]: Update "\/", "\," escape material.
    
    Our documentation went out of its way, for reasons not evident to me, to
    avoid the term "italic correction".  But I've seen it in contexts
    outside of groff, so I think we should use it.  Doing so lets people
    stop reading sooner if they're familiar with the concept.
    
    * doc/groff.texi (Ligatures and Kerning) <\/>: Relocate material to
      front the definition of "italic correction".  Use Texinfo @samp
      command to quote letter "f" (use-mention distinction).  Add motivation
      for feature from groff_diff(7): not using italic corrections can cause
      ugly typography.  Drop code example, which has to jump through a lot
      of Texinfo hoops to achieve the rendering, which was flawed anyway,
      drawing the "f" glyph from the wrong family.
      <\,>: Relocate material to front the definition of "left italic
      correction".  Add descriptive example of the problem the lack of it
      causes.  Drop code example for parallelism.
    
    * man/groff.7.man (Escape Sequences/Escape short reference) <\/, \,>:
      Replace descriptions with the corresponding leading 2 sentences from
      our Texinfo manual.
    
    * man/groff_diff.7.man: Sync with our Texinfo manual.  Expose more of
      the motivation to readers using nroff devices, reserving only the
      inline examples of bad typography for troff devices.
---
 doc/groff.texi       | 52 ++++++++++++----------------------------
 man/groff.7.man      | 17 ++++++++-----
 man/groff_diff.7.man | 67 ++++++++++++++++++++++++++++++++++------------------
 3 files changed, 70 insertions(+), 66 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4fbf27d..0e62fcd 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10606,26 +10606,14 @@ this.
 @cindex roman glyph, correction after italic glyph (@code{\/})
 @cindex italic glyph, correction before roman glyph (@code{\/})
 @cindex glyph, italic correction (@code{\/})
-Increase the width of the preceding glyph so that the spacing between
-that glyph and the following glyph is correct if the following glyph is
-a roman glyph.  For example, if an italic@tie{}@code{f} is immediately
-followed by a roman right parenthesis, then in many fonts the top right
-portion of the@tie{}@code{f} overlaps the top left of the right
-parenthesis.  Use this escape sequence whenever an italic glyph is
+Apply an @dfn{italic correction}: increase the width of the preceding
+glyph so that the spacing between that glyph and the following glyph is
+correct if the following glyph is a roman glyph.  For example, if an
+italic@tie{}@samp{f} is immediately followed by a roman right
+parenthesis, then in many fonts the top right portion of
+the@tie{}@samp{f} overlaps the top left of the right parenthesis, which
+is ugly.  Use this escape sequence whenever an italic glyph is
 immediately followed by a roman glyph without any intervening space.
-This small amount of space is also called @dfn{italic correction}.
-
-@iftex
-@c can't use @Example...@endExample here
-@example
-@group
-\f[I]f\f[R])
-    @result{} {@it f}@r{)}
-\f[I]f\/\f[R])
-    @result{} @i{f}@r{)}
-@end group
-@end example
-@end iftex
 @endDefesc
 
 @Defesc {\\\,, , , }
@@ -10634,24 +10622,14 @@ This small amount of space is also called @dfn{italic 
correction}.
 @cindex glyph, left italic correction (@code{\,})
 @cindex roman glyph, correction before italic glyph (@code{\,})
 @cindex italic glyph, correction after roman glyph (@code{\,})
-Modify the spacing of the following glyph so that the spacing between
-that glyph and the preceding glyph is correct if the preceding glyph is
-a roman glyph.  Use this escape sequence whenever a roman glyph is
-immediately followed by an italic glyph without any intervening space.
-In analogy to above, this space could be called @dfn{left italic
-correction}, but this term isn't used widely.
-
-@iftex
-@c can't use @Example...@endExample here
-@example
-@group
-q\f[I]f
-    @result{} @r{q}@i{f}
-q\,\f[I]f
-    @result{} @r{q}@math{@ptexcomma}@i{f}
-@end group
-@end example
-@end iftex
+Apply a @dfn{left italic correction}: modify the spacing of the
+following glyph so that the spacing between that glyph and the preceding
+glyph is correct if the preceding glyph is a roman glyph.  For example,
+if a roman left parenthesis is immediately followed by an
+italic@tie{}@samp{f}, then in many fonts the bottom left portion of
+the@tie{}@samp{f} overlaps the bottom of the left parenthesis, which is
+ugly.  Use this escape sequence whenever a roman glyph is immediately
+followed by an italic glyph without any intervening space.
 @endDefesc
 
 @Defesc {\\&, , , }
diff --git a/man/groff.7.man b/man/groff.7.man
index 89ee591..ac38dab 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3391,17 +3391,22 @@ except that it behaves like a glyph declared with the
 request to be transparent for the purposes of end-of-sentence
 recognition.
 .
+.
 .TP
 .ESC /
-Increases the width of the preceding glyph so that the spacing
-between that glyph and the following glyph is correct if
-the following glyph is a roman glyph.
+Apply italic correction.
+.
+Use between an immediately adjacent italic glyph on the left and a roman
+glyph on the right.
+.
 .
 .TP
 .ESC ,
-Modifies the spacing of the following glyph so that the spacing
-between that glyph and the preceding glyph is correct if the
-preceding glyph is a roman glyph.
+Apply left italic correction.
+.
+Use between an immediately adjacent roman glyph on the left and an
+italic glyph on the right.
+.
 .
 .TP
 .ESC \[ti]
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index e1c7d6e..0f3977f 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -778,46 +778,67 @@ taking
 \&.\|.\|.\&
 as arguments.
 .
+.
 .\" Keep \/ before \, in spite of collation.
 .TP
 .B \[rs]/
-This increases the width of the preceding glyph so that the
-spacing between that glyph and the following glyph is
-correct if the following glyph is a roman glyph.
+Apply an
+.IR "italic correction" :
+increase the width of the preceding glyph so that the spacing between
+that glyph and the following glyph is correct if the following glyph is
+a roman glyph.
+.
+For example,
+if an italic\~\[lq]f\[rq] is immediately followed by a roman right
+parenthesis, then in many fonts the top right portion of
+the\[lq]\~f\[rq] overlaps the top left of the right parenthesis\c
+.if t producing \f[I]f\f[R])\c
+, which is ugly.
 .
+Inserting
+.B \[rs]/
+between them
 .if t \{\
-.  nop For example, if an italic\~f is immediately followed by a roman
-.  nop right parenthesis, then in many fonts the top right portion of
-.  nop the\~f overlaps the top left of the right parenthesis
-.  nop producing \f[I]f\f[R]), which is ugly.
-.  nop Inserting
-.  B \[rs]/
 .  nop produces
 .  ie \n(.g \f[I]f\/\f[R])
 .  el       \f[I]f\|\f[R])
-.  nop and avoids this problem.
+.  nop and
 .\}
-It is a good idea to use this escape sequence whenever an italic
-glyph is immediately followed by a roman glyph without any
-intervening space.
+avoids this problem.
+.
+Use this escape sequence whenever an italic glyph is immediately
+followed by a roman glyph without any intervening space.
+.
 .
 .TP
 .B \[rs],
-This modifies the spacing of the following glyph so that the
-spacing between that glyph and the preceding glyph is
-correct if the preceding glyph is a roman glyph.
+Apply a
+.IR "left italic correction" :
+modify the spacing of the following glyph so that the spacing between
+that glyph and the preceding glyph is correct if the preceding glyph is
+a roman glyph.
 .
+For example,
+if a roman left parenthesis is immediately followed by an
+italic\~\[lq]f\[rq],
+then in many fonts the bottom left portion of the\~\[lq]f\[rq] overlaps
+the bottom of the left parenthesis\c
+.if t producing \f[R](\f[I]f\f[R]\c
+, which is ugly.
+.
+Inserting
+.B \[rs],
+between them
 .if t \{\
-.  nop For example, inserting
-.  B \[rs],
-.  nop between the parenthesis and the\~f changes
-.  nop \f[R](\f[I]f\f[R] to
+.  nop produces
 .  ie \n(.g \f[R](\,\f[I]f\f[R].
 .  el       \f[R](\^\f[I]f\f[R].
+.  nop and
 .\}
-It is a good idea to use this escape sequence whenever a roman
-glyph is immediately followed by an italic glyph without any
-intervening space.
+avoids this problem.
+.
+Use this escape sequence whenever a roman glyph is immediately followed
+by an italic glyph without any intervening space.
 .
 .
 .TP