version 1.43, 2011/04/20 22:50:22 |
version 1.54, 2013/11/10 14:32:57 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org> |
|
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Nm mandoc_char |
.Nm mandoc_char |
.Nd mandoc special characters |
.Nd mandoc special characters |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
This page documents the special characters and predefined strings accepted by |
This page documents the |
|
.Xr roff 7 |
|
escape sequences accepted by |
.Xr mandoc 1 |
.Xr mandoc 1 |
to format |
to represent special characters in |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr man 7 |
.Xr man 7 |
documents. |
documents. |
.Pp |
.Pp |
Both |
The rendering depends on the |
.Xr mdoc 7 |
.Xr mandoc 1 |
and |
output mode; in ASCII output, most characters are completely |
.Xr man 7 |
unintelligible. |
encode special characters with |
For that reason, 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. |
|
.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 (\-), |
|
the en-dash (\(en), |
|
and the em-dash (\(em). |
|
.Pp |
|
Hyphens are used for adjectives; |
|
to separate the two parts of a compound word; |
|
or to separate a word across two successive lines of text. |
|
The hyphen does not need to be escaped: |
|
.Bd -unfilled -offset indent |
|
blue-eyed |
|
lorry-driver |
|
.Ed |
|
.Pp |
|
The mathematical minus sign is used for negative numbers or subtraction. |
|
It should be written as |
|
.Sq \e- : |
|
.Bd -unfilled -offset indent |
|
a = 3 \e- 1; |
|
b = \e-2; |
|
.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, |
|
just use the normal space character |
|
.Pq Sq \ . |
|
.Pp |
|
When filling text, lines may be broken between words, i.e. at space |
|
characters. |
|
To prevent a line break between two particular words, |
|
use the non-breaking space escape sequence |
|
.Pq Sq \e~ |
|
instead of the normal space character. |
|
For example, the input string |
|
.Dq number\e~1 |
|
will be kept together as |
|
.Dq number\~1 |
|
on the same output line. |
|
.Pp |
|
On request and macro lines, the normal space character serves as an |
|
argument delimiter. |
|
To include whitespace into arguments, quoting is usually the best choice. |
|
In some cases, using either the non-breaking |
|
.Pq Sq \e~ |
|
or the breaking |
|
.Pq Sq \e\ \& |
|
space escape sequence may be preferable. |
|
To escape macro names and to protect whitespace at the end |
|
of input lines, the zero-width space |
|
.Pq Sq \e& |
|
is often useful. |
|
For example, in |
|
.Xr mdoc 7 , |
|
a normal space character can be displayed in single quotes in either |
|
of the following ways: |
|
.Pp |
|
.Dl .Sq \(dq \(dq |
|
.Dl .Sq \e \e& |
|
.Ss Quotes |
|
On request and macro lines, the double-quote character |
|
.Pq Sq \(dq |
|
is handled specially to allow quoting. |
|
One way to prevent this special handling is by using the |
|
.Sq \e(dq |
|
escape sequence. |
|
.Pp |
|
Note that on text lines, literal double-quote characters can be used |
|
verbatim. |
|
All other quote-like characters can be used verbatim as well, |
|
even on request and macro lines. |
|
.Ss Periods |
|
The period |
|
.Pq Sq \&. |
|
is handled specially at the beginning of an input line, |
|
where it introduces a |
|
.Xr roff 7 |
|
request or a macro, and when appearing alone as a macro argument in |
|
.Xr mdoc 7 . |
|
In such situations, prepend a zero-width space |
|
.Pq Sq \e&. |
|
to make it behave like normal text. |
|
.Pp |
|
Do not use the |
|
.Sq \e. |
|
escape sequence. |
|
It does not prevent special handling of the period. |
|
.Ss Backslashes |
|
To include a literal backslash |
|
.Pq Sq \e |
|
into the output, use the |
|
.Pq Sq \ee |
|
escape sequence. |
|
.Pp |
|
Note that doubling it |
|
.Pq Sq \e\e |
|
is not the right way to output a backslash. |
|
Because |
|
.Xr mandoc 1 |
|
does not implement full |
|
.Xr roff 7 |
|
functionality, it may work with |
|
.Xr mandoc 1 , |
|
but it may have weird effects on complete |
|
.Xr roff 7 |
|
implementations. |
|
.Sh SPECIAL CHARACTERS |
|
Special characters are encoded as |
.Sq \eX |
.Sq \eX |
.Pq for a one-character escape , |
.Pq for a one-character escape , |
.Sq \e(XX |
.Sq \e(XX |
Line 41 encode special characters with |
|
Line 185 encode special characters with |
|
and |
and |
.Sq \e[N] |
.Sq \e[N] |
.Pq N-character . |
.Pq N-character . |
One may generalise |
For details, see the |
.Sq \e(XX |
.Em Special Characters |
as |
subsection of the |
.Sq \e[XX] |
.Xr roff 7 |
and |
manual. |
.Sq \eX |
|
as |
|
.Sq \e[X] . |
|
Predefined strings are functionally similar to special characters, using |
|
.Sq \e*X |
|
.Pq for a one-character escape , |
|
.Sq \e*(XX |
|
.Pq two-character , |
|
and |
|
.Sq \e*[N] |
|
.Pq N-character . |
|
One may generalise |
|
.Sq \e*(XX |
|
as |
|
.Sq \e*[XX] |
|
and |
|
.Sq \e*X |
|
as |
|
.Sq \e*[X] . |
|
.Pp |
.Pp |
Note that each output mode will have a different rendering of the |
|
characters. |
|
It's guaranteed that each input symbol will correspond to a |
|
(more or less) meaningful output rendering, regardless the mode. |
|
.Sh SPECIAL CHARACTERS |
|
These are the preferred input symbols for producing special characters. |
|
.Pp |
|
Spacing: |
Spacing: |
.Bl -column -compact -offset indent "Input" "Description" |
.Bl -column "Input" "Description" -offset indent -compact |
.It Em Input Ta Em Description |
.It Em Input Ta Em Description |
.It \e~ Ta non-breaking, non-collapsing space |
.It \e~ Ta non-breaking, non-collapsing space |
.It \e Ta breaking, non-collapsing n-width space |
.It \e Ta breaking, non-collapsing n-width space |
|
|
.El |
.El |
.Pp |
.Pp |
Lines: |
Lines: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(ba Ta \(ba Ta bar |
.It \e(ba Ta \(ba Ta bar |
.It \e(br Ta \(br Ta box rule |
.It \e(br Ta \(br Ta box rule |
|
|
.El |
.El |
.Pp |
.Pp |
Text markers: |
Text markers: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(ci Ta \(ci Ta circle |
.It \e(ci Ta \(ci Ta circle |
.It \e(bu Ta \(bu Ta bullet |
.It \e(bu Ta \(bu Ta bullet |
|
|
.El |
.El |
.Pp |
.Pp |
Legal symbols: |
Legal symbols: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(co Ta \(co Ta copyright |
.It \e(co Ta \(co Ta copyright |
.It \e(rg Ta \(rg Ta registered |
.It \e(rg Ta \(rg Ta registered |
|
|
.El |
.El |
.Pp |
.Pp |
Punctuation: |
Punctuation: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(em Ta \(em Ta em-dash |
.It \e(em Ta \(em Ta em-dash |
.It \e(en Ta \(en Ta en-dash |
.It \e(en Ta \(en Ta en-dash |
|
|
.El |
.El |
.Pp |
.Pp |
Quotes: |
Quotes: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(Bq Ta \(Bq Ta right low double-quote |
.It \e(Bq Ta \(Bq Ta right low double-quote |
.It \e(bq Ta \(bq Ta right low single-quote |
.It \e(bq Ta \(bq Ta right low single-quote |
|
|
.El |
.El |
.Pp |
.Pp |
Brackets: |
Brackets: |
.Bl -column -compact -offset indent "xxbracketrightbpx" Rendered Description |
.Bl -column "xxbracketrightbpx" Rendered Description -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(lB Ta \(lB Ta left bracket |
.It \e(lB Ta \(lB Ta left bracket |
.It \e(rB Ta \(rB Ta right bracket |
.It \e(rB Ta \(rB Ta right bracket |
|
|
.El |
.El |
.Pp |
.Pp |
Arrows: |
Arrows: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(<- Ta \(<- Ta left arrow |
.It \e(<- Ta \(<- Ta left arrow |
.It \e(-> Ta \(-> Ta right arrow |
.It \e(-> Ta \(-> Ta right arrow |
|
|
.El |
.El |
.Pp |
.Pp |
Logical: |
Logical: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(AN Ta \(AN Ta logical and |
.It \e(AN Ta \(AN Ta logical and |
.It \e(OR Ta \(OR Ta logical or |
.It \e(OR Ta \(OR Ta logical or |
|
|
.El |
.El |
.Pp |
.Pp |
Mathematical: |
Mathematical: |
.Bl -column -compact -offset indent "xxcoproductxx" "Rendered" "Description" |
.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(pl Ta \(pl Ta plus |
.It \e(pl Ta \(pl Ta plus |
.It \e(mi Ta \(mi Ta minus |
.It \e(mi Ta \(mi Ta minus |
|
|
.It \e(Re Ta \(Re Ta real |
.It \e(Re Ta \(Re Ta real |
.It \e(pd Ta \(pd Ta partial differential |
.It \e(pd Ta \(pd Ta partial differential |
.It \e(-h Ta \(-h Ta Planck constant over 2\(*p |
.It \e(-h Ta \(-h Ta Planck constant over 2\(*p |
|
.It \e[12] Ta \[12] Ta one-half |
|
.It \e[14] Ta \[14] Ta one-fourth |
|
.It \e[34] Ta \[34] Ta three-fourths |
.El |
.El |
.Pp |
.Pp |
Ligatures: |
Ligatures: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(ff Ta \(ff Ta ff ligature |
.It \e(ff Ta \(ff Ta ff ligature |
.It \e(fi Ta \(fi Ta fi ligature |
.It \e(fi Ta \(fi Ta fi ligature |
|
|
.El |
.El |
.Pp |
.Pp |
Accents: |
Accents: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(a" Ta \(a" Ta Hungarian umlaut |
.It \e(a" Ta \(a" Ta Hungarian umlaut |
.It \e(a- Ta \(a- Ta macron |
.It \e(a- Ta \(a- Ta macron |
|
|
.El |
.El |
.Pp |
.Pp |
Accented letters: |
Accented letters: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e('A Ta \('A Ta acute A |
.It \e('A Ta \('A Ta acute A |
.It \e('E Ta \('E Ta acute E |
.It \e('E Ta \('E Ta acute E |
Line 390 Accented letters: |
|
Line 511 Accented letters: |
|
.El |
.El |
.Pp |
.Pp |
Special letters: |
Special letters: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(-D Ta \(-D Ta Eth |
.It \e(-D Ta \(-D Ta Eth |
.It \e(Sd Ta \(Sd Ta eth |
.It \e(Sd Ta \(Sd Ta eth |
Line 401 Special letters: |
|
Line 522 Special letters: |
|
.El |
.El |
.Pp |
.Pp |
Currency: |
Currency: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(Do Ta \(Do Ta dollar |
.It \e(Do Ta \(Do Ta dollar |
.It \e(ct Ta \(ct Ta cent |
.It \e(ct Ta \(ct Ta cent |
|
|
.El |
.El |
.Pp |
.Pp |
Units: |
Units: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(de Ta \(de Ta degree |
.It \e(de Ta \(de Ta degree |
.It \e(%0 Ta \(%0 Ta per-thousand |
.It \e(%0 Ta \(%0 Ta per-thousand |
|
|
.El |
.El |
.Pp |
.Pp |
Greek letters: |
Greek letters: |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
.Bl -column "Input" "Rendered" "Description" -offset indent -compact |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e(*A Ta \(*A Ta Alpha |
.It \e(*A Ta \(*A Ta Alpha |
.It \e(*B Ta \(*B Ta Beta |
.It \e(*B Ta \(*B Ta Beta |
Line 489 for use, as they differ across implementations. |
|
Line 610 for use, as they differ across implementations. |
|
Manuals using these predefined strings are almost certainly not |
Manuals using these predefined strings are almost certainly not |
portable. |
portable. |
.Pp |
.Pp |
.Bl -column -compact -offset indent "Input" "Rendered" "Description" |
Their syntax is similar to special characters, using |
|
.Sq \e*X |
|
.Pq for a one-character escape , |
|
.Sq \e*(XX |
|
.Pq two-character , |
|
and |
|
.Sq \e*[N] |
|
.Pq N-character . |
|
For details, see the |
|
.Em Predefined Strings |
|
subsection of the |
|
.Xr roff 7 |
|
manual. |
|
.Bl -column "Input" "Rendered" "Description" -offset indent |
.It Em Input Ta Em Rendered Ta Em Description |
.It Em Input Ta Em Rendered Ta Em Description |
.It \e*(Ba Ta \*(Ba Ta vertical bar |
.It \e*(Ba Ta \*(Ba Ta vertical bar |
.It \e*(Ne Ta \*(Ne Ta not equal |
.It \e*(Ne Ta \*(Ne Ta not equal |
|
|
.It \e*(Px Ta \*(Px Ta POSIX standard name |
.It \e*(Px Ta \*(Px Ta POSIX standard name |
.It \e*(Ai Ta \*(Ai Ta ANSI standard name |
.It \e*(Ai Ta \*(Ai Ta ANSI standard name |
.El |
.El |
|
.Sh UNICODE CHARACTERS |
|
The escape sequence |
|
.Pp |
|
.Dl \e[uXXXX] |
|
.Pp |
|
is interpreted as a Unicode codepoint. |
|
The codepoint must be in the range above U+0080 and less than U+10FFFF. |
|
For compatibility, the hexadecimal digits |
|
.Sq A |
|
to |
|
.Sq F |
|
must be given as uppercase characters, |
|
and points must be zero-padded to four characters; if |
|
greater than four characters, no zero padding is allowed. |
|
Unicode surrogates are not allowed. |
|
.\" .Pp |
|
.\" Unicode glyphs attenuate to the |
|
.\" .Sq \&? |
|
.\" character if invalid or not rendered by current output media. |
.Sh NUMBERED CHARACTERS |
.Sh NUMBERED CHARACTERS |
For backward compatibility with existing manuals, |
For backward compatibility with existing manuals, |
.Xr mandoc 1 |
.Xr mandoc 1 |
Line 536 For example, do not use \eN'34', use \e(dq, or even th |
|
Line 689 For example, do not use \eN'34', use \e(dq, or even th |
|
.Sq \(dq |
.Sq \(dq |
character where possible. |
character where possible. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other |
troff implementations, at this time limited to GNU troff |
troff implementations, at this time limited to GNU troff |
.Pq Qq groff . |
.Pq Qq groff . |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
|
The \eN\(aq\(aq escape sequence is limited to printable characters; in |
|
groff, it accepts arbitrary character numbers. |
|
.It |
In |
In |
.Fl T Ns Cm ascii , |
.Fl T Ns Cm ascii , |
the |
the |
Line 569 from mandoc either because they are poorly documented |
|
Line 725 from mandoc either because they are poorly documented |
|
known representation. |
known representation. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 |
.Xr mandoc 1 , |
|
.Xr man 7 , |
|
.Xr mdoc 7 , |
|
.Xr roff 7 |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |
manual page was written by |
manual page was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
.Sh CAVEATS |
.Sh CAVEATS |
The |
The |
.Sq \e*(Ba |
.Sq \e*(Ba |