commit 3c2bea2fa7f3450ac5d65e5365b5f3224e51d74a Author: G. Branden Robinson 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