]> git.cameronkatri.com Git - mandoc.git/blobdiff - mandoc_char.7
Ignore unreasonably large spacing modifiers in tbl layouts.
[mandoc.git] / mandoc_char.7
index a372b3e91dfcbf69b2c3980b7f0d03f57ecd8b5f..a29577bc54318cf25617a822b9046b16bbdd5491 100644 (file)
@@ -1,8 +1,8 @@
-.\"    $Id: mandoc_char.7,v 1.67 2017/06/14 20:57:07 schwarze Exp $
+.\"    $Id: mandoc_char.7,v 1.77 2020/02/13 16:18:29 schwarze Exp $
 .\"
 .\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2011, 2013, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2011,2013,2015,2017-2020 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -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 14 2017 $
+.Dd $Mdocdate: February 13 2020 $
 .Dt MANDOC_CHAR 7
 .Os
 .Sh NAME
@@ -35,23 +35,37 @@ 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 <integral> ,
+.Qq <degree> ,
+or
+.Qq <Gamma> ,
+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
 names; instead, provide ASCII transcriptions of the names.
 .Ss Dashes and Hyphens
 In typography there are different types of dashes of various width:
-the hyphen (-),
-the minus sign (\(mi),
+the hyphen (\(hy),
 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;
@@ -62,6 +76,42 @@ blue-eyed
 lorry-driver
 .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
+.Sq \e(en :
+.Bd -unfilled -offset indent
+pp. 95\e(en97.
+Go away \e(en or else!
+.Ed
+.Pp
+The em-dash can be used to show an interruption
+or can be used the same way as colons, semi-colons, or parentheses.
+It should be written as
+.Sq \e(em :
+.Bd -unfilled -offset indent
+Three things \e(em apples, oranges, and bananas.
+This is not that \e(em rather, this is that.
+.Ed
+.Pp
+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 requires
+that subtlety, so in manual pages, it is sufficient to write plain
+.Sq -
+to represent hyphen, minus, and hyphen-minus.
+.Pp
 If a word on a text input line contains a hyphen, a formatter may decide
 to insert an output line break after the hyphen if that helps filling
 the current output line, but the whole word would overflow the line.
@@ -85,37 +135,6 @@ Such automatic hyphenation is not supported by
 .Xr mandoc 1 ,
 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
-.Sq \e(en :
-.Bd -unfilled -offset indent
-pp. 95\e(en97.
-Go away \e(en or else!
-.Ed
-.Pp
-The em-dash can be used to show an interruption
-or can be used the same way as colons, semi-colons, or parentheses.
-It should be written as
-.Sq \e(em :
-.Bd -unfilled -offset indent
-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.
 .Ss Spaces
 To separate words in normal text, for indenting and alignment
 in literal context, and when none of the following special cases apply,
@@ -242,16 +261,18 @@ subsection of the
 .Xr roff 7
 manual.
 .Pp
-Spacing:
+Spaces, non-breaking unless stated otherwise:
 .Bl -column "Input" "Description" -offset indent -compact
 .It Em Input Ta Em Description
-.It Sq \e\ \& Ta unpaddable non-breaking space
-.It \e\(ti   Ta paddable non-breaking space
-.It \e0      Ta unpaddable, breaking digit-width space
+.It Sq \e\ \& Ta unpaddable space
+.It \e\(ti   Ta paddable space
+.It \e0      Ta digit-width space
 .It \e|      Ta one-sixth \e(em narrow space, zero width in nroff mode
 .It \e^      Ta one-twelfth \e(em half-narrow space, zero width in nroff
 .It \e&      Ta zero-width space
+.It \e)      Ta zero-width space transparent to end-of-sentence detection
 .It \e%      Ta zero-width space allowing hyphenation
+.It \e:      Ta zero-width space allowing line break
 .El
 .Pp
 Lines:
@@ -319,8 +340,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
@@ -336,7 +357,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
@@ -389,8 +410,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
@@ -402,19 +423,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
@@ -511,8 +533,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:
@@ -523,11 +545,13 @@ Accented letters:
 .It \e(\(aqI Ta \('I        Ta acute I
 .It \e(\(aqO Ta \('O        Ta acute O
 .It \e(\(aqU Ta \('U        Ta acute U
+.It \e(\(aqY Ta \('Y        Ta acute Y
 .It \e(\(aqa Ta \('a        Ta acute a
 .It \e(\(aqe Ta \('e        Ta acute e
 .It \e(\(aqi Ta \('i        Ta acute i
 .It \e(\(aqo Ta \('o        Ta acute o
 .It \e(\(aqu Ta \('u        Ta acute u
+.It \e(\(aqy Ta \('y        Ta acute y
 .It \e(\(gaA Ta \(`A        Ta grave A
 .It \e(\(gaE Ta \(`E        Ta grave E
 .It \e(\(gaI Ta \(`I        Ta grave I
@@ -741,14 +765,16 @@ For backward compatibility with existing manuals,
 .Xr mandoc 1
 also supports the
 .Pp
-.Dl \eN\(aq Ns Ar number Ns \(aq
+.Dl \eN\(aq Ns Ar number Ns \(aq and \e[ Ns Cm char Ns Ar number ]
 .Pp
-escape sequence, inserting the character
+escape sequences, inserting the character
 .Ar number
 from the current character set into the output.
 Of course, this is inherently non-portable and is already marked
-as deprecated in the Heirloom roff manual.
-For example, do not use \eN\(aq34\(aq, use \e(dq, or even the plain
+as deprecated in the Heirloom roff manual;
+on top of that, the second form is a GNU extension.
+For example, do not use \eN\(aq34\(aq or \e[char34], use \e(dq,
+or even the plain
 .Sq \(dq
 character where possible.
 .Sh COMPATIBILITY