=================================================================== RCS file: /cvs/mandoc/mandoc_char.7,v retrieving revision 1.66 retrieving revision 1.70 diff -u -p -r1.66 -r1.70 --- mandoc/mandoc_char.7 2017/06/02 12:43:52 1.66 +++ mandoc/mandoc_char.7 2018/08/08 14:03:27 1.70 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_char.7,v 1.66 2017/06/02 12:43:52 schwarze Exp $ +.\" $Id: mandoc_char.7,v 1.70 2018/08/08 14:03:27 schwarze Exp $ .\" .\" Copyright (c) 2003 Jason McIntyre .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons @@ -16,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 2 2017 $ +.Dd $Mdocdate: August 8 2018 $ .Dt MANDOC_CHAR 7 .Os .Sh NAME @@ -35,13 +35,27 @@ documents. .Pp The rendering depends on the .Xr mandoc 1 -output mode; in ASCII output, most characters are completely -unintelligible. -For that reason, using any of the special characters documented here, -except those discussed in the +output mode; it can be inspected by calling +.Xr man 1 +on the +.Nm +manual page with different +.Fl T +arguments. +In ASCII output, the rendering of some characters may be hard +to interpret for the reader. +Many are rendered as descriptive strings like +.Qq , +.Qq , +or +.Qq , +which may look ugly, and many are replaced by similar ASCII characters. +In particular, accented characters are usually shown without the accent. +For that reason, try to avoid using any of the special characters +documented here except those discussed in the .Sx DESCRIPTION , -is strongly discouraged; they are supported merely for backwards -compatibility with existing documents. +unless they are essential for explaining the subject matter at hand, +for example when documenting complicated mathematical functions. .Pp In particular, in English manual pages, do not use special-character escape sequences to represent national language characters in author @@ -49,9 +63,9 @@ names; instead, provide ASCII transcriptions of the na .Ss Dashes and Hyphens In typography there are different types of dashes of various width: the hyphen (-), -the minus sign (\(mi), the en-dash (\(en), -and the em-dash (\(em). +the em-dash (\(em), +and the mathematical minus sign (\(mi). .Pp Hyphens are used for adjectives; to separate the two parts of a compound word; @@ -86,14 +100,6 @@ Such automatic hyphenation is not supported by which only breaks the line at whitespace, and inside words only after existing hyphens. .Pp -The mathematical minus sign is used for negative numbers or subtraction. -It should be written as -.Sq \e(mi : -.Bd -unfilled -offset indent -a = 3 \e(mi 1; -b = \e(mi2; -.Ed -.Pp The en-dash is used to separate the two elements of a range, or can be used the same way as an em-dash. It should be written as @@ -112,10 +118,23 @@ Three things \e(em apples, oranges, and bananas. This is not that \e(em rather, this is that. .Ed .Pp -Note: -hyphens, minus signs, and en-dashes look identical under normal ASCII output. -Other formats, such as PostScript, render them correctly, -with differing widths. +In +.Xr roff 7 +documents, the minus sign is normally written as +.Sq \e- . +In manual pages, some style guides recommend to also use +.Sq \e- +if an ASCII 0x2d +.Dq hyphen-minus +output glyph that can be copied and pasted is desired in output modes +supporting it, for example in +.Fl T Cm utf8 +and +.Fl T Cm html . +But currently, no practically relevant manual page formatter actually +requires that subtlety, so in manual pages just write plain +.Sq - +to represent hyphen, minus, and hyphen-minus. .Ss Spaces To separate words in normal text, for indenting and alignment in literal context, and when none of the following special cases apply, @@ -260,6 +279,7 @@ Lines: .It \e(ba Ta \(ba Ta bar .It \e(br Ta \(br Ta box rule .It \e(ul Ta \(ul Ta underscore +.It \e(ru Ta \(ru Ta underscore (width 0.5m) .It \e(rn Ta \(rn Ta overline .It \e(bb Ta \(bb Ta broken bar .It \e(sl Ta \(sl Ta forward slash @@ -318,8 +338,8 @@ Quotes: .It \e(rq Ta \(rq Ta right double-quote .It \e(oq Ta \(oq Ta left single-quote .It \e(cq Ta \(cq Ta right single-quote -.It \e(aq Ta \(aq Ta apostrophe quote (text) -.It \e(dq Ta \(dq Ta double quote (text) +.It \e(aq Ta \(aq Ta apostrophe quote (ASCII character) +.It \e(dq Ta \(dq Ta double quote (ASCII character) .It \e(Fo Ta \(Fo Ta left guillemet .It \e(Fc Ta \(Fc Ta right guillemet .It \e(fo Ta \(fo Ta left single guillemet @@ -335,7 +355,7 @@ Brackets: .It \e(rC Ta \(rC Ta right brace .It \e(la Ta \(la Ta left angle .It \e(ra Ta \(ra Ta right angle -.It \e(bv Ta \(bv Ta brace extension +.It \e(bv Ta \(bv Ta brace extension (special font) .It \e[braceex] Ta \[braceex] Ta brace extension .It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket .It \e[bracketleftbt] Ta \[bracketleftbt] Ta bottom-left hooked bracket @@ -388,8 +408,8 @@ Logical: .It Em Input Ta Em Rendered Ta Em Description .It \e(AN Ta \(AN Ta logical and .It \e(OR Ta \(OR Ta logical or -.It \e(no Ta \(no Ta logical not -.It \e[tno] Ta \[tno] Ta logical not (text) +.It \e[tno] Ta \[tno] Ta logical not (text font) +.It \e(no Ta \(no Ta logical not (special font) .It \e(te Ta \(te Ta existential quantifier .It \e(fa Ta \(fa Ta universal quantifier .It \e(st Ta \(st Ta such that @@ -401,19 +421,20 @@ Logical: Mathematical: .Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact .It Em Input Ta Em Rendered Ta Em Description -.It \e(pl Ta \(pl Ta plus -.It \e(mi Ta \(mi Ta minus -.It \e- Ta \- Ta minus (text) +.It \e- Ta \- Ta minus (text font) +.It \e(mi Ta \(mi Ta minus (special font) +.It + Ta + Ta plus (text font) +.It \e(pl Ta \(pl Ta plus (special font) .It \e(-+ Ta \(-+ Ta minus-plus -.It \e(+- Ta \(+- Ta plus-minus -.It \e[t+-] Ta \[t+-] Ta plus-minus (text) +.It \e[t+-] Ta \[t+-] Ta plus-minus (text font) +.It \e(+- Ta \(+- Ta plus-minus (special font) .It \e(pc Ta \(pc Ta center-dot -.It \e(mu Ta \(mu Ta multiply -.It \e[tmu] Ta \[tmu] Ta multiply (text) +.It \e[tmu] Ta \[tmu] Ta multiply (text font) +.It \e(mu Ta \(mu Ta multiply (special font) .It \e(c* Ta \(c* Ta circle-multiply .It \e(c+ Ta \(c+ Ta circle-plus -.It \e(di Ta \(di Ta divide -.It \e[tdi] Ta \[tdi] Ta divide (text) +.It \e[tdi] Ta \[tdi] Ta divide (text font) +.It \e(di Ta \(di Ta divide (special font) .It \e(f/ Ta \(f/ Ta fraction .It \e(** Ta \(** Ta asterisk .It \e(<= Ta \(<= Ta less-than-equal @@ -510,8 +531,8 @@ Accents: .It \e(ao Ta \(ao Ta ring .It \e(a\(ti Ta \(a~ Ta tilde .It \e(ho Ta \(ho Ta ogonek -.It \e(ha Ta \(ha Ta hat (text) -.It \e(ti Ta \(ti Ta tilde (text) +.It \e(ha Ta \(ha Ta hat (ASCII character) +.It \e(ti Ta \(ti Ta tilde (ASCII character) .El .Pp Accented letters: