At 2017-09-11T17:49:52+0100, Ralph Corderoy wrote: > Hi Branden, > > > Proposed patch: > > > > commit 3c2bea2fa7f3450ac5d65e5365b5f3224e51d74a > ... > > Full patch attached. > > Nope. :-)
Hrm, well, let me just try that again... -- Regards, Branden
commit 3c2bea2fa7f3450ac5d65e5365b5f3224e51d74a
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
Date: Mon Sep 4 14:12:48 2017 -0400
Expand portable escape section of groff_man(7).
Make some additional minor wording changes.
* Fix misspelling of English singular "apostrophe" as "apostroph" [sic].
* Hyphenate phrasal adjectives where idiomatic.
* Recast "one single word" (redundant) as "a single word".
* Stop referring to troff-to-HTML processors as "increasingly common";
that may have been true 20 years ago but may not be today.
* Characterize troff-to-HTML processors as doing transformation rather
than rendering, to further suggest the lack of precision involved.
* Indent examples with .RS/.IP/.EX/.EE/.RE for consistency with other
examples in this man page, in favor of mixed-level .sp/.EX/.EE/.sp
requests.
* \ :
+ Explain explicit double-quotes in document.
+ Ask for use case in comment.
* Document \~ escape, with example.
* \&:
+ Recast explanation.
+ Provide illustrative example of how things go wrong if you don't
use it.
* Document \[oq] and \[cq] escapes.
* Document \[lq] and \[rq] escapes.
* Add mnemonics for \[dq], \[em], \[en], and \c.
* Add mnemonic for \[rs] (en passant).
* Slightly soften the language about what isn't portable about using
.TP and \c when the rendering system isn't even identified.
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 5e7b7758..67421662 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -90,7 +90,7 @@ package.
.
The
.B man
-macros understand the following command line options (which define
+macros understand the following command-line options (which define
various registers).
.
.
@@ -1152,8 +1152,7 @@ info pages for a complete reference of all requests.
.
.PP
Note, however, that using raw troff requests is likely to make your
-page render poorly on the (increasingly common) class of viewers that
-render it to HTML.
+page render poorly on the class of viewers that transform it to HTML.
.
Troff requests make implicit assumptions about things like character
and page sizes that may break in an HTML environment; also, many of
@@ -1207,44 +1206,115 @@ even in manual pages and usually do not cause portability problems:
.RB \(dq \e\ \(dq
Unpaddable non-breaking space character.
.
+(The double-quotes are to make the presence of the space character
+clear in this document, and are not necessary in the input file.)
+.
+.\" TODO: Find a use case for this. Please let it not be ersatz table
+.\" layout in fixed-width character cells.
+.
+.TP
+.B \e\(ti
+Paddable non-breaking space character.
+.
+Useful for preventing breaking between a numerical quantity and its
+corresponding unit(s), for instance:
+.
+.RS
+.IP
+.EX
+There are 2.54\e\[ti]cm in an inch, 1,024\e\[ti]bytes in 1\e\[ti]kiB.
+.EE
+.RE
+.
.TP
.B \e&
Zero-width space.
.
-Used for different kinds of escaping, for example after abbreviations
-that occur at the end of an input line to prevent misinterpretation
-of the final dot as a full stop ending a sentence, or before an
-apostroph or dot at the beginning of a text input line to prevent
-misinterpretation as a macro line, for example:
-.sp
+Can be used to (1)\~suppress recognition of end-of-sentence punctuation
+sequences at the end of an input line, and (2)\~suppress recognition of
+a dot or apostrophe at the beginning of a line as a troff request.
+.
+As an example of each:
+.
+.RS
+.IP
.EX
The
-\&.B .gcolor
+\&.B
+\e&.gcolor
request supports several color names, e.g.\e&
-\e&'green', by default.
+\e&'green', by default,
+and others may be known to your system.
.EE
+.RE
+.
+.IP
+Without
+.BR \e& ,
+the above renders as:
+.RS
+.IP
+The
+.B
+.gcolor
+request supports several color names, e.g.
+'green', by default,
+and others may be known to your system.
+.RE
+.
+.IP
+Note the undesired inter-sentence spacing after \[lq]e.g.\[rq], among
+more obvious defects.
.
.TP
.B \e(aq
-ASCII apostroph.
+ASCII apostrophe.
.
Useful for syntax elements of programming languages because some
output devices might replace unescaped apostrophes with right single
quotation marks.
.
.TP
+.B \e(oq
+Opening single quotation mark.
+.
+.TQ
+.B \e(cq
+Closing single quotation mark.
+.
+.IP
+Use these for paired directional single quotes, \(oqlike this\(cq.
+.
+.TP
.B \e(dq
+ASCII double-quote.
+.
Sometimes needed on macro lines to prevent the interpretation of the
ASCII quotation mark character \(oq\(dq\(cq as the beginning or end
of a macro argument.
.
.TP
+.B \e(lq
+Left double quotation mark.
+.
+.TQ
+.B \e(rq
+Right double quotation mark.
+.
+.IP
+Use these for paired directional double quotes, \(lqlike this\(rq.
+.
+.TP
.B \e(em
+Em-dash.
+.
Used as a punctuation mark for an interruption in a sentence\(emlike
in this one.
.
.TP
.B \e(en
+En-dash.
+.
Used to separate the two ends of a range, in particular between
numbers, for example: the digits 1\(en9.
.
@@ -1277,7 +1347,7 @@ like the Unicode U+02DC small tilde.
Minus sign.
.
Also use this to display syntax elements that require the ASCII
-hyphen-minus character, for example command line options and C
+hyphen-minus character, for example command-line options and C
language operators.
.
The unesacped \(oq\-\(cq input character is not appropriate for
@@ -1285,29 +1355,35 @@ these cases because it may render as a hyphen on some output devices.
.
.TP
.B \ec
+(Mnemonic: \[lq]continue\[rq] next input line on output.)
+.
If this escape sequence occurs at the end of an input line, no
-white space is inserted between the last glyph resulting from this
-and the first glyph resulting from the next input line.
+white space or is inserted between the last glyph resulting from this
+and the first glyph resulting from the next input line, as would
+normally be done.
.
This is occasionally useful when three different fonts are needed
-in one single word, for example:
-.sp
+in a single word, for example:
+.
+.RS
+.IP
.EX
\&.BR "dd if" =\ec
\&.I file
.EE
-.sp
-Alternatively, and with likely better portability, the
+.RE
+.
+.IP
+Alternatively, and perhaps with better portability, the
.B \ef
-font escape sequence can be used, see below.
+font escape sequence can be used; see below.
.sp
Attempting to use
.B \ec
to include the output from more than one macro line into the head of a
.B .TP
-macro is non-portable and will misrender with groff-1.22.3,
-mandoc-1.14.1, older versions of these programs, and with other
-formatters.
+macro will misrender with groff-1.22.3, mandoc-1.14.1, older versions of
+these programs, and perhaps with some other formatters.
.
.TP
.B \ee
@@ -1318,6 +1394,7 @@ It works reliably as long as the
request is not used, which should never happen in manual pages, and
it is slightly more portable than the more exact
.B \e(rs
+(\[lq]reverse solidus\[rq])
escape sequence.
.
.TP
@@ -1327,16 +1404,21 @@ respectively.
.
This is needed when three different fonts are required on a single
input line, for example:
-.sp
+.
+.RS
+.IP
.EX
\&.TP
\efBif\efP=\efIfile\efP
.EE
-.sp
-It can also be used if three different fonts are needed in one
-single word. It is likely more portable than
+.RE
+.
+.IP
+It can also be used if three different fonts are needed in a
+single word.
+It may be more portable than
.BR \ec .
-.sp
+.IP
As long as only two fonts are needed, using font alternation
macros like
.B .BR
signature.asc
Description: PGP signature
