diff options
Diffstat (limited to 'static/openbsd/man7')
24 files changed, 12194 insertions, 0 deletions
diff --git a/static/openbsd/man7/Makefile b/static/openbsd/man7/Makefile new file mode 100644 index 00000000..fa959b6f --- /dev/null +++ b/static/openbsd/man7/Makefile @@ -0,0 +1,26 @@ +MAN = airport.7 \ + ascii.7 \ + environ.7 \ + eqn.7 \ + glob.7 \ + hier.7 \ + hostname.7 \ + intro.7 \ + library-specs.7 \ + man.7 \ + mandoc_char.7 \ + mdoc.7 \ + mirroring-ports.7 \ + operator.7 \ + packages-specs.7 \ + packages.7 \ + pkgpath.7 \ + ports.7 \ + roff.7 \ + script.7 \ + securelevel.7 \ + tbl.7 \ + utf8.7 + +include ../../mandoc.mk + diff --git a/static/openbsd/man7/airport.7 b/static/openbsd/man7/airport.7 new file mode 100644 index 00000000..651343a6 --- /dev/null +++ b/static/openbsd/man7/airport.7 @@ -0,0 +1,42 @@ +.\" $OpenBSD: airport.7,v 1.4 2022/02/18 10:24:32 jsg Exp $ +.\" +.\" Copyright (c) 2017 Sebastian Benoit <benno@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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: February 18 2022 $ +.Dt AIRPORT 7 +.Os +.Sh NAME +.Nm airport +.Nd list of IATA airport codes +.Sh DESCRIPTION +The +.Nm +file is a list of airports that have an IATA airport code. +The list is sorted alphabetically by airport code. +.Pp +The list is not a complete list of all IATA codes. +New airports can only be added by +.Ox +developers who have visited an airport and thereby have verified its existence. +.Sh FILES +.Bl -tag -width /usr/share/misc/airport -compact +.It Pa /usr/share/misc/airport +.El +.Sh SEE ALSO +.Lk https://www.iata.org/codes "Airline and Airport Code Search" +.Sh CAVEATS +There are also railway stations with IATA codes. +These may not be listed, except if someone landed there by plane and +survived to update the file. diff --git a/static/openbsd/man7/ascii.7 b/static/openbsd/man7/ascii.7 new file mode 100644 index 00000000..a908337d --- /dev/null +++ b/static/openbsd/man7/ascii.7 @@ -0,0 +1,116 @@ +.\" $OpenBSD: ascii.7,v 1.12 2024/12/21 03:34:31 jsg Exp $ +.\" $NetBSD: ascii.7,v 1.3 1994/11/30 19:07:06 jtc Exp $ +.\" +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ascii.7 8.1 (Berkeley) 6/5/93 +.\" +.Dd $Mdocdate: December 21 2024 $ +.Dt ASCII 7 +.Os +.Sh NAME +.Nm ascii +.Nd octal, hexadecimal and decimal ASCII character sets +.Sh DESCRIPTION +The +.Nm octal +set: +.Bd -literal -offset left +000 nul 001 soh 002 stx 003 etx 004 eot 005 enq 006 ack 007 bel +010 bs 011 ht 012 lf 013 vt 014 ff 015 cr 016 so 017 si +020 dle 021 dc1 022 dc2 023 dc3 024 dc4 025 nak 026 syn 027 etb +030 can 031 em 032 sub 033 esc 034 fs 035 gs 036 rs 037 us +040 sp 041 ! 042 " 043 # 044 $ 045 % 046 & 047 ' +050 ( 051 ) 052 * 053 + 054 , 055 - 056 . 057 / +060 0 061 1 062 2 063 3 064 4 065 5 066 6 067 7 +070 8 071 9 072 : 073 ; 074 < 075 = 076 > 077 ? +100 @ 101 A 102 B 103 C 104 D 105 E 106 F 107 G +110 H 111 I 112 J 113 K 114 L 115 M 116 N 117 O +120 P 121 Q 122 R 123 S 124 T 125 U 126 V 127 W +130 X 131 Y 132 Z 133 [ 134 \e\ 135 ] 136 ^ 137 _ +140 ` 141 a 142 b 143 c 144 d 145 e 146 f 147 g +150 h 151 i 152 j 153 k 154 l 155 m 156 n 157 o +160 p 161 q 162 r 163 s 164 t 165 u 166 v 167 w +170 x 171 y 172 z 173 { 174 | 175 } 176 ~ 177 del +.Ed +.Pp +The +.Nm hexadecimal +set: +.Bd -literal -offset left + 00 nul 01 soh 02 stx 03 etx 04 eot 05 enq 06 ack 07 bel + 08 bs 09 ht 0a lf 0b vt 0c ff 0d cr 0e so 0f si + 10 dle 11 dc1 12 dc2 13 dc3 14 dc4 15 nak 16 syn 17 etb + 18 can 19 em 1a sub 1b esc 1c fs 1d gs 1e rs 1f us + 20 sp 21 ! 22 " 23 # 24 $ 25 % 26 & 27 ' + 28 ( 29 ) 2a * 2b + 2c , 2d - 2e . 2f / + 30 0 31 1 32 2 33 3 34 4 35 5 36 6 37 7 + 38 8 39 9 3a : 3b ; 3c < 3d = 3e > 3f ? + 40 @ 41 A 42 B 43 C 44 D 45 E 46 F 47 G + 48 H 49 I 4a J 4b K 4c L 4d M 4e N 4f O + 50 P 51 Q 52 R 53 S 54 T 55 U 56 V 57 W + 58 X 59 Y 5a Z 5b [ 5c \e\ 5d ] 5e ^ 5f _ + 60 \` 61 a 62 b 63 c 64 d 65 e 66 f 67 g + 68 h 69 i 6a j 6b k 6c l 6d m 6e n 6f o + 70 p 71 q 72 r 73 s 74 t 75 u 76 v 77 w + 78 x 79 y 7a z 7b { 7c | 7d } 7e ~ 7f del +.Ed +.Pp +The +.Nm decimal +set: +.Bd -literal -offset left + 0 nul 1 soh 2 stx 3 etx 4 eot 5 enq 6 ack 7 bel + 8 bs 9 ht 10 lf 11 vt 12 ff 13 cr 14 so 15 si + 16 dle 17 dc1 18 dc2 19 dc3 20 dc4 21 nak 22 syn 23 etb + 24 can 25 em 26 sub 27 esc 28 fs 29 gs 30 rs 31 us + 32 sp 33 ! 34 " 35 # 36 $ 37 % 38 & 39 ' + 40 ( 41 ) 42 * 43 + 44 , 45 - 46 . 47 / + 48 0 49 1 50 2 51 3 52 4 53 5 54 6 55 7 + 56 8 57 9 58 : 59 ; 60 < 61 = 62 > 63 ? + 64 @ 65 A 66 B 67 C 68 D 69 E 70 F 71 G + 72 H 73 I 74 J 75 K 76 L 77 M 78 N 79 O + 80 P 81 Q 82 R 83 S 84 T 85 U 86 V 87 W + 88 X 89 Y 90 Z 91 [ 92 \e\ 93 ] 94 ^ 95 _ + 96 ` 97 a 98 b 99 c 100 d 101 e 102 f 103 g +104 h 105 i 106 j 107 k 108 l 109 m 110 n 111 o +112 p 113 q 114 r 115 s 116 t 117 u 118 v 119 w +120 x 121 y 122 z 123 { 124 | 125 } 126 ~ 127 del +.Ed +.Sh STANDARDS +.Rs +.%T Information Systems - Coded Character Sets - 7-Bit American National\ + Standard Code for Information Interchange (7-Bit ASCII) +.%R INCITS 4-1986[R2017] +.%Q InterNational Committee for Information Technology Standards +.Re +.Sh HISTORY +An +.Nm +manual page appeared in +.At v1 . diff --git a/static/openbsd/man7/environ.7 b/static/openbsd/man7/environ.7 new file mode 100644 index 00000000..c1247995 --- /dev/null +++ b/static/openbsd/man7/environ.7 @@ -0,0 +1,218 @@ +.\" $OpenBSD: environ.7,v 1.22 2020/02/09 00:11:23 jsg Exp $ +.\" $NetBSD: environ.7,v 1.4 1995/07/03 19:45:07 jtc Exp $ +.\" +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)environ.7 8.3 (Berkeley) 4/19/94 +.\" +.Dd $Mdocdate: February 9 2020 $ +.Dt ENVIRON 7 +.Os +.Sh NAME +.Nm environ +.Nd user environment +.Sh SYNOPSIS +.Vt extern char **environ ; +.Sh DESCRIPTION +An array of strings called the +.Dq environment +is made available by +.Xr execve 2 +when a process begins. +By convention these strings have the form +.Ar name Ns = Ns Ar value . +The following variables are recognized by various commands: +.Bl -tag -width BLOCKSIZE +.It Ev BLOCKSIZE +The size of the block units used by several commands, most notably +.Xr df 1 , +.Xr du 1 , +and +.Xr ls 1 . +May be specified in units of a byte by specifying a number, +in units of a kilobyte by specifying a number followed by +.Sq K +or +.Sq k , +in units of a megabyte by specifying a number followed by +.Sq M +or +.Sq m , +or in units of a gigabyte by specifying a number followed +by +.Sq G +or +.Sq g . +Sizes less than 512 bytes or greater than a gigabyte are ignored. +.It Ev EXINIT +A list of startup commands read by +.Xr ex 1 +and +.Xr vi 1 . +.It Ev HOME +The user's login directory, set by +.Xr login 1 +from the password file +.Xr passwd 5 . +.It Ev LOGNAME +The login name of the user. +.It Ev PATH +The sequence of directories, separated by colons, searched by +.Xr csh 1 , +.Xr sh 1 , +.Xr ksh 1 , +.Xr system 3 , +.Xr execvp 3 , +etc. when looking for an executable file. +Initially set to the value of +.Dv _PATH_DEFPATH +by +.Xr login 1 , +traditionally +.Pa /usr/bin:/bin , +but expanded to include +.Pa /usr/sbin , +.Pa /sbin , +.Pa /usr/X11R6/bin , +.Pa /usr/local/bin , +and +.Pa /usr/local/sbin +in +.Ox . +.It Ev PRINTER +The name of the default printer to be used by +.Xr lpq 1 , +.Xr lpr 1 , +and +.Xr lprm 1 . +.It Ev PWD +The current working directory. +.It Ev SHELL +The full pathname of the user's login shell. +.It Ev TERM +The kind of terminal for which output is to be prepared. +This information is used by commands such as +.Xr mandoc 1 +which may exploit special terminal capabilities. +See +.Pa /usr/share/misc/termcap +.Pq Xr termcap 5 +for a list of terminal types. +.It Ev TERMCAP +The string describing the terminal in +.Ev TERM , +or, if it begins with a +.Ql / , +the name of the termcap file. +See +.Ev TERMPATH +below, +.Xr termcap 5 , +and +.Xr termcap 3 . +.It Ev TERMPATH +A sequence of pathnames of termcap files, separated by colons or spaces, +which are searched for terminal descriptions in the order listed. +Having no +.Ev TERMPATH +is equivalent to a +.Ev TERMPATH +of +.Pa $HOME/.termcap:/etc/termcap . +.Ev TERMPATH +is ignored if +.Ev TERMCAP +contains a full pathname. +.It Ev TMPDIR +The directory in which to store temporary files. +Most applications use either +.Pa /tmp +or +.Pa /var/tmp . +Setting this variable will make them use another directory. +.It Ev TZ +The time zone to use when displaying dates. +The normal format is a pathname relative to +.Pa /usr/share/zoneinfo . +For example, the command +.Ic env TZ=America/Los_Angeles date +displays the current time in California. +See +.Xr tzset 3 +for more information. +.It Ev USER +Deprecated synonym of +.Ev LOGNAME +(for backwards compatibility). +.El +.Pp +Further names may be placed in the environment by the +.Ic export +command and +.Ar name Ns = Ns Ar value +arguments in +.Xr sh 1 , +or by the +.Ic setenv +command if you use +.Xr csh 1 . +It is unwise to change certain +.Xr sh 1 +variables that are frequently exported by +.Pa .profile +files, such as +.Ev MAIL , +.Ev PS1 , +.Ev PS2 , +and +.Ev IFS , +unless you know what you are doing. +.Pp +The current environment variables can be printed with +.Xr env 1 +or +.Xr printenv 1 . +.Sh SEE ALSO +.Xr csh 1 , +.Xr env 1 , +.Xr ex 1 , +.Xr login 1 , +.Xr printenv 1 , +.Xr sh 1 , +.Xr execve 2 , +.Xr execle 3 , +.Xr getenv 3 , +.Xr system 3 , +.Xr termcap 3 , +.Xr tzset 3 , +.Xr termcap 5 +.Sh HISTORY +An +.Nm +manual page appeared in +.At v7 . diff --git a/static/openbsd/man7/eqn.7 b/static/openbsd/man7/eqn.7 new file mode 100644 index 00000000..5d4c3a04 --- /dev/null +++ b/static/openbsd/man7/eqn.7 @@ -0,0 +1,507 @@ +.\" $OpenBSD: eqn.7,v 1.12 2020/01/10 11:54:05 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2014 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 10 2020 $ +.Dt EQN 7 +.Os +.Sh NAME +.Nm eqn +.Nd eqn language reference for mandoc +.Sh DESCRIPTION +The +.Nm eqn +language is an equation-formatting language. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +.Ux +manual pages. +It describes the +.Em structure +of an equation, not its mathematical meaning. +This manual describes the +.Nm +language accepted by the +.Xr mandoc 1 +utility, which corresponds to the Second Edition +.Nm +specification (see +.Sx SEE ALSO +for references). +.Pp +An equation starts with an input line containing exactly the characters +.Sq \&.EQ , +may contain multiple input lines, and ends with an input line +containing exactly the characters +.Sq \&.EN . +Equivalently, an equation can be given in the middle of a single +text input line by surrounding it with the equation delimiters +defined with the +.Cm delim +statement. +.Pp +The equation grammar is as follows, where quoted strings are +case-sensitive literals in the input: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | \(dq{\(dq eqn \(dq}\(dq + | \(dqdefine\(dq text text + | \(dqndefine\(dq text text + | \(dqtdefine\(dq text text + | \(dqgfont\(dq text + | \(dqgsize\(dq text + | \(dqset\(dq text text + | \(dqundef\(dq text + | \(dqsqrt\(dq box + | box pos box + | box mark + | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq + | pile \(dq{\(dq list \(dq}\(dq + | font box + | \(dqsize\(dq text box + | \(dqleft\(dq text eqn [\(dqright\(dq text] +col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq +text : [^space\e\(dq]+ | \e\(dq.*\e\(dq +pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq +pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq +mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq + | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq +font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq +list : eqn + | list \(dqabove\(dq eqn +space : [\e^~ \et] +.Ed +.Pp +White-space consists of the space, tab, circumflex, and tilde +characters. +It is required to delimit tokens consisting of alphabetic characters +and it is ignored at other places. +Braces and quotes also delimit tokens. +If within a quoted string, these space characters are retained. +Quoted strings are also not scanned for keywords, glyph names, +and expansion of definitions. +To print a literal quote character, it can be prepended with a +backslash or expressed with the \e(dq escape sequence. +.Pp +Subequations can be enclosed in braces to pass them as arguments +to operation keywords, overriding standard operation precedence. +Braces can be nested. +To set a brace verbatim, it needs to be enclosed in quotes. +.Pp +The following text terms are translated into a rendered glyph, if +available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, +lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, +upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, +THETA, UPSILON, XI, inter (intersection), union (union), prod (product), +int (integral), sum (summation), grad (gradient), del (vector +differential), times (multiply), cdot (center-dot), nothing (zero-width +space), approx (approximately equals), prime (prime), half (one-half), +partial (partial differential), inf (infinity), >> (much greater), << +(much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), != +(not equal), == (equivalence), <= (less-than-equal), and >= +(more-than-equal). +The character escape sequences documented in +.Xr mandoc_char 7 +can be used, too. +.Pp +The following control statements are available: +.Bl -tag -width Ds +.It Cm define +Replace all occurrences of a key with a value. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key cvalc +.Pp +The first character of the value string, +.Ar c , +is used as the delimiter for the value +.Ar val . +This allows for arbitrary enclosure of terms (not just quotes), such as +.Pp +.D1 Cm define Ar foo \(aqbar baz\(aq +.D1 Cm define Ar foo cbar bazc +.Pp +It is an error to have an empty +.Ar key +or +.Ar val . +Note that a quoted +.Ar key +causes errors in some +.Nm +implementations and should not be considered portable. +It is not expanded for replacements. +Definitions may refer to other definitions; these are evaluated +recursively when text replacement occurs and not when the definition is +created. +.Pp +Definitions can create arbitrary strings, for example, the following is +a legal construction. +.Bd -literal -offset indent +define foo \(aqdefine\(aq +foo bar \(aqbaz\(aq +.Ed +.Pp +Self-referencing definitions will raise an error. +The +.Cm ndefine +statement is a synonym for +.Cm define , +while +.Cm tdefine +is discarded. +.It Cm delim +This statement takes a string argument consisting of two bytes, +to be used as the opening and closing delimiters for equations +in the middle of text input lines. +Conventionally, the dollar sign is used for both delimiters, +as follows: +.Bd -literal -offset indent +\&.EQ +delim $$ +\&.EN +An equation like $sin pi = 0$ can now be entered +in the middle of a text input line. +.Ed +.Pp +The special statement +.Cm delim off +temporarily disables previously declared delimiters and +.Cm delim on +reenables them. +.It Cm gfont +Set the default font of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gfont Ar font +.Pp +In mandoc, this value is discarded. +.It Cm gsize +Set the default size of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gsize Oo +|\- Oc Ns Ar size +.Pp +The +.Ar size +value should be an integer. +If prepended by a sign, +the font size is changed relative to the current size. +.It Cm set +Set an equation mode. +In mandoc, both arguments are thrown away. +Its syntax is as follows: +.Pp +.D1 Cm set Ar key val +.Pp +The +.Ar key +and +.Ar val +are not expanded for replacements. +This statement is a GNU extension. +.It Cm undef +Unset a previously-defined key. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key +.Pp +Once invoked, the definition for +.Ar key +is discarded. +The +.Ar key +is not expanded for replacements. +This statement is a GNU extension. +.El +.Pp +Operation keywords have the following semantics: +.Bl -tag -width Ds +.It Cm above +See +.Cm pile . +.It Cm bar +Draw a line over the preceding box. +.It Cm bold +Set the following box using bold font. +.It Cm ccol +Like +.Cm cpile , +but for use in +.Cm matrix . +.It Cm cpile +Like +.Cm pile , +but with slightly increased vertical spacing. +.It Cm dot +Set a single dot over the preceding box. +.It Cm dotdot +Set two dots (dieresis) over the preceding box. +.It Cm dyad +Set a dyad symbol (left-right arrow) over the preceding box. +.It Cm fat +A synonym for +.Cm bold . +.It Cm font +Set the second argument using the font specified by the first argument; +currently not recognized by the +.Xr mandoc 1 +.Nm +parser. +.It Cm from +Set the following box below the preceding box, +using a slightly smaller font. +Used for sums, integrals, limits, and the like. +.It Cm hat +Set a hat (circumflex) over the preceding box. +.It Cm italic +Set the following box using italic font. +.It Cm lcol +Like +.Cm lpile , +but for use in +.Cm matrix . +.It Cm left +Set the first argument as a big left delimiter before the second argument. +As an optional third argument, +.Cm right +can follow. +In that case, the fourth argument is set as a big right delimiter after +the second argument. +.It Cm lpile +Like +.Cm cpile , +but subequations are left-justified. +.It Cm matrix +Followed by a list of columns enclosed in braces. +All columns need to have the same number of subequations. +The columns are set as a matrix. +The difference compared to multiple subsequent +.Cm pile +operators is that in a +.Cm matrix , +corresponding subequations in all columns line up horizontally, +while each +.Cm pile +does vertical spacing independently. +.It Cm over +Set a fraction. +The preceding box is the numerator, the following box is the denominator. +.It Cm pile +Followed by a list of subequations enclosed in braces, +the subequations being separated by +.Cm above +keywords. +Sets the subequations one above the other, each of them centered. +Typically used to represent vectors in coordinate representation. +.It Cm rcol +Like +.Cm rpile , +but for use in +.Cm matrix . +.It Cm right +See +.Cm left ; +.Cm right +cannot be used without +.Cm left . +To set a big right delimiter without a big left delimiter, the following +construction can be used: +.Pp +.D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter +.It Cm roman +Set the following box using the default font. +.It Cm rpile +Like +.Cm cpile , +but subequations are right-justified. +.It Cm size +Set the second argument with the font size specified by the first +argument; currently ignored by +.Xr mandoc 1 . +By prepending a plus or minus sign to the first argument, +the font size can be selected relative to the current size. +.It Cm sqrt +Set the square root of the following box. +.It Cm sub +Set the following box as a subscript to the preceding box. +.It Cm sup +Set the following box as a superscript to the preceding box. +As a special case, if a +.Cm sup +clause immediately follows a +.Cm sub +clause as in +.Pp +.D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox +.Pp +both are set with respect to the same +.Ar mainbox , +that is, +.Ar supbox +is set above +.Ar subbox . +.It Cm tilde +Set a tilde over the preceding box. +.It Cm to +Set the following box above the preceding box, +using a slightly smaller font. +Used for sums and integrals and the like. +As a special case, if a +.Cm to +clause immediately follows a +.Cm from +clause as in +.Pp +.D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox +.Pp +both are set below and above the same +.Ar mainbox . +.It Cm under +Underline the preceding box. +.It Cm vec +Set a vector symbol (right arrow) over the preceding box. +.El +.Pp +The binary operations +.Cm from , +.Cm to , +.Cm sub , +and +.Cm sup +group to the right, that is, +.Pp +.D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox +.Pp +is the same as +.Pp +.D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox +.Pp +and different from +.Pp +.D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox . +.Pp +By contrast, +.Cm over +groups to the left. +.Pp +In the following list, earlier operations bind more tightly than +later operations: +.Pp +.Bl -enum -compact +.It +.Cm dyad , +.Cm vec , +.Cm under , +.Cm bar , +.Cm tilde , +.Cm hat , +.Cm dot , +.Cm dotdot +.It +.Cm fat , +.Cm roman , +.Cm italic , +.Cm bold , +.Cm size +.It +.Cm sub , +.Cm sup +.It +.Cm sqrt +.It +.Cm over +.It +.Cm from , +.Cm to +.El +.Sh COMPATIBILITY +This section documents the compatibility of mandoc +.Nm +and the troff +.Nm +implementation (including GNU troff). +.Pp +.Bl -dash -compact +.It +The text string +.Sq \e\(dq +is interpreted as a literal quote in troff. +In mandoc, this is interpreted as a comment. +.It +In troff, The circumflex and tilde white-space symbols map to +fixed-width spaces. +In mandoc, these characters are synonyms for the space character. +.It +The troff implementation of +.Nm +allows for equation alignment with the +.Cm mark +and +.Cm lineup +tokens. +mandoc discards these tokens. +The +.Cm back Ar n , +.Cm fwd Ar n , +.Cm up Ar n , +and +.Cm down Ar n +commands are also ignored. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T System for Typesetting Mathematics +.%J Communications of the ACM +.%V 18 +.%P pp. 151\(en157 +.%D March, 1975 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide +.%D 1976 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide (Second Edition) +.%D 1978 +.Re +.Sh HISTORY +The eqn utility, a preprocessor for troff, was originally written by +Brian W. Kernighan and Lorinda L. Cherry in 1975. +The GNU reimplementation of eqn, part of the GNU troff package, was +released in 1989 by James Clark. +The eqn component of +.Xr mandoc 1 +was added in 2011. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/openbsd/man7/glob.7 b/static/openbsd/man7/glob.7 new file mode 100644 index 00000000..48076472 --- /dev/null +++ b/static/openbsd/man7/glob.7 @@ -0,0 +1,149 @@ +.\" $OpenBSD: glob.7,v 1.8 2023/05/30 14:04:53 aisha Exp $ +.\" +.\" Copyright (c) 2009 Todd C. Miller <millert@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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.Dd $Mdocdate: May 30 2023 $ +.Dt GLOB 7 +.Os +.Sh NAME +.Nm glob +.Nd shell-style pattern matching +.Sh DESCRIPTION +Globbing characters +.Pq wildcards +are special characters used to perform pattern matching of pathnames and +command arguments in the +.Xr csh 1 , +.Xr ksh 1 , +and +.Xr sh 1 +shells as well as +the C library functions +.Xr fnmatch 3 +and +.Xr glob 3 . +A glob pattern is a word containing one or more unquoted +.Ql \&? +or +.Ql * +characters, or +.Dq [..] +sequences. +.Pp +Globs should not be confused with the more powerful +regular expressions used by programs such as +.Xr grep 1 . +While there is some overlap in the special characters used in regular +expressions and globs, their meaning is different. +.Pp +The pattern elements have the following meaning: +.Bl -tag -width Ds +.It \&? +Matches any single character. +.It \&* +Matches any sequence of zero or more characters. +.It [..] +Matches any of the characters inside the brackets. +Ranges of characters can be specified by separating two characters by a +.Ql - +(e.g.\& +.Dq [a0-9] +matches the letter +.Sq a +or any digit). +In order to represent itself, a +.Ql - +must either be quoted or the first or last character in the character list. +Similarly, a +.Ql \&] +must be quoted or the first character in the list if it is to represent itself +instead of the end of the list. +Also, a +.Ql \&! +appearing at the start of the list has special meaning (see below), so to +represent itself it must be quoted or appear later in the list. +.Pp +Within a bracket expression, the name of a +.Em character class +enclosed in +.Sq [: +and +.Sq :] +stands for the list of all characters belonging to that class. +Supported character classes: +.Bl -column "xdigit" "xdigit" "xdigit" -offset indent +.It Li "alnum" Ta Li "cntrl" Ta Li "lower" Ta Li "space" +.It Li "alpha" Ta Li "digit" Ta Li "print" Ta Li "upper" +.It Li "blank" Ta Li "graph" Ta Li "punct" Ta Li "xdigit" +.El +.Pp +These match characters using the macros specified in +.Xr isalnum 3 , +.Xr isalpha 3 , +and so on. +A character class may not be used as an endpoint of a range. +.It [!..] +Like [..], +except it matches any character not inside the brackets. +.It \e +Matches the character following it verbatim. +This is useful to quote the special characters +.Ql \&? , +.Ql \&* , +.Ql \&[ , +and +.Ql \e +such that they lose their special meaning. +For example, the pattern +.Dq \e\e\e\&*\e[x]\e\&? +matches the string +.Dq \e\&*[x]\&? . +.El +.Pp +Note that when matching a pathname, the path separator +.Ql / , +is not matched by a +.Ql \&? , +or +.Ql * , +character or by a +.Dq [..] +sequence. +Thus, +.Pa /usr/*/*/X11 +would match +.Pa /usr/X11R6/lib/X11 +and +.Pa /usr/X11R6/include/X11 +while +.Pa /usr/*/X11 +would not match either. +Likewise, +.Pa /usr/*/bin +would match +.Pa /usr/local/bin +but not +.Pa /usr/bin . +.Sh SEE ALSO +.Xr fnmatch 3 , +.Xr glob 3 , +.Xr re_format 7 +.Sh HISTORY +A stand-alone program, +.Pa /etc/glob , +first appeared in +.At v1 . +In PWB/UNIX 1.0 this functionality was incorporated into the shell itself. diff --git a/static/openbsd/man7/hier.7 b/static/openbsd/man7/hier.7 new file mode 100644 index 00000000..fde15952 --- /dev/null +++ b/static/openbsd/man7/hier.7 @@ -0,0 +1,658 @@ +.\" $OpenBSD: hier.7,v 1.170 2022/10/23 08:00:29 jmc Exp $ +.\" $NetBSD: hier.7,v 1.7 1994/11/30 19:07:10 jtc Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)hier.7 8.1 (Berkeley) 6/5/93 +.\" +.Dd $Mdocdate: October 23 2022 $ +.Dt HIER 7 +.Os +.Sh NAME +.Nm hier +.Nd layout of filesystems +.Sh DESCRIPTION +A sketch of the filesystem hierarchy. +.Bl -tag -width "/altroot/" +.It / +Root directory. +.It /altroot/ +Alternate (backup) location for the root +.Pq Sq / +filesystem +(see +.Xr daily 8 ) . +.It /bin/ +User utilities fundamental to both single and multi-user environments. +These programs are statically compiled and therefore do not depend on any +system libraries to run. +.It /bsd +Pure kernel executable +(the operating system loaded into memory at boot-time). +.It /bsd.mp +Pure kernel executable +for multiprocessor machines. +.It /bsd.rd +Installation kernel. +The built-in RAM disk contains utilities which can be run +without an external file system, so this kernel is useful +for limited system maintenance too. +.It /bsd.sp +Pure kernel executable +for single processor machines. +.It /dev/ +Block and character device files. +.Pp +.Bl -tag -width MAKEDEV -compact +.It MAKEDEV +Script for creating device files (see +.Xr MAKEDEV 8 ) . +.It fd/ +File descriptor files (see +.Xr fd 4 ) . +.El +.It /etc/ +System configuration files and scripts. +.Pp +.Bl -tag -width "raddb/servers/" -compact +.It localtime +Local time zone information (see +.Xr ctime 3 ) . +.It X11/ +Configuration files for the X11 window system. +.It acme/ +Private keys for +.Xr acme-client 1 . +.It amd/ +Contains map files for +.Xr amd 8 . +.It authpf/ +Configuration files for the authenticating gateway user shell (see +.Xr authpf 8 ) . +.It examples/ +Example configuration files for base system daemons. +.It firmware/ +Firmware files for various devices. +.It fonts/ +Configuration files for X11 window system fonts. +.It hotplug/ +Scripts for the hotplug daemon, +.Xr hotplugd 8 . +.It iked/ +Configuration files for +.Xr iked 8 . +.It isakmpd/ +Configuration files for +.Xr isakmpd 8 . +.It ldap/ +Certificates and schema definition files for +.Xr ldapd 8 . +.It login.conf.d/ +Additional login attributes for +.Xr login.conf 5 . +.It mail/ +System mail configuration files. +.It mtree/ +.Xr mtree 8 +configuration files. +.It npppd/ +.Xr npppd 8 +configuration files. +.It ppp/ +.Xr pppd 8 +configuration files. +.It raddb/servers/ +List of radius servers and their associated shared secrets for +.Xr login_radius 8 . +.It rc.d/ +.Xr packages 7 +start/stop scripts and subroutines for +.Xr rc 8 . +.It rpki/ +TAL and configuration files for +.Xr rpki-client 8 . +.It signify/ +Key files used by +.Xr signify 1 . +.It skel/ +Example +.Sq .\& +(dot) files for new accounts. +.It skey/ +One-time password user database for +.Xr skey 1 . +.It ssh/ +Configuration files for +.Xr ssh 1 +and +.Xr sshd 8 . +.It ssl/ +OpenSSL configuration files (see +.Xr openssl 1 ) . +.El +.It /home/ +Default location for user home directories. +.Pp +.Bl -tag -width _sysupgrade/ -compact +.It _sysupgrade/ +Download location for +.Xr sysupgrade 8 . +.El +.It /mnt/ +Empty directory commonly used by +system administrators as a temporary mount point. +.It /root/ +Default home directory for the superuser. +.It /sbin/ +System programs and administration utilities +fundamental to both single and multi-user environments. +Most of these programs are statically compiled and therefore do not +depend on any system libraries to run. +.It /tmp/ +Temporary files that are +.Em not +preserved between system reboots. +Periodically cleaned by +.Xr daily 8 . +.It /usr/ +Contains the majority of user utilities and applications. +.Pp +.Bl -tag -width "xenocara/" -compact +.It X11R6/ +Files required for the X11 window system. +.Pp +.Bl -tag -width "include/" -compact +.It bin/ +X11 binaries. +.It include/ +X11-specific C include files. +.It lib/ +X11 archive libraries. +.Pp +.Bl -tag -width "pkgconfig/" -compact +.It X11/ +Default configuration files for X11 and companion applications. +.It modules/ +Various libraries and drivers for the X11 window system. +.It pkgconfig/ +Package metadata for +.Xr pkg-config 1 . +.It xorg/ +Data files used by the X server. +.El +.Pp +.It man/ +X11 manual pages. +.It share/ +Architecture independent data files. +.El +.Pp +.It bin/ +Common utilities, programming tools, and applications. +.It games/ +Useful and semi-frivolous programs. +.It include/ +Standard C include files. +.Pp +.Bl -tag -width "libmilter/" -compact +.It arpa/ +C include files for Internet service protocols. +.It c++/ +Include files for the Clang C++ compiler. +.It cbor/ +C include files for the Concise Binary Object Representation (CBOR) +library. +.It crypto/ +C include files for the cryptographic libraries. +.It ddb/ +C include files for the kernel debugger (see +.Xr ddb 4 ) . +.It dev/ +Device-specific C include files. +.It fido/ +C include files for the U2F/FIDO2 communication library. +.It g++/ +Include files for the GNU C++ compiler. +.It isofs/ +C include files for the ISO standard file systems (currently only cd9660). +.It llvm/ +C++ include files for LLVM. +.It llvm-c/ +C include files for LLVM. +.It machine/ +Machine specific C include files. +.It miscfs/ +C include files for miscellaneous file systems. +.It msdosfs/ +C include files for MS-DOS file system. +.It net/ +Miscellaneous network C include files. +.It net80211/ +C include files for 802.11 wireless networking. +.It netinet/ +C include files for Internet standard protocols (see +.Xr inet 4 ) . +.It netinet6/ +C include files for Internet protocol version 6 (see +.Xr inet6 4 ) . +.It netmpls/ +C include files for the MPLS protocol. +.It nfs/ +C include files for NFS (Network File System). +.It ntfs/ +C include files for NTFS file system. +.It openssl/ +C include files for the OpenSSL library (see +.Xr ssl 8 ) . +.It protocols/ +C include files for Berkeley service protocols. +.It readline/ +C include files for the +.Xr readline 3 +library. +.It rpc/ +C include files for remote procedure calling (see +.Xr rpc 5 ) . +.It rpcsvc/ +C include files for rpcsvc. +.It scsi/ +SCSI-specific C include files. +.It sys/ +System C include files (kernel data structures). +.It ufs/ +C include files for UFS (the U-word File System). +.It uvm/ +C include files for the virtual memory interface. +.El +.Pp +.It lib/ +System libraries. +See +.Xr intro 3 +for a description of library types. +.It libdata/ +Miscellaneous utility data files. +.Pp +.Bl -tag -width "ldscripts/" -compact +.It cvs/ +Placeholder for user contributed +.Xr cvs 1 +code/scripts. +.It ldscripts/ +ELF linker scripts. +.It perl5/ +Data files for +.Xr perl 1 . +.El +.Pp +.It libexec/ +System daemons and utilities (executed by other programs). +.Pp +.Bl -tag -width "cvs/contrib/" -compact +.It auth/ +Login scripts used to authenticate users (for +.Bx +Authentication). +.It cvs/contrib/ +User contributed +.Xr cvs 1 +scripts. +.It lpr/ +Contains the lpf filter for +.Xr lpd 8 . +.It radiusd/ +Authentication modules for +.Xr radiusd 8 . +.It snmpd/ +SNMP subagents. +.El +.Pp +.It local/ +Local executables, libraries, etc. +.It mdec/ +Boot-related executables. +.It obj/ +Architecture specific target tree produced by building the +.Pa /usr/src +tree. +.It ports/ +The +.Ox +ports collection (see +.Xr ports 7 ) . +.It sbin/ +System daemons and utilities (executed by users). +.It share/ +Architecture independent data files. +.Pp +.Bl -tag -width "calendar/" -compact +.It calendar/ +Variety of pre-fab calendar files (see +.Xr calendar 1 ) . +.It dict/ +Word lists (see +.Xr look 1 +and +.Xr spell 1 ) . +.Pp +.Bl -tag -width propernames -compact +.It american +Spellings preferred in American usage. +.It british +Spellings preferred in British usage. +.It propernames +List of proper names. +.It stop +Forms that would otherwise be derivable by +.Xr spell 1 +from words in the other files in +.Pa /usr/share/dict , +but should not be accepted. +.It web2 +Words from Webster's 2nd International. +.It web2a +Additional words from Webster's. +.It words +Common words. +.It papers/ +Reference databases. +.It special/ +Custom word lists. +.El +.Pp +.It doc/ +Miscellaneous documentation. +.It games/ +ASCII text files used by various games. +.It info/ +Texinfo source files. +.It locale/ +Locales for multi-language support. +.It man/ +Manual pages. +.Pp +.Bl -tag -width man3p/ -compact +.It man1/ +General commands (tools and utilities). +.It man2/ +System calls and error numbers. +.It man3/ +Libraries. +.It man3p/ +.Xr perl 1 +programmers' reference guide. +.It man4/ +Special files and hardware support. +.It man5/ +File formats. +.It man6/ +Games. +.It man7/ +Miscellaneous. +.It man8/ +System maintenance and operation commands. +.It man9/ +Kernel internals. +.El +.Pp +.It misc/ +Miscellaneous system-wide ASCII text files. +.Pp +.Bl -tag -width pcvtfonts/ -compact +.It termcap +Terminal characteristics database (see +.Xr termcap 5 ) . +.It pcvtfonts/ +Additional console fonts. +.El +.Pp +.It mk/ +Templates for +.Xr make 1 . +.It relink/ +Link kit for boot-time kernel and library relinking. +.It snmp/ +Data files for +.Xr snmpd 8 . +.Pp +.Bl -tag -width mibs/ -compact +.It mibs/ +Management Information Base (MIB) definitions. +.El +.Pp +.It tabset/ +Tab description files for a variety of terminals; used in +the termcap file (see +.Xr termcap 5 ) . +.It terminfo/ +Compiled terminal characteristic files (see +.Xr terminfo 5 ) . +.It texinfo/ +Templates for +.Xr texinfo 5 . +.It zoneinfo/ +Time zone configuration information (see +.Xr tzfile 5 ) . +.El +.Pp +.It src/ +.Bx +and/or local source files. +.Pp +.Bl -tag -width "usr.sbin/" -compact +.It bin/ +Source for files in +.Pa /bin . +.It distrib/ +Source for making distribution sets. +.It etc/ +Source for files in +.Pa /etc . +.It games/ +Source for files in +.Pa /usr/games . +.It gnu/ +Source for files under GPL or other restrictive licenses. +.It include/ +Source for files in +.Pa /usr/include . +.It lib/ +Source for files in +.Pa /usr/lib . +.It libexec/ +Source for files in +.Pa /usr/libexec . +.It regress/ +Regress framework. +.It sbin/ +Source for files in +.Pa /sbin . +.It share/ +Source for files in +.Pa /usr/share . +.It sys/ +Kernel source files. +.It usr.bin/ +Source for files in +.Pa /usr/bin . +.It usr.sbin/ +Source for files in +.Pa /usr/sbin . +.El +.Pp +.It xenocara/ +Source for the X11 window system. +.Pp +.It xobj/ +Architecture specific target tree produced by building the +.Pa /usr/xenocara +tree. +.El +.It /var/ +Multi-purpose log, temporary, transient, and spool files. +.Pp +.Bl -tag -width "sysmerge/" -compact +.It account/ +System accounting files. +.Pp +.Bl -tag -width acct -compact +.It acct +Execution accounting file (see +.Xr acct 5 ) . +.El +.Pp +.It agentx/ +Master socket for AgentX-based backends, +managed by +.Xr snmpd 8 . +.It audit/ +Audit logs. +.It authpf/ +PID file for +.Xr authpf 8 . +.It backups/ +Miscellaneous backup files. +.It cache/ +Data cached for programs. +.It crash/ +Crash dumps written by +.Xr savecore 8 . +.It cron/ +Spools and configuration files for +.Xr cron 8 +and +.Xr at 1 . +.Pp +.Bl -tag -width atjobs/ -compact +.It atjobs/ +.Xr at 1 +jobs. +.It tabs/ +Individual +.Xr crontab 1 +files. +.El +.Pp +.It db/ +Miscellaneous, automatically generated system-specific database files. +.It empty/ +Generic +.Xr chroot 2 +directory. +.It games/ +Miscellaneous game status and log files. +.It log/ +Miscellaneous system log files. +.Pp +.Bl -tag -width rdist/ -compact +.It wtmp +Login/logout log (see +.Xr wtmp 5 ) . +.It rdist/ +Log files for +.Xr rdist 1 . +.El +.Pp +.It mail/ +User mailbox files. +.It nsd/ +Database and zone files for +.Xr nsd 8 . +.It quotas/ +Filesystem quota information files. +.It run/ +System information files describing various info about the +system since it was booted. +.Pp +.Bl -tag -width rc.d/ -compact +.It rc.d/ +Details of currently running daemons; +used by +.Xr rc.d 8 . +.It utmp +Database of current users (see +.Xr utmp 5 ) . +.El +.Pp +.It spool/ +Miscellaneous printer and mail system spooling directories. +.Pp +.Bl -tag -width "output/" -compact +.It ftp/ +Commonly ~ftp; the anonymous ftp root directory. +.It lock/ +Lock files for utilities such as +.Xr pppd 8 . +.It output/ +Line printer spooling directories. +.It smtpd/ +Mail spool for +.Xr smtpd 8 . +.El +.Pp +.It sysmerge/ +Checksum files and reference sets +for +.Xr sysmerge 8 . +.It syspatch/ +Rollback tarballs and patch files for +.Xr syspatch 8 . +.It tmp -> ../tmp +A symbolic link to the system +.Pa /tmp +directory. +To protect other users of +.Pa /var +from overfill conditions, this is no longer a space you can trust to +retain storage over a reboot. +Periodically cleaned by +.Xr daily 8 . +.It unbound/ +Configuration files for +.Xr unbound 8 . +.It www/ +Configuration files for +.Xr httpd 8 . +.It yp/ +Files for the +.Xr yp 8 +subsystem. +.El +.El +.Sh SEE ALSO +.Xr apropos 1 , +.Xr find 1 , +.Xr locate 1 , +.Xr whatis 1 , +.Xr whereis 1 , +.Xr which 1 +.Sh HISTORY +A +.Nm +manual page appeared in +.At v7 . diff --git a/static/openbsd/man7/hostname.7 b/static/openbsd/man7/hostname.7 new file mode 100644 index 00000000..13ccd601 --- /dev/null +++ b/static/openbsd/man7/hostname.7 @@ -0,0 +1,80 @@ +.\" $OpenBSD: hostname.7,v 1.11 2019/05/12 16:55:11 schwarze Exp $ +.\" $NetBSD: hostname.7,v 1.4 1994/11/30 19:07:14 jtc Exp $ +.\" +.\" Copyright (c) 1987, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)hostname.7 8.2 (Berkeley) 12/30/93 +.\" +.Dd $Mdocdate: May 12 2019 $ +.Dt HOSTNAME 7 +.Os +.Sh NAME +.Nm hostname +.Nd host name resolution description +.Sh DESCRIPTION +Hostnames are domains, where a domain is a hierarchical, dot-separated +list of subdomains; for example, the machine monet, in the Berkeley +subdomain of the EDU subdomain of the Internet would be represented as +.Pp +.Dl monet.Berkeley.EDU +.Pp +(with no trailing dot). +.Pp +Hostnames are often used with network client and server programs, +which must generally translate the name to an address for use. +(This function is generally performed by the library routine +.Xr gethostbyname 3 . ) +Hostnames are resolved by the Internet name resolver in the following +fashion. +.Pp +If the input name ends with a trailing dot, +the trailing dot is removed, +and the remaining name is looked up with no further processing. +.Pp +If the input name does not end with a trailing dot, it is looked up +by searching through a list of domains until a match is found. +The default search list includes first the local domain, +then its parent domains with at least 2 name components (longest first). +For example, +in the domain CS.Berkeley.EDU, the name lithium.CChem will be checked first +as lithium.CChem.CS.Berkeley.EDU and then as lithium.CChem.Berkeley.EDU. +Lithium.CChem.EDU will not be tried, as there is only one component +remaining from the local domain. +The search path can be changed from the default +by a system-wide configuration file (see +.Xr resolv.conf 5 ) . +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr resolv.conf 5 , +.Xr nsd 8 , +.Xr unbound 8 +.Sh HISTORY +A +.Nm +manual page appeared in +.Bx 4.2 . diff --git a/static/openbsd/man7/intro.7 b/static/openbsd/man7/intro.7 new file mode 100644 index 00000000..3eb37239 --- /dev/null +++ b/static/openbsd/man7/intro.7 @@ -0,0 +1,99 @@ +.\" $OpenBSD: intro.7,v 1.20 2018/09/30 13:24:33 schwarze Exp $ +.\" $NetBSD: intro.7,v 1.3 1994/11/30 19:07:15 jtc Exp $ +.\" +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)intro.7 8.1 (Berkeley) 6/5/93 +.\" +.Dd $Mdocdate: September 30 2018 $ +.Dt INTRO 7 +.Os +.Sh NAME +.Nm intro +.Nd miscellaneous information pages +.Sh DESCRIPTION +The manual pages in section 7 contain miscellaneous documentation. +.Pp +.Bl -tag -width "mirroring-ports(7)" -compact +.It Xr ascii 7 +Map of ASCII character set. +.It Xr environ 7 +User environment. +.It Xr eqn 7 +Eqn language reference for +.Xr mandoc 1 . +.It Xr glob 7 +Shell-style pattern matching. +.It Xr hier 7 +File system hierarchy. +.It Xr hostname 7 +Hostname resolution rules. +.It Xr library-specs 7 +Shared library name specifications. +.It Xr man 7 +Man language reference. +.It Xr mandoc_char 7 +Mandoc special characters. +.It Xr mdoc 7 +Mdoc language reference. +.It Xr mirroring-ports 7 +How to build a mirror for ports distfiles. +.It Xr operator 7 +C operator precedence. +.It Xr packages 7 +Overview of the binary package system. +.It Xr packages-specs 7 +Binary package names specifications. +.It Xr pkgpath 7 +Ports tree location for a package build. +.It Xr ports 7 +Contributed applications. +.It Xr re_format 7 +POSIX regular expressions. +.It Xr roff 7 +Roff language reference for +.Xr mandoc 1 . +.It Xr script 7 +Interpreter script execution. +.It Xr securelevel 7 +The securelevel kernel state and its effects. +.It Xr sndio 7 +Interface to audio and MIDI. +.It Xr symlink 7 +Symbolic link handling. +.It Xr tbl 7 +Tbl language reference for +.Xr mandoc 1 . +.It Xr term 7 +Conventions for naming terminal types. +.El +.Sh HISTORY +An +.Nm +manual for section 7 appeared in +.Bx 4.2 . diff --git a/static/openbsd/man7/library-specs.7 b/static/openbsd/man7/library-specs.7 new file mode 100644 index 00000000..e0d82d62 --- /dev/null +++ b/static/openbsd/man7/library-specs.7 @@ -0,0 +1,150 @@ +.\" $OpenBSD: library-specs.7,v 1.13 2018/07/09 15:34:10 jmc Exp $ +.\" +.\" Copyright (c) 2001-2010 Marc Espie +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: July 9 2018 $ +.Dt LIBRARY-SPECS 7 +.Os +.Sh NAME +.Nm library-specs +.Nd shared library name specifications +.Sh DESCRIPTION +Each +.Ev WANTLIB +item in the ports tree conforms to +.Bd -literal -offset indent +[path/]libname[=major[.minor]] +.Ed +.Pp +or +.Bd -literal -offset indent +[path/]libname[>=major[.minor]] +.Ed +.Pp +All libraries that a package needs must be mentioned in that list. +Except for system and X11 libraries, they all must be reachable through +.Ev LIB_DEPENDS +and +.Ev RUN_DEPENDS , +directly, or indirectly through recursive dependencies. +.Pp +Conversely, the ports tree +uses +.Ev WANTLIB +to check whether a given +.Ev LIB_DEPENDS +will be required at runtime for shared libraries, and thus turn it into a +.Cm @depend +line +.Po +see +.Xr pkg_create 1 +.Pc . +.Pp +The package system will embed correct dependency checks in the built +package in the form of +.Cm @wantlib +lines, according to the normal shared library semantics: any library with +the same major number, and a greater or equal minor number will do. +.Pp +Note that static libraries can only satisfy a library specification if +no shared library has been found. +Thus, if WANTLIB = foo>=5, and both libfoo.so.4.0 and libfoo.a are present, +the check will fail. +.Pp +Therefore, porters must strive to respect correct shared library semantics +in their own ports: by bumping the minor number each time the interface is +augmented, and by bumping the major number each time the interface changes. +Note that adding functions to a library is an interface augmentation. +Removing functions is an interface change. +.Pp +The major.minor components of the library specification are used only as a +build-time check, the run-time checks are computed by +.Xr port-resolve-lib-helper 1 . +For +.Sq libname>=major[.minor] , +any library which is more recent than the given major.minor version will +do. +If a specific major number is needed, use the form +.Sq libname=major[.minor] . +If the minor component is left empty, any minor will do. +If both components are left empty, any version will do. +.Pp +Most specifications won't mention a +.Pa path : +.Xr port-resolve-lib-helper 1 +will look in the default +.Xr ldconfig 8 +path automatically, namely +.Pa /usr/local/lib , +.Pa /usr/X11R6/lib , +.Pa /usr/lib . +It is generally a bad idea to put libraries elsewhere as they won't be +reached directly. +.Pp +However, distinct ports may install different major versions of the same +library in +.Pa /usr/local/lib , +and disambiguate the build by creating a link in a separate directory, +and specifying the right options to the linker. +.Pp +These libraries will require a +.Pa path +component in the corresponding +.Ev WANTLIB +to make sure the right library is resolved. +This path is rooted under +.Pa /usr/local . +For instance, to refer to +.Pa /usr/local/lib/qt3/libqt-mt.so.33.0 , +one would use +.Sq lib/qt3/qt-mt>=33 . +.Sh SEE ALSO +.Xr check-lib-depends 1 , +.Xr ld 1 , +.Xr ld.so 1 , +.Xr pkg_add 1 , +.Xr port-resolve-lib-helper 1 , +.Xr bsd.port.mk 5 , +.Xr packages 7 , +.Xr packages-specs 7 , +.Xr ports 7 , +.Xr ldconfig 8 +.Sh HISTORY +Full support for library specifications first appeared in +.Ox 3.1 . +The format of specifications changed slightly to include +.Sq >= +before +.Ox 4.0 . +The interactions between +.Ev LIB_DEPENDS +and +.Ev WANTLIB +were modified and clarified for +.Ox 4.8 . +The format of specifications changed again before +.Ox 4.9 +to remove extra noise. diff --git a/static/openbsd/man7/man.7 b/static/openbsd/man7/man.7 new file mode 100644 index 00000000..f3942ad3 --- /dev/null +++ b/static/openbsd/man7/man.7 @@ -0,0 +1,672 @@ +.\" $OpenBSD: man.7,v 1.67 2025/11/03 09:59:05 bentley Exp $ +.\" +.\" Copyright (c) 2011-2015, 2017-2020, 2023, 2025 +.\" Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2017 Anthony J. Bentley <bentley@openbsd.org> +.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: November 3 2025 $ +.Dt MAN 7 +.Os +.Sh NAME +.Nm man +.Nd legacy formatting language for manual pages +.Sh DESCRIPTION +The +.Nm man +language was the standard formatting language for +.At +manual pages from 1979 to 1989. +Do not use it to write new manual pages: it is a purely presentational +language and lacks support for semantic markup. +Use the +.Xr mdoc 7 +language, instead. +.Pp +In a +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It usually consists of two capital letters. +For a list of portable macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.SH Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 7 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +.Pp +Each +.Nm +document starts with the +.Ic TH +macro specifying the document's name and section, followed by the +.Sx NAME +section formatted as follows: +.Bd -literal -offset indent +\&.TH PROGNAME 1 1979-01-10 +\&.SH NAME +\efBprogname\efR \e(en one line about what it does +.Ed +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together. +Deprecated and non-portable macros are not included in the overview, +but can be found in the alphabetical reference below. +.Ss Page header and footer meta-data +.Bl -column "RS, RE" description +.It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume +.It Ic AT Ta display AT&T UNIX version in the page footer (<= 2 arguments) +.It Ic UC Ta display BSD version in the page footer (<= 1 argument) +.El +.Ss Sections and paragraphs +.Bl -column "RS, RE" description +.It Ic SH Ta section header (one line) +.It Ic SS Ta subsection header (one line) +.It Ic PP Ta start an undecorated paragraph (no arguments) +.It Ic IP Ta indented paragraph: Op Ar head Op Ar width +.It Ic TP Ta tagged paragraph: Op Ar width +.It Ic HP Ta hanged paragraph: Op Ar width +.It Ic PD Ta set vertical paragraph distance: Op Ar height +.It Ic EX , EE Ta display an example (no arguments) +.It Ic RS , RE Ta reset the left margin: Op Ar width +.It Ic in Ta additional indent: Op Ar width +.El +.Ss Physical markup +.Bl -column "RS, RE" description +.It Ic B Ta boldface font +.It Ic I Ta italic font +.It Ic SB Ta small boldface font +.It Ic SM Ta small roman font +.It Ic BI Ta alternate between boldface and italic fonts +.It Ic BR Ta alternate between boldface and roman fonts +.It Ic IB Ta alternate between italic and boldface fonts +.It Ic IR Ta alternate between italic and roman fonts +.It Ic RB Ta alternate between roman and boldface fonts +.It Ic RI Ta alternate between roman and italic fonts +.El +.Sh MACRO REFERENCE +This section is a canonical reference to all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Bl -tag -width 3n +.It Ic AT +Sets the volume for the footer for compatibility with man pages from +.At +releases. +The optional arguments specify which release it is from. +This macro is an extension that first appeared in +.Bx 4.3 . +.It Ic B +Text is rendered in bold face. +.It Ic BI +Text is rendered alternately in bold face and italic. +Thus, +.Sq .BI this word and that +causes +.Sq this +and +.Sq and +to render in bold face, while +.Sq word +and +.Sq that +render in italics. +Whitespace between arguments is omitted in output. +.Pp +Example: +.Pp +.Dl \&.BI bold italic bold italic +.It Ic BR +Text is rendered alternately in bold face and roman (the default font). +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic DT +Restore the default tabulator positions. +They are at intervals of 0.5 inches. +This has no effect unless the tabulator positions were changed with the +.Xr roff 7 +.Ic ta +request. +.It Ic EE +End an example block started with +.Ic EX . +This is a Version 9 +.At +extension later adopted by GNU. +In +.Xr mandoc 1 , +it does the same as the +.Xr roff 7 +.Ic fi +request (switch to fill mode). +.It Ic EX +Begin a block to display an example. +This is a Version 9 +.At +extension later adopted by GNU. +In +.Xr mandoc 1 , +it does the same as the +.Xr roff 7 +.Ic nf +request (switch to no-fill mode). +.It Ic HP +Begin a paragraph whose initial output line is left-justified, but +subsequent output lines are indented, with the following syntax: +.Pp +.D1 Pf . Ic HP Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If specified, it's saved for later paragraph left margins; +if unspecified, the saved or default width is used. +.It Ic I +Text is rendered in italics. +.It Ic IB +Text is rendered alternately in italics and bold face. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic IP +Begin an indented paragraph with the following syntax: +.Pp +.D1 Pf . Ic IP Op Ar head Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width defining the left margin. +It's saved for later paragraph left-margins; if unspecified, the saved or +default width is used. +.Pp +The +.Ar head +argument is used as a leading term, flushed to the left margin. +This is useful for bulleted paragraphs and so on. +.It Ic IR +Text is rendered alternately in italics and roman (the default font). +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic LP +A synonym for +.Ic PP . +.It Ic ME +End a mailto block started with +.Ic MT . +This is a GNU extension. +.It Ic MR +Reference another manual page. +This is a Plan 9 extension also supported by GNU. +It has the following syntax: +.Pp +.D1 Pf . Ic MR Ar name section Op Ar suffix +.Pp +The optional, single +.Ar suffix +argument is appended without preceding whitespace +and typically used for trailing punctuation. +.It Ic MT +Begin a mailto block. +This is a GNU extension. +It has the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic MT Ar address +link description to be shown +.Pf . Ic ME +.Ed +.It Ic OP +Optional command-line argument. +This is a deprecated GNU extension. +The name and purpose of the macro match an earlier DWB extension, +but both the syntax and semantics are incompatible. +In GNU and +.Xr mandoc 1 , +it has the following syntax: +.Pp +.D1 Pf . Ic OP Ar key Op Ar value +.Pp +The +.Ar key +is usually a command-line flag and +.Ar value +its argument. +.It Ic P +This synonym for +.Ic PP +is an +.At III +extension later adopted by +.Bx 4.3 . +.It Ic PD +Specify the vertical space to be inserted before each new paragraph. +.br +The syntax is as follows: +.Pp +.D1 Pf . Ic PD Op Ar height +.Pp +The +.Ar height +argument is a +.Xr roff 7 +scaling width. +It defaults to +.Cm 1v . +If the unit is omitted, +.Cm v +is assumed. +.Pp +This macro affects the spacing before any subsequent instances of +.Ic HP , +.Ic IP , +.Ic LP , +.Ic P , +.Ic PP , +.Ic SH , +.Ic SS , +.Ic SY , +and +.Ic TP . +.It Ic PP +Begin an undecorated paragraph. +The scope of a paragraph is closed by a subsequent paragraph, +sub-section, section, or end of file. +The saved paragraph left-margin width is reset to the default. +.It Ic RB +Text is rendered alternately in roman (the default font) and bold face. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic RE +Explicitly close out the scope of a prior +.Ic RS . +The default left margin is restored to the state before that +.Ic RS +invocation. +.Pp +The syntax is as follows: +.Pp +.D1 Pf . Ic RE Op Ar level +.Pp +Without an argument, the most recent +.Ic RS +block is closed out. +If +.Ar level +is 1, all open +.Ic RS +blocks are closed out. +Otherwise, +.Ar level No \(mi 1 +nested +.Ic RS +blocks remain open. +.It Ic RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic RS +Temporarily reset the default left margin. +This has the following syntax: +.Pp +.D1 Pf . Ic RS Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If not specified, the saved or default width is used. +.Pp +See also +.Ic RE . +.It Ic SB +Text is rendered in small size (one point smaller than the default font) +bold face. +This macro is an extension that probably first appeared in SunOS 4.0 +and was later adopted by GNU and by +.Bx 4.4 . +.It Ic SH +Begin a section. +The scope of a section is only closed by another section or the end of +file. +The paragraph left-margin width is reset to the default. +.It Ic SM +Text is rendered in small size (one point smaller than the default +font). +.It Ic SS +Begin a sub-section. +The scope of a sub-section is closed by a subsequent sub-section, +section, or end of file. +The paragraph left-margin width is reset to the default. +.It Ic SY +Begin a synopsis block with the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic SY Ar command +.Ar arguments +.Pf . Ic YS +.Ed +.Pp +This is a GNU extension and rarely used even in GNU manual pages. +Formatting is similar to +.Ic IP . +.It Ic TH +Set the name of the manual page for use in the page header +and footer with the following syntax: +.Pp +.D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume +.Pp +Conventionally, the document +.Ar name +is given in all caps. +The +.Ar section +is usually a single digit, in a few cases followed by a letter. +The recommended +.Ar date +format is +.Sy YYYY-MM-DD +as specified in the ISO-8601 standard; +if the argument does not conform, it is printed verbatim. +If the +.Ar date +is empty or not specified, the current date is used. +The optional +.Ar source +string specifies the organisation providing the utility. +When unspecified, +.Xr mandoc 1 +uses its +.Fl Ios +argument. +The +.Ar volume +string replaces the default volume title of the +.Ar section . +.Pp +Examples: +.Pp +.Dl \&.TH CVS 5 "1992-02-12" GNU +.It Ic TP +Begin a paragraph where the head, if exceeding the indentation width, is +followed by a newline; if not, the body follows on the same line after +advancing to the indentation width. +Subsequent output lines are indented. +The syntax is as follows: +.Bd -unfilled -offset indent +.Pf . Ic TP Op Ar width +.Ar head No \e" one line +.Ar body +.Ed +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.It Ic TQ +Like +.Ic TP , +except that no vertical spacing is inserted before the paragraph. +This is a GNU extension. +.It Ic UC +Sets the volume for the footer for compatibility with man pages from +.Bx +releases. +The optional first argument specifies which release it is from. +This macro is an extension that first appeared in +.Bx 3 . +.It Ic UE +End a uniform resource identifier block started with +.Ic UR . +This is a GNU extension. +.It Ic UR +Begin a uniform resource identifier block. +This is a GNU extension. +It has the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic UR Ar uri +link description to be shown +.Pf . Ic UE +.Ed +.It Ic YS +End a synopsis block started with +.Ic SY . +This is a GNU extension. +.It Ic in +Indent relative to the current indentation: +.Pp +.D1 Pf . Ic in Op Ar width +.Pp +If +.Ar width +is signed, the new offset is relative. +Otherwise, it is absolute. +This value is reset upon the next paragraph, section, or sub-section. +.El +.Sh MACRO SYNTAX +The +.Nm +macros are classified by scope: line scope or block scope. +Line macros are only scoped to the current line (and, in some +situations, the subsequent line). +Block macros are scoped to the current line and subsequent lines until +closed by another block macro. +.Ss Line Macros +Line macros are generally scoped to the current line, with the body +consisting of zero or more arguments. +If a macro is scoped to the next line and the line arguments are empty, +the next line, which must be text, is used instead. +Thus: +.Bd -literal -offset indent +\&.I +foo +.Ed +.Pp +is equivalent to +.Sq .I foo . +If next-line macros are invoked consecutively, only the last is used. +If a next-line macro is followed by a non-next-line macro, an error is +raised. +.Pp +The syntax is as follows: +.Bd -literal -offset indent +\&.\e" current-line syntax +\&.YO \(lBbody ...\(rB + +\&.\e" next-line syntax +\&.YO +body ... +.Ed +.Bl -column -offset indent\ + "Macro" "Arguments" "curr and next" "Version 9 AT&T UNIX" +.It Em Macro Ta Em Arguments Ta Em Line Scope Ta Em Notes +.It Ic AT Ta 0 to 2 Ta current Ta \& +.It Ic B Ta 1 or more Ta curr or next Ta \& +.It Ic BI Ta 2 or more Ta current Ta \& +.It Ic BR Ta 2 or more Ta current Ta \& +.It Ic DT Ta 0 Ta none Ta \& +.It Ic EE Ta 0 Ta none Ta Version 9 At +.It Ic EX Ta 0 Ta none Ta Version 9 At +.It Ic I Ta 1 or more Ta curr or next Ta \& +.It Ic IB Ta 2 or more Ta current Ta \& +.It Ic IR Ta 2 or more Ta current Ta \& +.It Ic MR Ta 2 or 3 Ta current Ta Plan 9 +.It Ic OP Ta 1 or 2 Ta current Ta GNU +.It Ic PD Ta 0 or 1 Ta current Ta \& +.It Ic RB Ta 2 or more Ta current Ta \& +.It Ic RI Ta 2 or more Ta current Ta \& +.It Ic SB Ta 1 or more Ta curr or next Ta \& +.It Ic SM Ta 1 or more Ta curr or next Ta \& +.It Ic TH Ta 3 to 5 Ta current Ta \& +.It Ic UC Ta 0 or 1 Ta current Ta \& +.It Ic in Ta 0 or 1 Ta current Ta Xr roff 7 +.El +.Ss Block Macros +Block macros comprise a head and body. +As with in-line macros, the head is scoped to the current line or, +for some macros, to the next line (the next-line stipulations as in +.Sx Line Macros +apply here as well). +.Pp +The syntax is as follows: +.Bd -literal -offset indent +\&.\e" current-line syntax +\&.YO \(lBhead ...\(rB +body ... +\&... + +\&.\e" next-line syntax +\&.YO \(lBhead\(rB +head ... +body ... +\&... +.Ed +.Pp +The closure of body scope may be to the section, where a macro is closed +by +.Ic SH ; +sub-section, closed by a section or +.Ic SS ; +paragraph, closed by a section, sub-section, +.Ic HP , +.Ic IP , +.Ic LP , +.Ic P , +.Ic PP , +.Ic RS , +.Ic SY , +.Ic TP , +or +.Ic TQ ; +or to an explicit block closing macro. +.Pp +As a rule, block macros may not be nested; thus, calling a block macro +while another block macro scope is open, and the open scope is not +implicitly closed, is syntactically incorrect. +.Bl -column -offset indent\ + "Macro" "Arguments" "curr and next" "sub-section" "Notes" +.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes +.It Ic HP Ta 0 or 1 Ta current Ta paragraph Ta \& +.It Ic IP Ta 0 to 2 Ta current Ta paragraph Ta \& +.It Ic LP Ta 0 Ta none Ta paragraph Ta \& +.It Ic ME Ta 0 or 1 Ta current Ta none Ta GNU +.It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU +.It Ic P Ta 0 Ta none Ta paragraph Ta \& +.It Ic PP Ta 0 Ta none Ta paragraph Ta \& +.It Ic RE Ta 0 or 1 Ta current Ta none Ta \& +.It Ic RS Ta 0 or 1 Ta current Ta to \&RE Ta \& +.It Ic SH Ta 1 or more Ta curr or next Ta section Ta \& +.It Ic SS Ta 1 or more Ta curr or next Ta sub-section Ta \& +.It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU +.It Ic TP Ta 0 or 1 Ta curr and next Ta paragraph Ta \& +.It Ic TQ Ta 0 or 1 Ta curr and next Ta paragraph Ta GNU +.It Ic UE Ta 0 or 1 Ta current Ta none Ta GNU +.It Ic UR Ta 1 Ta current Ta to \&UE Ta GNU +.It Ic YS Ta 0 Ta none Ta none Ta GNU +.El +.Pp +If a block macro is next-line scoped, it may only be followed by in-line +macros for decorating text. +.Ss Font handling +In +.Nm +documents, both +.Sx Physical markup +macros and +.Xr roff 7 +.Ql \ef +font escape sequences can be used to choose fonts. +In text lines, the effect of manual font selection by escape sequences +only lasts until the next macro invocation; in macro lines, it only lasts +until the end of the macro scope. +Note that macros like +.Ic BR +open and close a font scope for each argument. +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 +.Sh HISTORY +The +.Nm +language first appeared as a macro package for the roff typesetting +system in +.At v7 . +.Pp +The stand-alone implementation that is part of the +.Xr mandoc 1 +utility first appeared in +.Ox 4.6 . +.Sh AUTHORS +.An -nosplit +.An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu +designed and implemented the original version of these macros, +wrote the original version of this manual page, +and was the first to use them when he edited volume 1 of the +.At v7 +manual pages. +.Pp +.An James Clark +later rewrote the macros for groff. +.An Eric S. Raymond Aq Mt esr@thyrsus.com +and +.An Werner Lemberg Aq Mt wl@gnu.org +added the extended +.Nm +macros to groff in 2007. +.Pp +The +.Xr mandoc 1 +program and this +.Nm +reference were written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/openbsd/man7/mandoc_char.7 b/static/openbsd/man7/mandoc_char.7 new file mode 100644 index 00000000..178302c6 --- /dev/null +++ b/static/openbsd/man7/mandoc_char.7 @@ -0,0 +1,834 @@ +.\" $OpenBSD: mandoc_char.7,v 1.44 2022/06/02 14:49:25 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-2020, 2022 +.\" 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" 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 2022 $ +.Dt MANDOC_CHAR 7 +.Os +.Sh NAME +.Nm mandoc_char +.Nd mandoc special characters +.Sh DESCRIPTION +This page documents the +.Xr roff 7 +escape sequences accepted by +.Xr mandoc 1 +to represent special characters in +.Xr mdoc 7 +and +.Xr man 7 +documents. +.Pp +The rendering depends on the +.Xr mandoc 1 +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 , +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 (\(hy), +the en-dash (\(en), +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; +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 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. +If it is important that the word is not broken across lines in this +way, a zero-width space +.Pq Sq \e& +can be inserted before or after the hyphen. +While +.Xr mandoc 1 +never breaks the output line after hyphens adjacent to a zero-width +space, after any of the other dash- or hyphen-like characters +represented by escape sequences, or after hyphens inside words in +macro arguments, other software may not respect these rules and may +break the line even in such cases. +.Pp +Some +.Xr roff 7 +implementations contains dictionaries allowing to break the line +at syllable boundaries even inside words that contain no hyphens. +Such automatic hyphenation is not supported by +.Xr mandoc 1 , +which only breaks the line at whitespace, and inside words only +after existing hyphens. +.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, output lines may be broken between words, i.e. at space +characters. +To prevent a line break between two particular words, +use the unpaddable 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; +see the MACRO SYNTAX section in +.Xr roff 7 . +In some cases, using the non-breaking space escape sequence +.Pq Sq \e\ \& +may be preferable. +.Pp +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 Accents +In output modes supporting such special output characters, for example +.Fl T Cm pdf , +and sometimes less consistently in +.Fl T Cm utf8 , +some +.Xr roff 7 +formatters convert the following ASCII input characters to the +following Unicode special output characters: +.Bl -column x(ga U+2018 -offset indent +.It \(ga Ta U+2018 Ta left single quotation mark +.It \(aq Ta U+2019 Ta right single quotation mark +.It \(ti Ta U+02DC Ta small tilde +.It \(ha Ta U+02C6 Ta modifier letter circumflex +.El +.Pp +In prose, this automatic substitution is often desirable; +but when these characters have to be displayed as plain ASCII +characters, for example in source code samples, they require +escaping to render as follows: +.Bl -column x(ga U+2018 -offset indent +.It \e(ga Ta U+0060 Ta grave accent +.It \e(aq Ta U+0027 Ta apostrophe +.It \e(ti Ta U+007E Ta tilde +.It \e(ha Ta U+005E Ta circumflex accent +.El +.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 character pair +.Sq \e. +to escape a period because +.Sq \e. +is not a character escape sequence, does not prevent special handling +of the period under normal circumstances, and is only intended to +be used in the very special situation of defining a user-defined +macro that, when called, defines another user-defined macro, which +no manual page is ever supposed to do. +.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 +.Pq for a one-character escape , +.Sq \e(XX +.Pq two-character , +and +.Sq \e[N] +.Pq N-character . +For details, see the +.Em Special Characters +subsection of the +.Xr roff 7 +manual. +.Pp +Spaces, non-breaking unless stated otherwise: +.Bl -column "Input" "Description" -offset indent -compact +.It Em Input Ta Em Description +.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: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.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 +.It \e(rs Ta \(rs Ta backward slash +.El +.Pp +Text markers: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ci Ta \(ci Ta circle +.It \e(bu Ta \(bu Ta bullet +.It \e(dd Ta \(dd Ta double dagger +.It \e(dg Ta \(dg Ta dagger +.It \e(lz Ta \(lz Ta lozenge +.It \e(sq Ta \(sq Ta white square +.It \e(ps Ta \(ps Ta paragraph +.It \e(sc Ta \(sc Ta section +.It \e(lh Ta \(lh Ta left hand +.It \e(rh Ta \(rh Ta right hand +.It \e(at Ta \(at Ta at +.It \e(sh Ta \(sh Ta hash (pound) +.It \e(CR Ta \(CR Ta carriage return +.It \e(OK Ta \(OK Ta check mark +.It \e(CL Ta \(CL Ta club suit +.It \e(SP Ta \(SP Ta spade suit +.It \e(HE Ta \(HE Ta heart suit +.It \e(DI Ta \(DI Ta diamond suit +.El +.Pp +Legal symbols: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(co Ta \(co Ta copyright +.It \e(rg Ta \(rg Ta registered +.It \e(tm Ta \(tm Ta trademarked +.El +.Pp +Punctuation: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(em Ta \(em Ta em-dash +.It \e(en Ta \(en Ta en-dash +.It \e(hy Ta \(hy Ta hyphen +.It \ee Ta \e Ta back-slash +.It \e(r! Ta \(r! Ta upside-down exclamation +.It \e(r? Ta \(r? Ta upside-down question +.El +.Pp +Quotes: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.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 single-quote +.It \e(lq Ta \(lq Ta left double-quote +.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 (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 +.It \e(fc Ta \(fc Ta right single guillemet +.El +.Pp +Brackets: +.Bl -column "xxbracketrightbtx" Rendered Description -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(lB Ta \(lB Ta left bracket +.It \e(rB Ta \(rB Ta right bracket +.It \e(lC Ta \(lC Ta left brace +.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 (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 +.It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension +.It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket +.It \e[bracketrightbt] Ta \[bracketrightbt] Ta bottom-right hooked bracket +.It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension +.It \e(lt Ta \(lt Ta top-left hooked brace +.It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace +.It \e(lk Ta \(lk Ta mid-left hooked brace +.It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace +.It \e(lb Ta \(lb Ta bottom-left hooked brace +.It \e[braceleftbt] Ta \[braceleftbt] Ta bottom-left hooked brace +.It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension +.It \e(rt Ta \(rt Ta top-left hooked brace +.It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace +.It \e(rk Ta \(rk Ta mid-right hooked brace +.It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace +.It \e(rb Ta \(rb Ta bottom-right hooked brace +.It \e[bracerightbt] Ta \[bracerightbt] Ta bottom-right hooked brace +.It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension +.It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis +.It \e[parenleftbt] Ta \[parenleftbt] Ta bottom-left hooked parenthesis +.It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension +.It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis +.It \e[parenrightbt] Ta \[parenrightbt] Ta bottom-right hooked parenthesis +.It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension +.El +.Pp +Arrows: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(<- Ta \(<- Ta left arrow +.It \e(-> Ta \(-> Ta right arrow +.It \e(<> Ta \(<> Ta left-right arrow +.It \e(da Ta \(da Ta down arrow +.It \e(ua Ta \(ua Ta up arrow +.It \e(va Ta \(va Ta up-down arrow +.It \e(lA Ta \(lA Ta left double-arrow +.It \e(rA Ta \(rA Ta right double-arrow +.It \e(hA Ta \(hA Ta left-right double-arrow +.It \e(uA Ta \(uA Ta up double-arrow +.It \e(dA Ta \(dA Ta down double-arrow +.It \e(vA Ta \(vA Ta up-down double-arrow +.It \e(an Ta \(an Ta horizontal arrow extension +.El +.Pp +Logical: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.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[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 +.It \e(tf Ta \(tf Ta therefore +.It \e(3d Ta \(3d Ta therefore +.It \e(or Ta \(or Ta bitwise or +.El +.Pp +Mathematical: +.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.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[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[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[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 +.It \e(>= Ta \(>= Ta greater-than-equal +.It \e(<< Ta \(<< Ta much less +.It \e(>> Ta \(>> Ta much greater +.It \e(eq Ta \(eq Ta equal +.It \e(!= Ta \(!= Ta not equal +.It \e(== Ta \(== Ta equivalent +.It \e(ne Ta \(ne Ta not equivalent +.It \e(ap Ta \(ap Ta tilde operator +.It \e(|= Ta \(|= Ta asymptotically equal +.It \e(=\(ti Ta \(=~ Ta approximately equal +.It \e(\(ti\(ti Ta \(~~ Ta almost equal +.It \e(\(ti= Ta \(~= Ta almost equal +.It \e(pt Ta \(pt Ta proportionate +.It \e(es Ta \(es Ta empty set +.It \e(mo Ta \(mo Ta element +.It \e(nm Ta \(nm Ta not element +.It \e(sb Ta \(sb Ta proper subset +.It \e(nb Ta \(nb Ta not subset +.It \e(sp Ta \(sp Ta proper superset +.It \e(nc Ta \(nc Ta not superset +.It \e(ib Ta \(ib Ta reflexive subset +.It \e(ip Ta \(ip Ta reflexive superset +.It \e(ca Ta \(ca Ta intersection +.It \e(cu Ta \(cu Ta union +.It \e(/_ Ta \(/_ Ta angle +.It \e(pp Ta \(pp Ta perpendicular +.It \e(is Ta \(is Ta integral +.It \e[integral] Ta \[integral] Ta integral +.It \e[sum] Ta \[sum] Ta summation +.It \e[product] Ta \[product] Ta product +.It \e[coproduct] Ta \[coproduct] Ta coproduct +.It \e(gr Ta \(gr Ta gradient +.It \e(sr Ta \(sr Ta square root +.It \e[sqrt] Ta \[sqrt] Ta square root +.It \e(lc Ta \(lc Ta left-ceiling +.It \e(rc Ta \(rc Ta right-ceiling +.It \e(lf Ta \(lf Ta left-floor +.It \e(rf Ta \(rf Ta right-floor +.It \e(if Ta \(if Ta infinity +.It \e(Ah Ta \(Ah Ta aleph +.It \e(Im Ta \(Im Ta imaginary +.It \e(Re Ta \(Re Ta real +.It \e(wp Ta \(wp Ta Weierstrass p +.It \e(pd Ta \(pd Ta partial differential +.It \e(-h Ta \(-h Ta Planck constant over 2\(*p +.It \e[hbar] Ta \[hbar] 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 +.It \e(18 Ta \(18 Ta one-eighth +.It \e(38 Ta \(38 Ta three-eighths +.It \e(58 Ta \(58 Ta five-eighths +.It \e(78 Ta \(78 Ta seven-eighths +.It \e(S1 Ta \(S1 Ta superscript 1 +.It \e(S2 Ta \(S2 Ta superscript 2 +.It \e(S3 Ta \(S3 Ta superscript 3 +.El +.Pp +Ligatures: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ff Ta \(ff Ta ff ligature +.It \e(fi Ta \(fi Ta fi ligature +.It \e(fl Ta \(fl Ta fl ligature +.It \e(Fi Ta \(Fi Ta ffi ligature +.It \e(Fl Ta \(Fl Ta ffl ligature +.It \e(AE Ta \(AE Ta AE +.It \e(ae Ta \(ae Ta ae +.It \e(OE Ta \(OE Ta OE +.It \e(oe Ta \(oe Ta oe +.It \e(ss Ta \(ss Ta German eszett +.It \e(IJ Ta \(IJ Ta IJ ligature +.It \e(ij Ta \(ij Ta ij ligature +.El +.Pp +Accents: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(a" Ta \(a" Ta Hungarian umlaut +.It \e(a- Ta \(a- Ta macron +.It \e(a. Ta \(a. Ta dotted +.It \e(a^ Ta \(a^ Ta circumflex +.It \e(aa Ta \(aa Ta acute +.It \e\(aq Ta \' Ta acute +.It \e(ga Ta \(ga Ta grave +.It \e\(ga Ta \` Ta grave +.It \e(ab Ta \(ab Ta breve +.It \e(ac Ta \(ac Ta cedilla +.It \e(ad Ta \(ad Ta dieresis +.It \e(ah Ta \(ah Ta caron +.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 (ASCII character) +.It \e(ti Ta \(ti Ta tilde (ASCII character) +.El +.Pp +Accented letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.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(\(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 +.It \e(\(gaO Ta \(`O Ta grave O +.It \e(\(gaU Ta \(`U Ta grave U +.It \e(\(gaa Ta \(`a Ta grave a +.It \e(\(gae Ta \(`e Ta grave e +.It \e(\(gai Ta \(`i Ta grave i +.It \e(\(gao Ta \(`i Ta grave o +.It \e(\(gau Ta \(`u Ta grave u +.It \e(\(tiA Ta \(~A Ta tilde A +.It \e(\(tiN Ta \(~N Ta tilde N +.It \e(\(tiO Ta \(~O Ta tilde O +.It \e(\(tia Ta \(~a Ta tilde a +.It \e(\(tin Ta \(~n Ta tilde n +.It \e(\(tio Ta \(~o Ta tilde o +.It \e(:A Ta \(:A Ta dieresis A +.It \e(:E Ta \(:E Ta dieresis E +.It \e(:I Ta \(:I Ta dieresis I +.It \e(:O Ta \(:O Ta dieresis O +.It \e(:U Ta \(:U Ta dieresis U +.It \e(:a Ta \(:a Ta dieresis a +.It \e(:e Ta \(:e Ta dieresis e +.It \e(:i Ta \(:i Ta dieresis i +.It \e(:o Ta \(:o Ta dieresis o +.It \e(:u Ta \(:u Ta dieresis u +.It \e(:y Ta \(:y Ta dieresis y +.It \e(^A Ta \(^A Ta circumflex A +.It \e(^E Ta \(^E Ta circumflex E +.It \e(^I Ta \(^I Ta circumflex I +.It \e(^O Ta \(^O Ta circumflex O +.It \e(^U Ta \(^U Ta circumflex U +.It \e(^a Ta \(^a Ta circumflex a +.It \e(^e Ta \(^e Ta circumflex e +.It \e(^i Ta \(^i Ta circumflex i +.It \e(^o Ta \(^o Ta circumflex o +.It \e(^u Ta \(^u Ta circumflex u +.It \e(,C Ta \(,C Ta cedilla C +.It \e(,c Ta \(,c Ta cedilla c +.It \e(/L Ta \(/L Ta stroke L +.It \e(/l Ta \(/l Ta stroke l +.It \e(/O Ta \(/O Ta stroke O +.It \e(/o Ta \(/o Ta stroke o +.It \e(oA Ta \(oA Ta ring A +.It \e(oa Ta \(oa Ta ring a +.El +.Pp +Special letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(-D Ta \(-D Ta Eth +.It \e(Sd Ta \(Sd Ta eth +.It \e(TP Ta \(TP Ta Thorn +.It \e(Tp Ta \(Tp Ta thorn +.It \e(.i Ta \(.i Ta dotless i +.It \e(.j Ta \(.j Ta dotless j +.El +.Pp +Currency: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Do Ta \(Do Ta dollar +.It \e(ct Ta \(ct Ta cent +.It \e(Eu Ta \(Eu Ta Euro symbol +.It \e(eu Ta \(eu Ta Euro symbol +.It \e(Ye Ta \(Ye Ta yen +.It \e(Po Ta \(Po Ta pound +.It \e(Cs Ta \(Cs Ta Scandinavian +.It \e(Fn Ta \(Fn Ta florin +.El +.Pp +Units: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(de Ta \(de Ta degree +.It \e(%0 Ta \(%0 Ta per-thousand +.It \e(fm Ta \(fm Ta minute +.It \e(sd Ta \(sd Ta second +.It \e(mc Ta \(mc Ta micro +.It \e(Of Ta \(Of Ta Spanish female ordinal +.It \e(Om Ta \(Om Ta Spanish masculine ordinal +.El +.Pp +Greek letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(*A Ta \(*A Ta Alpha +.It \e(*B Ta \(*B Ta Beta +.It \e(*G Ta \(*G Ta Gamma +.It \e(*D Ta \(*D Ta Delta +.It \e(*E Ta \(*E Ta Epsilon +.It \e(*Z Ta \(*Z Ta Zeta +.It \e(*Y Ta \(*Y Ta Eta +.It \e(*H Ta \(*H Ta Theta +.It \e(*I Ta \(*I Ta Iota +.It \e(*K Ta \(*K Ta Kappa +.It \e(*L Ta \(*L Ta Lambda +.It \e(*M Ta \(*M Ta Mu +.It \e(*N Ta \(*N Ta Nu +.It \e(*C Ta \(*C Ta Xi +.It \e(*O Ta \(*O Ta Omicron +.It \e(*P Ta \(*P Ta Pi +.It \e(*R Ta \(*R Ta Rho +.It \e(*S Ta \(*S Ta Sigma +.It \e(*T Ta \(*T Ta Tau +.It \e(*U Ta \(*U Ta Upsilon +.It \e(*F Ta \(*F Ta Phi +.It \e(*X Ta \(*X Ta Chi +.It \e(*Q Ta \(*Q Ta Psi +.It \e(*W Ta \(*W Ta Omega +.It \e(*a Ta \(*a Ta alpha +.It \e(*b Ta \(*b Ta beta +.It \e(*g Ta \(*g Ta gamma +.It \e(*d Ta \(*d Ta delta +.It \e(*e Ta \(*e Ta epsilon +.It \e(*z Ta \(*z Ta zeta +.It \e(*y Ta \(*y Ta eta +.It \e(*h Ta \(*h Ta theta +.It \e(*i Ta \(*i Ta iota +.It \e(*k Ta \(*k Ta kappa +.It \e(*l Ta \(*l Ta lambda +.It \e(*m Ta \(*m Ta mu +.It \e(*n Ta \(*n Ta nu +.It \e(*c Ta \(*c Ta xi +.It \e(*o Ta \(*o Ta omicron +.It \e(*p Ta \(*p Ta pi +.It \e(*r Ta \(*r Ta rho +.It \e(*s Ta \(*s Ta sigma +.It \e(*t Ta \(*t Ta tau +.It \e(*u Ta \(*u Ta upsilon +.It \e(*f Ta \(*f Ta phi +.It \e(*x Ta \(*x Ta chi +.It \e(*q Ta \(*q Ta psi +.It \e(*w Ta \(*w Ta omega +.It \e(+h Ta \(+h Ta theta variant +.It \e(+f Ta \(+f Ta phi variant +.It \e(+p Ta \(+p Ta pi variant +.It \e(+e Ta \(+e Ta epsilon variant +.It \e(ts Ta \(ts Ta sigma terminal +.El +.Sh PREDEFINED STRINGS +Predefined strings are inherited from the macro packages of historical +troff implementations. +They are +.Em not recommended +for use, as they differ across implementations. +Manuals using these predefined strings are almost certainly not +portable. +.Pp +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 . +.Bl -column "Input" "Rendered" "Description" -offset indent +.It Em Input Ta Em Rendered Ta Em Description +.It \e*(Ba Ta \*(Ba Ta vertical bar +.It \e*(Ne Ta \*(Ne Ta not equal +.It \e*(Ge Ta \*(Ge Ta greater-than-equal +.It \e*(Le Ta \*(Le Ta less-than-equal +.It \e*(Gt Ta \*(Gt Ta greater-than +.It \e*(Lt Ta \*(Lt Ta less-than +.It \e*(Pm Ta \*(Pm Ta plus-minus +.It \e*(If Ta \*(If Ta infinity +.It \e*(Pi Ta \*(Pi Ta pi +.It \e*(Na Ta \*(Na Ta NaN +.It \e*(Am Ta \*(Am Ta ampersand +.It \e*R Ta \*R Ta restricted mark +.It \e*(Tm Ta \*(Tm Ta trade mark +.It \e*q Ta \*q Ta double-quote +.It \e*(Rq Ta \*(Rq Ta right-double-quote +.It \e*(Lq Ta \*(Lq Ta left-double-quote +.It \e*(lp Ta \*(lp Ta right-parenthesis +.It \e*(rp Ta \*(rp Ta left-parenthesis +.It \e*(lq Ta \*(lq Ta left double-quote +.It \e*(rq Ta \*(rq Ta right double-quote +.It \e*(ua Ta \*(ua Ta up arrow +.It \e*(va Ta \*(va Ta up-down arrow +.It \e*(<= Ta \*(<= Ta less-than-equal +.It \e*(>= Ta \*(>= Ta greater-than-equal +.It \e*(aa Ta \*(aa Ta acute +.It \e*(ga Ta \*(ga Ta grave +.It \e*(Px Ta \*(Px Ta POSIX standard name +.It \e*(Ai Ta \*(Ai Ta ANSI standard name +.El +.Sh UNICODE CHARACTERS +The escape sequences +.Pp +.Dl \e[uXXXX] and \eC\(aquXXXX\(aq +.Pp +are interpreted as Unicode codepoints. +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. +.Sh NUMBERED CHARACTERS +For backward compatibility with existing manuals, +.Xr mandoc 1 +also supports the +.Pp +.Dl \eN\(aq Ns Ar number Ns \(aq and \e[ Ns Cm char Ns Ar number ] +.Pp +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; +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 +This section documents compatibility between mandoc and other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . +.Pp +.Bl -dash -compact +.It +The \eN\(aq\(aq escape sequence is limited to printable characters; in +groff, it accepts arbitrary character numbers. +.It +In +.Fl T Ns Cm ascii , +the +\e(ss, \e(nm, \e(nb, \e(nc, \e(ib, \e(ip, \e(pp, \e[sum], \e[product], +\e[coproduct], \e(gr, \e(-h, and \e(a. special characters render +differently between mandoc and groff. +.It +In +.Fl T Ns Cm html , +the \e(\(ti=, \e(nb, and \e(nc special characters render differently +between mandoc and groff. +.It +The +.Fl T Ns Cm ps +and +.Fl T Ns Cm pdf +modes format like +.Fl T Ns Cm ascii +instead of rendering glyphs as in groff. +.It +The \e[radicalex], \e[sqrtex], and \e(ru special characters have been omitted +from mandoc either because they are poorly documented or they have no +known representation. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Sh AUTHORS +The +.Nm +manual page was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.Sh CAVEATS +The predefined string +.Sq \e*(Ba +mimics the behaviour of the +.Sq \&| +character in +.Xr mdoc 7 ; +thus, if you wish to render a vertical bar with no side effects, use +the +.Sq \e(ba +escape. diff --git a/static/openbsd/man7/mdoc.7 b/static/openbsd/man7/mdoc.7 new file mode 100644 index 00000000..f9f2c7f3 --- /dev/null +++ b/static/openbsd/man7/mdoc.7 @@ -0,0 +1,3294 @@ +.\" $OpenBSD: mdoc.7,v 1.192 2025/08/19 14:08:41 schwarze Exp $ +.\" +.\" Copyright (c) 2010-2021, 2024, 2025 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 19 2025 $ +.Dt MDOC 7 +.Os +.Sh NAME +.Nm mdoc +.Nd semantic markup language for formatting manual pages +.Sh DESCRIPTION +The +.Nm mdoc +language supports authoring of manual pages for the +.Xr man 1 +utility by allowing semantic annotations of words, phrases, +page sections and complete manual pages. +Such annotations are used by formatting tools to achieve a uniform +presentation across all manuals written in +.Nm , +and to support hyperlinking if supported by the output medium. +.Pp +This reference document describes the structure of manual pages +and the syntax and usage of the +.Nm +language. +The reference implementation of a parsing and formatting tool is +.Xr mandoc 1 ; +the +.Sx COMPATIBILITY +section describes compatibility with other implementations. +.Pp +In an +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It consists of two or three letters. +Most macro names begin with a capital letter. +For a list of available macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro, optionally +including the names of other, callable macros; see +.Sx MACRO SYNTAX +for details. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.Sh Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 7 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +However, using +.Xr roff 7 +requests in +.Nm +documents is discouraged; +.Xr mandoc 1 +supports some of them merely for backward compatibility. +.Sh MANUAL STRUCTURE +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. +.Pp +The prologue, which consists of the +.Ic \&Dd , +.Ic \&Dt , +and +.Ic \&Os +macros in that order, is required for every document. +.Pp +The first section (sections are denoted by +.Ic \&Sh ) +must be the NAME section, consisting of at least one +.Ic \&Nm +followed by +.Ic \&Nd . +.Pp +Following that, convention dictates specifying at least the +.Em SYNOPSIS +and +.Em DESCRIPTION +sections, although this varies between manual sections. +.Pp +The following is a well-formed skeleton +.Nm +file for a utility +.Qq progname : +.Bd -literal -offset indent +\&.Dd $\&Mdocdate$ +\&.Dt PROGNAME section +\&.Os +\&.Sh NAME +\&.Nm progname +\&.Nd one line about what it does +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, and 9 only. +\&.\e\(dq Not used in OpenBSD. +\&.Sh SYNOPSIS +\&.Nm progname +\&.Op Fl options +\&.Ar +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\(dq .Sh CONTEXT +\&.\e\(dq For section 9 functions only. +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq Not used in OpenBSD. +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, and 9 function return values only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 6, 7, and 8 only. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 6, and 8 only. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +\&.\e\(dq .Sh SECURITY CONSIDERATIONS +\&.\e\(dq Not used in OpenBSD. +.Ed +.Pp +The sections in an +.Nm +document are conventionally ordered as they appear above. +Sections should be composed as follows: +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a one line description of the documented material. +The syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 , +\&.Nm name1 , +\&.Nm name2 +\&.Nd a one line description +.Ed +.Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp +The +.Ic \&Nm +macro(s) must precede the +.Ic \&Nd +macro. +.Pp +See +.Ic \&Nm +and +.Ic \&Nd . +.It Em LIBRARY +The name of the library containing the documented functions. +Using this section is no longer recommended. +If any +.Ic \&Lb +macro is needed, put it at the beginning of the +.Em SYNOPSIS +section instead. +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +Commands should be ordered alphabetically. +.Pp +For the second, function calls (sections 2, 3, 9): +.Bd -literal -offset indent +\&.Lb libname \e" unless the functions are in libc +\&.In header.h +\&.Vt extern const char *global; +\&.Ft char * +\&.Fn foo "const char *src" +\&.Ft char * +\&.Fn bar "const char *src" +.Ed +.Pp +Ordering of +.Ic \&In , +.Ic \&Vt , +.Ic \&Fn , +and +.Ic \&Fo +macros should follow C header-file conventions. +.Pp +And for the third, configurations (section 4): +.Bd -literal -offset indent +\&.Cd \(dqit* at isa? port 0x2e\(dq +\&.Cd \(dqit* at isa? port 0x4e\(dq +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.Pp +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Ic \&Nm , +.Ic \&Cd , +.Ic \&Fd , +.Ic \&Fn , +.Ic \&Fo , +.Ic \&In , +.Ic \&Vt , +and +.Ic \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pairwise invoked (except for +.Ic \&Ft +before +.Ic \&Fo +or +.Ic \&Fn ) , +they are separated by a vertical space, unless in the case of +.Ic \&Fo , +.Ic \&Fn , +and +.Ic \&Ft , +which are always separated by vertical space. +.Pp +When text and macros following an +.Ic \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Ic \&Nm +macro, up to the next +.Ic \&Nm , +.Ic \&Sh , +or +.Ic \&Ss +macro or the end of an enclosing block, whichever comes first. +.It Em DESCRIPTION +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The options are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +.Pp +List the options in alphabetical order, +uppercase before lowercase for each letter and +with no regard to whether an option takes an argument. +Put digits in ascending order before all letter options. +.Pp +Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Ic \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Ic \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. +.It Em CONTEXT +This section lists the contexts in which functions can be called in section 9. +The contexts are autoconf, process, or interrupt. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. +This is useful when implementing standard functions that may have side +effects or notable algorithmic implications. +.It Em RETURN VALUES +This section documents the +return values of functions in sections 2, 3, and 9. +.Pp +See +.Ic \&Rv . +.It Em ENVIRONMENT +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 7 +manual provides examples of typical content and formatting. +.Pp +See +.Ic \&Ev . +.It Em FILES +Documents files used. +It's helpful to document both the file name and a short description of how +the file is used (created, modified, etc.). +.Pp +See +.Ic \&Pa . +.It Em EXIT STATUS +This section documents the +command exit status for section 1, 6, and 8 utilities. +Historically, this information was described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Ic \&Ex . +.It Em EXAMPLES +Example usages. +This often contains snippets of well-formed, well-tested invocations. +Make sure that examples work properly! +.It Em DIAGNOSTICS +Documents error messages. +In section 4 and 9 manuals, these are usually messages printed by the +kernel to the console and to the kernel log. +In section 1, 6, 7, and 8, these are usually messages printed by +userland programs to the standard error output. +.Pp +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +.Pp +See +.Ic \&Bl +.Fl diag . +.It Em ERRORS +Documents +.Xr errno 2 +settings in sections 2, 3, 4, and 9. +.Pp +See +.Ic \&Er . +.It Em SEE ALSO +References other manuals with related topics. +This section should exist for most manuals. +Cross-references should conventionally be ordered first by section, then +alphabetically (ignoring case). +.Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp +See +.Ic \&Rs +and +.Ic \&Xr . +.It Em STANDARDS +References any standards implemented or used. +If not adhering to any standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Ic \&St . +.It Em HISTORY +A brief history of the subject, including where it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. +.It Em AUTHORS +Credits to the person or persons who wrote the code and/or documentation. +Authors should generally be noted by both name and email address. +.Pp +See +.Ic \&An . +.It Em CAVEATS +Common misuses and misunderstandings should be explained +in this section. +.It Em BUGS +Known bugs, limitations, and work-arounds should be described +in this section. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +.El +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together, to help find the best macro for any given purpose. +Deprecated macros are not included in the overview, but can be found below +in the alphabetical +.Sx MACRO REFERENCE . +.Ss Document preamble and NAME section macros +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year +.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch +.It Ic \&Os Ta operating system footer: Op Ar footer text +.It Ic \&Nm Ta document name (one argument) +.It Ic \&Nd Ta document description (one line) +.El +.Ss Sections and cross references +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Sh Ta section header (one line) +.It Ic \&Ss Ta subsection header (one line) +.It Ic \&Sx Ta internal cross reference to a section or subsection +.It Ic \&Xr Ta cross reference to another manual page: Ar name section +.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments +.It Ic \&Pp Ta start a text paragraph (no arguments) +.El +.Ss Displays and lists +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Bd , \&Ed Ta display block: +.Fl Ar type +.Op Fl offset Ar width +.Op Fl compact +.It Ic \&D1 Ta indented display (one line) +.It Ic \&Dl Ta indented literal display (one line) +.It Ic \&Ql Ta normal in-line literal display: Ql text +.It Ic \&Li Ta unquoted in-line literal display: Li text +.It Ic \&Bl , \&El Ta list block: +.Fl Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.It Ic \&It Ta list item (syntax depends on Fl Ar type ) +.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists +.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) +.El +.Ss Spacing control +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Pf Ta prefix, no following horizontal space (one argument) +.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) +.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) +.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off +.It Ic \&Bk , \&Ek Ta keep block: Fl words +.El +.Ss Semantic markup for command line utilities +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility +.It Ic \&Fl Ta command line options (flags) (>=0 arguments) +.It Ic \&Cm Ta command modifier (>0 arguments) +.It Ic \&Ar Ta command arguments (>=0 arguments) +.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) +.It Ic \&Ic Ta internal or interactive command (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.It Ic \&Pa Ta file system path (>=0 arguments) +.El +.Ss Semantic markup for function libraries +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Lb Ta function library (>0 arguments) +.It Ic \&In Ta include file (one argument) +.It Ic \&Fd Ta other preprocessor directive (>0 arguments) +.It Ic \&Ft Ta function type (>0 arguments) +.It Ic \&Fo , \&Fc Ta function block: Ar funcname +.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... +.It Ic \&Fa Ta function argument (>0 arguments) +.It Ic \&Vt Ta variable type (>0 arguments) +.It Ic \&Va Ta variable name (>0 arguments) +.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) +.It Ic \&Er Ta error constant (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.El +.Ss Various semantic markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&An Ta author name (>0 arguments) +.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name +.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain +.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) +.It Ic \&Ad Ta memory address (>0 arguments) +.It Ic \&Ms Ta mathematical symbol (>0 arguments) +.El +.Ss Physical markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) +.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) +.It Ic \&No Ta return to roman font (normal) (>0 arguments) +.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy +.El +.Ss Physical enclosures +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text +.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text +.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text +.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text +.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text +.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text +.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text +.It Ic \&Eo , \&Ec Ta generic enclosure +.El +.Ss Text production +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... +.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... +.It Ic \&St Ta reference to a standards document (one argument) +.It Ic \&At Ta At +.It Ic \&Bx Ta Bx +.It Ic \&Bsx Ta Bsx +.It Ic \&Nx Ta Nx +.It Ic \&Fx Ta Fx +.It Ic \&Ox Ta Ox +.It Ic \&Dx Ta Dx +.El +.Sh MACRO REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Bl -tag -width 3n +.It Ic \&%A Ar first_name ... last_name +Author name of an +.Ic \&Rs +block. +Multiple authors should each be accorded their own +.Ic \%%A +line. +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.It Ic \&%B Ar title +Book title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographic context when +referring to book titles. +.It Ic \&%C Ar location +Publication city or location of an +.Ic \&Rs +block. +.It Ic \&%D Oo Ar month day , Oc Ar year +Publication date of an +.Ic \&Rs +block. +Provide the full English name of the +.Ar month +and all four digits of the +.Ar year . +.It Ic \&%I Ar name +Publisher or issuer name of an +.Ic \&Rs +block. +.It Ic \&%J Ar name +Journal name of an +.Ic \&Rs +block. +.It Ic \&%N Ar number +Issue number (usually for journals) of an +.Ic \&Rs +block. +.It Ic \&%O Ar line +Optional information of an +.Ic \&Rs +block. +.It Ic \&%P Ar number +Book or journal page number of an +.Ic \&Rs +block. +Conventionally, the argument starts with +.Ql p.\& +for a single page or +.Ql pp.\& +for a range of pages, for example: +.Pp +.Dl .%P pp. 42\e(en47 +.It Ic \&%Q Ar name +Institutional author (school, government, etc.) of an +.Ic \&Rs +block. +Multiple institutional authors should each be accorded their own +.Ic \&%Q +line. +.It Ic \&%R Ar name +Technical report name of an +.Ic \&Rs +block. +.It Ic \&%T Ar title +Article title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographical context when +referring to article titles. +.It Ic \&%U Ar protocol Ns :// Ns Ar path +URI of reference document. +.It Ic \&%V Ar number +Volume number of an +.Ic \&Rs +block. +.It Ic \&Ac +Close an +.Ic \&Ao +block. +Does not have any tail arguments. +.Tg Ad +.It Ic \&Ad Ar address +Memory address. +Do not use this for postal addresses. +.Pp +Examples: +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 +.Tg An +.It Ic \&An Fl split | nosplit | Ar first_name ... last_name +Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. +Requires either the name of an author or one of the following arguments: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact +.It Fl split +Start a new output line before each subsequent invocation of +.Ic \&An . +.It Fl nosplit +The opposite of +.Fl split . +.El +.Pp +The default is +.Fl nosplit . +The effect of selecting either of the +.Fl split +modes ends at the beginning of the +.Em AUTHORS +section. +In the +.Em AUTHORS +section, the default is +.Fl nosplit +for the first author listing and +.Fl split +for all other author listings. +.Pp +Examples: +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.It Ic \&Ao Ar block +Begin a block enclosed by angle brackets. +Does not have any head arguments. +This macro is almost never useful. +See +.Ic \&Aq +for more details. +.Tg Ap +.It Ic \&Ap +Inserts an apostrophe without any surrounding whitespace. +This is generally used as a grammatical device when referring to the verb +form of a function. +.Pp +Examples: +.Dl \&.Fn execve \&Ap d +.Tg Aq +.It Ic \&Aq Ar line +Enclose the rest of the input line in angle brackets. +The only important use case is for email addresses. +See +.Ic \&Mt +for an example. +.Pp +Occasionally, it is used for names of characters and keys, for example: +.Bd -literal -offset indent +Press the +\&.Aq escape +key to ... +.Ed +.Pp +For URIs, use +.Ic \&Lk +instead, and +.Ic \&In +for +.Dq #include +directives. +Never wrap +.Ic \&Ar +in +.Ic \&Aq . +.Pp +Since +.Ic \&Aq +usually renders with non-ASCII characters in non-ASCII output modes, +do not use it where the ASCII characters +.Sq < +and +.Sq > +are required as syntax elements. +Instead, use these characters directly in such cases, combining them +with the macros +.Ic \&Pf , +.Ic \&Ns , +or +.Ic \&Eo +as needed. +.Pp +See also +.Ic \&Ao . +.Tg Ar +.It Ic \&Ar Op Ar placeholder ... +Command arguments. +If an argument is not provided, the string +.Dq file ...\& +is used as a default. +.Pp +Examples: +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Ic \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Ic \&Fl +or +.Ic \&Cm . +.Tg At +.It Ic \&At Op Ar version +Formats an +.At +version. +Accepts one optional argument: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact +.It Cm v[1-7] | 32v +A version of +.At . +.It Cm III +.At III . +.It Cm V | V.[1-4] +A version of +.At V . +.El +.Pp +Note that these arguments do not begin with a hyphen. +.Pp +Examples: +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 +.Pp +See also +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bc +Close a +.Ic \&Bo +block. +Does not have any tail arguments. +.Tg Bd +.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact +Begin a display block. +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and text lines. +By default, a display block is preceded by a vertical space. +.Pp +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Produce one output line from each input line, and center-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. +.It Fl filled +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. +.It Fl literal +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. +.It Fl ragged +Change the positions of line breaks to fill each line, and left-justify +the resulting block. +.It Fl unfilled +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. +.El +.Pp +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: +.Bl -item +.It +One of the pre-defined strings +.Cm indent , +the width of a standard indentation (six constant width characters); +.Cm indent-two , +twice +.Cm indent ; +.Cm left , +which has no effect; +.Cm right , +which justifies to the right margin; or +.Cm center , +which aligns around an imagined center axis. +.It +A macro invocation, which selects a predefined width +associated with that macro. +The most popular is the imaginary macro +.Ar \&Ds , +which resolves to +.Sy 6n . +.It +A scaling width as described in +.Xr roff 7 . +.It +An arbitrary string, which indents by the length of this string. +.El +.Pp +When the argument is missing, +.Fl offset +is ignored. +.It Fl compact +Do not assert vertical space before the display. +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent \-compact + Hello world. +\&.Ed +.Ed +.Pp +See also +.Ic \&D1 +and +.Ic \&Dl . +.Tg Bf +.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy +Change the font mode for a scoped block of text. +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy , +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Ic \&Ef +is encountered. +.Pp +See also +.Ic \&Li , +.Ic \&Ef , +.Ic \&Em , +and +.Ic \&Sy . +.Tg Bk +.It Ic \&Bk Fl words +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. +.Pp +The +.Fl words +argument is required; additional arguments are ignored. +.Pp +The following example will not break within each +.Ic \&Op +macro line: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op Fl f Ar flags +\&.Op Fl o Ar output +\&.Ek +.Ed +.Pp +Be careful in using over-long lines within a keep block! +Doing so will clobber the right margin. +.Tg Bl +.It Xo +.Ic \&Bl +.Fl Ns Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op Ar col ... +.Xc +Begin a list. +Lists consist of items specified using the +.Ic \&It +macro, containing a head or a body or both. +.Pp +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept macro names as described for +.Ic \&Bd +.Fl offset , +scaling widths as described in +.Xr roff 7 , +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp +The following list types are commonly used: +.Bl -tag -width 12n -offset indent +.It Fl bullet +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the +.Fl width +argument. +.It Fl column +A columnated list. +The +.Fl width +argument has no effect; instead, the string length of each argument +specifies the width of one column. +The width specification for the last column does not affect formatting. +.Pp +For two-column lists, using +.Fl tag +often results in simpler code, identical terminal output, and better HTML +output, especially when the first column contains short identifiers. +.Pp +For compatibility with legacy documents, if the first line of the body of a +.Fl column +list is not an +.Ic \&It +macro line, +.Ic \&It +contexts spanning one input line each are implied until an +.Ic \&It +macro line is encountered, at which point items start being interpreted as +described in the +.Ic \&It +documentation. +.It Fl dash +Like +.Fl bullet , +except that dashes are used in place of bullets. +.It Fl diag +Like +.Fl inset , +except that item heads are not parsed for macro invocations. +Most often used in the +.Em DIAGNOSTICS +section with error messages in the item heads. +.It Fl enum +A numbered list. +No item heads can be specified. +Formatted like +.Fl bullet , +except that ordinal numbers are used in place of bullets, +starting at 1. +.It Fl tag +Item bodies are indented according to the +.Fl width +argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. +.El +.Pp +The following list types are rarely useful: +.Bl -tag -width 12n -offset indent +.It Fl hang +Like +.Fl tag , +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl item +No item heads can be specified, and none are printed. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl ohang +Item bodies start on the line following item heads and are not indented. +The +.Fl width +argument is ignored. +.El +.Pp +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.Pp +See also +.Ic \&El +and +.Ic \&It . +.It Ic \&Bo Ar block +Begin a block enclosed by square brackets. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bo 1 , +\&.Dv BUFSIZ \&Bc +.Ed +.Pp +See also +.Ic \&Bq . +.Tg Bq +.It Ic \&Bq Ar line +Encloses its arguments in square brackets. +.Pp +Examples: +.Dl \&.Bq 1 , \&Dv BUFSIZ +.Pp +.Em Remarks : +this macro is sometimes abused to emulate optional arguments for +commands; the correct macros to use for this purpose are +.Ic \&Op , +.Ic \&Oo , +and +.Ic \&Oc . +.Pp +See also +.Ic \&Bo . +.It Ic \&Brc +Close a +.Ic \&Bro +block. +Does not have any tail arguments. +.It Ic \&Bro Ar block +Begin a block enclosed by curly braces. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bro 1 , ... , +\&.Va n \&Brc +.Ed +.Pp +See also +.Ic \&Brq . +.Tg Brq +.It Ic \&Brq Ar line +Encloses its arguments in curly braces. +.Pp +Examples: +.Dl \&.Brq 1 , ... , \&Va n +.Pp +See also +.Ic \&Bro . +.Tg Bsx +.It Ic \&Bsx Op Ar version +Format the +.Bsx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Bsx 1.0 +.Dl \&.Bsx +.Pp +See also +.Ic \&At , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bt +Supported only for compatibility, do not use this in new manuals. +Prints +.Dq is currently in beta test. +.Tg Bx +.It Ic \&Bx Op Ar version Op Ar variant +Format the +.Bx +version provided as an argument, or a default value if no +argument is provided. +.Pp +Examples: +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.Tg Cd +.It Ic \&Cd Ar line +Kernel configuration declaration. +This denotes strings accepted by +.Xr config 8 . +It is most often used in section 4 manual pages. +.Pp +Examples: +.Dl \&.Cd device le0 at scode? +.Pp +.Em Remarks : +this macro is commonly abused by using quoted literals to retain +whitespace and align consecutive +.Ic \&Cd +declarations. +This practise is discouraged. +.Tg Cm +.It Ic \&Cm Ar keyword ... +Command modifiers. +Typically used for fixed strings passed as arguments to interactive +commands, to commands in interpreted scripts, or to configuration +file directives, unless +.Ic \&Fl +is more appropriate. +.Pp +Examples: +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Ic set Fl o Cm vi" +.Dl ".Ic lookup Cm file bind" +.Dl ".Ic permit Ar identity Op Cm as Ar target" +.Tg D1 +.It Ic \&D1 Ar line +One-line indented display. +This is formatted by the default rules and is useful for simple indented +statements. +It is followed by a newline. +.Pp +Examples: +.Dl \&.D1 \&Fl abcdefgh +.Pp +See also +.Ic \&Bd +and +.Ic \&Dl . +.It Ic \&Db +This macro is obsolete. +No replacement is needed. +It is ignored by +.Xr mandoc 1 +and groff including its arguments. +It was formerly used to toggle a debugging mode. +.It Ic \&Dc +Close a +.Ic \&Do +block. +Does not have any tail arguments. +.Tg Dd +.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year +Document date for display in the page footer, +by convention the date of the last change. +This is the mandatory first macro of any +.Nm +manual. +.Pp +The +.Ar month +is the full English month name, the +.Ar day +is an integer number, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of +.Xr cvs 1 , +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +The traditional, purely numeric +.Xr man 7 +format +.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day +is accepted, too. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El +.Pp +Examples: +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 2 2018$ +.Dl \&.Dd July 2, 2018 +.Pp +See also +.Ic \&Dt +and +.Ic \&Os . +.Tg Dl +.It Ic \&Dl Ar line +One-line indented literal display. +This is formatted using a constant-width font +and is useful for commands and invocations. +It is followed by a newline. +.Pp +Examples: +.Dl \&.Dl % mandoc mdoc.7 \e(ba less +.Pp +See also +.Ic \&Ql , +.Ic \&Bd Fl literal , +and +.Ic \&D1 . +.It Ic \&Do Ar block +Begin a block enclosed by double quotes. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Do +April is the cruellest month +\&.Dc +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Dq . +.Tg Dq +.It Ic \&Dq Ar line +Encloses its arguments in +.Dq typographic +double-quotes. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Dq April is the cruellest month +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Qq , +.Ic \&Sq , +and +.Ic \&Do . +.Tg Dt +.It Ic \&Dt Ar TITLE section Op Ar arch +Document title for display in the page header. +This is the mandatory second macro of any +.Nm +file. +.Pp +Its arguments are as follows: +.Bl -tag -width section -offset 2n +.It Ar TITLE +The document's title (name), defaulting to +.Dq UNTITLED +if unspecified. +To achieve a uniform appearance of page header lines, +it should by convention be all caps. +.It Ar section +The manual section. +This may be one of +.Cm 1 +.Pq General Commands , +.Cm 2 +.Pq System Calls , +.Cm 3 +.Pq Library Functions , +.Cm 3p +.Pq Perl Library , +.Cm 4 +.Pq Device Drivers , +.Cm 5 +.Pq File Formats , +.Cm 6 +.Pq Games , +.Cm 7 +.Pq Miscellaneous Information , +.Cm 8 +.Pq System Manager's Manual , +or +.Cm 9 +.Pq Kernel Developer's Manual . +It should correspond to the manual's filename suffix and defaults to +the empty string if unspecified. +.It Ar arch +This specifies the machine architecture a manual page applies to, +where relevant. +For +.Ox , +the following are valid architectures: +.Cm alpha , +.Cm amd64 , +.Cm armv7 , +.Cm arm64 , +.Cm hppa , +.Cm i386 , +.Cm landisk , +.Cm loongson , +.Cm luna88k , +.Cm macppc , +.Cm mips64 , +.Cm octeon , +.Cm powerpc64 , +.Cm riscv64 , +and +.Cm sparc64 . +.El +.Pp +Examples: +.Dl \&.Dt FOO 1 +.Dl \&.Dt FOO 9 i386 +.Pp +See also +.Ic \&Dd +and +.Ic \&Os . +.Tg Dv +.It Ic \&Dv Ar identifier ... +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. +.Pp +Examples: +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO +.Pp +See also +.Ic \&Er +and +.Ic \&Ev +for special-purpose constants, +.Ic \&Va +for variable symbols, and +.Ic \&Fd +for listing preprocessor variable definitions in the +.Em SYNOPSIS . +.Tg Dx +.It Ic \&Dx Op Ar version +Format the +.Dx +version provided as an argument, or a default +value if no argument is provided. +.Pp +Examples: +.Dl \&.Dx 2.4.1 +.Dl \&.Dx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Ec Op Ar closing_delimiter +Close a scope started by +.Ic \&Eo . +.Pp +The +.Ar closing_delimiter +argument is used as the enclosure tail, for example, specifying \e(rq +will emulate +.Ic \&Dc . +.It Ic \&Ed +End a display context started by +.Ic \&Bd . +.It Ic \&Ef +End a font mode context started by +.Ic \&Bf . +.It Ic \&Ek +End a keep context started by +.Ic \&Bk . +.It Ic \&El +End a list context started by +.Ic \&Bl . +See also +.Ic \&It . +.Tg Em +.It Ic \&Em Ar word ... +Request an italic font. +If the output device does not provide that, underline. +.Pp +This is most often used for stress emphasis (not to be confused with +importance, see +.Ic \&Sy ) . +In the rare cases where none of the semantic markup macros fit, +it can also be used for technical terms and placeholders, except +that for syntax elements, +.Ic \&Sy +and +.Ic \&Ar +are preferred, respectively. +.Pp +Examples: +.Bd -literal -compact -offset indent +Selected lines are those +\&.Em not +matching any of the specified patterns. +Some of the functions use a +\&.Em hold space +to save the pattern space for subsequent retrieval. +.Ed +.Pp +See also +.Ic \&No , +.Ic \&Ql , +and +.Ic \&Sy . +.It Ic \&En Ar word ... +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It encloses its argument in the delimiters specified by the last +.Ic \&Es +macro. +.Tg Eo +.It Ic \&Eo Op Ar opening_delimiter +An arbitrary enclosure. +The +.Ar opening_delimiter +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Ic \&Do . +.Tg Er +.It Ic \&Er Ar identifier ... +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. +.Pp +Examples: +.Dl \&.Er EPERM +.Dl \&.Er ENOENT +.Pp +See also +.Ic \&Dv +for general constants. +.It Ic \&Es Ar opening_delimiter closing_delimiter +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It takes two arguments, defining the delimiters to be used by subsequent +.Ic \&En +macros. +.Tg Ev +.It Ic \&Ev Ar identifier ... +Environmental variables such as those specified in +.Xr environ 7 . +.Pp +Examples: +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Ic \&Dv +for general constants. +.Tg Ex +.It Ic \&Ex Fl std Op Ar utility ... +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1, 6, and 8 manual pages. +.Pp +If +.Ar utility +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar utility +arguments are treated as separate utilities. +.Pp +See also +.Ic \&Rv . +.Tg Fa +.It Ic \&Fa Ar argument ... +Function argument or parameter. +Each argument may be a name and a type (recommended for the +.Em SYNOPSIS +section), a name alone (for function invocations), +or a type alone (for function prototypes). +If both a type and a name are given or if the type consists of multiple +words, all words belonging to the same function argument have to be +given in a single argument to the +.Ic \&Fa +macro. +.Pp +This macro is also used to specify the field name of a structure. +.Pp +Most often, the +.Ic \&Fa +macro is used in the +.Em SYNOPSIS +within +.Ic \&Fo +blocks when documenting multi-line function prototypes. +If invoked with multiple arguments, the arguments are separated by a +comma. +Furthermore, if the following macro is another +.Ic \&Fa , +the last argument will also have a trailing comma. +.Pp +Examples: +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa \(dqchar *\(dq size_t +.Pp +See also +.Ic \&Fo . +.It Ic \&Fc +End a function context started by +.Ic \&Fo . +.Tg Fd +.It Ic \&Fd Pf # Ar directive Op Ar argument ... +Preprocessor directive, in particular for listing it in the +.Em SYNOPSIS . +Historically, it was also used to document include files. +The latter usage has been deprecated in favour of +.Ic \&In . +.Pp +Examples: +.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler +.Dl \&.Fd #define SIO_MAXNFDS +.Dl \&.Fd #ifdef FS_DEBUG +.Dl \&.Ft void +.Dl \&.Fn dbg_open \(dqconst char *\(dq +.Dl \&.Fd #endif +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&In , +and +.Ic \&Dv . +.Tg Fl +.It Ic \&Fl Op Ar word ... +Command-line flag or option. +Used when listing arguments to command-line utilities. +For each argument, prints an ASCII hyphen-minus character +.Sq \- , +immediately followed by the argument. +If no arguments are provided, a hyphen-minus is printed followed by a space. +If the argument is a macro, a hyphen-minus is prefixed +to the subsequent macro output. +.Pp +Examples: +.Dl ".Nm du Op Fl H | L | P" +.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Nm route Cm add Fl inet Ar destination gateway" +.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" +.Dl ".Nm aucat Fl o Fl" +.Dl ".Nm kill Fl Ar signal_number" +.Pp +For GNU-style long options, escaping the additional hyphen-minus is not +strictly required, but may be safer with future versions of GNU troff; see +.Xr mandoc_char 7 +for details. +.Pp +See also +.Ic \&Cm . +.Tg Fn +.It Ic \&Fn Ar funcname Op Ar argument ... +A function name. +.Pp +Function arguments are surrounded in parenthesis and +are delimited by commas. +If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. +.Pp +Examples: +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq +.Dl \&.Fn funcname arg0 +.Bd -literal -offset indent +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +When referring to a function documented in another manual page, use +.Ic \&Xr +instead. +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fo , +and +.Ic \&Ft . +.Tg Fo +.It Ic \&Fo Ar funcname +Begin a function block. +This is a multi-line version of +.Ic \&Fn . +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Ic \&Ft Ar functype +.br +.Pf \. Ic \&Fo Ar funcname +.br +.Pf \. Ic \&Fa Qq Ar argtype Ar argname +.br +\&.\.\. +.br +.Pf \. Ic \&Fc +.Ed +.Pp +A +.Ic \&Fo +scope is closed by +.Ic \&Fc . +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fa , +.Ic \&Fc , +and +.Ic \&Ft . +.It Ic \&Fr Ar number +This macro is obsolete. +No replacement markup is needed. +.Pp +It was used to show numerical function return values in an italic font. +.Tg Ft +.It Ic \&Ft Ar functype +A function type. +.Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp +Examples: +.Dl \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fn , +and +.Ic \&Fo . +.Tg Fx +.It Ic \&Fx Op Ar version +Format the +.Fx +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Fx 7.1 +.Dl \&.Fx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Hf Ar filename +This macro is not implemented in +.Xr mandoc 1 . +It was used to include the contents of a (header) file literally. +.Tg Ic +.It Ic \&Ic Ar keyword ... +Internal or interactive command, or configuration instruction +in a configuration file. +See also +.Ic \&Cm . +.Pp +Examples: +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias +.Pp +Note that using +.Ic \&Ql , +.Ic \&Dl , +or +.Ic \&Bd Fl literal +is preferred for displaying code samples; the +.Ic \&Ic +macro is used when referring to an individual command name. +.Tg In +.It Ic \&In Ar filename +The name of an include file. +This macro is most often used in section 2, 3, and 9 manual pages. +.Pp +When invoked as the first macro on an input line in the +.Em SYNOPSIS +section, the argument is displayed in angle brackets +and preceded by +.Qq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +In other sections, it only encloses its argument in angle brackets +and causes no line break. +.Pp +Examples: +.Dl \&.In sys/types.h +.Pp +See also +.Sx MANUAL STRUCTURE . +.Tg It +.It Ic \&It Op Ar head +A list item. +The syntax of this macro depends on the list type. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following syntax: +.Pp +.D1 Pf \. Ic \&It Ar args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following syntax: +.Pp +.D1 Pf \. Ic \&It +.Pp +with subsequent lines interpreted within the scope of the +.Ic \&It +until either a closing +.Ic \&El +or another +.Ic \&It . +.Pp +The +.Fl tag +list has the following syntax: +.Pp +.D1 Pf \. Ic \&It Op Cm args +.Pp +Subsequent lines are interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is as follows: +.Pp +.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... +.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... +.Pp +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by the special +.Ic \&Ta +block macro or by literal tab characters. +.Pp +Using literal tabs is strongly discouraged because they are very +hard to use correctly and +.Nm +code using them is very hard to read. +In particular, a blank character is syntactically significant +before and after the literal tab character. +If a word precedes or follows the tab without an intervening blank, +that word is never interpreted as a macro call, but always output +literally. +.Pp +The tab cell delimiter may only be used within the +.Ic \&It +line itself; on following lines, only the +.Ic \&Ta +macro can be used to delimit cells, and portability requires that +.Ic \&Ta +is called by other macros: some parsers do not recognize it when +it appears as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an +.Ic \&It +line. +For example, +.Pp +.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; +.Pp +will preserve the whitespace before both commas, +but not the whitespace before the semicolon. +.Pp +See also +.Ic \&Bl . +.Tg Lb +.It Ic \&Lb Cm lib Ns Ar name Op Cm lib Ns Ar name ... +Specify one or more libraries to link against. +Putting this macro at the beginning of the +.Em SYNOPSIS +section is recommended, in which case it prints this comment: +.D1 /* Fl l Ns Ar name Oo Fl l Ns Ar name ... Oc */ +.Pp +If used outside the +.Em SYNOPSIS , +this macro prints +.D1 library Dq Cm lib Ns Ar name +instead. +For system libraries, some operating systems +print a short library description. +.Pp +Example: +.Bd -literal -offset indent -compact +\&.Sh SYNOPSIS +\&.Lb libtls libssl libcrypto +\&.In tls.h +\&.Ft int +\&.Fn tls_init void +.Ed +.Tg Li +.It Ic \&Li Ar word ... +Unquoted in-line literal display, always set in a constant-width font. +In most cases, use +.Ic \&Ql +instead because on terminal output devices, +.Ic \&Li +is usually indistinguishable from normal text. +This macro is only useful when enclosing the argument in quotes +is explicitly not desired, for example because it already stands out +due to being wrapped in another macro, e.g. in an +.Ic \&It +head. +.Pp +For longer literal displays, use +.Ic \&Dl Pq single line +or +.Ic \&Bd Fl literal Pq multi-line +instead. +.Tg Lk +.It Ic \&Lk Ar uri Op Ar display_name +Format a hyperlink. +.Pp +Examples: +.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq +.Dl \&.Lk https://bsd.lv +.Pp +See also +.Ic \&Mt . +.It Ic \&Lp +Deprecated synonym for +.Ic \&Pp . +.Tg Ms +.It Ic \&Ms Ar name +Display a mathematical symbol. +.Pp +Examples: +.Dl \&.Ms sigma +.Dl \&.Ms aleph +.Tg Mt +.It Ic \&Mt Ar localpart Ns @ Ns Ar domain +Format a +.Dq mailto: +hyperlink. +.Pp +Examples: +.Dl \&.Mt discuss@manpages.bsd.lv +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.Tg Nd +.It Ic \&Nd Ar line +A one line description of the manual's content. +This is the mandatory last macro of the +.Em NAME +section and not appropriate for other sections. +.Pp +Examples: +.Dl Pf . Ic \&Nd mdoc language reference +.Dl Pf . Ic \&Nd format and display UNIX manuals +.Pp +The +.Ic \&Nd +macro technically accepts child macros and terminates with a subsequent +.Ic \&Sh +invocation. +Do not assume this behaviour: some +.Xr whatis 1 +database generators are not smart enough to parse more than the line +arguments and will display macros verbatim. +.Pp +See also +.Ic \&Nm . +.Tg Nm +.It Ic \&Nm Op Ar name +The name of the manual page, or \(em in particular in section 1, 6, +and 8 pages \(em of an additional command or feature documented in +the manual page. +When first invoked, the +.Ic \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Ic \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Ic \&Fn +macro rather than +.Ic \&Nm +to mark up the name of the manual page. +.Tg No +.It Ic \&No Ar word ... +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Ic \&Em +or +.Ic \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. +.Pp +Examples: +.Dl ".Em italic , Sy bold , No and roman" +.Bd -literal -offset indent +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&Ql , +and +.Ic \&Sy . +.Tg Ns +.It Ic \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Ic \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp +Examples: +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".Fl o Ns Ar output" +.Pp +See also +.Ic \&No +and +.Ic \&Sm . +.Tg Nx +.It Ic \&Nx Op Ar version +Format the +.Nx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Nx 5.01 +.Dl \&.Nx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Ox . +.It Ic \&Oc +Close multi-line +.Ic \&Oo +context. +.It Ic \&Oo Ar block +Multi-line version of +.Ic \&Op . +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Oo +\&.Op Fl flag Ns Ar value +\&.Oc +.Ed +.Tg Op +.It Ic \&Op Ar line +Optional part of a command line. +Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. +.Pp +Examples: +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b +.Pp +See also +.Ic \&Oo . +.Tg Os +.It Ic \&Os Op Ar footer text +The mandatory third macro of every +.Nm +file. +Usually, do not specify any arguments, +in particular not the operating system name and/or version. +.Pp +If no argument is given, +.Xr mandoc 1 +prints its +.Fl Ios +argument in the page footer, or +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 +by default. +.Pp +Manual pages that are part of a portable software project can override +the default by giving the project name and version number as arguments, +but leaving it blank is never a bad choice. +.Pp +See also +.Ic \&Dd +and +.Ic \&Dt . +.It Ic \&Ot Ar functype +This macro is obsolete. +Use +.Ic \&Ft +instead; with +.Xr mandoc 1 , +both have the same effect. +.Pp +Historical +.Nm +packages described it as +.Dq "old function type (FORTRAN)" . +.Tg Ox +.It Ic \&Ox Op Ar version +Format the +.Ox +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Ox 4.5 +.Dl \&.Ox +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Nx . +.Tg Pa +.It Ic \&Pa Ar name ... +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. +.Pp +Examples: +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man7/mdoc.7 +.Pp +See also +.Ic \&Lk . +.It Ic \&Pc +Close parenthesised context opened by +.Ic \&Po . +.Tg Pf +.It Ic \&Pf Ar prefix macro Op Ar argument ... +Removes the space between its argument and the following macro. +It is equivalent to: +.Pp +.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... +.Pp +The +.Ar prefix +argument is not parsed for macro names or delimiters, +but used verbatim as if it were escaped. +.Pp +Examples: +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf . Ar macro_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Ic \&Ns +and +.Ic \&Sm . +.It Ic \&Po Ar block +Multi-line version of +.Ic \&Pq . +.Tg Pp +.It Ic \&Pp +Break a paragraph. +This will assert vertical space between prior and subsequent macros +and/or text. +.Pp +Paragraph breaks are not needed before or after +.Ic \&Sh +or +.Ic \&Ss +macros or before displays +.Pq Ic \&Bd Ar line +or lists +.Pq Ic \&Bl +unless the +.Fl compact +flag is given. +.Tg Pq +.It Ic \&Pq Ar line +Parenthesised enclosure. +.Pp +See also +.Ic \&Po . +.It Ic \&Qc +Close quoted context opened by +.Ic \&Qo . +.Tg Ql +.It Ic \&Ql Ar line +Normal in-line literal display, always set in constant-width font and +additionally enclosed in quotes by many formatters in many cases. +This can be used for complete command invocations and for multi-word +code examples when an indented display is not desired. +.Pp +See also +.Ic \&Dl , +.Ic \&Bd +.Fl literal , +and +.Ic \&Li . +.It Ic \&Qo Ar block +Multi-line version of +.Ic \&Qq . +.Tg Qq +.It Ic \&Qq Ar line +Encloses its arguments in +.Qq typewriter +double-quotes. +Consider using +.Ic \&Dq . +.Pp +See also +.Ic \&Dq , +.Ic \&Sq , +and +.Ic \&Qo . +.It Ic \&Re +Close an +.Ic \&Rs +block. +Does not have any tail arguments. +.Tg Rs +.It Ic \&Rs +Begin a bibliographic +.Pq Dq reference +block. +Does not have any head arguments. +The block macro may only contain +.Ic \&%A , +.Ic \&%B , +.Ic \&%C , +.Ic \&%D , +.Ic \&%I , +.Ic \&%J , +.Ic \&%N , +.Ic \&%O , +.Ic \&%P , +.Ic \&%Q , +.Ic \&%R , +.Ic \&%T , +.Ic \&%U , +and +.Ic \&%V +child macros (at least one must be specified). +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusetts +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Ic \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Tg Rv +.It Ic \&Rv Fl std Op Ar function ... +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +.Pp +If +.Ar function +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. +.Pp +See also +.Ic \&Ex . +.It Ic \&Sc +Close single-quoted context opened by +.Ic \&So . +.Tg Sh +.It Ic \&Sh Ar TITLE LINE +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +Use the conventional sections where applicable. +For unusually long and complicated manual pages, +adding custom sections is occasionally useful. +.Pp +Avoid using macros inside the +.Ar TITLE LINE +and keep that line unique within the manual page, +such that it can be pointed to with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Ss , +and +.Ic \&Sx . +.Tg Sm +.It Ic \&Sm Op Cm on | off +Switches the spacing mode for output generated from macros. +.Pp +By default, spacing is +.Cm on . +When switched +.Cm off , +no white space is inserted between macro arguments and between the +output generated from adjacent macros, but text lines +still get normal spacing between words and sentences. +.Pp +When called without an argument, the +.Ic \&Sm +macro toggles the spacing mode. +Using this is not recommended because it makes the code harder to read. +.It Ic \&So Ar block +Multi-line version of +.Ic \&Sq . +.Tg Sq +.It Ic \&Sq Ar line +Encloses its arguments in +.Sq typewriter +single-quotes. +.Pp +See also +.Ic \&Dq , +.Ic \&Qq , +and +.Ic \&So . +.Tg Ss +.It Ic \&Ss Ar Title line +Begin a new subsection. +Unlike with +.Ic \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +the conventional sections described in +.Sx MANUAL STRUCTURE +rarely have subsections. +.Pp +Avoid using macros inside the +.Ar Title line +and keep that line unique within the manual page, +such that it can be pointed to with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Sh , +and +.Ic \&Sx . +.Tg St +.It Ic \&St Fl Ns Ar abbreviation +Replace an abbreviation for a standard with the full form. +The following standards are recognised. +Where multiple lines are given without a blank line in between, +they all refer to the same standard, and using the first form +is recommended. +.Bl -tag -width 1n +.It C language standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 +.It \-isoC +.St -isoC +.It \-isoC-90 +.St -isoC-90 +.br +The original C standard. +.Pp +.It \-isoC-amd1 +.St -isoC-amd1 +.Pp +.It \-isoC-tcor1 +.St -isoC-tcor1 +.Pp +.It \-isoC-tcor2 +.St -isoC-tcor2 +.Pp +.It \-isoC-99 +.St -isoC-99 +.br +Edition 2 of the C language standard. +.Pp +.It \-isoC-2011 +.St -isoC-2011 +.br +Edition 3 of the C language standard. +.Pp +.It \-isoC-2023 +.St -isoC-2023 +.br +Edition 5 of the C language standard. +.El +.It POSIX.1 before XPG4.2 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1 +.St -p1003.1 +.br +The original POSIX standard, based on ANSI C. +.Pp +.It \-p1003.1-90 +.St -p1003.1-90 +.It \-iso9945-1-90 +.St -iso9945-1-90 +.br +The first update of POSIX.1. +.Pp +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1b +.St -p1003.1b +.br +Real-time extensions. +.Pp +.It \-p1003.1c-95 +.St -p1003.1c-95 +.br +POSIX thread interfaces. +.Pp +.It \-p1003.1i-95 +.St -p1003.1i-95 +.br +Technical Corrigendum. +.Pp +.It \-p1003.1-96 +.St -p1003.1-96 +.It \-iso9945-1-96 +.St -iso9945-1-96 +.br +Includes POSIX.1-1990, 1b, 1c, and 1i. +.El +.It X/Open Portability Guide before XPG4.2 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-xpg3 +.St -xpg3 +.br +An XPG4 precursor, published in 1989. +.Pp +.It \-p1003.2 +.St -p1003.2 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.br +An XCU4 precursor. +.Pp +.It \-p1003.2a-92 +.St -p1003.2a-92 +.br +Updates to POSIX.2. +.Pp +.It \-xpg4 +.St -xpg4 +.br +Based on POSIX.1 and POSIX.2, published in 1992. +.El +.It X/Open Portability Guide Issue 4 Version 2 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv1 +.St -susv1 +.It \-xpg4.2 +.St -xpg4.2 +.br +This standard was published in 1994. +It was used as the basis for UNIX 95 certification. +The following two refer to parts of it. +.Pp +.It \-xcurses4.2 +.St -xcurses4.2 +.Pp +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.br +Networking APIs, including sockets. +.Pp +.It \-svid4 +.St -svid4 , +.br +Published in 1995. +.El +.It X/Open Portability Guide Issue 5 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv2 +.St -susv2 +.br +This Standard was published in 1997 +and is also called X/Open Portability Guide Issue 5. +It was used as the basis for UNIX 98 certification. +The following refer to parts of it. +.Pp +.It \-xbd5 +.St -xbd5 +.Pp +.It \-xsh5 +.St -xsh5 +.Pp +.It \-xcu5 +.St -xcu5 +.Pp +.It \-xns5 +.St -xns5 +.It \-xns5.2 +.St -xns5.2 +.El +.It POSIX Issue 6 +.Pp +.Bl -tag -width "-p1003.1-2001" -compact +.It \-p1003.1-2001 +.St -p1003.1-2001 +.It \-susv3 +.St -susv3 +.br +This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. +It is also called X/Open Portability Guide Issue 6. +It is used as the basis for UNIX 03 certification. +.Pp +.It \-p1003.1-2004 +.St -p1003.1-2004 +.br +The second and last Technical Corrigendum. +.El +.It POSIX Issues 7 and 8 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-susv4 +.St -susv4 +.br +This standard is based on C99. +It is also called the +Open Group Standard Base Specifications, Issue 7. +.El +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2024 +.St -p1003.1-2024 +.br +This standard is based on C17. +It is also called the +Open Group Standard Base Specifications, Issue 8. +.El +.It Other standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ieee754 +.St -ieee754 +.br +Floating-point arithmetic. +.Pp +.It \-iso8601 +.St -iso8601 +.br +Representation of dates and times, published in 1988. +.Pp +.It \-iso8802-3 +.St -iso8802-3 +.br +Ethernet local area networks. +.Pp +.It \-ieee1275-94 +.St -ieee1275-94 +.El +.El +.Tg Sx +.It Ic \&Sx Ar Title line +Reference a section or subsection in the same manual page. +The referenced section or subsection name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Ic \&Sh +and +.Ic \&Ss . +.Tg Sy +.It Ic \&Sy Ar word ... +Request a boldface font. +.Pp +This is most often used to indicate importance or seriousness (not to be +confused with stress emphasis, see +.Ic \&Em ) . +When none of the semantic macros fit, it is also adequate for syntax +elements that have to be given or that appear verbatim. +.Pp +Examples: +.Bd -literal -compact -offset indent +\&.Sy Warning : +If +\&.Sy s +appears in the owner permissions, set-user-ID mode is set. +This utility replaces the former +\&.Sy dumpdir +program. +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&No , +and +.Ic \&Ql . +.Tg Ta +.It Ic \&Ta +Table cell separator in +.Ic \&Bl Fl column +lists; can only be used below +.Ic \&It . +.Tg Tg +.It Ic \&Tg Op Ar term +Announce that the next input line starts a definition of the +.Ar term . +This macro must appear alone on its own input line. +The argument defaults to the first argument of the first macro +on the next line. +The argument may not contain whitespace characters, not even when it is quoted. +This macro is a +.Xr mandoc 1 +extension and is typically ignored by other formatters. +.Pp +When viewing terminal output with +.Xr less 1 , +the interactive +.Ic :t +command can be used to go to the definition of the +.Ar term +as described for the +.Ev MANPAGER +variable in +.Xr man 1 ; +when producing HTML output, a fragment identifier +.Pq Ic id No attribute +is generated, to be used for deep linking to this place of the document. +.Pp +In most cases, adding a +.Ic \&Tg +macro would be redundant because +.Xr mandoc 1 +is able to automatically tag most definitions. +This macro is intended for cases where automatic tagging of a +.Ar term +is unsatisfactory, for example if a definition is not tagged +automatically (false negative) or if places are tagged that do +not define the +.Ar term +(false positives). +When there is at least one +.Ic \&Tg +macro for a +.Ar term , +no other places are automatically marked as definitions of that +.Ar term . +.It Ic \&Tn Ar word ... +Supported only for compatibility, do not use this in new manuals. +Even though the macro name +.Pq Dq tradename +suggests a semantic function, historic usage is inconsistent, mostly +using it as a presentation-level macro to request a small caps font. +.It Ic \&Ud +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq currently under development. +.It Ic \&Ux +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq Ux . +.Tg Va +.It Ic \&Va Oo Ar type Oc Ar identifier ... +A variable name. +.Pp +Examples: +.Dl \&.Va foo +.Dl \&.Va const char *bar ; +.Pp +For function arguments and parameters, use +.Ic \&Fa +instead. +For declarations of global variables in the +.Em SYNOPSIS +section, use +.Ic \&Vt . +.Tg Vt +.It Ic \&Vt Ar type Op Ar identifier +A variable type. +.Pp +This is also used for indicating global variables in the +.Em SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro on an input line in the +.Em SYNOPSIS +section, else it accepts ordinary +.Sx In-line +syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. +.Pp +Examples: +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; +.Pp +For parameters in function prototypes, use +.Ic \&Fa +instead, for function return types +.Ic \&Ft , +and for variable names outside the +.Em SYNOPSIS +section +.Ic \&Va , +even when including a type with the name. +See also +.Sx MANUAL STRUCTURE . +.It Ic \&Xc +Close a scope opened by +.Ic \&Xo . +.It Ic \&Xo Ar block +Extend the header of an +.Ic \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 7 . +.Tg Xr +.It Ic \&Xr Ar name section +Link to another manual +.Pq Qq cross-reference . +.Pp +Cross reference the +.Ar name +and +.Ar section +number of another man page. +.Pp +Examples: +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour +.El +.Sh MACRO SYNTAX +The syntax of a macro depends on its classification. +In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. +.Pp +The +.Em Callable +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +.Pp +The +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. +.Pp +The +.Em Scope +column, if applicable, describes closure rules. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only +.Ic \&Bf +and +.Pq optionally +.Ic \&Bl +contain a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed +.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef +.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek +.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El +.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd +.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf +.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk +.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl +.El +.Ss Block full-implicit +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some +.Po +.Ic \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +don't have heads; only one +.Po +.Ic \&It +in +.Ic \&Bl Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El +.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh +.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss +.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh +.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss +.El +.Pp +Note that the +.Ic \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head +.Po +.Ic \&Fo , +.Ic \&Eo +.Pc +and/or tail +.Pq Ic \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao +.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac +.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo +.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc +.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro +.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc +.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do +.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc +.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo +.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec +.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo +.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc +.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo +.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc +.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po +.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc +.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo +.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc +.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs +.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re +.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So +.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc +.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo +.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc +.El +.Ss Block partial-implicit +Like block full-implicit, but with single-line scope closed by the +end of the line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed +.It Ic \&Aq Ta Yes Ta Yes +.It Ic \&Bq Ta Yes Ta Yes +.It Ic \&Brq Ta Yes Ta Yes +.It Ic \&D1 Ta \&No Ta \&Yes +.It Ic \&Dl Ta \&No Ta Yes +.It Ic \&Dq Ta Yes Ta Yes +.It Ic \&En Ta Yes Ta Yes +.It Ic \&Op Ta Yes Ta Yes +.It Ic \&Pq Ta Yes Ta Yes +.It Ic \&Ql Ta Yes Ta Yes +.It Ic \&Qq Ta Yes Ta Yes +.It Ic \&Sq Ta Yes Ta Yes +.It Ic \&Vt Ta Yes Ta Yes +.El +.Pp +Note that the +.Ic \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Special block macro +The +.Ic \&Ta +macro can only be used below +.Ic \&It +in +.Ic \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It +.El +.Ss In-line +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments +.It Ic \&%A Ta \&No Ta \&No Ta >0 +.It Ic \&%B Ta \&No Ta \&No Ta >0 +.It Ic \&%C Ta \&No Ta \&No Ta >0 +.It Ic \&%D Ta \&No Ta \&No Ta >0 +.It Ic \&%I Ta \&No Ta \&No Ta >0 +.It Ic \&%J Ta \&No Ta \&No Ta >0 +.It Ic \&%N Ta \&No Ta \&No Ta >0 +.It Ic \&%O Ta \&No Ta \&No Ta >0 +.It Ic \&%P Ta \&No Ta \&No Ta >0 +.It Ic \&%Q Ta \&No Ta \&No Ta >0 +.It Ic \&%R Ta \&No Ta \&No Ta >0 +.It Ic \&%T Ta \&No Ta \&No Ta >0 +.It Ic \&%U Ta \&No Ta \&No Ta >0 +.It Ic \&%V Ta \&No Ta \&No Ta >0 +.It Ic \&Ad Ta Yes Ta Yes Ta >0 +.It Ic \&An Ta Yes Ta Yes Ta >0 +.It Ic \&Ap Ta Yes Ta Yes Ta 0 +.It Ic \&Ar Ta Yes Ta Yes Ta n +.It Ic \&At Ta Yes Ta Yes Ta 1 +.It Ic \&Bsx Ta Yes Ta Yes Ta n +.It Ic \&Bt Ta \&No Ta \&No Ta 0 +.It Ic \&Bx Ta Yes Ta Yes Ta n +.It Ic \&Cd Ta Yes Ta Yes Ta >0 +.It Ic \&Cm Ta Yes Ta Yes Ta >0 +.It Ic \&Db Ta \&No Ta \&No Ta 1 +.It Ic \&Dd Ta \&No Ta \&No Ta n +.It Ic \&Dt Ta \&No Ta \&No Ta n +.It Ic \&Dv Ta Yes Ta Yes Ta >0 +.It Ic \&Dx Ta Yes Ta Yes Ta n +.It Ic \&Em Ta Yes Ta Yes Ta >0 +.It Ic \&Er Ta Yes Ta Yes Ta >0 +.It Ic \&Es Ta Yes Ta Yes Ta 2 +.It Ic \&Ev Ta Yes Ta Yes Ta >0 +.It Ic \&Ex Ta \&No Ta \&No Ta n +.It Ic \&Fa Ta Yes Ta Yes Ta >0 +.It Ic \&Fd Ta \&No Ta \&No Ta >0 +.It Ic \&Fl Ta Yes Ta Yes Ta n +.It Ic \&Fn Ta Yes Ta Yes Ta >0 +.It Ic \&Fr Ta Yes Ta Yes Ta >0 +.It Ic \&Ft Ta Yes Ta Yes Ta >0 +.It Ic \&Fx Ta Yes Ta Yes Ta n +.It Ic \&Hf Ta \&No Ta \&No Ta n +.It Ic \&Ic Ta Yes Ta Yes Ta >0 +.It Ic \&In Ta Yes Ta Yes Ta 1 +.It Ic \&Lb Ta \&No Ta \&No Ta >0 +.It Ic \&Li Ta Yes Ta Yes Ta >0 +.It Ic \&Lk Ta Yes Ta Yes Ta >0 +.It Ic \&Lp Ta \&No Ta \&No Ta 0 +.It Ic \&Ms Ta Yes Ta Yes Ta >0 +.It Ic \&Mt Ta Yes Ta Yes Ta >0 +.It Ic \&Nm Ta Yes Ta Yes Ta n +.It Ic \&No Ta Yes Ta Yes Ta >0 +.It Ic \&Ns Ta Yes Ta Yes Ta 0 +.It Ic \&Nx Ta Yes Ta Yes Ta n +.It Ic \&Os Ta \&No Ta \&No Ta n +.It Ic \&Ot Ta Yes Ta Yes Ta >0 +.It Ic \&Ox Ta Yes Ta Yes Ta n +.It Ic \&Pa Ta Yes Ta Yes Ta n +.It Ic \&Pf Ta Yes Ta Yes Ta 1 +.It Ic \&Pp Ta \&No Ta \&No Ta 0 +.It Ic \&Rv Ta \&No Ta \&No Ta n +.It Ic \&Sm Ta \&No Ta \&No Ta <2 +.It Ic \&St Ta \&No Ta Yes Ta 1 +.It Ic \&Sx Ta Yes Ta Yes Ta >0 +.It Ic \&Sy Ta Yes Ta Yes Ta >0 +.It Ic \&Tg Ta \&No Ta \&No Ta <2 +.It Ic \&Tn Ta Yes Ta Yes Ta >0 +.It Ic \&Ud Ta \&No Ta \&No Ta 0 +.It Ic \&Ux Ta Yes Ta Yes Ta n +.It Ic \&Va Ta Yes Ta Yes Ta n +.It Ic \&Vt Ta Yes Ta Yes Ta >0 +.It Ic \&Xr Ta Yes Ta Yes Ta 2 +.El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +Spacing is suppressed after opening delimiters +and before closing delimiters. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&.\& +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter, which does not suppress spacing: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. +.Pp +Appending a zero-width space +.Pq Sq \e& +to the end of an input line is also useful to prevent the interpretation +of a trailing period, exclamation or question mark as the end of a +sentence, for example when an abbreviation happens to occur +at the end of a text or macro input line. +.Ss Font handling +In +.Nm +documents, usage of semantic markup is recommended in order to have +proper fonts automatically selected; only when no fitting semantic markup +is available, consider falling back to +.Sx Physical markup +macros. +Whenever any +.Nm +macro switches the +.Xr roff 7 +font mode, it will automatically restore the previous font when exiting +its scope. +Manually switching the font using the +.Xr roff 7 +.Ql \ef +font escape sequences is never required. +.Sh COMPATIBILITY +This section provides an incomplete list of compatibility issues +between mandoc and GNU troff +.Pq Qq groff . +.Pp +The following problematic behaviour is found in groff: +.Pp +.Bl -dash -compact +.It +.Ic \&Pa +does not format its arguments when used in the FILES section under +certain list types. +.It +.Ic \&Ta +can only be called by other macros, but not at the beginning of a line. +.It +.Sq \ef +.Pq font face +and +.Sq \eF +.Pq font family face +.Sx Text Decoration +escapes behave irregularly when specified within line-macro scopes. +.It +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact +.It +.Ic \&Bd Fl file Ar file +is unsupported for security reasons. +.It +.Ic \&Bd +.Fl filled +does not adjust the right margin, but is an alias for +.Ic \&Bd +.Fl ragged . +.It +.Ic \&Bd +.Fl literal +does not use a literal font, but is an alias for +.Ic \&Bd +.Fl unfilled . +.It +.Ic \&Bd +.Fl offset Cm center +and +.Fl offset Cm right +don't work. +Groff does not implement centered and flush-right rendering either, +but produces large indentations. +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr roff 7 , +.Xr tbl 7 +.Pp +The web page +.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" +provides a few tutorial-style pages for beginners, an extensive style +guide for advanced authors, and an alphabetic index helping to choose +the best macros for various kinds of content. +.Pp +The manual page +.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)" +contained in the +.Dq groff +package documents exactly the same language in a somewhat different style. +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . +.Sh AUTHORS +The +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/openbsd/man7/mirroring-ports.7 b/static/openbsd/man7/mirroring-ports.7 new file mode 100644 index 00000000..d6b85e33 --- /dev/null +++ b/static/openbsd/man7/mirroring-ports.7 @@ -0,0 +1,145 @@ +.\" $OpenBSD: mirroring-ports.7,v 1.29 2025/05/19 10:16:17 sthen Exp $ +.\" +.\" Copyright (c) 2000,2012 Marc Espie +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: May 19 2025 $ +.Dt MIRRORING-PORTS 7 +.Os +.Sh NAME +.Nm mirroring-ports +.Nd how to build a mirror for ports distfiles +.Sh DESCRIPTION +The +.Nm OpenBSD Ports Collection +offers some powerful tools to mirror software sources. +.Pp +.Xr dpb 1 +features a +.Fl F +option which is explicitly designed for mirroring distfiles. +.Pp +If run with +.Fl F Ar jobs , +.Nm dpb +will +.Bl -bullet +.It +Limit itself to fetching distfiles, and not build any packages. +.It +Disregard any architecture or broken annotation, and try to fetch every +distfile. +.It +Fetch files to a temporary copy named +.Pa some_file.part +using +.Ic ftp -C +to resume interrupted downloads. +.It +Keep a global list of sha256 checksums as +.Pa ${DISTDIR}/distinfo , +and use that to refetch files when the ports tree records a changing checksum. +.It +Produces a log of old distfiles in +.Pa ${DISTDIR}/history , +.It +Create sha256 links under +.Pa ${DISTDIR}/by_cipher/sha256 +as per +.Xr link-checksum 1 Ns 's +former duties. +.El +.Pp +For partial distfiles collections, +.Nm dpb +can also be run with +.Fl D Ns Ar HISTORY_ONLY +to scan the full ports tree and update +.Pa ${DISTDIR}/history +without fetching anything. +.Sh FILES +.Bl -tag -width toto +.It Pa ${DISTDIR}/distinfo +a cache of known distfiles with their respective checksums. +.It Pa ${DISTDIR}/history +List of files appearing in +.Pa ${DISTDIR}/distinfo +that seem to no longer be required by the ports tree. +.Xr dpb 1 +will append to this file each time it is run on the whole tree +(option +.Fl a ) +and only if the ports tree scan finishes without error. +Each line is of the form +.Bd -literal -offset indent +timestamp SHA256 (file) = sha +.Ed +.Pp +denoting the first time a file/sha entry was no longer seen in the ports tree. +.El +.Sh SEE ALSO +.Xr clean-old-distfiles 1 , +.Xr dpb 1 , +.Xr ports 7 +.Sh HISTORY +The new integrated +.Fl F +option to +.Xr dpb 1 +was introduced in +.Ox 5.1 , +replacing the original infrastructure introduced in +.Ox 2.7 . +.Sh CAVEATS +Changing checksums is a recurring problem that is outside the direct +control of the +.Ox +Project. +Some software distributors change distribution files without +warning, without changing the file name proper. +Once the problem has been identified, the port maintainer should usually +contact the software author to fix the problem or, if the software author +is unresponsive, the maintainer should use +.Ev DIST_SUBDIR +to provide some state to guard against shifting checksums. +.Pp +However, a more robust approach is also needed, so that ports users can +depend on distfiles mirrors to carry what they need irrespective of those +synchronization issues. +The +.Pa ${DISTFILES}/by_cipher/sha256 +directory provides more persistent access to the distfiles, +indexed through the actual checksums that the files should match. +Provided mirroring is run sufficiently often, +two versions of the same distfile with respective checksums cksum1 and cksum2 +will be available under the names +.Pa ${DISTFILES}/by_cipher/sha256/c1/cksum1/distfile +and +.Pa ${DISTFILES}/by_cipher/sha256/c2/cksum2/distfile . +.Pp +If +.Ev REFETCH +is set to true, +.Xr bsd.port.mk 5 +will try to retrieve files under that naming scheme as a last resort. diff --git a/static/openbsd/man7/operator.7 b/static/openbsd/man7/operator.7 new file mode 100644 index 00000000..e620c985 --- /dev/null +++ b/static/openbsd/man7/operator.7 @@ -0,0 +1,59 @@ +.\" $OpenBSD: operator.7,v 1.11 2019/06/21 02:28:34 bentley Exp $ +.\" $NetBSD: operator.7,v 1.3 1994/11/30 19:07:26 jtc Exp $ +.\" +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)operator.7 8.1 (Berkeley) 6/9/93 +.\" +.Dd $Mdocdate: June 21 2019 $ +.Dt OPERATOR 7 +.Os +.Sh NAME +.Nm operator +.Nd C operator precedence and associativity +.Sh DESCRIPTION +.Bd -ragged -offset indent +.Bl -column "= += -= *= /= %= <<= >>= &= ^= |=" "Associativity" +.It Sy Operator Ta Sy Associativity +.It "\&() [] -> \&." Ta "left to right" +.It "! ~ ++ -- - (type) * & sizeof" Ta "right to left" +.It "\&* / %" Ta "left to right" +.It "\&+ -" Ta "left to right" +.It "\&<< >>" Ta "left to right" +.It "\&< <= > >=" Ta "left to right" +.It "\&== !=" Ta "left to right" +.It "\&&" Ta "left to right" +.It "\&^" Ta "left to right" +.It "\&|" Ta "left to right" +.It "\&&&" Ta "left to right" +.It "\&||" Ta "left to right" +.It "\&?:" Ta "right to left" +.It "= += -= *= /= %= <<= >>= &= ^= |=" Ta "right to left" +.It "\&," Ta "left to right" +.El +.Ed diff --git a/static/openbsd/man7/packages-specs.7 b/static/openbsd/man7/packages-specs.7 new file mode 100644 index 00000000..216006be --- /dev/null +++ b/static/openbsd/man7/packages-specs.7 @@ -0,0 +1,358 @@ +.\" $OpenBSD: packages-specs.7,v 1.31 2024/10/09 07:25:35 tb Exp $ +.\" +.\" Copyright (c) 2001 Marc Espie +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: October 9 2024 $ +.Dt PACKAGES-SPECS 7 +.Os +.Sh NAME +.Nm packages-specs +.Nd binary package names specifications +.Sh DESCRIPTION +Each package has a name consisting of at most three parts: +.Bd -literal -offset indent +stem-version[-flavors] +.Ed +.Pp +The +.Ar stem +part identifies the package. +It may contain some dashes, but its form is mostly conventional. +For instance, japanese packages usually +start with a +.Sq ja +prefix, e.g., +.Qq ja-kterm-6.2.0 . +.Pp +The +.Ar version +part starts at the first digit that follows a +.Sq - , +and goes on up to the following +.Sq - , +or to the end of the package name, whichever comes first. +.Pp +It is followed by the (possibly empty) +.Op - Ns Ar flavors +part. +.Pp +Thus, version numbers should always start with a digit and cannot contain +a +.Sq - , +whereas flavors should never start with a digit. +.Pp +All packages must have a version number. +Normally, the version number directly matches the original software +distribution version number, or release date. +In case there are substantial changes in the +.Ox +package, a patch level marker should be appended, e.g., +.Sq p0 , +.Sq p1 ... +For example, assuming that the screen package for release 2.8 was +named +.Qq screen-2.9.8 +and that an important security patch led to a newer package, +the new package would be called +.Qq screen-2.9.8p0 . +Obviously, these specific markers are reserved for +.Ox +purposes. +See +.Ev REVISION +in +.Xr bsd.port.mk 5 . +.Pp +Version comparison is done using the dewey notation with a few specific rules. +.Bl -bullet +.It +The version number is cut into separate parts on each dot +.Sq \&. . +Therefore, replace other upstream separators such as +.Sq _ +or +.Sq - +with dots. +.It +Comparison checks each part in turn, the first part that differs yields +a comparison result. +.It +If parts are numbers, they are compared numerically. +.It +Parts can also be numbers with an optional letter appended. +The numbers are compared numerically, and in case of equality, the letter +makes the difference. +.It +Other parts are compared alphabetically. +.It +The last part may contain an extra suffix matching +.Ar rc[N] , +.Ar alpha[N] , +.Ar beta[N] , +.Ar pre[N] , +or +.Ar pl[N] , +with +.Ar N +an optional number. +These correspond to traditional notations for +.Sq release candidate , +.Sq alpha version , +.Sq beta version , +.Sq pre-release , +.Sq patch-level , +and are ordered accordingly, e.g., +.Ar alpha +is oldest, then +.Ar beta , +.Ar rc +and +.Ar pre +are next (and non-comparable to one another), +then normal version, and finally +.Ar pl . +.Bl -dash +.It +"foo-1.01" is equal to "foo-1.1", which can lead to surprises.. +.It +"foo-1.001" is older than "foo-1.002", which in turns is older than "foo-1.0010" +.It +"foo-1.0rc2" is not comparable to "foo-1.0pre3" +.It +"bar-1.0alpha5" is older than "bar-1.0beta3" +.It +"bar-1.0beta3" is older than "bar-1.0rc1" +.It +"baz-1.0" is older than "baz-1.0pl1" +.El +.El +.Pp +In some rare cases, a change to a port would cause the version number to +compare as older than the previous version. +This happens if an update is reverted, if upstream's numbering scheme changes +completely, or if their usual scheme does not align with the one used by +.Ox . +A version style marker, of the form +.Sq v0 , +.Sq v1 ... +can be appended to the version number (after the patch level) +to denote the new numbering scheme. +This marker is added by setting +.Ev EPOCH +in the port Makefile and it takes precedence over the regular package version. +See +.Xr bsd.port.mk 5 . +.Pp +Flavored packages will also contain a list of flavors after the version +identifier, in a canonical order determined by +.Ev FLAVORS +in the corresponding port's +.Pa Makefile . +For instance, kterm has an xaw3d flavor: +.Qq ja-kterm-xaw3d . +.Pp +Note that, to uniquely identify the version part, no flavor shall ever +start with a digit. +Usually, flavored packages are slightly different versions of the same +package that offer very similar functionalities. +.Pp +Also note that user commands have short-hands for installing new packages +that are substantially different from formal +.Nm +(branch specifications and explicit flavoring). +The special character +.Sq % +is explicitly forbidden in formal package names and specs. +.Pp +.Xr pkg_check-version 1 +can be used to verify the ordering of package names. +.Sh CONFLICTS +Most conflicts between packages are handled on a package name basis. +Unless the packages have been specially prepared, it is +normally not possible to install two packages with the same +.Ar stem . +.Pp +Note that the +.Ar stem +ends at the +.Ar version +part. +So, for instance, +.Qq kdelibs-1.1.2 +and +.Qq kdelibs-2.1.1 +conflict. +But +.Qq openldap-2.0.7 +and +.Qq openldap-client-2.0.7 +don't. +Neither do +.Qq qt-1.45 +and +.Qq qt2-3.0 . +.Sh DEPENDENCIES +Packages may depend on other packages, as specified by their port's +Makefile, in a +.Ev BUILD_DEPENDS , +.Ev LIB_DEPENDS , +.Ev TEST_DEPENDS +or +.Ev RUN_DEPENDS . +All those conform to +.Bd -literal -offset indent +[pkgspec:]pkgpath +.Ed +.Pp +The +.Xr pkgpath 7 +part of the dependency is always used to obtain the default dependency for +the given package (the package that will be built and installed if no package +is found). +The corresponding package name is also used as a package specification, +after removing any version and flavor requirements. +.Pp +Without a +.Sq pkgspec\&: +part, by default, any package with the right stem will do: in effect, +the pkgspec used is +.Sq stem-* . +.Pp +In +.Ox 4.9 , +the dependent port may override this default, and set +.Ev PKGSPEC +to achieve a more restrictive default, for instance, +.Pa databases/db/v3 +sets the default to +.Qq PKGSPEC = db->=3,<4 +to avoid collision with +.Pa databases/db/v4 . +Be extra cautious with this functionality: this tweaks the depends line for +any including package, thus usually requiring a version bump, and is in +general only required for very messy cases where several incompatible versions +of the same software coexist as packages with the same stem. +.Pp +An explicit specification such as +.Qq png-1.0.7 . +may be used to ask for a more specific version number. +Version numbers may also include ranges, separated by commas, so for +instance, +.Qq foo->=1.3 +would match any foo with version at least 1.3, and +.Qq foo->=1.3,<=1.5 +would match any version of foo between 1.3 and 1.5, inclusive. +.Pp +As a convenience, the ports tree recognizes a specification that starts +with STEM, and will replace this with the correct stem, which can be useful +for embarrassingly long package names. +.Pp +As another convenience, the ports tree recognizes constructs like +.Qq graphics/png>=1.2.0 +and transforms it into +.Qq STEM->=1.2.0:graphics/png . +More specifically, package paths never contain <, >, or =, and those +characters trigger the transform. +.Pp +If the flavor specification is left blank, any flavor will do. +Note that most default package names don't contain flavor specification, +which means that any flavor will do +For instance, in +.Bd -literal -offset indent +LIB_DEPENDS = graphics/aalib +.Ed +.Pp +both +.Qq aalib-1.2 +and +.Qq aalib-1.2-no_x11 +will do. +To restrict the specification to packages that match flavor +.Sq f , +append +.Sq -f . +To restrict the specification to packages that do not match flavor +.Sq f , +append +.Sq -!f . +In the preceding case, one may use +.Bd -literal -offset indent +LIB_DEPENDS = aalib-*-!no_x11:graphics/aalib +.Ed +.Pp +to ensure the no_x11 flavor is not picked. +.Sh DEPENDENCIES RESOLUTION +Several packages may be specified for a dependency: +.Qq foo-*|bar-* +will match either any version of package foo, or any version of package bar. +In the general case, each package holds a tree of dependencies. +Resolution occurs at +.Xr pkg_add 1 +time, and all dependencies are tracked only as far as needed. +.Pp +For instance, if package +.Qq foo-1.0 +depends on either +.Qq bar-* +or +.Qq fuzz-* , +and +.Qq bar-2.0 +depends +on +.Qq toughluck-* , +.Xr pkg_add 1 +will first check whether +.Qq bar-* +or +.Qq fuzz-* +is installed. +If either is there, the +.Qq toughluck-* +dependency will never be examined. +It would only be used in the case where neither +.Qq bar-* +nor +.Qq fuzz-* +are present, thus +.Xr pkg_add 1 +would decide to bring in +.Qq bar-2.0 , +and so would check on +.Qq toughluck-* . +.Sh SEE ALSO +.Xr pkg_add 1 , +.Xr pkg_check-version 1 , +.Xr bsd.port.mk 5 , +.Xr library-specs 7 , +.Xr packages 7 , +.Xr pkgpath 7 , +.Xr ports 7 +.Sh HISTORY +Support for a more complex form of those package specifications first +appeared in +.Ox 2.9 . +The current simplified form was introduced in +.Ox 4.9 . diff --git a/static/openbsd/man7/packages.7 b/static/openbsd/man7/packages.7 new file mode 100644 index 00000000..2a508259 --- /dev/null +++ b/static/openbsd/man7/packages.7 @@ -0,0 +1,320 @@ +.\" $OpenBSD: packages.7,v 1.47 2022/01/05 17:39:25 jmc Exp $ +.\" +.\" Copyright (c) 2000 Marc Espie +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: January 5 2022 $ +.Dt PACKAGES 7 +.Os +.Sh NAME +.Nm packages +.Nd overview of the binary package system +.Sh DESCRIPTION +The +.Ox +binary packages feature a vast array of third-party software ready +to be installed on a new machine. +They are built through the +.Xr ports 7 +infrastructure. +Adding a new package is as simple as +.Pp +.Dl # pkg_add foo-1.0-vanilla.tgz +.Pp +In appearance, packages seem to be .tgz archives and, as such, can be +examined on almost any computer system; but there is a bit more to it, +as described in +.Xr package 5 . +.Pp +Even though the names are similar, +note that the basic +.Ox +distribution +.Po +.Pa baseXX.tgz , +.Pa compXX.tgz ... +.Pc +is not composed of such packages, but of plain tarballs. +.Sh FINDING PACKAGES +The official builds feature packages that will help with finding a given piece +of software: +.Bl -tag -width ports-readmes-dancer +.It pkglocatedb +a +.Xr locate 1 +database of all files in the ports tree, +.It sqlports +an sqlite database of all meta-info of each port, along with an index, +and a tool to trace dependencies chains, +.It ports-readmes-dancer +a simple local webserver that interfaces with that database to +display information. +.Po +There is a running instance of that server hosted on +.Lk https://openports.pl/ +.Pc . +.El +.Sh SECURITY CAVEAT +The packages are not as thoroughly audited as the main +.Ox +source tree (in many cases, they have not been audited at all). +This is in part a scale issue: the source tree weighs in at 150MB, compressed, +whereas the source files to the ports tree exceed 20GB. +Also, most +.Ox +developers concentrate on making the release as safe as possible and, +correspondingly, human resources for the ports tree are somewhat lacking. +.Pp +Starting with +.Ox 5.5 , +packages are now signed using +.Xr pkg_sign 1 : +understand that this is only a basic guarantee that the binary package +can't be tampered with while in transit. +.Pp +Starting with +.Ox 5.6 , +the special package +.Ar quirks +is always updated, and its signature date displayed. +Among other things it contains a list of older packages that have +security issues and +.Xr pkg_add 1 +will warn if those are installed and cannot be updated. +This prevents a scenario where a bad guy would maintain a partial mirror +with outdated packages. +.Pp +A small number of packages contain insecure code requiring +.Xr mmap 2 +memory both writeable and executable. +To use such insecurely written software, a separate +.Pa /usr/local +file system with the +.Cm wxallowed +.Xr mount 8 +option is needed. +.Sh MANAGING FILES +The package system offers some strong warranties. +.Ss "Installing a package won't erase existing files" +.Xr pkg_add 1 +will instead identify conflicts, display an +error message and stop. +.Ss "Modifying installed files is safe" +.Xr pkg_delete 1 +will checksum the files it installed before removing them. +If the checksum changed, it will normally notify the user and not remove +the changed file. +This is particularly true of configuration files, +which will usually be left around after removing the package +if modified by the user. +.Pp +These should apply to most packages. +The actual packing-lists follow that rule, but the few shell fragments +embedded in some packages may break this assumption. +Such a problem is a bug and should be reported. +.Ss "Packages install to /usr/local" +This includes X11 packages, which no longer install under +.Pa /usr/X11R6 . +The only exception is +Japanese dictionaries, which install under +.Pa /var/dict , +and some web packages, which install under +.Pa /var/www . +.Pp +Some packages installation scripts will also create new configuration +files in +.Pa /etc , +install daemon control scripts in +.Pa /etc/rc.d , +or need some working directory under +.Pa /var +to function correctly (e.g., +.Nm squid , +or +.Nm mariadb ) . +.Pp +.Ox +specific information installs under +.Pa /usr/local/share/doc/pkg-readmes . +.Pp +The current package system has some deliberate design limitations. +.Ss "The package system cannot account for system failures" +If the system shuts down abruptly in the middle of a package change, +the information under +.Pa /var/db/pkg +may well be corrupted. +Use +.Xr pkg_check 8 +in case of such problems. +.Ss "The package system is not aware of shared network installations" +And thus, it does not handle that situation well. +For instance, there is no mechanism to mark some files as being shareable +on several machines, or even on several architectures. +Bear in mind that the package database is normally stored in +.Pa /var/db/pkg , +which is usually not shared across machines. +.Pp +Always installing packages on the same machine, and exporting +.Pa /usr/local +to other machines should mostly work. +In such a case, always run +.Xr pkg_add 1 +in +.Qq "verbose, don't actually install the package" +mode first, so that +additional steps may be figured out. +.Ss "The package system does not handle shared files across packages" +If two packages install a file with the same name, there is a conflict. +Two packages can't safely install an exact identical +copy of a given file: +.Xr pkg_delete 1 +would blindly remove that file when deleting the first package, thus +breaking the other installed package. +.Pp +Packages that are distinct but rely on a common subset of files usually +install a basic +.Qq common +package that holds those files, and is not useful as a stand-alone package. +.Sh PACKAGE VERSIONS +All packages have an obvious version number in their name, +and a not so obvious version inside the actual package: +the run-time dependencies used for building. +Tools like +.Nm pkg_add Fl u +and +.Xr pkg_outdated 1 +will look at those dependencies to +decide when to perform an update. +.Pp +The full version (package name and dependency names) is known as the +.Sq update signature , +and can be queried with +.Nm pkg_info Fl S , +for packages, or +.Nm make Ar print-update-signature +for ports. +.Pp +Additionally, some packages with similar names and different versions may +exist at the same moment, because they have been built from different places +in the ports tree: snapshot versus stable version of some software, or +different flavors (note that this is different from the usual -current versus +-stable versions of the +.Ox +ports tree). +.Pp +Every package includes at least one +.Xr pkgpath 7 +marker to record the ports tree +location used to build it, so that users do not have their packages randomly +switch from a stable to a snapshot package, or from a gtk to a gtk2 flavor. +.Sh PACKAGE NAMING +All package names follow the pattern +.Qq name-version-flavor , +where +.Qq name +(also called stem, see +.Xr packages-specs 7 ) +is the actual package name, +.Qq version +is the version number, and +.Qq flavor +denotes some options that were used when creating the package. +.Pp +Packages with the same name will usually not coexist peacefully, as +they contain different instances of the same program. +Hence, by default, +.Xr pkg_add 1 +does not allow several packages with the same name to be installed +simultaneously, and prints an error message instead. +.Pp +The most notable exception is the tcl/tk suite, where several versions +of the tcl/tk packages will coexist peacefully on a single machine. +.Pp +Members of the +.Ox +project routinely scan built packages for conflicting files, +using +.Xr pkg_check-problems 1 . +Most packages should contain correct annotations, and not allow themselves +to be installed on top of a conflicting package. +.Pp +Some packages follow special naming conventions: +.Pp +.Bl -tag -width *-firmware-* -compact +.It Pa .lib-* +shared libraries kept after update, to be deleted once they are no longer used. +.It debug-* +debug information for the corresponding package. +.It Pa partial-* +partial installation of a package that couldn't finish. +.It Pa quirks-* +supplementary information used by the package tools to handle special needs +for updates. +.It Pa *-firmware-* +special system packages managed by +.Xr fw_update 8 . +.El +.Sh PACKAGE DEPENDENCIES +Each package holds a full list of pre-required packages. +.Xr pkg_add 1 +will automatically install required dependencies before installing a given +package. +Installs through +.Xr ftp 1 +are supported: pointing +.Ev PKG_PATH +to a distant package repository, e.g., +.Bd -literal -offset 1n +# export PKG_PATH=ftp.openbsd.org +.Ed +.Pp +will let +.Xr pkg_add 1 +automatically download dependencies as well. +.Pp +Always a difficult balancing act writing proper dependencies is (but the +Source is strong with this one). +Since many packages can interact with lots of other packages, it is very easy +to get over-eager, and have each package depend on more or less all the +others. +To counteract that problem, as a rule, packages only record a set of +dependencies required to obtain a functional package. +Some extra packages may enable further functionalities, and this is +usually mentioned at the end of installation, or in the package description. +.Pp +Some flavors are also explicitly provided to avoid having to depend on the +kitchen sink. +For instance, an +.Nm emacs--no_x11 +package is provided, which does not depend on X11 being installed to be +functional. +.Sh SEE ALSO +.Xr pkg_add 1 , +.Xr pkg_delete 1 , +.Xr pkg_info 1 , +.Xr pkg_sign 1 , +.Xr tar 1 , +.Xr package 5 , +.Xr packages-specs 7 , +.Xr ports 7 diff --git a/static/openbsd/man7/pkgpath.7 b/static/openbsd/man7/pkgpath.7 new file mode 100644 index 00000000..5789b64a --- /dev/null +++ b/static/openbsd/man7/pkgpath.7 @@ -0,0 +1,169 @@ +.\" $OpenBSD: pkgpath.7,v 1.5 2017/03/27 10:37:43 fcambus Exp $ +.\" +.\" Copyright (c) 2011 Marc Espie <espie@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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.Dd $Mdocdate: March 27 2017 $ +.Dt PKGPATH 7 +.Os +.Sh NAME +.Nm pkgpath +.Nd ports tree location for a package build +.Sh DESCRIPTION +Each location in the ports tree is uniquely identified through a +.Nm , +which encodes the directory, flavor and subpackage information +that allows the build of a package. +This is not to be confused with +.Ev PKG_PATH , +the list of URLs from which +.Xr pkg_add 1 +retrieves binary packages. +.Pp +Every +.Nm +conforms to the pattern +.Ar some/directory[,-sub][,flavor...] . +.Pp +The +.Ar some/directory +part refers to the directory part, to find under the +portstree, usually in +.Pa /usr/ports +(or +.Pa /usr/ports/mystuff +for port developers). +.Pp +The +.Ar ,-sub +optional part refers to a specific subpackage from a +multi-package port. +It can be left blank for non multi-package ports, or to get +the default subpackage +(usually +.Ar -main ) . +.Pp +The +.Ar ,flavor... +optional part refers to the flavors or pseudo-flavors to use +when building the package. +If left blank, it refers to the default flavor. +An explicit empty flavor can also be specified to make sure to +get an empty flavor, even if it does not correspond to the default +flavor. +.Pp +Note that +.Ar -sub +and +.Ar flavor +parts can be specified in any order, as all subpackages start with +a dash. +It is an error to ask for several subs at once, e.g.\& +.Ar some/path,-sub1,-sub2 , +though it won't always be flagged as a problem. +.Pp +For instance: +.Bl -tag -width small +.It Ar misc/screen +A simple directory, default flavor, which happens to be empty. +.It Ar misc/screen,static +Same port, +.Ar static +flavor. +.It Ar x11/kde/libs3 +A multi-package port with no subpackage nor flavor, refers to +.Ar x11/kde/libs3,-main . +.It Ar net/avahi +Multi-package port with default flavor. +Will actually build with FLAVOR="no_gui no_mono no_qt3 no_qt4 bootstrap" +(all of which are pseudo-flavors), so that only the main package will build. +.It Ar net/avahi,no_mono,-qt3 +Build avahi with the "no_mono" pseudo-flavor, which will build the +-main, -qt3, -qt4, -gui, -gtk, -gtk3, and -ui subpackages, and refer to the +.Ar -qt3 +subpackage. +.It Ar net/avahi, +.Ar net/avahi +with an explicit empty flavor, default subpackage +.Po +which happens to be +.Ar -main +.Pc . +.It Ar net/avahi,,-qt4 +.Ar net/avahi +with an explicit empty flavor, +.Ar -qt4 +subpackage. +.El +.Pp +The ports tree can iterate over lists of +.Nm +through +.Li SUBDIR="pkgpath1 pkgpath2..." +or through a full list through +.Li SUBDIRLIST=file . +.Pp +.Xr dpb 1 +also handles +.Nm +lists for many options. +.Sh NORMALISATION AND THE FULLPATH CONVENTION +When the ports tree handles dependencies, it passes +.Nm +from +.Ev BUILD_DEPENDS , +.Ev LIB_DEPENDS , +.Ev RUN_DEPENDS , +and +.Ev TEST_DEPENDS +to the dependent port for normalisation purposes. +That way, the +.Nm +that gets recorded in the package doesn't have any "default" flavor +or "default" subpackage left: those are always resolved to the correct +value. +.Pp +Likewise, pseudo-flavors vanish from the +.Nm pkgpath , +since they only participate in the build process, but do not intervene +in the built package. +.Pp +As a result, such +.Nm +are slightly different from the description above, as a flavor left blank +is the empty flavor (and not the default flavor). +This is the +.Qq fullpath convention . +.Pp +Tools such as +.Xr dpb 1 +display fullpath pkgpaths, +and binary packages store full pkgpaths. +.Pp +.Ev SUBDIR +and +.Ev SUBDIRLIST +can be forced to follow the fullpath convention by explicitly passing +.Li FULLPATH=Yes +to the corresponding +.Xr make 1 +invocations. +.Pp +Most tools that process binary packages do so. +.Sh SEE ALSO +.Xr dpb 1 , +.Xr bsd.port.mk 5 , +.Xr library-specs 7 , +.Xr packages 7 , +.Xr packages-specs 7 , +.Xr ports 7 diff --git a/static/openbsd/man7/ports.7 b/static/openbsd/man7/ports.7 new file mode 100644 index 00000000..7fbf270f --- /dev/null +++ b/static/openbsd/man7/ports.7 @@ -0,0 +1,734 @@ +.\" +.\" Copyright (c) 1997 David E. O'Brien +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $OpenBSD: ports.7,v 1.132 2023/09/07 17:19:19 espie Exp $ +.\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $ +.\" +.Dd $Mdocdate: September 7 2023 $ +.Dt PORTS 7 +.Os +.Sh NAME +.Nm ports +.Nd contributed applications +.Sh DESCRIPTION +The +.Ox +Ports Collection +is the infrastructure used to create binary packages for third party +applications. +.Pp +For normal usage refer to +.Xr packages 7 , +as most ports produce binary packages which are available from +the official HTTP mirrors. +.Pp +Each port contains any patches necessary to make the original +application source code compile and run on +.Ox . +Compiling an application is as simple as typing +.Ic make +in the port directory! +The +.Pa Makefile +automatically fetches the +application source code, either from a local disk or via HTTP, unpacks it +on the local system, applies the patches, and compiles it. +If all goes well, simply type +.Ic doas make install +to install the application. +.Pp +For more information about using ports, see +.Lk https://www.openbsd.org/faq/ports/ports.html "Working with Ports" . +For information about creating new ports, see +.Lk https://www.openbsd.org/faq/ports/ "The OpenBSD Porter's Handbook" . +.Pp +For a detailed description of the build process, see +.Xr bsd.port.mk 5 . +.Sh PORTS MASTER MAKEFILE +The ports master Makefile, normally located in +.Pa /usr/ports/Makefile +(but see +.Ev PORTSDIR +below) +offers a few deprecated targets for the time being. +.Bl -tag -width print-index +.It Cm print-index +display the contents of the index in a +.Sq user-friendly +way, +.It Cm search +invoked with a key, e.g., +.Ic make search key=foo , +retrieve information relevant to a given port (obsolescent). +.El +.Pp +Starting in +.Ox 4.0 , +there is a port, +.Pa databases/sqlports , +that builds an sqlite database containing most information relevant to +every port in the ports tree. +This database can be searched using any tool able to manipulate such +databases, for instance sqlitebrowser, or a script language with an +sqlite interface, e.g., perl, python, ocaml, lua, php. +.Pp +All static index generating information has now been superseded by the +.Pa sqlports , +.Pa portslist +or +.Pa pkglocatedb +packages, which contain +similar information to the old INDEX file, but are frequently updated. +See +.Pa databases/sqlports +.Pa databases/pkglocatedb +and +.Xr pkg_mklocatedb 1 +for details. +.Sh SELECTING A SET OF PORTS +One can define +.Ev SUBDIRLIST +to point to a file that contains a list of +.Ev FULLPKGPATHs , +one per line, to build stuff only in some directories. +.Pp +If +.Pa portslist +is up to date, it is possible to select subsets by setting the following +variables on the command line: +.Bl -tag -width category +.It Va key +package name matching the given key, +.It Va category +port belonging to category, +.It Va maintainer +port maintained by a given person. +.El +.Pp +For instance, to invoke +.Cm clean +on all ports in the x11 category, one can say: +.Bd -literal -offset indent +$ make category=x11 clean +.Ed +.Pp +The index search is done by a perl script, so all regular expressions from +.Xr perlre 1 +apply. +.Sh TARGETS +Individual ports are controlled through a few documented targets. +Some of these targets work recursively through subdirectories, so that +someone can, for example, install all of the net +ports. +.Pp +The variable +.Ev SKIPDIR +can hold a set of package directories to avoid during recursion. +These are always specified relative to the root of the ports tree, +and can contain a flavor or subpackage part +.Po +see +.Xr packages-specs 7 +.Pc . +.Ev SKIPDIR +is handled by a +.Ic case +statement, and so can contain simple wildcards +.Po +see +.Xr sh 1 +.Dq File name patterns +.Pc , +e.g., SKIPDIR='editors/openoffice*'. +.Pp +The variable +.Ev STARTDIR +can hold the path to a starting directory. +The recursion will skip all directories up to that package path. +This can be used to resume a full build at some specific point without having +to go through thousands of directories first. +.Pp +The variable +.Ev STARTAFTER +can hold the path to a starting directory. +The recursion will skip all directories up to and including that package path. +This can be used to resume a full build after some specific point without having +to go through thousands of directories first. +.Pp +In case of failure in a subdirectory, the shell fragment held in +.Ev REPORT_PROBLEM +is executed. +Default behavior is to call exit, but this can be overridden on the command +line, e.g., to avoid stopping after each problem. +.Bd -literal -offset indent +$ make REPORT_PROBLEM=true +.Ed +.Pp +If +.Ev REPORT_PROBLEM_LOGFILE +is non empty, then +.Ev REPORT_PROBLEM +will default to: +.Bd -literal -offset indent +echo $$subdir ($@) >>$${REPORT_PROBLEM_LOGFILE} +.Ed +.Pp +That is, any failure will append the faulty directory name together +with the target that failed to +.Pa ${REPORT_PROBLEM_LOGFILE} +and proceed. +.Pp +Some targets that do this are +.Cm all , build , checksum , clean , +.Cm configure , extract , fake , +.Cm fetch , install , distclean , +.Cm deinstall , reinstall , package , prepare , +.Cm show , regress , +.Cm lib-depends-check , +.Cm license-check , all-dir-depends , build-dir-depends , +.Cm run-dir-depends +and +.Cm generate-readmes . +.Pp +Target names starting with +.Sq _ +are private to the ports infrastructure, +should not be invoked directly, and are liable to change without notice. +.Pp +In the following list, each target will run the preceding targets +in order automatically. +That is, +.Cm build +will be run +.Pq if necessary +by +.Cm install , +and so on all the way to +.Cm fetch . +In typical use, one will only run +.Cm install +explicitly (as normal user, with +.Ev SUDO +defined in +.Pa /etc/mk.conf ) , +or +.Cm build +(as user), then +.Cm install +(as root). +.Bl -tag -width configure +.It Cm fetch +Fetch all of the files needed to build this port from the site(s) +listed in +.Ev SITES . +See +.Ev FETCH_CMD . +Use +.Xr dpb 1 +with option +.Fl F +to quickly fetch distfiles for a subtree. +.It Cm checksum +Verify that the fetched distfile matches the one the port was tested against. +Defining +.Ev NO_CHECKSUM +to +.Dv Yes +will skip this step. +Sometimes, distfiles change without warning. +The main +.Ox +mirror should still hold a copy of old distfiles, indexed by checksum. +Using +.Bd -literal -offset indent +$ make checksum REFETCH=true +.Ed +.Pp +will try to get a set of distfiles that match the recorded checksum. +.It Cm prepare +Install +any build dependencies of the current port. +Defining +.Ev NO_DEPENDS +to +.Dv Yes +will skip this step. +.It Cm extract +Expand the distfile into a work directory. +.It Cm patch +Apply any patches that are necessary for the port. +.It Cm gen +Recreate configure machinery if needed, mainly used by GNU based software +that wants autogen/autoconf/automake. +.It Cm configure +Configure the port. +Some ports will ask questions during this stage. +See +.Ev INTERACTIVE +and +.Ev BATCH . +.It Cm build +Build the port. +This is the same as calling the +.Cm all +target. +.It Cm fake +Pretend to install the port under a subdirectory of the work directory. +.It Cm generate-readmes +Create READMEs and rc scripts under the fake subdirectory. +.It Cm package +Create a binary package from the fake installation. +The package is a .tgz file that can be used to +install the port with +.Xr pkg_add 1 . +.It Cm install +Install the resulting package. +.El +.Pp +The following targets are not run during the normal install process +.Po +exception +.Cm clean +is run for dependencies with the default settings of +.Ev BULK Ns = Ns Dv Auto +.Pc . +.Bl -tag -width fetch-list +.It Cm print-build-depends , print-run-depends +Print an ordered list of all the compile and run dependencies. +.It Cm clean +Remove the expanded source code. +This does not recurse to dependencies unless +.Ev CLEANDEPENDS +is defined to +.Dv Yes . +.It Cm distclean +Remove the port's distfile(s). +This does not recurse to dependencies. +.It Cm regress +Runs the ports regression tests. +Usually needs a completed build. +.It Cm reinstall +Use this to restore a port after using +.Xr pkg_delete 1 . +.It Cm update +Alternative target to +.Cm install . +Does not install new packages, but updates existing ones. +.El +.Sh LOCK INFRASTRUCTURE +The ports tree can be used concurrently for building several ports at the +same time, thanks to a locking mechanism. +By default, locks are stored under +.Pa /tmp/portslocks . +Defining +.Ev LOCKDIR +will point them elsewhere, or disable the mechanism if set to an empty value. +.Pp +All locks will be stored in +.Pa ${LOCKDIR} . +.Ev LOCK_CMD +should be used to acquire a lock, and +.Ev UNLOCK_CMD +should be used to release it. +.Pp +Locks are named +.Pa ${LOCKDIR}/${FULLPKGNAME}.lock , +or +.Pa ${LOCKDIR}/${DISTFILE}.lock +for distfiles fetching. +.Pp +The default values of +.Ev LOCK_CMD +and +.Ev UNLOCK_CMD +are appropriate for most uses. +.Pp +The locking protocol follows a big-lock model: each top-level target +in a port directory will acquire the corresponding lock, complete its job, +then release the lock, e.g., running +.Bd -literal -offset indent +$ make build +.Ed +.Pp +will acquire the lock, run the port +through +.Cm fetch , +.Cm checksum , +.Cm extract , +.Cm patch , +.Cm configure , +.Cm build , +then release the lock. +If dependencies are involved, they will invoke top-level targets in other +directories, and thus acquire some other locks as well. +.Pp +The infrastructure contains some protection against acquiring the same lock +twice, thus recursive locking is not needed for +.Ev LOCK_CMD . +.Pp +Starting with +.Ox 4.3 , +the infrastructure supports manual locking: the targets +.Cm lock +and +.Cm unlock +can be used to acquire and release individual locks. +Both these targets output a shell command that must be used to update +environment variables. +Manual locking can be used to protect a directory against interference +by an automated build job, while the user is looking at or modifying a +given port. +.Sh UPDATING PACKAGES +Instead of deinstalling each package and rebuilding from scratch, the +ports tree can be used to update installed packages. +The +.Cm update +target will replace an installed package using +.Xr pkg_add 1 +in replacement mode. +If +.Ev FORCE_UPDATE +is set to +.Dv Yes , +dependencies will also be updated first, and packages will always be updated, +even if there is no difference between the old and the new packages. +.Pp +Updates use a mechanism similar to bulk cookies and deposit cookies in +the +.Ev UPDATE_COOKIES_DIR . +See the next section for more details, since most of the fine points of +bulk package building also apply to updates. +.Pp +However, also note that +.Li make update +is not guaranteed to work, see +.Sx CAVEATS +below. +.Sh BULK PACKAGE BUILDING +Building any significant number of packages from the ports tree should use +.Xr dpb 1 , +a tool located inside the ports tree proper +.Po +normally as +.Pa /usr/ports/infrastructure/bin/dpb +.Pc . +In particular, it can take advantage of machine clusters (same architecture +and same installation), and of multi-core machines. +.Pp +For more detailed information, see +.Xr bulk 8 . +.Sh FLAVORS +The +.Ox +ports tree comes with a mechanism called +.Ic FLAVORS . +Thanks to this mechanism, users can select specific options provided by +a given port. +.Pp +If a port is +.Qq flavored , +there should be a terse description of available flavors in the +.Pa pkg/DESCR +file. +.Pp +For example, the +.Pa misc/screen +port comes with a flavor called +.Ic static . +This changes the building process so a statically compiled version of +the program will be built. +To avoid confusion with other packages or flavors, +the package name will be extended with a dash-separated list of +the selected flavors. +.Pp +In this instance, the corresponding package will be called +.Ic screen-4.0.2-static . +.Pp +To see the flavors of a port, use the +.Cm show +target: +.Bd -literal -offset indent +$ make show=FLAVORS +.Ed +.Pp +To build a port with a specific flavor, just pass +.Ev FLAVOR +in the environment of the +.Xr make 1 +command: +.Bd -literal -offset indent +$ env FLAVOR="static" make package +.Ed +.Pp +and of course, use the same settings for the subsequent invocations of make: +.Bd -literal -offset indent +$ env FLAVOR="static" make install +$ env FLAVOR="static" make clean +.Ed +.Pp +More than one flavor may be specified: +.Bd -literal -offset indent +$ cd /usr/ports/mail/exim +$ env FLAVOR="mysql ldap" make package +.Ed +.Pp +Specifying a flavor that does not exist is an error. +Additionally, some ports impose some further restrictions on flavor +combinations, when such combinations do not make sense. +.Pp +Lots of ports can be built without X11 requirement and accordingly +have a +.Ic no_x11 +flavor. +.Pp +Flavor settings are not propagated to dependencies. +If a specific combination is needed, careful hand-building of the +required set of packages is still necessary. +.Sh MULTI_PACKAGES +The +.Ox +ports tree comes with a mechanism called +.Ic MULTI_PACKAGES . +This mechanism is used when a larger package is broken down into +several smaller components referred to as subpackages. +.Pp +If a port is +.Qq subpackaged , +each subpackage will have a corresponding description in the +.Pa pkg/DESCR-subpackage +file. +.Pp +For example, the +.Pa databases/mariadb +port comes with subpackages called +.Ic -main , +.Ic -tests +and +.Ic -server . +.Pp +In this instance, the build will yield multiple packages, one +corresponding to each subpackage. +In the case of our mariadb example, +the packages will be called +.Ic mariadb-client-<version> , +.Ic mariadb-tests-<version> , +and +.Ic mariadb-server-<version> . +.Pp +To install/deinstall a specific subpackage of a port, you may +.Xr pkg_add 1 +them manually, or alternatively, you may set +.Ev SUBPACKAGE +in the environment of the +.Xr make 1 +command during the install/deinstall phase: +.Bd -literal -offset indent +$ env SUBPACKAGE="-server" make install +$ env SUBPACKAGE="-server" make deinstall +.Ed +.Sh PORT VARIABLES +These can be changed in the environment, or in +.Pa /etc/mk.conf +for persistence. +They can also be set on make's command line, e.g., +.Ic make VAR_FOO Ns = Ns Dv foo +.Pp +Boolean variables should be set to +.Dv Yes +instead of simply being defined, for uniformity and future compatibility. +.Pp +Variable names starting with +.Sq _ +are private to the ports infrastructure, +should not be changed by the user, and are liable to change without notice. +.Bl -tag -width PORTS_PRIVSEP +.It Ev PORTS_PRIVSEP +If set to +.Sq Yes , +all operations will happen as restricted users +.Ar _pfetch +and +.Ar _pbuild . +.It Ev PORTSDIR +Location of the ports tree +(usually +.Pa /usr/ports ) . +.It Ev DISTDIR +Where to find/put distfiles, normally +.Pa ${PORTSDIR}/distfiles . +.It Ev PACKAGE_REPOSITORY +Used only for the +.Cm package +target; the base directory for the packages tree, normally +.Pa ${PORTSDIR}/packages . +If this directory exists, the package tree will be (partially) constructed. +.It Ev BULK_COOKIES_DIR +During bulk package building, used to store cookies for already built +packages to avoid rebuilding them, since the actual +working directory will already have been cleaned out. +Defaults to +.Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} . +.It Ev UPDATE_COOKIES_DIR +Used to store cookies for package updates, defaults to +.Pa ${PORTSDIR}/update/${MACHINE_ARCH} . +If set to empty, it will revert to a file under +.Pa ${WRKDIR} . +.It Ev LOCALBASE +Where to install things in general +(usually +.Pa /usr/local ) . +.It Ev SITES +Primary sites for distribution files if not found locally. +.It Ev CLEANDEPENDS +If set to +.Dv Yes , +let +.Cm clean +recurse to dependencies. +.It Ev FETCH_CMD +Command to use to fetch files. +Normally +.Xr ftp 1 . +.It Ev FETCH_PACKAGES +If set, +try to use as options to +.Xr pkg_add 1 +to install missing packages from +.Ev PKG_PATH . +.Xr bsd.port.mk 5 +does not set +.Ev FETCH_PACKAGES , +so even an empty value amounts to setting the variable. +.Pp +For instance, to run +.Xr pkg_add 1 +with default options : +.Bd -literal -offset indent +make FETCH_PACKAGES= +.Ed +.Pp +or, to use the snapshots directory during the final beta period: +.Bd -literal -offset indent +make FETCH_PACKAGES=-Dsnap +.Ed +.It Ev PATCH_DEBUG +If defined, display verbose output when applying each patch. +.It Ev INTERACTIVE +If defined, only operate on a port if it requires interaction. +.It Ev BATCH +If defined, only operate on a port if it can be installed 100% automatically. +.El +.Sh USING A READ-ONLY PORTS TREE +Select read-write partition(s) that can accommodate working directories, the +distfiles repository, and the built packages. +Set +.Ev WRKOBJDIR , +.Ev PACKAGE_REPOSITORY , +.Ev BULK_COOKIES_DIR , +.Ev UPDATE_COOKIES_DIR , +.Ev DISTDIR , +and +.Ev PLIST_REPOSITORY +in +.Pa /etc/mk.conf +accordingly. +.Sh FILES +.Bl -tag -width /usr/ports/xxxxxxxx -compact +.It Pa /usr/ports +The default ports directory. +.It Pa /usr/ports/Makefile +Ports master Makefile. +.It Pa /usr/local/share/ports-INDEX +Ports index, part of the +.Pa portlist +package. +.It Pa /usr/ports/pobj +Build directories. +A number of insecurely coded ports require a dedicated file system with the +.Cm wxallowed +.Xr mount 8 +option. +.It Pa /usr/ports/infrastructure/mk/bsd.port.mk +The ports main engine. +.It Pa /usr/ports/infrastructure/db/network.conf +Network configuration. +.It Pa /usr/ports/infrastructure/db/user.list +List of users and groups created by ports. +.El +.Sh SEE ALSO +.Xr dpb 1 , +.Xr make 1 , +.Xr pkg_add 1 , +.Xr pkg_create 1 , +.Xr pkg_delete 1 , +.Xr pkg_info 1 , +.Xr bsd.port.mk 5 , +.Xr port-modules 5 , +.Xr mirroring-ports 7 , +.Xr packages 7 +.Pp +The +.Ox +Ports System: +.Lk https://www.openbsd.org/faq/ports/ports.html +.Pp +The +.Ox +Porter's Handbook: +.Lk https://www.openbsd.org/faq/ports/ +.Sh HISTORY +.Nm The Ports Collection +appeared in +.Fx 1.0 . +It was introduced in +.Ox +by Ejovi Nuwere, with much initial effort by Angelos D. Keromytis. +Maintenance passed then to Marco S. Hyman, and then to Christopher Turan. +It is currently managed by Marc Espie, Christian Weisgerber, +along with a host of others found at +.Mt ports@openbsd.org . +.Sh AUTHORS +This man page was originated by +.An David O'Brien , +from the +.Fx +project. +.Sh CAVEATS +Building a new version of an already installed package is not guaranteed +to work. +.Pp +The safer way would be to create a sandbox for building the updated port +using +.Xr proot 1 +.Po see also +.Xr bulk 8 +.Pc , +and then update the installed package. +.Pp +Specifically: most software expects building in a virgin environment +with only the required dependency. +As a result, lots of time, libraries and headers under +.Pa /usr/local +will be favored over the currently building version. diff --git a/static/openbsd/man7/roff.7 b/static/openbsd/man7/roff.7 new file mode 100644 index 00000000..4c54ad2f --- /dev/null +++ b/static/openbsd/man7/roff.7 @@ -0,0 +1,2464 @@ +.\" $OpenBSD: roff.7,v 1.104 2025/08/04 23:11:52 schwarze Exp $ +.\" +.\" Copyright (c) 2010-2019,2022-2023,2025 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 4 2025 $ +.Dt ROFF 7 +.Os +.Sh NAME +.Nm roff +.Nd roff language reference for mandoc +.Sh DESCRIPTION +The +.Nm roff +language is a general purpose text formatting language. +Since traditional implementations of the +.Xr mdoc 7 +and +.Xr man 7 +manual formatting languages are based on it, +many real-world manuals use small numbers of +.Nm +requests and escape sequences intermixed with their +.Xr mdoc 7 +or +.Xr man 7 +code. +To properly format such manuals, the +.Xr mandoc 1 +utility supports a subset of +.Nm +requests and escapes. +Even though this manual page lists all +.Nm +requests and escape sequences, it only contains partial information +about requests not supported by +.Xr mandoc 1 +and about language features that do not matter for manual pages. +For complete +.Nm +manuals, consult the +.Sx SEE ALSO +section. +.Pp +Input lines beginning with the control character +.Sq \&. +are parsed for requests and macros. +Such lines are called +.Dq request lines +or +.Dq macro lines , +respectively. +Requests change the processing state and manipulate the formatting; +some macros also define the document structure and produce formatted +output. +The single quote +.Pq Qq \(aq +is accepted as an alternative control character, +treated by +.Xr mandoc 1 +just like +.Ql \&. +.Pp +Lines not beginning with control characters are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context. +.Sh LANGUAGE SYNTAX +.Nm +documents are text files containing only printable +.Xr ascii 7 +characters, the space character, +and, in certain circumstances, the tab character. +The backslash character +.Sq \e +indicates the start of an escape sequence, used for example for +.Sx Comments +and +.Sx Special Characters . +For a complete listing of escape sequences, consult the +.Sx ESCAPE SEQUENCE REFERENCE +below. +.Ss Comments +Text following an escaped double-quote +.Sq \e\(dq , +whether in a request, macro, or text line, is ignored to the end of the line. +A request line beginning with a control character and comment escape +.Sq \&.\e\(dq +is also ignored. +Furthermore, request lines with only a control character and optional +trailing whitespace are stripped from input. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.\e\(dq This is a comment line. +\&.\e\(dq The next line is ignored: +\&. +\&.Sh EXAMPLES \e\(dq This is a comment, too. +\&example text \e\(dq And so is this. +.Ed +.Ss Special Characters +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in request, macro, and text lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis +.Sq \&( +for two-character sequences; an open-bracket +.Sq \&[ +for n-character sequences (terminated at a close-bracket +.Sq \&] ) ; +or a single one character sequence. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e(em +Two-letter em dash escape. +.It Li \ee +One-letter backslash escape. +.El +.Pp +See +.Xr mandoc_char 7 +for a complete list. +.Ss Font Selection +In +.Xr mdoc 7 +and +.Xr man 7 +documents, fonts are usually selected with macros. +The +.Ic \ef +escape sequence and the +.Ic \&ft +request can be used to manually change the font, +but this is not recommended in +.Xr mdoc 7 +documents. +Such manual font changes are overridden by many subsequent macros. +.Pp +The following fonts are supported: +.Pp +.Bl -tag -width CW -offset indent -compact +.It Cm B +Bold font. +.It Cm BI +A font that is both bold and italic. +.It Cm CB +Bold constant width font. +Same as +.Cm B +in terminal output. +.It Cm CI +Italic constant width font. +Same as +.Cm I +in terminal output. +.It Cm CR +Regular constant width font. +Same as +.Cm R +in terminal output. +.It Cm CW +An alias for +.Cm CR . +.It Cm I +Italic font. +.It Cm P +Return to the previous font. +If a macro caused a font change since the last +.Ic \ef +escape sequence or +.Ic \&ft +request, this returns to the font before the last font change in +the macro rather than to the font before the last manual font change. +.It Cm R +Roman font. +This is the default font. +.It Cm 1 +An alias for +.Cm R . +.It Cm 2 +An alias for +.Cm I . +.It Cm 3 +An alias for +.Cm B . +.It Cm 4 +An alias for +.Cm BI . +.El +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \efBbold\efR +Write in \fBbold\fP, then switch to regular font mode. +.It Li \efIitalic\efP +Write in \fIitalic\fP, then return to previous font mode. +.It Li \ef(BIbold italic\efP +Write in \f(BIbold italic\fP, then return to previous font mode. +.El +.Ss Whitespace +Whitespace consists of the space character. +In text lines, whitespace is preserved within a line. +In request and macro lines, whitespace delimits arguments and is discarded. +.Pp +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a space character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp +Literal space characters can be produced in the output +using escape sequences. +In macro lines, they can also be included in arguments using quotation; see +.Sx MACRO SYNTAX +for details. +.Pp +Blank text lines, which may include whitespace, are only permitted +within literal contexts. +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Scaling Widths +Many requests and macros support scaled widths for their arguments. +The syntax for a scaled width is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or followed by at least one digit. +.Pp +The following scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (1/6 inch) +.It p +point (1/72 inch) +.It f +scale +.Sq u +by 65536 +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +device-dependent basic units +.It M +mini-em (1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +or +.Sq v +is necessarily non-portable across output media. +See +.Sx COMPATIBILITY . +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Pp +Examples: +.Bl -tag -width "xBl -tag -width 2i" -offset indent -compact +.It Li \&.Bl -tag -width 2i +two-inch tagged list indentation in +.Xr mdoc 7 +.It Li \&.HP 2i +two-inch tagged list indentation in +.Xr man 7 +.It Li \&.sp 2v +two vertical spaces +.El +.Ss Sentence Spacing +Each sentence should terminate at the end of an input line. +By doing this, a formatter will be able to apply the proper amount of +spacing after the end of sentence (unescaped) period, exclamation mark, +or question mark followed by zero or more non-sentence closing +delimiters +.Po +.Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" +.Pc . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line. +.Pp +If an input line happens to end with a period, exclamation or question +mark that isn't the end of a sentence, append a zero-width space +.Pq Sq \e& . +.Pp +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A macro would end like this: +\&.Xr mandoc 1 \&. +An abbreviation at the end of an input line needs escaping, e.g.\e& +like this. +.Ed +.Sh REQUEST SYNTAX +A request or macro line consists of: +.Pp +.Bl -enum -compact +.It +the control character +.Sq \&. +or +.Sq \(aq +at the beginning of the line, +.It +optionally an arbitrary amount of whitespace, +.It +the name of the request or the macro, which is one word of arbitrary +length, terminated by whitespace, +.It +and zero or more arguments delimited by whitespace. +.El +.Pp +Thus, the following request lines are all equivalent: +.Bd -literal -offset indent +\&.ig end +\&.ig end +\&. ig end +.Ed +.Sh MACRO SYNTAX +Macros are provided by the +.Xr mdoc 7 +and +.Xr man 7 +languages and can be defined by the +.Ic \&de +request. +When called, they follow the same syntax as requests, except that +macro arguments may optionally be quoted by enclosing them +in double quote characters +.Pq Sq \(dq . +Quoted text, even if it contains whitespace or would cause +a macro invocation when unquoted, is always considered literal text. +Inside quoted text, pairs of double quote characters +.Pq Sq Qq +resolve to single double quote characters. +.Pp +To be recognised as the beginning of a quoted argument, the opening +quote character must be preceded by a space character. +A quoted argument extends to the next double quote character that is not +part of a pair, or to the end of the input line, whichever comes earlier. +Leaving out the terminating double quote character at the end of the line +is discouraged. +For clarity, if more arguments follow on the same input line, +it is recommended to follow the terminating double quote character +by a space character; in case the next character after the terminating +double quote character is anything else, it is regarded as the beginning +of the next, unquoted argument. +.Pp +Both in quoted and unquoted arguments, pairs of backslashes +.Pq Sq \e\e +resolve to single backslashes. +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li .Fn strlen \(dqconst char *s\(dq +Group arguments +.Qq const char *s +into one function argument. +If unspecified, +.Qq const , +.Qq char , +and +.Qq *s +would be considered separate arguments. +.It Li .Op \(dqFl a\(dq +Consider +.Qq \&Fl a +as literal text instead of a flag macro. +.El +.Sh REQUEST REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following requests. +For requests marked as "ignored" or "unsupported", any arguments are +ignored, and the number of arguments is not checked. +.Bl -tag -width Ds +.It Ic \&ab Op Ar message +Abort processing. +Currently unsupported. +.It Ic \&ad Op Cm b | c | l | n | r +Set line adjustment mode for subsequent text. +Currently ignored. +.It Ic \&af Ar registername format +Assign an output format to a number register. +Currently ignored. +.It Ic \&aln Ar newname oldname +Create an alias for a number register. +Currently unsupported. +.It Ic \&als Ar newname oldname +Create an alias for a request, string, macro, or diversion. +.It Ic \&am Ar macroname Op Ar endmacro +Append to a macro definition. +The syntax of this request is the same as that of +.Ic \&de . +.It Ic \&am1 Ar macroname Op Ar endmacro +Append to a macro definition, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&de1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&am . +.It Ic \&ami Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei . +.It Ic \&ami1 Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +and switching roff compatibility mode off during macro execution +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ami . +.It Ic \&as Ar stringname Op Ar string +Append to a user-defined string. +The syntax of this request is the same as that of +.Ic \&ds . +If a user-defined string with the specified name does not yet exist, +it is set to the empty string before appending. +.It Ic \&as1 Ar stringname Op Ar string +Append to a user-defined string, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&ds1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&as . +.It Ic \&asciify Ar divname +Fully unformat a diversion. +Currently unsupported. +.It Ic \&backtrace +Print a backtrace of the input stack. +This is a groff extension and currently ignored. +.It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset +Artificially embolden by repeated printing with small shifts. +Currently ignored. +.It Ic \&bleedat Ar left top width height +Set the BleedBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&blm Ar macroname +Set a blank line trap. +Currently unsupported. +.It Ic \&box Ar divname +Begin a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&boxa Ar divname +Add to a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber +Begin a new page. +Currently ignored. +.It Ic \&BP Ar source height width position offset flags label +Define a frame and place a picture in it. +This is a Heirloom extension and currently unsupported. +.It Ic \&br +Break the output line. +.It Ic \&break +Break out of the innermost +.Ic \&while +loop. +.It Ic \&breakchar Ar char ... +Optional line break characters. +This is a Heirloom extension and currently ignored. +.It Ic \&brnl Ar N +Break output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&brp +Break and spread output line. +Currently, this is implemented as an alias for +.Ic \&br . +.It Ic \&brpnl Ar N +Break and spread output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&c2 Op Ar char +Change the no-break control character. +Currently unsupported. +.It Ic \&cc Op Ar char +Change the control character. +If +.Ar char +is not specified, the control character is reset to +.Sq \&. . +Trailing characters are ignored. +.It Ic \&ce Op Ar N +Center the next +.Ar N +input lines without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends centering. +Currently, high level macros abort centering. +.It Ic \&cf Ar filename +Output the contents of a file. +Ignored because insecure. +.It Ic \&cflags Ar flags char ... +Set character flags. +This is a groff extension and currently ignored. +.It Ic \&ch Ar macroname Op Ar dist +Change a trap location. +Currently ignored. +.It Ic \&char Ar glyph Op Ar string +Define or redefine the ASCII character or character escape sequence +.Ar glyph +to be rendered as +.Ar string , +which can be empty. +Only partially supported in +.Xr mandoc 1 ; +may interact incorrectly with +.Ic \&tr . +.It Ic \&chop Ar stringname +Remove the last character from a macro, string, or diversion. +Currently unsupported. +.It Ic \&class Ar classname char ... +Define a character class. +This is a groff extension and currently ignored. +.It Ic \&close Ar streamname +Close an open file. +Ignored because insecure. +.It Ic \&CL Ar color text +Print text in color. +This is a Heirloom extension and currently unsupported. +.It Ic \&color Op Cm 1 | 0 +Activate or deactivate colors. +This is a groff extension and currently ignored. +.It Ic \&composite Ar from to +Define a name component for composite glyph names. +This is a groff extension and currently unsupported. +.It Ic \&continue +Immediately start the next iteration of a +.Ic \&while +loop. +Currently unsupported. +.It Ic \&cp Op Cm 1 | 0 +Switch +.Nm +compatibility mode on or off. +Currently ignored. +.It Ic \&cropat Ar left top width height +Set the CropBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&cs Ar font Op Ar width Op Ar emsize +Constant character spacing mode. +Currently ignored. +.It Ic \&cu Op Ar N +Underline next +.Ar N +input lines including whitespace. +Currently ignored. +.It Ic \&da Ar divname +Append to a diversion. +Currently unsupported. +.It Ic \&dch Ar macroname Op Ar dist +Change a trap location in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&de Ar macroname Op Ar endmacro +Define a +.Nm +macro. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname +.Ar definition +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname endmacro +.Ar definition +.Pf . Ar endmacro +.Ed +.Pp +Both forms define or redefine the macro +.Ar macroname +to represent the +.Ar definition , +which may consist of one or more input lines, including the newline +characters terminating each line, optionally containing calls to +.Nm +requests, +.Nm +macros or high-level macros like +.Xr man 7 +or +.Xr mdoc 7 +macros, whichever applies to the document in question. +.Pp +Specifying a custom +.Ar endmacro +works in the same way as for +.Ic \&ig ; +namely, the call to +.Sq Pf . Ar endmacro +first ends the +.Ar definition , +and after that, it is also evaluated as a +.Nm +request or +.Nm +macro, but not as a high-level macro. +.Pp +The macro can be invoked later using the syntax +.Pp +.D1 Pf . Ar macroname Op Ar argument Op Ar argument ... +.Pp +Regarding argument parsing, see +.Sx MACRO SYNTAX +above. +.Pp +The line invoking the macro will be replaced +in the input stream by the +.Ar definition , +replacing all occurrences of +.No \e\e$ Ns Ar N , +where +.Ar N +is a digit, by the +.Ar N Ns th Ar argument . +For example, +.Bd -literal -offset indent +\&.de ZN +\efI\e^\e\e$1\e^\efP\e\e$2 +\&.. +\&.ZN XtFree . +.Ed +.Pp +produces +.Pp +.D1 \efI\e^XtFree\e^\efP. +.Pp +in the input stream, and thus in the output: \fI\^XtFree\^\fP. +Each occurrence of \e\e$* is replaced with all the arguments, +joined together with single space characters. +The variant \e\e$@ is similar, except that each argument is +individually quoted. +.Pp +Since macros and user-defined strings share a common string table, +defining a macro +.Ar macroname +clobbers the user-defined string +.Ar macroname , +and the +.Ar definition +can also be printed using the +.Sq \e* +string interpolation syntax described below +.Ic ds , +but this is rarely useful because every macro definition contains at least +one explicit newline character. +.Pp +In order to prevent endless recursion, both groff and +.Xr mandoc 1 +limit the stack depth for expanding macros and strings +to a large, but finite number, and +.Xr mandoc 1 +also limits the length of the expanded input line. +Do not rely on the exact values of these limits. +.It Ic \&de1 Ar macroname Op Ar endmacro +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&de . +.It Ic \&defcolor Ar newname scheme component ... +Define a color name. +This is a groff extension and currently ignored. +.It Ic \&dei Ar macrostring Op Ar endstring +Define a +.Nm +macro, specifying the macro name indirectly (groff extension). +The syntax of this request is the same as that of +.Ic \&de . +The effect is the same as: +.Pp +.D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring +.It Ic \&dei1 Ar macrostring Op Ar endstring +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution, +specifying the macro name indirectly (groff extension). +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&dei . +.It Ic \&device Ar string ... +.It Ic \&devicem Ar stringname +These two requests only make sense with the groff-specific intermediate +output format and are unsupported. +.It Ic \&di Ar divname +Begin a diversion. +Currently unsupported. +.It Ic \&do Ar command Op Ar argument ... +Execute +.Nm +request or macro line with compatibility mode disabled. +Currently unsupported. +.It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string. +The +.Ar stringname +and +.Ar string +arguments are space-separated. +If the +.Ar string +begins with a double-quote character, that character will not be part +of the string. +All remaining characters on the input line form the +.Ar string , +including whitespace and double-quote characters, even trailing ones. +.Pp +The +.Ar string +can be interpolated into subsequent text by using +.No \e* Ns Bq Ar stringname +for a +.Ar stringname +of arbitrary length, or \e*(NN or \e*N if the length of +.Ar stringname +is two or one characters, respectively. +Interpolation can be prevented by escaping the leading backslash; +that is, an asterisk preceded by an even number of backslashes +does not trigger string interpolation. +.Pp +Since user-defined strings and macros share a common string table, +defining a string +.Ar stringname +clobbers the macro +.Ar stringname , +and the +.Ar stringname +used for defining a string can also be invoked as a macro, +in which case the following input line will be appended to the +.Ar string , +forming a new input line passed to the +.Nm +parser. +For example, +.Bd -literal -offset indent +\&.ds badidea .S +\&.badidea +H SYNOPSIS +.Ed +.Pp +invokes the +.Ic SH +macro when used in a +.Xr man 7 +document. +Such abuse is of course strongly discouraged. +.It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string that will be expanded with +.Nm +compatibility mode switched off during string expansion. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ds . +.It Ic \&dwh Ar dist macroname +Set a location trap in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&dt Op Ar dist macroname +Set a trap within a diversion. +Currently unsupported. +.It Ic \&ec Op Ar char +Enable the escape mechanism and change the escape character. +The +.Ar char +argument defaults to the backslash +.Pq Sq \e . +.It Ic \&ecr +Restore the escape character. +Currently unsupported. +.It Ic \&ecs +Save the escape character. +Currently unsupported. +.It Ic \&el Ar body +The +.Dq else +half of an if/else conditional. +Pops a result off the stack of conditional evaluations pushed by +.Ic \&ie +and uses it as its conditional. +If no stack entries are present (e.g., due to no prior +.Ic \&ie +calls) +then false is assumed. +The syntax of this request is similar to +.Ic \&if +except that the conditional is missing. +.It Ic \&em Ar macroname +Set a trap at the end of input. +Currently unsupported. +.It Ic \&EN +End an equation block. +See +.Ic \&EQ . +.It Ic \&eo +Disable the escape mechanism completely. +.It Ic \&EP +End a picture started by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&EQ +Begin an equation block. +See +.Xr eqn 7 +for a description of the equation language. +.It Ic \&errprint Ar message +Print a string like an error message. +This is a Heirloom extension and currently ignored. +.It Ic \&ev Op Ar envname +Switch to another environment. +Currently unsupported. +.It Ic \&evc Op Ar envname +Copy an environment into the current environment. +Currently unsupported. +.It Ic \&ex +Abort processing and exit. +Currently unsupported. +.It Ic \&fallback Ar curfont font ... +Select the fallback sequence for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fam Op Ar familyname +Change the font family. +This is a groff extension and currently ignored. +.It Ic \&fc Op Ar delimchar Op Ar padchar +Define a delimiting and a padding character for fields. +Currently unsupported. +.It Ic \&fchar Ar glyphname Op Ar string +Define a fallback glyph. +Currently unsupported. +.It Ic \&fcolor Ar colorname +Set the fill color for \eD objects. +This is a groff extension and currently ignored. +.It Ic \&fdeferlig Ar font string ... +Defer ligature building. +This is a Heirloom extension and currently ignored. +.It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name +Enable or disable an OpenType feature. +This is a Heirloom extension and currently ignored. +.It Ic \&fi +Break the output line and switch to fill mode, +which is active by default but can be ended with the +.Ic \&nf +request. +In fill mode, input from subsequent input lines is added to +the same output line until the next word no longer fits, +at which point the output line is broken. +This request is implied by the +.Xr mdoc 7 +.Ic \&Sh +macro and by the +.Xr man 7 +.Ic \&SH , +.Ic \&SS , +and +.Ic \&EE +macros. +.It Ic \&fkern Ar font minkern +Control the use of kerning tables for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fl +Flush output. +Currently ignored. +.It Ic \&flig Ar font string char ... +Define ligatures. +This is a Heirloom extension and currently ignored. +.It Ic \&fp Ar position font Op Ar filename +Assign font position. +Currently ignored. +.It Ic \&fps Ar mapname ... +Mount a font with a special character map. +This is a Heirloom extension and currently ignored. +.It Ic \&fschar Ar font glyphname Op Ar string +Define a font-specific fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&fspacewidth Ar font Op Ar afmunits +Set a font-specific width for the space character. +This is a Heirloom extension and currently ignored. +.It Ic \&fspecial Ar curfont Op Ar font ... +Conditionally define a special font. +This is a groff extension and currently ignored. +.It Ic \&ft Op Ar font +Change the font; see +.Sx Font Selection . +The +.Ar font +argument defaults to +.Cm P . +.It Ic \&ftr Ar newname Op Ar oldname +Translate font name. +This is a groff extension and currently ignored. +.It Ic \&fzoom Ar font Op Ar permille +Zoom font size. +Currently ignored. +.It Ic \&gcolor Op Ar colorname +Set glyph color. +This is a groff extension and currently ignored. +.It Ic \&hc Op Ar char +Set the hyphenation character. +Currently ignored. +.It Ic \&hcode Ar char code ... +Set hyphenation codes of characters. +Currently ignored. +.It Ic \&hidechar Ar font char ... +Hide characters in a font. +This is a Heirloom extension and currently ignored. +.It Ic \&hla Ar language +Set hyphenation language. +This is a groff extension and currently ignored. +.It Ic \&hlm Op Ar number +Set maximum number of consecutive hyphenated lines. +Currently ignored. +.It Ic \&hpf Ar filename +Load hyphenation pattern file. +This is a groff extension and currently ignored. +.It Ic \&hpfa Ar filename +Load hyphenation pattern file, appending to the current patterns. +This is a groff extension and currently ignored. +.It Ic \&hpfcode Ar code code ... +Define mapping values for character codes in hyphenation patterns. +This is a groff extension and currently ignored. +.It Ic \&hw Ar word ... +Specify hyphenation points in words. +Currently ignored. +.It Ic \&hy Op Ar mode +Set automatic hyphenation mode. +Currently ignored. +.It Ic \&hylang Ar language +Set hyphenation language. +This is a Heirloom extension and currently ignored. +.It Ic \&hylen Ar nchar +Minimum word length for hyphenation. +This is a Heirloom extension and currently ignored. +.It Ic \&hym Op Ar length +Set hyphenation margin. +This is a groff extension and currently ignored. +.It Ic \&hypp Ar penalty ... +Define hyphenation penalties. +This is a Heirloom extension and currently ignored. +.It Ic \&hys Op Ar length +Set hyphenation space. +This is a groff extension and currently ignored. +.It Ic \&ie Ar condition body +The +.Dq if +half of an if/else conditional. +The result of the conditional is pushed into a stack used by subsequent +invocations of +.Ic \&el , +which may be separated by any intervening input (or not exist at all). +Its syntax is equivalent to +.Ic \&if . +.It Ic \&if Ar condition body +Begin a conditional. +This request can also be written as follows: +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{ Ns Ar body +.Ar body ... Ns \e} +.Ed +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Ar body ... +.Pf . No \e} +.Ed +.Pp +The +.Ar condition +is a boolean expression. +Currently, +.Xr mandoc 1 +supports the following subset of roff conditionals: +.Bl -bullet +.It +If +.Sq \&! +is prefixed to +.Ar condition , +it is logically inverted. +.It +If the first character of +.Ar condition +is +.Sq n +.Pq nroff mode +or +.Sq o +.Pq odd page , +it evaluates to true, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq e +.Pq even page , +.Sq t +.Pq troff mode , +or +.Sq v +.Pq vroff mode , +it evaluates to false, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq c +.Pq character available , +it evaluates to true if the following character is an ASCII character +or a valid character escape sequence, or to false otherwise. +The +.Ar body +starts with the character following that next character. +.It +If the first character of +.Ar condition +is +.Sq d , +it evaluates to true if the rest of +.Ar condition +is the name of an existing user defined macro or string; +otherwise, it evaluates to false. +.It +If the first character of +.Ar condition +is +.Sq r , +it evaluates to true if the rest of +.Ar condition +is the name of an existing number register; +otherwise, it evaluates to false. +.It +If the +.Ar condition +starts with a parenthesis or with an optionally signed +integer number, it is evaluated according to the rules of +.Sx Numerical expressions +explained below. +It evaluates to true if the result is positive, +or to false if the result is zero or negative. +.It +Otherwise, the first character of +.Ar condition +is regarded as a delimiter and it evaluates to true if the string +extending from its first to its second occurrence is equal to the +string extending from its second to its third occurrence. +.It +If +.Ar condition +cannot be parsed, it evaluates to false. +.El +.Pp +If a conditional is false, its children are not processed, but are +syntactically interpreted to preserve the integrity of the input +document. +Thus, +.Pp +.D1 \&.if t .ig +.Pp +will discard the +.Sq \&.ig , +which may lead to interesting results, but +.Pp +.D1 \&.if t .if t \e{\e +.Pp +will continue to syntactically interpret to the block close of the final +conditional. +Sub-conditionals, in this case, obviously inherit the truth value of +the parent. +.Pp +If the +.Ar body +section is begun by an escaped brace +.Sq \e{ , +scope continues until the end of the input line containing the +matching closing-brace escape sequence +.Sq \e} . +If the +.Ar body +is not enclosed in braces, scope continues until the end of the line. +If the +.Ar condition +is followed by a +.Ar body +on the same line, whether after a brace or not, then requests and macros +.Em must +begin with a control character. +It is generally more intuitive, in this case, to write +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Pf . Ar request +.Pf . No \e} +.Ed +.Pp +than having the request or macro follow as +.Pp +.D1 Pf . Ic \&if Ar condition Pf \e{. Ar request +.Pp +The scope of a conditional is always parsed, but only executed if the +conditional evaluates to true. +.Pp +Note that the +.Sq \e} +is converted into a zero-width escape sequence if not passed as a +standalone macro +.Sq \&.\e} . +For example, +.Pp +.D1 \&.Fl a \e} b +.Pp +will result in +.Sq \e} +being considered an argument of the +.Sq \&Fl +macro. +.It Ic \&ig Op Ar endmacro +Ignore input. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&ig +.Ar ignored text +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&ig Ar endmacro +.Ar ignored text +.Pf . Ar endmacro +.Ed +.Pp +In the first case, input is ignored until a +.Sq \&.. +request is encountered on its own line. +In the second case, input is ignored until the specified +.Sq Pf . Ar endmacro +is encountered. +Do not use the escape character +.Sq \e +anywhere in the definition of +.Ar endmacro ; +it would cause very strange behaviour. +.Pp +When the +.Ar endmacro +is a roff request or a roff macro, like in +.Pp +.D1 \&.ig if +.Pp +the subsequent invocation of +.Ic \&if +will first terminate the +.Ar ignored text , +then be invoked as usual. +Otherwise, it only terminates the +.Ar ignored text , +and arguments following it or the +.Sq \&.. +request are discarded. +.It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change indentation. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.It Ic \&index Ar register stringname substring +Find a substring in a string. +This is a Heirloom extension and currently unsupported. +.It Ic \&it Ar expression macro +Set an input line trap. +The named +.Ar macro +will be invoked after processing the number of input text lines +specified by the numerical +.Ar expression . +While evaluating the +.Ar expression , +the unit suffixes described below +.Sx Scaling Widths +are ignored. +.It Ic \&itc Ar expression macro +Set an input line trap, not counting lines ending with \ec. +Currently unsupported. +.It Ic \&IX Ar class keystring +To support the generation of a table of contents, +.Xr pod2man 1 +emits this user-defined macro, usually without defining it. +To avoid reporting large numbers of spurious errors, +.Xr mandoc 1 +ignores it. +.It Ic \&kern Op Cm 1 | 0 +Switch kerning on or off. +Currently ignored. +.It Ic \&kernafter Ar font char ... afmunits ... +Increase kerning after some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernbefore Ar font char ... afmunits ... +Increase kerning before some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernpair Ar font char ... font char ... afmunits +Add a kerning pair to the kerning table. +This is a Heirloom extension and currently ignored. +.It Ic \&lc Op Ar glyph +Define a leader repetition character. +Currently unsupported. +.It Ic \&lc_ctype Ar localename +Set the +.Dv LC_CTYPE +locale. +This is a Heirloom extension and currently unsupported. +.It Ic \&lds Ar macroname string +Define a local string. +This is a Heirloom extension and currently unsupported. +.It Ic \&length Ar register string +Count the number of input characters in a string. +Currently unsupported. +.It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax +Dynamic letter spacing and reshaping. +This is a Heirloom extension and currently ignored. +.It Ic \&lf Ar lineno Op Ar filename +Change the line number for error messages. +Ignored because insecure. +.It Ic \&lg Op Cm 1 | 0 +Switch the ligature mechanism on or off. +Currently ignored. +.It Ic \&lhang Ar font char ... afmunits +Hang characters at left margin. +This is a Heirloom extension and currently ignored. +.It Ic \&linetabs Op Cm 1 | 0 +Enable or disable line-tabs mode. +This is a groff extension and currently unsupported. +.It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change the output line length. +If the +.Ar width +argument is omitted, the line length is reset to its previous value. +The default setting for terminal output is 78n. +If a sign is given, the line length is added to or subtracted from; +otherwise, it is set to the provided value. +Using this request in new manuals is discouraged for several reasons, +among others because it overrides the +.Xr mandoc 1 +.Fl O Cm width +command line option. +.It Ic \&lnr Ar registername Xo +.Oo Cm + Ns | Ns Cm \- Oc Ns Ar value +.Op Ar increment +.Xc +Set local number register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lnrf Ar registername Xo +.Oo Cm + Ns | Ns Cm \- Oc Ns Ar value +.Op Ar increment +.Xc +Set local floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lpfx Ar string +Set a line prefix. +This is a Heirloom extension and currently unsupported. +.It Ic \&ls Op Ar factor +Set line spacing. +It takes one integer argument specifying the vertical distance of +subsequent output text lines measured in v units. +Currently ignored. +.It Ic \&lsm Ar macroname +Set a leading spaces trap. +This is a groff extension and currently unsupported. +.It Ic \< Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Set title line length. +Currently ignored. +.It Ic \&mc Ar glyph Op Ar dist +Print margin character in the right margin. +The +.Ar dist +is currently ignored; instead, 1n is used. +.It Ic \&mediasize Ar media +Set the device media size. +This is a Heirloom extension and currently ignored. +.It Ic \&minss Ar width +Set minimum word space. +This is a Heirloom extension and currently ignored. +.It Ic \&mk Op Ar register +Mark vertical position. +Currently ignored. +.It Ic \&mso Ar filename +Load a macro file using the search path. +Ignored because insecure. +.It Ic \&na +Disable adjusting without changing the adjustment mode. +Currently ignored. +.It Ic \&ne Op Ar height +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +Currently ignored. +.It Ic \&nf +Break the output line and switch to no-fill mode. +Subsequent input lines are kept together on the same output line +even when exceeding the right margin, +and line breaks in subsequent input cause output line breaks. +This request is implied by the +.Xr mdoc 7 +.Ic \&Bd Fl unfilled +and +.Ic \&Bd Fl literal +macros and by the +.Xr man 7 +.Ic \&EX +macro. +The +.Ic \&fi +request switches back to the default fill mode. +.It Ic \&nh +Turn off automatic hyphenation mode. +Currently ignored. +.It Ic \&nhychar Ar char ... +Define hyphenation-inhibiting characters. +This is a Heirloom extension and currently ignored. +.It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent +Print line numbers. +Currently unsupported. +.It Ic \&nn Op Ar number +Temporarily turn off line numbering. +Currently unsupported. +.It Ic \&nop Ar body +Execute the rest of the input line as a request, macro, or text line, +skipping the +.Ic \&nop +request and any space characters immediately following it. +This is mostly used to indent text lines inside macro definitions. +.It Ic \&nr Ar registername Xo +.Oo Cm + Ns | Ns Cm \- Oc Ns Ar expression +.Op Ar stepsize +.Xc +Define or change the number register with the given +.Ar registername . +A register can store an integer number. +For the syntax of +.Ar expression , +see +.Sx Numerical expressions +below. +If it is prefixed by a sign, the register will be +incremented or decremented instead of assigned to. +.Pp +Once set, the value of a number register can be interpolated using the +.Ic \en +escape sequence. +The +.Ar stepsize +is used by the +.Ic \en+ +auto-increment feature. +It remains unchanged when omitted while changing an existing register, +and it defaults to 0 when defining a new register. +.Pp +Some number registers can be read to inspect parser state, +and some can be changed to influence formatting. +For details about individual registers, see the +.Sx NUMBER REGISTER REFERENCE +below. +.It Xo +.Ic \&nrf Ar registername Oo Cm + Ns | Ns Cm \- Oc Ns Ar expression +.Op Ar increment +.Xc +Define or change a floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&nroff +Force nroff mode. +This is a groff extension and currently ignored. +.It Ic \&ns +Turn on no-space mode. +Currently ignored. +.It Ic \&nx Op Ar filename +Abort processing of the current input file and process another one. +Ignored because insecure. +.It Ic \&open Ar stream file +Open a file for writing. +Ignored because insecure. +.It Ic \&opena Ar stream file +Open a file for appending. +Ignored because insecure. +.It Ic \&os +Output saved vertical space. +Currently ignored. +.It Ic \&output Ar string +Output directly to intermediate output. +Not supported. +.It Ic \&padj Op Cm 1 | 0 +Globally control paragraph-at-once adjustment. +This is a Heirloom extension and currently ignored. +.It Ic \&papersize Ar media +Set the paper size. +This is a Heirloom extension and currently ignored. +.It Ic \&pc Op Ar char +Change the page number character. +Currently ignored. +.It Ic \&pev +Print environments. +This is a groff extension and currently ignored. +.It Ic \&pi Ar command +Pipe output to a shell command. +Ignored because insecure. +.It Ic \&PI +Low-level request used by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change page length. +Currently ignored. +.It Ic \&pm +Print names and sizes of macros, strings, and diversions +to standard error output. +Currently ignored. +.It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number +Change the page number of the next page. +Currently ignored. +.It Ic \&pnr +Print all number registers on standard error output. +Currently ignored. +.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset +Set a horizontal page offset. +If no argument is specified, the page offset is reverted to its +previous value. +If a sign is specified, the new page offset is calculated relative +to the current one; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size +Change point size. +Currently ignored. +.It Ic \&psbb Ar filename +Retrieve the bounding box of a PostScript file. +Currently unsupported. +.It Ic \&pshape Ar indent length ... +Set a special shape for the current paragraph. +This is a Heirloom extension and currently unsupported. +.It Ic \&pso Ar command +Include output of a shell command. +Ignored because insecure. +.It Ic \&ptr +Print the names and positions of all traps on standard error output. +This is a groff extension and currently ignored. +.It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change post-vertical spacing. +This is a groff extension and currently ignored. +.It Ic \&rchar Ar glyph ... +Remove glyph definitions. +Currently unsupported. +.It Ic \&rd Op Ar prompt Op Ar argument ... +Read from standard input. +Currently ignored. +.It Ic \&recursionlimit Ar maxrec maxtail +Set the maximum stack depth for recursive macros. +This is a Heirloom extension and currently ignored. +.It Ic \&return Op Ar twice +Exit the presently executed macro and return to the caller. +The argument is currently ignored. +.It Ic \&rfschar Ar font glyph ... +Remove font-specific fallback glyph definitions. +Currently unsupported. +.It Ic \&rhang Ar font char ... afmunits +Hang characters at right margin. +This is a Heirloom extension and currently ignored. +.It Ic \&rj Op Ar N +Justify the next +.Ar N +input lines to the right margin without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends right adjustment. +.It Ic \&rm Ar macroname +Remove a request, macro or string. +.It Ic \&rn Ar oldname newname +Rename a request, macro, diversion, or string. +In +.Xr mandoc 1 , +user-defined macros, +.Xr mdoc 7 +and +.Xr man 7 +macros, and user-defined strings can be renamed, but renaming of +predefined strings and of +.Nm +requests is not supported, and diversions are not implemented at all. +.It Ic \&rnn Ar oldname newname +Rename a number register. +Currently unsupported. +.It Ic \&rr Ar register +Remove a number register. +.It Ic \&rs +End no-space mode. +Currently ignored. +.It Ic \&rt Op Ar dist +Return to marked vertical position. +Currently ignored. +.It Ic \&schar Ar glyph Op Ar string +Define global fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&sentchar Ar char ... +Define sentence-ending characters. +This is a Heirloom extension and currently ignored. +.It Ic \&shc Op Ar glyph +Change the soft hyphen character. +Currently ignored. +.It Ic \&shift Op Ar number +Shift macro arguments +.Ar number +times, by default once: \e\e$i becomes what \e\e$i+number was. +Also decrement \en(.$ by +.Ar number . +.It Ic \&sizes Ar size ... +Define permissible point sizes. +This is a groff extension and currently ignored. +.It Ic \&so Ar filename +Include a source file. +The file is read and its contents processed as input in place of the +.Ic \&so +request line. +To avoid inadvertent inclusion of unrelated files, +.Xr mandoc 1 +only accepts relative paths not containing the strings +.Qq ../ +and +.Qq /.. . +.Pp +This request requires +.Xr man 1 +to change to the right directory before calling +.Xr mandoc 1 , +per convention to the root of the manual tree. +Typical usage looks like: +.Pp +.Dl \&.so man3/Xcursor.3 +.Pp +As the whole concept is rather fragile, the use of +.Ic \&so +is discouraged. +Use +.Xr ln 1 +instead. +.It Ic \&sp Op Ar height +Break the output line and emit vertical space. +The argument follows the syntax of +.Sx Scaling Widths +and defaults to one blank line +.Pq Li 1v . +.It Ic \&spacewidth Op Cm 1 | 0 +Set the space width from the font metrics file. +This is a Heirloom extension and currently ignored. +.It Ic \&special Op Ar font ... +Define a special font. +This is a groff extension and currently ignored. +.It Ic \&spreadwarn Op Ar width +Warn about wide spacing between words. +Currently ignored. +.It Ic \&ss Ar wordspace Op Ar sentencespace +Set space character size. +Currently ignored. +.It Ic \&sty Ar position style +Associate style with a font position. +This is a groff extension and currently ignored. +.It Ic \&substring Ar stringname startpos Op Ar endpos +Replace a user-defined string with a substring. +Currently unsupported. +.It Ic \&sv Op Ar height +Save vertical space. +Currently ignored. +.It Ic \&sy Ar command +Execute shell command. +Ignored because insecure. +.It Ic \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Ic \&TS . +.It Ic \&ta Op Ar width ... Op Cm T Ar width ... +Set tab stops. +Each +.Ar width +argument follows the syntax of +.Sx Scaling Widths . +If prefixed by a plus sign, it is relative to the previous tab stop. +The arguments after the +.Cm T +marker are used repeatedly as often as needed; for each reuse, +they are taken relative to the last previously established tab stop. +When +.Ic \&ta +is called without arguments, all tab stops are cleared. +.It Ic \&tc Op Ar glyph +Change tab repetition character. +Currently unsupported. +.It Ic \&TE +End a table context. +See +.Ic \&TS . +.It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Break the output line and indent the next output line by +.Ar width . +If a sign is specified, the temporary indentation is calculated +relative to the current indentation; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&tkf Ar font minps width1 maxps width2 +Enable track kerning for a font. +Currently ignored. +.It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap +Print a title line. +Currently unsupported. +.It Ic \&tm Ar string +Print to standard error output. +Currently ignored. +.It Ic \&tm1 Ar string +Print to standard error output, allowing leading blanks. +This is a groff extension and currently ignored. +.It Ic \&tmc Ar string +Print to standard error output without a trailing newline. +This is a groff extension and currently ignored. +.It Ic \&tr Ar glyph glyph ... +Output character translation. +The first glyph in each pair is replaced by the second one. +Character escapes can be used; for example, +.Pp +.Dl tr \e(xx\e(yy +.Pp +replaces all invocations of \e(xx with \e(yy. +.It Ic \&track Ar font minps width1 maxps width2 +Static letter space tracking. +This is a Heirloom extension and currently ignored. +.It Ic \&transchar Ar char ... +Define transparent characters for sentence-ending. +This is a Heirloom extension and currently ignored. +.It Ic \&trf Ar filename +Output the contents of a file, disallowing invalid characters. +This is a groff extension and ignored because insecure. +.It Ic \&trimat Ar left top width height +Set the TrimBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&trin Ar glyph glyph ... +Output character translation, ignored by +.Ic \&asciify . +Currently unsupported. +.It Ic \&trnt Ar glyph glyph ... +Output character translation, ignored by \e!. +Currently unsupported. +.It Ic \&troff +Force troff mode. +This is a groff extension and currently ignored. +.It Ic \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 7 +for a description of the tbl language. +.It Ic \&uf Ar font +Globally set the underline font. +Currently ignored. +.It Ic \&ul Op Ar N +Underline next +.Ar N +input lines. +Currently ignored. +.It Ic \&unformat Ar divname +Unformat spaces and tabs in a diversion. +Currently unsupported. +.It Ic \&unwatch Ar macroname +Disable notification for string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&unwatchn Ar register +Disable notification for register. +This is a Heirloom extension and currently ignored. +.It Ic \&vpt Op Cm 1 | 0 +Enable or disable vertical position traps. +This is a groff extension and currently ignored. +.It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change vertical spacing. +Currently ignored. +.It Ic \&warn Ar flags +Set warning level. +Currently ignored. +.It Ic \&warnscale Ar si +Set the scaling indicator used in warnings. +This is a groff extension and currently ignored. +.It Ic \&watch Ar macroname +Notify on change of string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&watchlength Ar maxlength +On change, report the contents of macros and strings +up to the specified length. +This is a Heirloom extension and currently ignored. +.It Ic \&watchn Ar register +Notify on change of register. +This is a Heirloom extension and currently ignored. +.It Ic \&wh Ar dist Op Ar macroname +Set a page location trap. +Currently unsupported. +.It Ic \&while Ar condition body +Repeated execution while a +.Ar condition +is true, with syntax similar to +.Ic \&if . +Currently implemented with two restrictions: cannot nest, +and each loop must start and end in the same scope. +.It Ic \&write Oo \(dq Oc Ns Ar string +Write to an open file. +Ignored because insecure. +.It Ic \&writec Oo \(dq Oc Ns Ar string +Write to an open file without appending a newline. +Ignored because insecure. +.It Ic \&writem Ar macroname +Write macro or string to an open file. +Ignored because insecure. +.It Ic \&xflag Ar level +Set the extension level. +This is a Heirloom extension and currently ignored. +.El +.Ss Numerical expressions +The +.Ic \&nr , +.Ic \&if , +and +.Ic \&ie +requests accept integer numerical expressions as arguments. +These are always evaluated using the C +.Vt int +type; integer overflow works the same way as in the C language. +Numbers consist of an arbitrary number of digits +.Sq 0 +to +.Sq 9 +prefixed by an optional sign +.Sq + +or +.Sq - . +Each number may be followed by one optional scaling unit described below +.Sx Scaling Widths . +The following equations hold: +.Bd -literal -offset indent +1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 +254c = 100i = 24000u = 24000 +1f = 65536u = 65536 +.Ed +.Pp +The following binary operators are implemented. +Unless otherwise stated, they behave as in the C language: +.Pp +.Bl -tag -width 2n -compact +.It Ic + +addition +.It Ic - +subtraction +.It Ic * +multiplication +.It Ic / +division +.It Ic % +remainder of division +.It Ic < +less than +.It Ic > +greater than +.It Ic == +equal to +.It Ic = +equal to, same effect as +.Ic == +(this differs from C) +.It Ic <= +less than or equal to +.It Ic >= +greater than or equal to +.It Ic <> +not equal to (corresponds to C +.Ic != ; +this one is of limited portability, it is supported by Heirloom roff, +but not by groff) +.It Ic & +logical and (corresponds to C +.Ic && ) +.It Ic \&: +logical or (corresponds to C +.Ic || ) +.It Ic <? +minimum (not available in C) +.It Ic >? +maximum (not available in C) +.El +.Pp +There is no concept of precedence; evaluation proceeds from left to right, +except when subexpressions are enclosed in parentheses. +Inside parentheses, whitespace is ignored. +.Sh ESCAPE SEQUENCE REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following escape sequences. +In +.Xr mdoc 7 +and +.Xr man 7 +documents, using escape sequences is discouraged except for those +described in the +.Sx LANGUAGE SYNTAX +section above. +.Pp +A backslash followed by any character not listed here +simply prints that character itself. +.Bl -tag -width Ds +.It Ic \e<newline> +A backslash at the end of an input line can be used to continue the +logical input line on the next physical input line, joining the text +on both lines together as if it were on a single input line. +.It Ic \e<space> +The escape sequence backslash-space +.Pq Sq \e\ \& +is an unpaddable space-sized non-breaking space character; see +.Sx Whitespace +and +.Xr mandoc_char 7 . +.It Ic \e! +Embed text up to and including the end of the input line into the +current diversion or into intermediate output without interpreting +requests, macros, and escapes. +Currently unsupported. +.It Ic \e\(dq +The rest of the input line is treated as +.Sx Comments . +.It Ic \e# +Line continuation with comment. +Discard the rest of the physical input line and continue the logical +input line on the next physical input line, joining the text on +both lines together as if it were on a single input line. +This is a groff extension. +.It Ic \e$ Ns Ar arg +Macro argument expansion, see +.Ic \&de . +.It Ic \e% +Hyphenation allowed at this point of the word; ignored by +.Xr mandoc 1 . +.It Ic \e& +Non-printing zero-width character, +often used for various kinds of escaping; see +.Sx Whitespace , +.Xr mandoc_char 7 , +and the +.Dq MACRO SYNTAX +and +.Dq Delimiters +sections in +.Xr mdoc 7 . +.It Ic \e\(aq +Acute accent special character; use +.Ic \e(aa +instead. +.It Ic \e( Ns Ar cc +.Sx Special Characters +with two-letter names, see +.Xr mandoc_char 7 . +.It Ic \e) +Zero-width space transparent to end-of-sentence detection; +ignored by +.Xr mandoc 1 . +.It Ic \e*[ Ns Ar name Ns Ic \&] +Interpolate the string with the +.Ar name . +For short names, there are variants +.Ic \e* Ns Ar c +and +.Ic \e*( Ns Ar cc . +.Pp +One string is predefined on the +.Nm +language level: +.Ic \e*(.T +expands to the name of the output device, +for example ascii, utf8, ps, pdf, html, or markdown. +.Pp +Macro sets traditionally predefine additional strings which are not +portable and differ across implementations. +Those supported by +.Xr mandoc 1 +are listed in +.Xr mandoc_char 7 . +.Pp +Strings can be defined, changed, and deleted with the +.Ic \&ds , +.Ic \&as , +and +.Ic \&rm +requests. +.It Ic \e, +Left italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e- +Special character +.Dq mathematical minus sign ; +see +.Xr mandoc_char 7 +for details. +.It Ic \e/ +Right italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e: +Breaking the line is allowed at this point of the word +without inserting a hyphen. +.It Ic \e? +Embed the text up to the next +.Ic \e? +into the current diversion without interpreting requests, macros, +and escapes. +This is a groff extension and currently unsupported. +.It Ic \e[ Ns Ar name Ns Ic \&] +.Sx Special Characters +with names of arbitrary length, see +.Xr mandoc_char 7 . +.It Ic \e^ +One-twelfth em half-narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e_ +Underline special character; use +.Ic \e(ul +instead. +.It Ic \e` +Grave accent special character; use +.Ic \e(ga +instead. +.It Ic \e{ +Begin conditional input; see +.Ic \&if . +.It Ic \e\(ba +One-sixth em narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e} +End conditional input; see +.Ic \&if . +.It Ic \e~ +Paddable non-breaking space character. +.It Ic \e0 +Digit width space character. +.It Ic \eA\(aq Ns Ar name Ns Ic \(aq +Interpolate +.Sq 1 +if +.Ar name +is a syntactically valid identifier that can be used +as a name for a macro or user-defined string, or +.Sq 0 +otherwise. +This is a thoroughly non-portable groff extension. +Heirloom troff uses the same escape sequence with the same syntax +for a completely different purpose, +defining a hyperlink target position, also called an +.Dq anchor , +with the given +.Ar name . +The Heirloom semantics is not supported by +.Xr mandoc 1 . +.It Ic \ea +Leader character; ignored by +.Xr mandoc 1 . +.It Ic \eB\(aq Ns Ar string Ns Ic \(aq +Interpolate +.Sq 1 +if +.Ar string +conforms to the syntax of +.Sx Numerical expressions +explained above or +.Sq 0 +otherwise. +.It Ic \eb\(aq Ns Ar string Ns Ic \(aq +Bracket building function; ignored by +.Xr mandoc 1 . +.It Ic \eC\(aq Ns Ar name Ns Ic \(aq +.Sx Special Characters +with names of arbitrary length. +.It Ic \ec +When encountered at the end of an input text line, +the next input text line is considered to continue that line, +even if there are request or macro lines in between. +No whitespace is inserted. +.It Ic \eD\(aq Ns Ar string Ns Ic \(aq +Draw graphics function; ignored by +.Xr mandoc 1 . +.It Ic \ed +Move down by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eE +Escape character intended to not be interpreted in copy mode. +In +.Xr mandoc 1 , +it currently does the same as +.Ic \e +itself. +.It Ic \ee +Backslash special character. +.It Ic \eF[ Ns Ar name Ns Ic \&] +Switch font family (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eF Ns Ar c +and +.Ic \eF( Ns Ar cc . +.It Ic \ef[ Ns Ar name Ns Ic \&] +Switch to the font +.Ar name , +see +.Sx Font Selection . +For short names, there are variants +.Ic \ef Ns Ar c +and +.Ic \ef( Ns Ar cc . +An empty name +.Ic \ef[] +defaults to +.Ic \efP . +.It Ic \eg[ Ns Ar name Ns Ic \&] +Interpolate the format of a number register; ignored by +.Xr mandoc 1 , +which interpolates an empty string instead. +For short names, there are variants +.Ic \eg Ns Ar c +and +.Ic \eg( Ns Ar cc . +.It Ic \eH\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Set the height of the current font; ignored by +.Xr mandoc 1 . +.It Ic \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns Ic \(aq +Horizontal motion. +If the vertical bar is given, the motion is relative to the current +indentation. +Otherwise, it is relative to the current position. +The default scaling unit is +.Cm m . +.It Ic \ek[ Ns Ar name Ns Ic \&] +Mark horizontal input place in register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \ek Ns Ar c +and +.Ic \ek( Ns Ar cc . +.It Ic \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns Ic \(aq +Vertical line drawing function; ignored by +.Xr mandoc 1 . +.It Ic \el\(aq Ns Ar width Ns Oo Ar c Oc Ns Ic \(aq +Draw a horizontal line of +.Ar width +using the glyph +.Ar c . +.It Ic \eM[ Ns Ar name Ns Ic \&] +Set fill (background) color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eM Ns Ar c +and +.Ic \eM( Ns Ar cc . +.It Ic \em[ Ns Ar name Ns Ic \&] +Set glyph drawing color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \em Ns Ar c +and +.Ic \em( Ns Ar cc . +.It Ic \eN\(aq Ns Ar number Ns Ic \(aq +Character +.Ar number +on the current font. +.It Ic \en Ns Oo +|- Oc Ns Ic \&[ Ns Ar name Ns Ic \&] +Interpolate the number register +.Ar name . +If the register is not yet defined, +it is automatically initialised to zero before interpolation. +For short names, there are variants +.Ic \en Ns Ar c +and +.Ic \en( Ns Ar cc . +If the optional sign is specified, +the register is first incremented or decremented by the +.Ar stepsize +that was specified in the relevant +.Ic \&nr +request, and the changed value is interpolated. +For the names of predefined registers, see the +.Sx NUMBER REGISTER REFERENCE +below. +.It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&] +Suppress output. +This is a groff extension and currently unsupported. +With an argument of +.Ic 1 , 2 , 3 , +or +.Ic 4 , +it is ignored. +.It Ic \eo\(aq Ns Ar string Ns Ic \(aq +Overstrike, writing all the characters contained in the +.Ar string +to the same output position. +In terminal and HTML output modes, +only the last one of the characters is visible. +.It Ic \ep +Break the output line at the end of the current word. +.It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq +Set number register; ignored by +.Xr mandoc 1 . +.It Ic \er +Reverse line feed: move up by one output line. +Currently unsupported. +.It Ic \eS\(aq Ns Ar number Ns Ic \(aq +Slant output; ignored by +.Xr mandoc 1 . +.It Ic \es\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Change point size; ignored by +.Xr mandoc 1 . +Alternative forms +.Ic \es Ns Oo +|- Oc Ns Ar n , +.Ic \es Ns Oo +|- Oc Ns Ic \(aq Ns Ar number Ns Ic \(aq , +.Ic \es[ Ns Oo +|- Oc Ns Ar number Ns Ic \&] , +and +.Ic \es Ns Oo +|- Oc Ns Ic \&[ Ns Ar number Ns Ic \&] +are also parsed and ignored. +.It Ic \et +Horizontal tab; ignored by +.Xr mandoc 1 . +.It Ic \eu +Move up by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eV[ Ns Ar name Ns Ic \&] +Interpolate an environment variable. +For short names, there are variants +.Ic \eV Ns Ar c +and +.Ic \eV( Ns Ar cc . +This escape sequence is intentionally unsupported; +.Xr mandoc 1 +prints the string +.Dq Pf $ Brq Ar name +instead of inspecting the environment. +.It Ic \ev\(aq Ns Ar number Ns Ic \(aq +Vertical motion; ignored by +.Xr mandoc 1 . +.It Ic \ew\(aq Ns Ar string Ns Ic \(aq +Interpolate the width of the +.Ar string . +The +.Xr mandoc 1 +implementation assumes that after expansion of user-defined strings, the +.Ar string +only contains normal characters, characters expressed as escape sequences, +and zero-width escape sequences, and that each +character has a width of 24 basic units. +.It Ic \eX\(aq Ns Ar string Ns Ic \(aq +Output +.Ar string +as device control function; ignored in nroff mode and by +.Xr mandoc 1 . +.It Ic \ex\(aq Ns Ar number Ns Ic \(aq +Extra line space function; ignored by +.Xr mandoc 1 . +.It Ic \eY[ Ns Ar name Ns Ic \&] +Output a string as a device control function; ignored in nroff mode and by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eY Ns Ar c +and +.Ic \eY( Ns Ar cc . +.It Ic \eZ\(aq Ns Ar string Ns Ic \(aq +Print +.Ar string +with zero width and height; ignored by +.Xr mandoc 1 . +.It Ic \ez +Output the next character without advancing the cursor position. +.El +.Sh NUMBER REGISTER REFERENCE +In +.Xr mdoc 7 +and +.Xr man 7 +documents, using registers is discouraged. +For compatibility with legacy documents, the +.Xr mandoc 1 +.Nm +parser recognises the following names of read-only registers: +.Bl -tag -width Ds +.It Cm .$ +The number of arguments of the innermost user-defined macro +currently being called, or 0 by default. +The +.Ic shift +request decrements the value of this register. +.It Cm .A +Whether ASCII approximation mode is on; +.Xr mandoc 1 +always returns 0, meaning off. +.It Cm .g +Whether the formatter claims groff compatibility; +.Xr mandoc 1 +always returns 1, meaning yes. +.It Cm .H +The minimum horizontal movement in basic units; +.Xr mandoc 1 +always returns 24, corresponding to one character position. +.It Cm .j +The current line adjustment mode; +.Xr mandoc 1 +always returns 0, meaning flush left. +.It Cm .l +The line length in basic units; +.Xr mandoc 1 +always returns 78 * 24, corresponding to 78 characters per line. +.It Cm \&.T +Whether an output device has been selected; +.Xr mandoc 1 +always returns 1, meaning yes. +.It Cm .V +The minimum vertical movement in basic units; +.Xr mandoc 1 +always returns 40, corresponding to one line height. +.El +.Pp +The +.Cm nS +register is handled specially. +If set to a positive integer value, certain +.Xr mdoc 7 +macros behave in the same way as in the +.Em SYNOPSIS +section. +If set to 0, these macros behave in the same way as outside the +.Em SYNOPSIS +section, even when called within the +.Em SYNOPSIS +section itself. +Starting a new +.Xr mdoc 7 +section with the +.Ic \&Sh +macro resets this register. +.Pp +Full +.Nm +implementations support large numbers of additional predefined registers. +While the +.Ic \&nr +request supports setting and the +.Ic \en +escape sequence supports inspecting arbitrary registers, +.Xr mandoc 1 +only defines the few registers listed above by default. +All other registers are undefined by default and yield 0 when interpolated. +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of the +.Nm +language is incomplete. +Major unimplemented features include: +.Pp +.Bl -dash -compact +.It +For security reasons, +.Xr mandoc 1 +never reads or writes external files except via +.Ic \&so +requests with safe relative paths. +.It +There is no automatic hyphenation and no support for the +.Ic \&ad +line adjustment request. +Except when the +.Ic \&ce +or +.Ic \&rj +requests or the +.Xr tbl 7 +cell specifications +.Cm c , +.Cm n , +or +.Cm r +or the table option +.Cm center +are used, output is always set flush-left. +.It +Support for setting tabulator and leader characters is missing, and the +.Ic \&in +indentation request is not supported in +.Xr mdoc 7 +input files. +.It +Width measurements are implemented in a crude way +and often yield wrong results. +Support for explicit movement requests and escapes is limited. +.It +There is no concept of output pages, no support for floats, +graphics drawing, and picture inclusion; +terminal output is always continuous. +.It +Requests regarding color, font families, font sizes, +and glyph manipulation are ignored. +Font support is very limited. +Kerning is not implemented, and no ligatures are produced. +.It +The +.Qq \(aq +macro control character does not suppress output line breaks. +.It +Diversions and environments are not implemented, +and support for traps is very incomplete. +.It +Use of macros is not supported inside +.Xr tbl 7 +code. +.El +.Pp +The special semantics of the +.Cm nS +number register is an idiosyncrasy of +.Ox +manuals and not supported by other +.Xr mdoc 7 +implementations. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr tbl 7 +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%I AT&T Bell Laboratories +.%T Troff User's Manual +.%R Computing Science Technical Report +.%N 54 +.%C Murray Hill, New Jersey +.%D 1976 and 1992 +.%U http://www.kohala.com/start/troff/cstr54.ps +.Re +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%A Gunnar Ritter +.%T Heirloom Documentation Tools Nroff/Troff User's Manual +.%D September 17, 2007 +.%U http://heirloom.sourceforge.net/doctools/troff.pdf +.Re +.Rs +.%A James Clark +.%A Werner Lemberg +.%A G. Branden Robinson +.%I Free Software Foundation, Inc. +.%T The GNU Troff Manual +.%D 1999\(en2023 +.%U https://www.gnu.org/software/groff/manual/ +.Re +.Sh HISTORY +The RUNOFF typesetting system, whose input forms the basis for +.Nm , +was written in MAD and FAP for the CTSS operating system by Jerome E. +Saltzer in 1964. +Doug McIlroy rewrote it in BCPL in 1969, renaming it +.Nm . +Dennis M. Ritchie rewrote McIlroy's +.Nm +in PDP-11 assembly for +.At v1 , +Joseph F. Ossanna improved roff and renamed it nroff +for +.At v2 , +then ported nroff to C as troff, which Brian W. Kernighan released with +.At v7 . +In 1989, James Clark re-implemented troff in C++, naming it groff. +.Sh AUTHORS +.An -nosplit +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/static/openbsd/man7/script.7 b/static/openbsd/man7/script.7 new file mode 100644 index 00000000..0905a2b0 --- /dev/null +++ b/static/openbsd/man7/script.7 @@ -0,0 +1,379 @@ +.\" $OpenBSD: script.7,v 1.9 2022/02/06 00:29:02 jsg Exp $ +.\" +.\" $NetBSD: script.7,v 1.1 2005/05/07 02:20:34 perry Exp $ +.\" +.\" Copyright (c) 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This document was originally contributed to The NetBSD Foundation +.\" by Perry E. Metzger of Metzger, Dowdeswell & Co. LLC. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: February 6 2022 $ +.Dt SCRIPT 7 +.Os +.Sh NAME +.Nm script +.Nd interpreter script execution +.Sh DESCRIPTION +The system is capable of treating a text file containing commands +intended for an interpreter, such as +.Xr sh 1 +or +.Xr awk 1 , +as an executable program. +.Pp +An +.Dq interpreter script +is a file which has been set executable (see +.Xr chmod 2 ) +and which has a first line of the form: +.Pp +.D1 Li #! Ar pathname Op Ar argument +.Pp +The +.Sq #! +must appear as the first two characters of the file. +A space between the +.Sq #! +and +.Ar pathname +is optional. +At most one +.Ar argument +may follow +.Ar pathname , +and the length of the entire line is limited (see below). +.Pp +If such a file is executed (such as via the +.Xr execve 2 +system call), the interpreter specified by the +.Ar pathname +is executed by the system. +(The +.Ar pathname +is executed without regard to the +.Ev PATH +variable, so in general +.Ar pathname +should be an absolute path.) +.Pp +The arguments passed to the interpreter will be as follows. +.Va argv[0] +will be the path to the interpreter itself, as specified on the first +line of the script. +If there is an +.Ar argument +following +.Ar pathname +on the first line of the script, it will be passed as +.Va argv[1] . +The subsequent elements of +.Va argv +will be the path to the interpreter script file itself (i.e. the +original +.Va argv[0] ) +followed by any further arguments passed when +.Xr execve 2 +was invoked to execute the script file. +.Pp +By convention, it is expected that an interpreter will open the script +file passed as an argument and process the commands within it. +Typical interpreters treat +.Sq # +as a comment character, and thus will ignore the initial line of the script +because it begins +.Sq #! , +but there is no requirement for this per se. +.Pp +On +.Ox , +the length of the interpreter line following the +.Sq #! +is limited to +.Dv MAXINTERP , +as defined in +.In sys/param.h . +Other operating systems impose different limits on the length of +the +.Sq #! +line (see below). +.Pp +Note that the interpreter may not itself be an interpreter script. +If +.Ar pathname +does not point to an executable binary, execution of the interpreter +script will fail. +.Ss Trampolines and Portable Scripts +Different operating systems often have interpreters located in +different locations, and the kernel executes the passed interpreter +without regard to the setting of environment variables such as +.Ev PATH . +This makes it somewhat challenging to set the +.Sq #! +line of a script so that it will run identically on different systems. +.Pp +Since the +.Xr env 1 +utility executes a command passed to it on its command line, it is +often used as a +.Dq trampoline +to render scripts portable. +If the leading line of a script reads +.Pp +.Dl #! /usr/bin/env interp +.Pp +then the +.Xr env 1 +command will execute the +.Dq interp +command it finds in its +.Ev PATH , +passing on to it all subsequent arguments with which it itself was called. +Since +.Pa /usr/bin/env +is found on almost all +.Tn POSIX +style systems, this trick is frequently exploited by authors who need +a script to execute without change on multiple systems. +.Ss Historical Note: Scripts without `#!' +Shell scripts predate the invention of the +.Sq #! +convention, which is implemented in the kernel. +In the days of +.At v7 , +there was only one interpreter used on the system, +.Pa /bin/sh , +and the shell treated any file that failed to execute with an +.Er ENOEXEC +error +(see +.Xr intro 2 ) +as a shell script. +.Pp +Most shells (such as +.Xr sh 1 ) +and certain other facilities (including +.Xr execlp 3 +and +.Xr execvp 3 ) +still pass interpreter scripts that do not include the +.Sq #! +(and thus fail to execute with +.Er ENOEXEC ) +to +.Pa /bin/sh . +.Pp +As this behavior is implemented outside the kernel, there is no +mechanism that forces it to be respected by all programs that execute +other programs. +It is thus not completely reliable. +It is therefore important to always include +.Pp +.Dl #!/bin/sh +.Pp +in front of Bourne shell scripts, and to treat the traditional +behavior as obsolete. +.Sh EXAMPLES +Suppose that an executable binary exists in +.Pa /bin/interp +and that the file +.Pa /tmp/script +contains: +.Bd -literal -offset indent +#!/bin/interp -arg + +[...] +.Ed +.Pp +and that +.Pa /tmp/script +is set mode 755. +.Pp +Executing +.Pp +.Dl $ /tmp/script one two three +.Pp +at the shell will result in +.Pa /bin/interp +being executed, receiving the following arguments in +.Va argv +(numbered from 0): +.Bd -ragged -offset indent +.Qq /bin/interp , +.Qq "-arg" , +.Qq /tmp/script , +.Qq one , +.Qq two , +.Qq three +.Ed +.Ss Portability Note: Multiple arguments +The behavior of multiple arguments on the +.Sq #! +line is highly non-portable between different systems. +In general, only one argument can be assumed to work consistently. +.Pp +Consider the following variation on the previous example. +Suppose that an executable binary exists in +.Pa /bin/interp +and that the file +.Pa /tmp/script +contains: +.Bd -literal -offset indent +#!/bin/interp -x -y + +[...] +.Ed +.Pp +and that +.Pa /tmp/script +is set mode 755. +.Pp +Executing +.Pp +.Dl $ /tmp/script one two three +.Pp +at the shell will result in +.Pa /bin/interp +being executed, receiving the following arguments in +.Va argv +(numbered from 0): +.Bd -ragged -offset indent +.Qq /bin/interp , +.Qq "-x -y" , +.Qq /tmp/script , +.Qq one , +.Qq two , +.Qq three +.Ed +.Pp +Note that +.Qq "-x -y" +will be passed on +.Ox +as a single argument. +.Pp +Although most +.Tn POSIX +style operating systems will pass only one +.Ar argument , +the behavior when multiple arguments are included is not +consistent between platforms. +Some, such as +.Ox , +will concatenate multiple arguments into a single argument (as above), +some will truncate them, and at least one will pass them as multiple +arguments. +.Pp +The +.Ox +behavior is common but not universal. +Sun's +.Tn Solaris +would present the above argument as +.Qq -x , +dropping the +.Qq " -y" +entirely. +Perhaps uniquely, recent versions of Apple's +.Tn OS X +will actually pass multiple arguments properly, i.e.: +.Bd -ragged -offset indent +.Qq /bin/interp , +.Qq -x , +.Qq -y , +.Qq /tmp/script , +.Qq one , +.Qq two , +.Qq three +.Ed +.Pp +The behavior of the system in the face of multiple arguments is thus +not currently standardized, should not be relied on, and may be +changed in future releases. +In general, pass at most one argument, and do not rely on multiple +arguments being concatenated. +.Sh SEE ALSO +.Xr awk 1 , +.Xr csh 1 , +.Xr ksh 1 , +.Xr sh 1 , +.Xr chmod 2 , +.Xr execve 2 , +.Xr intro 2 , +.Xr execlp 3 , +.Xr execvp 3 +.Sh STANDARDS +The behavior of interpreter scripts is obliquely referred to, but +never actually described in, +.St -p1003.1-2004 . +.Pp +The behavior is partially (but not completely) described in the +.St -svid4 . +.Pp +Although it has never been formally standardized, the behavior +described is largely portable across +.Tn POSIX +style systems, with two significant exceptions: the maximum length of the +.Sq #! +line, and the behavior if multiple arguments are passed. +Be aware that the behavior in the +face of multiple arguments is not consistent across systems. +.Sh HISTORY +The behavior of the kernel when encountering scripts that start in +.Sq #! +was not present in +.At v7 . +A Usenet posting to net.unix by Guy Harris on October 16, 1984 claims +that the idea for the +.Sq #! +behavior was first proposed by Dennis Ritchie but that the first +implementation was on +.Bx . +.Pp +Historical manuals (specifically the exec man page) indicate that the +behavior was present in +.Bx 4 +at least as early as April, 1981. +Information on precisely when it was first implemented, and in which +version of +.Ux , +is solicited. +.Sh CAVEATS +Numerous security problems are associated with setuid interpreter +scripts. +.Pp +In addition to the fact that many interpreters (and scripts) are +simply not designed to be robust in a setuid context, a race condition +exists between the moment that the kernel examines the interpreter +script file and the moment that the newly invoked interpreter opens +the file itself. +.Pp +Subtle techniques can be used to subvert even seemingly well written scripts. +Scripts executed by Bourne type shells can be subverted in numerous +ways, such as by setting the +.Ev IFS +variable before executing the script. +Other interpreters possess their own vulnerabilities. +Setting the Set-user-ID on execution (SUID) bit +is therefore very dangerous, and should not be done lightly, if at all. diff --git a/static/openbsd/man7/securelevel.7 b/static/openbsd/man7/securelevel.7 new file mode 100644 index 00000000..b26ff052 --- /dev/null +++ b/static/openbsd/man7/securelevel.7 @@ -0,0 +1,167 @@ +.\" $OpenBSD: securelevel.7,v 1.32 2025/04/29 17:44:00 jmc Exp $ +.\" +.\" Copyright (c) 2000 Hugh Graham +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: April 29 2025 $ +.Dt SECURELEVEL 7 +.Os +.Sh NAME +.Nm securelevel +.Nd securelevel and its effects +.Sh DESCRIPTION +The +.Ox +kernel provides four levels of system security: +.Bl -tag -width flag +.It \&-1 Em Permanently insecure mode +.Bl -hyphen -compact +.It +.Xr init 8 +will not attempt to raise the securelevel +.It +may only be set with +.Xr sysctl 8 +while the system is insecure +.It +otherwise identical to securelevel 0 +.El +.It \ 0 Em Insecure mode +.Bl -hyphen -compact +.It +used during bootstrapping and while the system is single-user +.It +all devices may be read or written subject to their permissions +.It +system file flags may be cleared with +.Xr chflags 2 +.El +.It \ 1 Em Secure mode +.Bl -hyphen -compact +.It +default mode when system is multi-user +.It +securelevel may no longer be lowered except by init +.It +.Pa /dev/mem +and +.Pa /dev/kmem +cannot be opened +.It +raw disk devices of mounted file systems are read-only +.It +system immutable and append-only file flags may not be removed +.It +the +.Va hw.allowpowerdown , +.Va kern.allowkmem , +.Va kern.utc_offset , +.Va net.inet.ip.sourceroute , +and +.Va machdep.kbdreset +.Xr sysctl 8 +variables may not be changed +.It +the +.Va ddb.console , +.Va ddb.panic , +and +.Va machdep.allowaperture +.Xr sysctl 8 +variables may not be raised +.It +.Xr gpioctl 8 +may only access GPIO pins configured at system startup +.El +.It \ 2 Em Highly secure mode +.Bl -hyphen -compact +.It +all effects of securelevel 1 +.It +raw disk devices are always read-only whether mounted or not +.It +.Xr settimeofday 2 +and +.Xr clock_settime 2 +may not set the time backwards or close to overflow +.It +.Xr pf 4 +filter and NAT rules may not be altered +.El +.El +.Pp +Securelevel provides convenient means of +.Dq locking down +a system to a degree suited to its environment. +It is normally set at boot by +.Xr rc 8 , +or the superuser may raise securelevel at any time by modifying the +.Va kern.securelevel +.Xr sysctl 8 +variable. +However, only +.Xr init 8 +may lower it once the system has entered secure mode. +.Pp +Highly secure mode may seem Draconian, but is intended as a last line of +defence should the superuser account be compromised. +Its effects preclude +circumvention of file flags by direct modification of a raw disk device, +or erasure of a file system by means of +.Xr newfs 8 . +Further, it can limit the potential damage of a compromised +.Dq firewall +by prohibiting the modification of packet filter rules. +Preventing +the system clock from being set backwards aids in post-mortem analysis +and helps ensure the integrity of logs. +Precision timekeeping is not +affected because the clock may still be slowed. +.Pp +Because securelevel can be modified with the in-kernel debugger +.Xr ddb 4 , +a convenient means of locking it off (if present) is provided +at securelevels 1 and 2. +This is accomplished by setting +.Va ddb.console +and +.Va ddb.panic +to 0 with the +.Xr sysctl 8 +utility. +.Sh FILES +.Bl -tag -width /etc/rc.securelevel -compact +.It Pa /etc/rc.securelevel +commands that run before the security level changes +.El +.Sh SEE ALSO +.Xr init 8 , +.Xr rc 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Ox 2.6 . +.Sh BUGS +The list of securelevel's effects may not be comprehensive. diff --git a/static/openbsd/man7/tbl.7 b/static/openbsd/man7/tbl.7 new file mode 100644 index 00000000..ec74af5b --- /dev/null +++ b/static/openbsd/man7/tbl.7 @@ -0,0 +1,455 @@ +.\" $OpenBSD: tbl.7,v 1.27 2022/08/28 13:51:58 schwarze Exp $ +.\" +.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2014,2015,2017,2018,2019 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 28 2022 $ +.Dt TBL 7 +.Os +.Sh NAME +.Nm tbl +.Nd tbl language reference for mandoc +.Sh DESCRIPTION +The +.Nm tbl +language formats tables. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +pages. +This manual describes the subset of the +.Nm +language accepted by the +.Xr mandoc 1 +utility. +.Pp +Each table is started with a +.Xr roff 7 +.Ic \&TS +macro, consist of at most one line of +.Sx Options , +one or more +.Sx Layout +lines, one or more +.Sx Data +lines, and ends with a +.Ic \&TE +macro. +All input must be 7-bit ASCII. +.Ss Options +If the first input line of a table ends with a semicolon, it contains +case-insensitive options separated by spaces, tabs, or commas. +Otherwise, it is interpreted as the first +.Sx Layout +line. +.Pp +The following options are available. +Some of them require arguments enclosed in parentheses: +.Bl -tag -width Ds +.It Cm allbox +Draw a single-line box around each table cell. +.It Cm box +Draw a single-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm frame . +.It Cm center +Center the table instead of left-adjusting it. +For GNU compatibility, this may also be invoked with +.Cm centre . +.It Cm decimalpoint +Use the single-character argument as the decimal point with the +.Cm n +layout key. +This is a GNU extension. +.It Cm delim +Use the two characters of the argument as +.Xr eqn 7 +delimiters. +Currently unsupported. +.It Cm doublebox +Draw a double-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm doubleframe . +.It Cm expand +Increase the width of the table to the current line length. +Currently ignored. +.It Cm linesize +Draw lines with the point size given by the unsigned integer argument. +Currently ignored. +.It Cm nokeep +Allow page breaks within the table. +This is a GNU extension and currently ignored. +.It Cm nospaces +Ignore leading and trailing spaces in data cells. +This is a GNU extension. +.It Cm nowarn +Suppress warnings about tables exceeding the current line length. +This is a GNU extension and currently ignored. +.It Cm tab +Use the single-character argument as a delimiter between data cells. +By default, the horizontal tabulator character is used. +.El +.Ss Layout +The table layout follows an +.Sx Options +line or a +.Xr roff 7 +.Ic \&TS +or +.Ic \&T& +macro. +Each layout line specifies how one line of +.Sx Data +is formatted. +The last layout line ends with a full stop. +It also applies to all remaining data lines. +Multiple layout lines can be joined by commas on a single physical +input line. +.Pp +Each layout line consists of one or more layout cell specifications, +optionally separated by whitespace. +The following case-insensitive key characters start a new cell +specification: +.Bl -tag -width 2n +.It Cm c +Center the string in this cell. +.It Cm r +Right-justify the string in this cell. +.It Cm l +Left-justify the string in this cell. +.It Cm n +Justify a number around its last decimal point. +If no decimal point is found in the number, +it is assumed to trail the number. +.It Cm s +Horizontally span columns from the last +.Pf non- Cm s +layout cell. +It is an error if a column span follows a +.Cm _ +or +.Cm = +cell, or comes first on a layout line. +The combined cell as a whole consumes only one cell +of the corresponding data line. +.It Cm a +Left-justify a string and pad with one space. +.It Cm \(ha +Vertically span rows from the last +.Pf non- Cm \(ha +layout cell. +It is an error to invoke a vertical span on the first layout line. +Unlike a horizontal span, a vertical span consumes a data cell +and discards the content. +.It Cm _ +Draw a single horizontal line in this cell. +This consumes a data cell and discards the content. +It may also be invoked with +.Cm \- . +.It Cm = +Draw a double horizontal line in this cell. +This consumes a data cell and discards the content. +.El +.Pp +Each cell key may be followed by zero or more of the following +case-insensitive modifiers: +.Bl -tag -width 2n +.It Cm b +Use a bold font for the contents of this cell. +.It Cm d +Move content down to the last row of this vertical span. +Currently ignored. +.It Cm e +Make this column wider to match the maximum width +of any other column also having the +.Cm e +modifier. +.It Cm f +The next one or two characters select the font to use for this cell. +One-character font names must be followed by a blank or period. +See the +.Xr roff 7 +manual for supported font names. +.It Cm i +Use an italic font for the contents of this cell. +.It Cm m +Specify a cell start macro. +This is a GNU extension and currently unsupported. +.It Cm p +Set the point size to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm v +Set the vertical line spacing to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm t +Do not vertically center content in this vertical span, +leave it in the top row. +Currently ignored. +.It Cm u +Move cell content up by half a table row. +Currently ignored. +.It Cm w +Specify a minimum column width. +.It Cm x +After determining the width of all other columns, distribute the +rest of the line length among all columns having the +.Cm x +modifier. +.It Cm z +Do not use this cell for determining the width of this column. +.It Cm \&| +Draw a single vertical line to the right of this cell. +.It Cm || +Draw a double vertical line to the right of this cell. +.El +.Pp +If a modifier consists of decimal digits, +it specifies a minimum spacing in units of +.Cm n +between this column and the next column to the right. +The default is 3. +If there is a vertical line, it is drawn inside the spacing. +.Ss Data +The data section follows the last +.Sx Layout +line. +Each data line consists of one or more data cells, delimited by +.Cm tab +characters. +.Pp +If a data cell contains only the two bytes +.Ql \e\(ha , +the cell above spans to this row, as if the layout specification +of this cell were +.Cm \(ha . +.Pp +If a data cell contains only the single character +.Ql _ +or +.Ql = , +a single or double horizontal line is drawn across the cell, +joining its neighbours. +If a data cell contains only the two character sequence +.Ql \e_ +or +.Ql \e= , +a single or double horizontal line is drawn inside the cell, +not joining its neighbours. +If a data line contains nothing but the single character +.Ql _ +or +.Ql = , +a horizontal line across the whole table is inserted +without consuming a layout row. +.Pp +In place of any data cell, a text block can be used. +It starts with +.Ic \&T{ +at the end of a physical input line. +Input line breaks inside the text block +neither end the text block nor its data cell. +It only ends if +.Ic \&T} +occurs at the beginning of a physical input line and is followed +by an end-of-cell indicator. +If the +.Ic \&T} +is followed by the end of the physical input line, the text block, +the data cell, and the data line ends at this point. +If the +.Ic \&T} +is followed by the +.Cm tab +character, only the text block and the data cell end, +but the data line continues with the data cell following the +.Cm tab +character. +If +.Ic \&T} +is followed by any other character, it does not end the text block, +which instead continues to the following physical input line. +.Sh EXAMPLES +String justification and font selection: +.Bd -literal -offset indent +\&.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +\&.TE +.Ed +.Bd -filled -offset indent +.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +.TE +.Ed +.Pp +Some ports in +.Ox 6.1 +to show number alignment and line drawing: +.Bd -literal -offset indent +\&.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +.TE +.Ed +.Pp +Spans and skipping width calculations: +.Bd -literal -offset indent +\&.TS +box tab(:); +lz s | rt +lt| cb| \(ha +\(ha | rz s. +left:r +l:center: +:right +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +lz s | rt +lt| cb| ^ +^ | rz s. +left:r +l:center: +:right +.TE +.Ed +.Pp +Text blocks, specifying spacings and specifying and equalizing +column widths, putting lines into individual cells, and overriding +.Cm allbox : +.Bd -literal -offset indent +\&.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\e_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +.TE +.Ed +.Pp +These examples were constructed to demonstrate many +.Nm +features in a compact way. +In real manual pages, keep tables as simple as possible. +They usually look better, are less fragile, and are more portable. +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of +.Nm +doesn't support +.Xr mdoc 7 +and +.Xr man 7 +macros and +.Xr eqn 7 +equations inside tables. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Rs +.%A M. E. Lesk +.%T Tbl \(em A Program to Format Tables +.%D June 11, 1976 +.Re +.Sh HISTORY +The tbl utility, a preprocessor for troff, was originally written by M. +E. Lesk at Bell Labs in 1975. +The GNU reimplementation of tbl, part of the groff package, was released +in 1990 by James Clark. +A standalone tbl implementation was written by Kristaps Dzonsons in +2010. +This formed the basis of the implementation that first appeared in +.Ox 4.9 +as a part of the +.Xr mandoc 1 +utility. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +.Sh BUGS +In +.Fl T +.Cm utf8 +output mode, heavy lines are drawn instead of double lines. +This cannot be improved because the Unicode standard only provides +an incomplete set of box drawing characters with double lines, +whereas it provides a full set of box drawing characters +with heavy lines. +It is unlikely this can be improved in the future because the box +drawing characters are already marked in Unicode as characters +intended only for backward compatibility with legacy systems, +and their use is not encouraged. +So it seems unlikely that the missing ones might get added in the future. diff --git a/static/openbsd/man7/utf8.7 b/static/openbsd/man7/utf8.7 new file mode 100644 index 00000000..97e6ace0 --- /dev/null +++ b/static/openbsd/man7/utf8.7 @@ -0,0 +1,99 @@ +.\" $OpenBSD: utf8.7,v 1.9 2022/02/18 10:24:32 jsg Exp $ +.\" +.\" Copyright (c) 2017 Ted Unangst <tedu@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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: February 18 2022 $ +.Dt UTF8 7 +.Os +.Sh NAME +.Nm utf8 +.Nd UTF-8 text encoding +.Sh DESCRIPTION +UTF-8 is a multibyte character encoding for Unicode text. +It is the preferred format for non ASCII text. +.Pp +Unicode codepoints are encoded as follows: +.Bl -tag -width Ds +.It U+0000 \(en U+007F: +One byte: 0....... (compatible with ASCII) +.It U+0080 \(en U+07FF: +Two bytes: 110..... 10...... +.It U+0800 \(en U+D7FF and U+E000 \(en U+FFFF: +Three bytes: 1110.... 10...... 10...... +.It U+10000 \(en U+10FFFF: +Four bytes: 11110... 10...... 10...... 10...... +.El +.Pp +The bits shown as dots contain the codepoint represented as a binary +integer. +.Pp +Bytes starting with the bit pattern 11...... are called UTF-8 start +bytes, and those starting with 10...... UTF-8 continuation bytes. +The number of leading 1 bits in a start byte indicates the total +number of bytes used to encode the codepoint, including the start +byte. +.Pp +Encodings using more bytes than required are invalid. +In particular, 11000000 and 11000001 are not valid start bytes, +the byte after 11100000 must be at least 10100000, +and the byte after 11110000 must be at least 10010000. +.Pp +The ranges U+D800 to U+DFFF and U+110000 to U+1FFFFF +do not contain valid Unicode codepoints. +Consequently, the corresponding three- and four-byte UTF-8 sequences +are invalid. +The highest valid byte after 11101101 is 10011111, +the highest valid byte of the form 1111.... is 11110100, +and the highest valid byte after 11110100 is 10001111. +.Pp +To summarize, the following is a complete list of bytes +that are invalid in all contexts: +.Pp +.Bl -tag -width 5n -offset 4n -compact +.It c0\(enc1 +two-byte sequence that has to be encoded as a single byte +.It f5\(enf7 +four-byte sequence beyond the Unicode range +.It f8\(enff +invalid sequence of five or more bytes +.El +.Pp +The following is a complete list of invalid two-byte combinations +of the form 11...... 10...... that consist of two valid bytes: +.Pp +.Bl -tag -width 9n -offset 4n -compact +.It e080\(ene09f +three-byte sequence that has to be encoded as two bytes +.It eda0\(enedbf +start of a UTF-16 surrogate, which is not valid UTF-8 +.It f080\(enf08f +four-byte sequence that has to be encoded as three bytes +.It f490\(enf4bf +four-byte sequence beyond the Unicode range +.El +.Sh SEE ALSO +.Xr locale 1 , +.Xr ascii 7 +.Sh STANDARDS +.Rs +.%A F. Yergeau +.%D November 2003 +.%R RFC 3629 +.%T UTF-8, a transformation format of ISO 10646 +.Re +.Pp +.Lk https://www.unicode.org/versions/latest/ "The Unicode Standard" +.Pp +.Lk https://www.unicode.org/reports/tr44/ "The Unicode Character Database" |