diff options
Diffstat (limited to 'share/man/man7')
| -rw-r--r-- | share/man/man7/Makefile | 16 | ||||
| -rw-r--r-- | share/man/man7/ascii.7 | 116 | ||||
| -rw-r--r-- | share/man/man7/environ.7 | 179 | ||||
| -rw-r--r-- | share/man/man7/hier.7 | 389 | ||||
| -rw-r--r-- | share/man/man7/hostname.7 | 92 | ||||
| -rw-r--r-- | share/man/man7/intro.7 | 60 | ||||
| -rw-r--r-- | share/man/man7/mailaddr.7 | 155 | ||||
| -rw-r--r-- | share/man/man7/mdoc.7 | 404 | ||||
| -rw-r--r-- | share/man/man7/mdoc.samples.7 | 2826 | ||||
| -rw-r--r-- | share/man/man7/operator.7 | 65 |
10 files changed, 4302 insertions, 0 deletions
diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile new file mode 100644 index 0000000..dd3fe2b --- /dev/null +++ b/share/man/man7/Makefile @@ -0,0 +1,16 @@ +# @(#)Makefile 8.1 (Berkeley) 6/5/93 + +MAN7= ascii.0 environ.0 eqnchar.0 hier.0 hostname.0 intro.0 mailaddr.0 \ + man.0 mdoc.0 mdoc.samples.0 ms.0 operator.0 term.0 +MLINKS= intro.7 miscellaneous.7 + +all: ${MAN7} + +clean depend lint tags: + +cleandir: + rm -f ${MAN7} + +install: maninstall + +.include <bsd.prog.mk> diff --git a/share/man/man7/ascii.7 b/share/man/man7/ascii.7 new file mode 100644 index 0000000..b876a53 --- /dev/null +++ b/share/man/man7/ascii.7 @@ -0,0 +1,116 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 June 5, 1993 +.Dt ASCII 7 +.Os +.Sh NAME +.Nm ascii +.Nd octal, hexadecimal and decimal +.Tn 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 nl 013 vt 014 np 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 nl 0b vt 0c np 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 nl 11 vt 12 np 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 FILES +.Bl -tag -width /usr/share/misc/ascii -compact +.It Pa /usr/share/misc/ascii +.El +.Sh HISTORY +An +.Nm ascii +manual page appeared in +.At v7 . diff --git a/share/man/man7/environ.7 b/share/man/man7/environ.7 new file mode 100644 index 0000000..3888626 --- /dev/null +++ b/share/man/man7/environ.7 @@ -0,0 +1,179 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 April 19, 1994 +.Dt ENVIRON 7 +.Os BSD 4.2 +.Sh NAME +.Nm environ +.Nd user environment +.Sh SYNOPSIS +.Ar extern char **environ ; +.Sh DESCRIPTION +An array of strings called the +.Ar environment +is made available by +.Xr execve 2 +when a process begins. By convention these strings have the form +.Dq Ar name=value . +The following names are used 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 . +BLOCKSIZE may be specified in units of a byte by specifying a number, +in units of a kilobyte by specifying a number followed by ``K'' or +``k'', in units of a megabyte by specifying a number followed by ``M'' +or ``m'' and in units of a gigabyte by specifying a number followed +by ``G'' or ``g''. +Sizes less than 512 bytes or greater than a gigabyte are ignored. +.It Ev EXINIT +A startup list of commands read by +.Xr ex 1 , +.Xr edit 1 , +and +.Xr vi 1 . +.It Ev HOME +A user's login directory, set by +.Xr login 1 +from the password file +.Xr passwd 5 . +.It Ev PATH +The sequence of directories, separated by colons, searched by +.Xr csh 1 , +.Xr sh 1 , +.Xr system 3 , +.Xr execvp 3 , +etc, when looking for an executable file. +PATH is set to ``:/usr/ucb:/bin:/usr/bin'' initially by +.Xr login 1 . +.It Ev PRINTER +The name of the default printer to be used by +.Xr lpr 1 , +.Xr lpq 1 , +and +.Xr lprm 1 . +.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 nroff 1 +or +.Xr plot 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 TERM, or, if +it begins with a '/', the name of the termcap file. +See +.Ev TERMPATH +below, +.Xr termcap 5 , +and +.Xr termcap . +.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 +.Dq 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 +.Dq /tmp +or +.Dq /var/tmp . +Setting this variable will make them use another directory. +.It Ev TZ +The timezone to use when displaying dates. +The normal format is a pathname relative to +.Dq /usr/share/zoneinfo . +For example, the command +.Dq env TZ=US/Pacific date +displays the current time in California. +See +.Xr tzset 3 +for more information. +.It Ev USER +The login name of the user. +.El +.Pp +Further names may be placed in the environment by the +.Xr export +command and +.Ar name=value +arguments in +.Xr sh 1 , +or by the +.Xr 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. +.Sh SEE ALSO +.Xr csh 1 , +.Xr ex 1 , +.Xr login 1 , +.Xr sh 1 , +.Xr execve 2 , +.Xr execle 3 , +.Xr system 3 , +.Xr termcap 3 , +.Xr termcap 5 +.Sh HISTORY +The +.Nm environ +manual page appeared in +.Bx 4.2 . diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 new file mode 100644 index 0000000..8d9ab10 --- /dev/null +++ b/share/man/man7/hier.7 @@ -0,0 +1,389 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 June 5, 1993 +.Dt HIER 7 +.Os +.Sh NAME +.Nm hier +.Nd layout of filesystems +.Sh DESCRIPTION +A sketch of the filesystem hierarchy. +.Bl -tag -width "/stand/" +.It Li / +root directory of the filesystem +.It Li /bin/ +user utilities fundamental to both single-user and multi-user environments +.It Li /dev/ +block and character device files +.Pp +.Bl -tag -width MAKEDEV -compact +.It Li MAKEDEV +script for creating device files; +see +.Xr makedev 8 +.It Li fd/ +file descriptor files; +see +.Xr \&fd 4 +.El +.It Li /etc/ +system configuration files and scripts +.Pp +.Bl -tag -width "disklabels/" -compact +.It Li localtime +local timezone information; +see +.Xr ctime 3 +.It Li disklabels/ +backup disklabels; +see +.Xr disklabel 8 +.It Li kerberosIV/ +configuration files for the kerberos version IV; +see +.Xr kerberos 1 +.It Li mtree/ +mtree configuration files; +see +.Xr mtree 1 +.It Li namedb/ +named configuration files; +see +.Xr named 8 +.El +.It Li /mnt/ +empty directory commonly used by +system administrators as a temporary mount point +.It Li /sbin/ +system programs and administration utilities +fundamental to both single-user and multi-user environments +.It Li /stand/ +programs used in a standalone environment +.It Li /tmp/ +temporary files, usually a +.Xr mfs 8 +memory-based filesystem (the contents +of /tmp are usually NOT preserved across a system reboot) +.It Li /usr/ +contains the majority of user utilities and applications +.Pp +.Bl -tag -width "libdata/" -compact +.It Li bin/ +common utilities, programming tools, and applications +.It Li contrib/ +large packages contributed to Berkeley by outside parties +.It Li games/ +useful and semi-frivolous programs +.It Li include/ +standard C include files +.Pp +.Bl -tag -width "kerberosIV/" -compact +.It Li X11/ +C include files for X11 window system +.It Li arpa/ +C include files for Internet service protocols +.It Li kerberosIV/ +C include files for kerberos authentication package; +see +.Xr kerberos 1 +.It Li machine/ +machine specific C include files +.It Li net/ +misc network C include files +.It Li netimp/ +C include files for IMP protocols; +see +.Xr imp 4 +.It Li netinet/ +C include files for Internet standard protocols; +see +.Xr inet 4 +.It Li netiso/ +C include files for ISO standard protocols; +see +.Xr iso 4 +.It Li netns/ +C include files for XNS standard protocols; +see +.Xr \&ns 4 +.It Li nfs/ +C include files for NFS (Network File System) +.It Li pascal/ +include files for pc 1 +.It Li protocols/ +C include files for Berkeley service protocols +.It Li sys/ +system C include files (kernel data structures) +.It Li ufs/ +C include files for UFS (The U-word File System) +.El +.Pp +.It Li lib/ +archive libraries +.Pp +.Bl -tag -width Fl -compact +.It Li uucp/ +UUCP configuration files (historically placed; to be moved) +.El +.It Li libdata/ +misc. utility data files +.It Li libexec/ +system daemons & system utilities (executed by other programs) +.It Li local/ +local executables, libraries, etc. +.It Li obj/ +architecture-specific target tree produced by building the /usr/src tree +.It Li old/ +programs from past lives of BSD which may disappear in future +releases +.It Li sbin/ +system daemons & system utilities (executed by users) +.It Li share/ +architecture-independent ascii text files +.Pp +.Bl -tag -width "calendar/" -compact +.It Li calendar/ +a variety of pre-fab calendar files; +see +.Xr calendar 1 +.It Li dict/ +word lists; +see +.Xr look 1 +.Pp +.Bl -tag -width Fl -compact +.It Li words +common words +.It Li web2 +words from Webster's 2nd International +.It Li papers/ +reference databases; +see +.Xr refer 1 +.It Li special/ +custom word lists; +see +.Xr spell 1 +.El +.Pp +.It Li doc/ +misc documentation; +src for most of the printed +.Bx BSD +manuals (available +from the +.Tn USENIX +association) +.It Li games/ +ascii text files used by various games +.It Li man/ +manual pages +.It Li me/ +macros for use with the me macro package +.It Li misc/ +misc system-wide ascii text files +.Bl -tag -width Fl -compact +.It Li termcap +terminal characteristics database; +see +.Xr termcap 5 +.El +.It Li mk/ +templates for make; +see +.Xr make 1 +.It Li ms/ +macros for use with the ms macro package +.It Li skel/ +example . (dot) files for new accounts +.It Li tabset/ +tab description files for a variety of terminals; used in +the termcap file; +see +.Xr termcap 5 +.It Li tmac/ +text processing macros; +see +.Xr nroff 1 +and +.Xr troff 1 +.It Li zoneinfo/ +timezone configuration information; +see +.Xr tzfile 5 +.El +.Pp +.It Li src/ +BSD and/or local source files +.Pp +.Bl -tag -width "kerberosIV/" -compact +.It Li bin/ +src for files in /bin +.It Li contrib/ +src for files in /usr/contrib +.It Li etc/ +src for files in /etc +.It Li games/ +src for files in /usr/games +.It Li include/ +src for files in /usr/include +.It Li kerberosIV/ +src for kerberos version IV +.It Li lib/ +src for files in /usr/lib +.It Li libexec/ +src for files in /usr/libexec +.It Li local/ +src for files in /usr/local +.It Li old/ +src for files in /usr/old +.It Li pgrm/ +src for programming tools in /usr/bin +.It Li sbin/ +src for files in /sbin +.It Li share/ +src for files in /usr/share +.It Li sys/ +kernel src files +.It Li usr.bin/ +src for files in /usr/bin +.It Li usr.sbin/ +src for files in /usr/sbin +.El +.El +.It Li /var/ +multi-purpose log, temporary, transient, and spool files +.Pp +.Bl -tag -width "preserve/" -compact +.It Li account/ +system accounting files +.Pp +.Bl -tag -width Fl -compact +.It Li acct +execution accounting file; +see +.Xr acct 5 +.El +.Pp +.It Li at/ +timed command scheduling files; +see +.Xr \&at 1 +.It Li backups/ +misc. backup files +.It Li db/ +misc. automatically generated system-specific database files +.It Li games/ +misc. game status and log files +.It Li log/ +misc. system log files +.Pp +.Bl -tag -width Fl -compact +.It Li wtmp +login/logout log; +see +.Xr wtmp 5 +.El +.Pp +.It Li mail/ +user mailbox files +.It Li preserve/ +temporary home of files preserved after an accidental death +of an editor; +see +.Xr \&ex 1 +.It Li quotas/ +filesystem quota information files +.It Li run/ +system information files describing various info about +system since it was booted +.Pp +.Bl -tag -width Fl -compact +.It Li utmp +database of current users; +see +.Xr utmp 5 +.El +.Pp +.It Li rwho/ +rwho data files; +see +.Xr rwhod 8 , +.Xr rwho 1 , +and +.Xr ruptime 1 +.It Li spool/ +misc. printer and mail system spooling directories +.Pp +.Bl -tag -width Fl -compact +.It Li ftp/ +commonly ~ftp; the anonymous ftp root directory +.It Li mqueue/ +undelivered mail queue; +see +.Xr sendmail 8 +.It Li output/ +line printer spooling directories +.It Li secretmail/ +secretmail spool directory; +see +.Xr xget 1 +.It Li uucp/ +uucp spool directory +.It Li uucppublic/ +commonly ~uucp; public uucp temporary directory +.El +.Pp +.It Li tmp/ +temporary files that are kept between system reboots +.El +.It Li /vmunix +pure kernel executable (the operating system loaded into memory +at boot time). +.El +.Sh SEE ALSO +.Xr \&ls 1 , +.Xr apropos 1 , +.Xr whatis 1 , +.Xr whereis 1 , +.Xr finger 1 , +.Xr which 1 , +.Xr find 1 , +.Xr grep 1 , +.Xr fsck 8 +.Sh HISTORY +A +.Nm hier +manual page appeared in +.At v7 . diff --git a/share/man/man7/hostname.7 b/share/man/man7/hostname.7 new file mode 100644 index 0000000..719ae0f --- /dev/null +++ b/share/man/man7/hostname.7 @@ -0,0 +1,92 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 December 30, 1993 +.Dt HOSTNAME 7 +.Os BSD 4.2 +.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 name consists of a single component, i.e. contains no dot, +and if the environment variable +.Dq Ev HOSTALIASES +is set to the name of a file, +that file is searched for any string matching the input hostname. +The file should consist of lines made up of two white-space separated strings, +the first of which is the hostname alias, +and the second of which is the complete hostname +to be substituted for that alias. +If a case-insensitive match is found between the hostname to be resolved +and the first field of a line in the file, the substituted name is looked +up with no further processing. +.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 the 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 resolver 5 ) . +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr resolver 5 , +.Xr mailaddr 7 , +.Xr named 8 +.Sh HISTORY +.Nm Hostname +appeared in 4.2 BSD. diff --git a/share/man/man7/intro.7 b/share/man/man7/intro.7 new file mode 100644 index 0000000..07ef6a8 --- /dev/null +++ b/share/man/man7/intro.7 @@ -0,0 +1,60 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 June 5, 1993 +.Dt INTRO 7 +.Os BSD 4.2 +.Sh NAME +.Nm intro +.Nd miscellaneous information pages +.Sh DESCRIPTION +This section contains miscellaneous documentation, mostly +in the area of text processing macro packages for +.Xr troff 1 . +.Pp +.Ds I +.Cw mailaddr +.Cl ascii map of ASCII character set +.Cl environ user environment +.Cl eqnchar special character definitions for eqn +.Cl hier file system hierarchy +.Cl mailaddr mail addressing description +.Cl man macros to typeset manual pages +.Cl \&me macros for formatting papers +.Cl \&ms macros for formatting manuscripts +.Cl term conventional names for terminals +.Cw +.De +.Sh HISTORY +.Nm intro +appeared in 4.2 BSD. diff --git a/share/man/man7/mailaddr.7 b/share/man/man7/mailaddr.7 new file mode 100644 index 0000000..96a98f9 --- /dev/null +++ b/share/man/man7/mailaddr.7 @@ -0,0 +1,155 @@ +.\" Copyright (c) 1983, 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)mailaddr.7 8.1 (Berkeley) 6/16/93 +.\" +.Dd June 16, 1993 +.Dt MAILADDR 7 +.Os BSD 4.2 +.Sh NAME +.Nm mailaddr +.Nd mail addressing description +.Sh DESCRIPTION +Mail addresses are based on the Internet protocol listed at the end of this +manual page. These addresses are in the general format +.Pp +.Dl user@domain +.Pp +where a domain is a hierarchical dot separated list of subdomains. For +example, a valid address is: +.Pp +.Dl eric@CS.Berkeley.EDU +.Pp +Unlike some other forms of addressing, domains do not imply any routing. +Thus, although this address is specified as an Internet address, it might +travel by an alternate route if that were more convenient or efficient. +For example, at Berkeley, the associated message would probably go directly +to CS over the Ethernet rather than going via the Berkeley Internet +gateway. +.Ss Abbreviation. +Under certain circumstances it may not be necessary to type the entire +domain name. In general, anything following the first dot may be omitted +if it is the same as the domain from which you are sending the message. +For example, a user on ``calder.berkeley.edu'' could send to ``eric@CS'' +without adding the ``berkeley.edu'' since it is the same on both sending +and receiving hosts. +.Ss Compatibility. +.Pp +Certain old address formats are converted to the new format to provide +compatibility with the previous mail system. In particular, +.Pp +.Dl user@host +.Pp +and +.Dl user@host.domain +.Pp +are allowed; +.Pp +.Dl host.domain!user +.Pp +is converted to +.Pp +.Dl user@host.domain +.Pp +and +.Pp +.Dl host!user +.Pp +is converted to +.Pp +.Dl user@host.UUCP +.Pp +This is normally converted back to the ``host!user'' form before being sent +on for compatibility with older UUCP hosts. +.Pp +.Ss Case Distinctions. +.Pp +Domain names (i.e., anything after the ``@'' sign) may be given in any mixture +of upper and lower case with the exception of UUCP hostnames. Most hosts +accept any combination of case in user names, with the notable exception of +MULTICS sites. +.Ss Route-addrs. +.Pp +Under some circumstances it may be necessary to route a message through +several hosts to get it to the final destination. Normally this routing +is done automatically, but sometimes it is desirable to route the message +manually. Addresses which show these relays are termed ``route-addrs.'' +These use the syntax: +.Pp +.Dl <@hosta,@hostb:user@hostc> +.Pp +This specifies that the message should be sent to hosta, from there to hostb, +and finally to hostc. This path is forced even if there is a more efficient +path to hostc. +.Pp +Route-addrs occur frequently on return addresses, since these are generally +augmented by the software at each host. It is generally possible to ignore +all but the ``user@hostc'' part of the address to determine the actual +sender. +.Pp +[Note: the route-addr syntax is officially deprecated +in RFC 1123 and should not be used.] +.Pp +Many sites also support the ``percent hack'' for simplistic routing: +.Pp +.Dl user%hostc%hostb@hosta +.Pp +is routed as indicated in the previous example. +.Ss Postmaster. +.Pp +Every site is required to have a user or user alias designated ``postmaster'' +to which problems with the mail system may be addressed. +.Ss Other Networks. +.Pp +Some other networks can be reached by giving the name of the network as the +last component of the domain. +.Em This is not a standard feature +and may +not be supported at all sites. For example, messages to CSNET or BITNET sites +can often be sent to ``user@host.CSNET'' or ``user@host.BITNET'' respectively. +.Sh SEE ALSO +.Xr mail 1 , +.Xr sendmail 8 ; +.br +Crocker, D. H., +.Em Standard for the Format of Arpa Internet Text Messages, +RFC822. +.Sh HISTORY +.Nm Mailaddr +appeared in 4.2 BSD. +.Sh BUGS +The RFC822 group syntax (``group:user1,user2,user3;'') is not supported +except in the special case of ``group:;'' because of a conflict with old +berknet-style addresses. +.Pp +Route-Address syntax is grotty. +.Pp +UUCP- and Internet-style addresses do not coexist politely. diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7 new file mode 100644 index 0000000..b7d92fb --- /dev/null +++ b/share/man/man7/mdoc.7 @@ -0,0 +1,404 @@ +.\" Copyright (c) 1991, 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93 +.\" +.Dd December 30, 1993 +.Os +.Dt MDOC 7 +.Sh NAME +.Nm mdoc +.Nd quick reference guide for the +.Nm \-mdoc +macro package +.Sh SYNOPSIS +.Nm groff +.Fl m Ns Ar doc +.Ar files ... +.Sh DESCRIPTION +The +.Nm \-mdoc +package is a set of content-based and domain-based macros +used to format the +.Bx +man pages. +The macro names and their meanings are +listed below for quick reference; for +a detailed explanation on using the package, +see the tutorial sampler +.Xr mdoc.samples 7 . +.Pp +The macros are described in two groups, the first +includes the structural and physical page layout macros. +The second contains the manual and general text domain +macros which differentiate the +.Nm -\mdoc +package from other +.Xr troff +formatting packages. +.Sh PAGE STRUCTURE DOMAIN +.Ss Title Macros +To create a valid manual page, these three macros, in this order, +are required: +.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact +.It Li "\&.Dd " Ar "Month day, year" +Document date. +.It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]" +Title, in upper case. +.It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]" +Operating system +.Pq Tn BSD . +.El +.Ss Page Layout Macros +Section headers, paragraph breaks, lists and displays. +.Bl -tag -width flag -compact +.It Li \&.Sh +Section Headers. +Valid headers, in the order of presentation: +.Bl -tag -width "RETURN VALUES" -compact +.It Ar NAME +Name section, should include the +.Ql \&.Nm +or +.Ql \&.Fn +and the +.Ql \&.Nd +macros. +.It Ar SYNOPSIS +Usage. +.It Ar DESCRIPTION +General description, should include +options and parameters. +.It Ar RETURN VALUES +Sections two and three function calls. +.It Ar ENVIRONMENT +Describe environment variables. +.It Ar FILES +Files associated with the subject. +.It Ar EXAMPLES +Examples and suggestions. +.It Ar DIAGNOSTICS +Normally used for section four device interface diagnostics. +.It Ar ERRORS +Sections two and three error and signal +handling. +.It Ar SEE ALSO +Cross references and citations. +.It Ar STANDARDS +Conformance to standards if applicable. +.It Ar HISTORY +If a standard is not applicable, the history +of the subject should be given. +.It Ar BUGS +Gotchas and caveats. +.It Ar other +Customized headers may be added at +the authors discretion. +.El +.It Li \&.Ss +Subsection Headers. +.It Li \&.Pp +Paragraph Break. +Vertical space (one line). +.It Li \&.D1 +(D-one) Display-one +Indent and display one text line. +.It Li \&.Dl +(D-ell) Display-one literal. +Indent and display one line of literal text. +.It Li \&.Bd +Begin-display block. +Display options: +.Bl -tag -width "xoffset string " -compact +.It Fl ragged +Unjustified (ragged edges). +.It Fl filled +Justified. +.It Fl literal +Literal text or code. +.It Fl file Ar name +Read in named +.Ar file +and display. +.It Fl offset Ar string +Offset display. +Acceptable +.Ar string +values: +.Bl -tag -width indent-two -compact +.It Ar left +Align block on left (default). +.It Ar center +Approximate center margin. +.It Ar indent +Six constant width spaces (a tab). +.It Ar indent-two +Two tabs. +.It Ar right +Left aligns block 2 inches from +right. +.It Ar xx Ns Cm n +Where +.Ar xx +is a number from +.No \&4 Ns Cm n +to +.No \&9\&9 Ns Cm n . +.It Ar Aa +Where +.Ar Aa +is a callable macro name. +.It Ar string +The width of +.Ar string +is used. +.El +.El +.It Li \&.Ed +End-display (matches \&.Bd). +.It Li \&.Bl +Begin-list. +Create lists or columns. Options: +.Bl -tag -width flag -compact +.It Ar List-types +.Bl -column xbullet -compact +.It Fl bullet Ta "Bullet Item List" +.It Fl item Ta "Unlabeled List" +.It Fl enum Ta "Enumerated List" +.It Fl tag Ta "Tag Labeled List" +.It Fl diag Ta "Diagnostic List" +.It Fl hang Ta "Hanging Labeled List" +.It Fl ohang Ta "Overhanging Labeled List" +.It Fl inset Ta "Inset or Run-on Labeled List" +.El +.It List-parameters +.Bl -tag -width "xcompact " -compact +.It Fl offset +(All lists.) See +.Ql \&.Bd +begin-display above. +.It Fl width +.Pf ( Fl tag +and +.Fl hang +lists only.) +See +.Ql \&.Bd . +.It Fl compact +(All lists.) +Suppresses blank lines. +.El +.El +.It Li \&.El +End-list. +.It Li \&.It +List item. +.El +.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS +The manual and general text domain macros are special in that +most of them are parsed for callable macros +for example: +.Bl -tag -width ".Op Fl s Ar filex" -offset indent +.It Li "\&.Op Fl s Ar file" +Produces +.Op Fl s Ar file +.El +.Pp +In this example, the option enclosure macro +.Ql \&.Op +is parsed, and calls the callable content macro +.Ql \&Fl +which operates on the argument +.Ql s +and then calls the callable content macro +.Ql \&Ar +which operates on the argument +.Ql file . +Some macros may be callable, but are not parsed and vice versa. +These macros are indicated in the +.Em parsed +and +.Em callable +columns below. +.Pp +Unless stated, manual domain macros share a common syntax: +.Pp +.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ] +.Pp +.Sy Note : +Opening and closing +punctuation characters are only recognized as such if they are presented +one at a time. +The string +.Ql ")," +is not recognized as punctuation and will be output with a leading white +space and in what ever font the calling macro uses. +The +argument list +.Ql "] ) ," +is recognized as three sequential closing punctuation characters +and a leading white space is not output between the characters +and the previous argument (if any). +The special meaning of a punctuation character may be escaped +with the string +.Ql \e& . +For example the following string, +.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent +.It Li "\&.Ar file1\ , file2\ , file3\ )\ ." +Produces +.Ar file1 , file2 , file3 ) . +.El +.ne 1i +.Ss Manual Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em Name Parsed Callable Description +.It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)" +.It Li \&Ar Ta Yes Ta Yes Ta "Command line argument." +.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)." +.It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier." +.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." +.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)." +.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable." +.It Li \&Fa Ta Yes Ta Yes Ta "Function argument." +.It Li \&Fd Ta Yes Ta Yes Ta "Function declaration." +.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." +.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command." +.It Li \&Li Ta Yes Ta Yes Ta "Literal text." +.It Li \&Nm Ta Yes Ta Yes Ta "Command name." +.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." +.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." +.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name." +.It Li \&St Ta Yes Ta Yes Ta "Standards (-p1003.2, -p1003.1 or -ansiC)" +.It Li \&Va Ta Yes Ta Yes Ta "Variable name." +.It Li \&Vt Ta Yes Ta Yes Ta "Variable type (Fortran only)." +.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." +.El +.Ss General Text Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em "Name Parsed Callable Description" +.It Li \&%A Ta Yes Ta \&No Ta "Reference author." +.It Li \&%B Ta Yes Ta Yes Ta "Reference book title." +.It Li \&%\&C Ta \&No Ta \&No Ta "Reference place of publishing (city)." +.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date." +.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title." +.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number." +.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information." +.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)." +.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name." +.It Li \&%T Ta Yes Ta Yes Ta "Reference article title." +.It Li \&%V Ta \&No Ta \&No Ta "Reference volume." +.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote." +.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote." +.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote." +.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX" +.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote." +.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode." +.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote." +.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote." +.It Li \&Bx Ta Yes Ta Yes Ta Bx . +.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)" +.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote." +.It Li \&Do Ta Yes Ta Yes Ta "Double open quote." +.It Li \&Dq Ta Yes Ta Yes Ta "Double quote." +.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." +.It Li \&Ef Ta \&No Ta \&No Ta "End font mode." +.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." +.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." +.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)." +.It Li \&Ns Ta Yes Ta Yes Ta "No space." +.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." +.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." +.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." +.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." +.It Li \&Qc Ta Yes Ta Yes Ta "Strait Double close quote." +.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." +.It Li \&Qo Ta Yes Ta Yes Ta "Strait Double open quote." +.It Li \&Qq Ta Yes Ta Yes Ta "Strait Double quote." +.It Li \&Re Ta \&No Ta \&No Ta "Reference start." +.It Li \&Rs Ta \&No Ta \&No Ta "Reference start." +.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." +.It Li \&So Ta Yes Ta Yes Ta "Single open quote." +.It Li \&Sq Ta Yes Ta Yes Ta "Single quote." +.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)" +.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." +.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." +.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." +.It Li \&Ux Ta Yes Ta Yes Ta Ux +.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close." +.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list close." +.El +.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" +.Pp +Macro names ending in +.Ql q +quote remaining items on the argument list. +Macro names ending in +.Ql o +begin a quote which may span more than one line of input and +are close quoted with the matching macro name ending in +.Ql c . +Enclosure macros may be nested and are limited to +eight arguments. +.Pp +Note: the extended argument list macros +.Pf ( Ql \&.Xo , +.Ql \&.Xc ) +and the function enclosure macros +.Pf ( Ql \&.Fo , +.Ql \&.Fc ) +are irregular. +The extended list macros are used when the number of macro arguments +would exceed the +.Xr troff +limitation of nine arguments. +.Sh CONFIGURATION +For site specific configuration of the macro package, +see the file +.Pa /usr/src/share/tmac/README . +.Sh FILES +.Bl -tag -width "tmac.doc-ditroff" -compact +.It Pa tmac.doc +Manual and general text domain macros. +.It Pa tmac.doc-common +Common structural macros and definitions. +.It Pa tmac.doc-nroff +Site dependent +.Xr nroff +style file. +.It Pa tmac.doc-ditroff +Site dependent +.Xr troff +style file. +.It Pa tmac.doc-syms +Special defines (such as the standards macro). +.El +.Sh SEE ALSO +.Xr mdoc.samples 7 diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7 new file mode 100644 index 0000000..c1cc9c6 --- /dev/null +++ b/share/man/man7/mdoc.samples.7 @@ -0,0 +1,2826 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 +.\" +.\" This tutorial sampler invokes every macro in the package several +.\" times and is guaranteed to give a worst case performance +.\" for an already extremely slow package. +.\" +.Dd December 30, 1993 +.Os +.Dt MDOC.SAMPLES 7 +.Sh NAME +.Nm mdoc.samples +.Nd tutorial sampler for writing +.Bx +manuals with +.Nm \-mdoc +.Sh SYNOPSIS +.Nm man mdoc.samples +.Sh DESCRIPTION +A tutorial sampler for writing +.Bx +manual pages with the +.Nm \-mdoc +macro package, a +.Em content Ns \-based +and +.Em domain Ns \-based +formatting +package for +.Xr troff 1 . +Its predecessor, the +.Xr \-man 7 +package, +addressed page layout leaving the +manipulation of fonts and other +typesetting details to the individual author. +In +.Nm \-mdoc , +page layout macros +make up the +.Em "page structure domain" +which consists of macros for titles, section headers, displays +and lists. Essentially items which affect the physical position +of text on a formatted page. +In addition to the page structure domain, there are two more domains, +the manual domain and the general text domain. +The general text domain is defined as macros which +perform tasks such as quoting or emphasizing pieces of text. +The manual domain is defined as macros that are a subset of the +day to day informal language used to describe commands, routines +and related +.Bx +files. +Macros in the manual domain handle +command names, command line arguments and options, function names, +function parameters, pathnames, variables, cross +references to other manual pages, and so on. +These domain +items have value +for both the author and the future user of the manual page. +It is hoped the consistency gained +across the manual set will provide easier +translation to future documentation tools. +.Pp +Throughout the +.Ux +manual pages, a manual entry +is simply referred +to as a man page, regardless of actual length and without +sexist intention. +.Sh GETTING STARTED +Since a tutorial document is normally read when a person +desires to use the material immediately, the assumption has +been made that the user of this document may be impatient. +The material presented in the remained of this document is +outlined as follows: +.Bl -enum -offset indent +.It +.Tn "TROFF IDIOSYNCRASIES" +.Bl -tag -width flag -compact -offset indent +.It "Macro Usage" . +.It "Passing Space Characters in an Argument" . +.It "Trailing Blank Space Characters (a warning)" . +.It "Escaping Special Characters" . +.El +.It +.Tn "THE ANATOMY OF A MAN PAGE" +.Bl -tag -width flag -compact -offset indent +.It "A manual page template" . +.El +.It +.Tn "INTRODUCTION OF TITLE MACROS" . +.It +.Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . +.Bl -tag -width flag -compact -offset indent +.It "What's in a name..." . +.It "General Syntax" . +.El +.It +.Tn "MANUAL DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Addresses" . +.It "Arguments" . +.It "Configuration Declarations (section four only)" . +.It "Command Modifier . +.It "Defined Variables" . +.It "Errno's (Section two only)" . +.It "Environment Variables" . +.It "Function Argument" . +.It "Function Declaration" . +.It "Flags" . +.It "Functions (library routines)" . +.It "Function Types" . +.\" .It "Header File (including source code)" . +.It "Interactive Commands" . +.It "Literals" . +.It "Names" . +.It "Options" . +.It "Pathnames" . +.It "Variables" . +.It "Cross References" . +.El +.It +.Tn "GENERAL TEXT DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "AT&T Macro" . +.It "BSD Macro" . +.It "UNIX Macro" . +.It "Emphasis Macro" . +.It "Enclosure/Quoting Macros" +.Bl -tag -width flag -compact -offset indent +.It "Angle Bracket Quote/Enclosure" . +.It "Bracket Quotes/Enclosure" . +.It "Double Quote macro/Enclosure" . +.It "Parenthesis Quote/Enclosure" . +.It "Single Quotes/Enclosure" . +.It "Prefix Macro" . +.El +.It "Extended Arguments" . +.It "No\-Op or Normal Text Macro" . +.It "No Space Macro" . +.It "Section Cross References" . +.It "Symbolic Macro" . +.It "References and Citations" . +.It "Trade Names (Acronyms and Type Names)" . +.El +.It +.Tn "PAGE STRUCTURE DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Section Headers" . +.It "Paragraphs and Line Spacing" . +.It "Keeps" . +.It "Displays" . +.It "Lists and Columns" . +.El +.It +.Tn "PREDEFINED STRINGS" +.It +.Tn "DIAGNOSTICS" +.It +.Tn "FORMATTING WITH GROFF, TROFF AND NROFF" +.It +.Tn "BUGS" +.El +.ne 7 +.Sh TROFF IDIOSYNCRASIES +The +.Nm \-mdoc +package attempts to simplify the process of writing a man page. +Theoretically, one should not have to learn the dirty details of +.Xr troff 1 +to use +.Nm \-mdoc ; +however, there are a few +limitations which are unavoidable and best gotten out +of the way. +And, too, be forewarned, this package is +.Em not +fast. +.Ss Macro Usage +As in +.Xr troff 1 , +a macro is called by placing a +.Ql \&\. +(dot character) +at the beginning of +a line followed by the two character name for the macro. +Arguments may follow the macro separated by spaces. +It is the dot character at the beginning of the line which causes +.Xr troff 1 +to interpret the next two characters as a macro name. +To place a +.Ql \&\. +(dot character) +at the beginning of a line in some context other than +a macro invocation, precede the +.Ql \&\. +(dot) with the +.Ql \e& +escape sequence. +The +.Ql \e& +translates literally to a zero width space, and is never displayed in the +output. +.Pp +In general, +.Xr troff 1 +macros accept up to nine arguments, any +extra arguments are ignored. +Most macros in +.Nm \-mdoc +accept nine arguments and, +in limited cases, arguments may be continued or extended +on the +next line (See +.Sx Extensions ) . +A few macros handle quoted arguments (see +.Sx Passing Space Characters in an Argument +below). +.Pp +Most of the +.Nm \-mdoc +general text domain and manual domain macros are special +in that their argument lists are +.Em parsed +for callable macro names. +This means an argument on the argument list which matches +a general text or manual domain macro name and is determined +to be callable will be executed +or called when it is processed. +In this case +the argument, although the name of a macro, +is not preceded by a +.Ql \&\. +(dot). +It is in this manner that many macros are nested; for +example +the option macro, +.Ql \&.Op , +may +.Em call +the flag and argument macros, +.Ql \&Fl +and +.Ql \&Ar , +to specify an optional flag with an argument: +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op Fl s Ar bytes +is produced by +.Li \&.Op \&Fl s \&Ar bytes +.El +.Pp +To prevent a two character +string from being interpreted as a macro name, precede +the string with the +escape sequence +.Ql \e& : +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op \&Fl s \&Ar bytes +is produced by +.Li \&.Op \e&Fl s \e&Ar bytes +.El +.Pp +Here the strings +.Ql \&Fl +and +.Ql \&Ar +are not interpreted as macros. +Macros whose argument lists are parsed for callable arguments +are referred to +as parsed and macros which may be called from an argument +list are referred to as callable +throughout this document and in the companion quick reference +manual +.Xr mdoc 7 . +This is a technical +.Em faux pas +as almost all of the macros in +.Nm \-mdoc +are parsed, but as it was cumbersome to constantly refer to macros +as being callable and being able to call other macros, +the term parsed has been used. +.Ss Passing Space Characters in an Argument +Sometimes it is desirable to give as one argument a string +containing one or more blank space characters. +This may be necessary +to defeat the nine argument limit or to specify arguments to macros +which expect particular arrangement of items in the argument list. +For example, +the function macro +.Ql \&.Fn +expects the first argument to be the name of a function and any +remaining arguments to be function parameters. +As +.Tn "ANSI C" +stipulates the declaration of function parameters in the +parenthesized parameter list, each parameter is guaranteed +to be at minimum a two word string. +For example, +.Fa int foo . +.Pp +There are two possible ways to pass an argument which contains +an embedded space. +.Em Implementation note : +Unfortunately, the most convenient way +of passing spaces in between quotes by reassigning individual +arguments before parsing was fairly expensive speed wise +and space wise to implement in all the macros for +.Tn AT&T +.Xr troff . +It is not expensive for +.Xr groff +but for the sake of portability, has been limited +to the following macros which need +it the most: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It Li \&Cd +Configuration declaration (section 4 +.Sx SYNOPSIS ) +.It Li \&Bl +Begin list (for the width specifier). +.It Li \&Em +Emphasized text. +.It Li \&Fn +Functions (sections two and four). +.It Li \&It +List items. +.It Li \&Li +Literal text. +.It Li \&Sy +Symbolic text. +.It Li \&%B +Book titles. +.It Li \&%J +Journal names. +.It Li \&%O +Optional notes for a reference. +.It Li \&%R +Report title (in a reference). +.It Li \&%T +Title of article in a book or journal. +.El +.Pp +One way of passing a string +containing blank spaces is to use the hard or unpaddable space character +.Ql \e\ , +that is, a blank space preceded by the escape character +.Ql \e . +This method may be used with any macro but has the side effect +of interfering with the adjustment of text +over the length of a line. +.Xr Troff +sees the hard space as if it were any other printable character and +cannot split the string into blank or newline separated pieces as one +would expect. +The method is useful for strings which are not expected +to overlap a line boundary. +For example: +.Bl -tag -width "fetch(char *str)" -offset indent +.It Fn fetch char\ *str +is created by +.Ql \&.Fn fetch char\e *str +.It Fn fetch "char *str" +can also be created by +.Ql \&.Fn fetch "\\*q*char *str\\*q" +.El +.Pp +If the +.Ql \e +or quotes +were omitted, +.Ql \&.Fn +would see three arguments and +the result would be: +.Pp +.Dl Fn fetch char *str +.Pp +For an example of what happens when the parameter list overlaps +a newline boundary, see the +.Sx BUGS +section. +.Ss Trailing Blank Space Characters +.Xr Troff +can be confused by blank space characters at the end of a line. +It +is a wise preventive measure to globally remove all blank spaces +from <blank-space><end-of-line> character sequences. +Should the need +arise to force a blank character at the end of a line, +it may be forced with an unpaddable space and the +.Ql \e& +escape character. +For example, +.Ql string\e\ \e& . +.Ss Escaping Special Characters +Special characters +like the newline character +.Ql \en , +are handled by replacing the +.Ql \e +with +.Ql \ee +(e.g. +.Ql \een ) +to preserve +the backslash. +.Sh THE ANATOMY OF A MAN PAGE +The body of a man page is easily constructed from a basic +template found in the file: +.Bd -literal -offset indent +\&.\e" /usr/share/misc/man.template: +\&.\e" The following six lines are required. +\&.Dd Month day, year +\&.Os OPERATING_SYSTEM [version/release] +\&.Dt DOCUMENT_TITLE [section number] [volume] +\&.Sh NAME +\&.Sh SYNOPSIS +\&.Sh DESCRIPTION +\&.\e" The following requests should be uncommented and +\&.\e" used where appropriate. This next request is +\&.\e" for sections 2 and 3 function return values only. +\&.\e" .Sh RETURN VALUES +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" .Sh ENVIRONMENT +\&.\e" .Sh FILES +\&.\e" .Sh EXAMPLES +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" (command return values (to shell) and +\&.\e" fprintf/stderr type diagnostics) +\&.\e" .Sh DIAGNOSTICS +\&.\e" The next request is for sections 2 and 3 error +\&.\e" and signal handling only. +\&.\e" .Sh ERRORS +\&.\e" .Sh SEE ALSO +\&.\e" .Sh STANDARDS +\&.\e" .Sh HISTORY +\&.\e" .Sh AUTHORS +\&.\e" .Sh BUGS +.Ed +.Pp +The first items in the template are the macros +.Pq Li \&.Dd , \&.Os , \&.Dt ; +the document date, +the operating system the man page or subject source is developed +or modified for, +and the man page title +.Pq Em in upper case +along with the section of the manual the page +belongs in. +These macros identify the page, +and are discussed below in +.Sx TITLE MACROS . +.Pp +The remaining items in the template are section headers +.Pq Li \&.Sh ; +of which +.Sx NAME , +.Sx SYNOPSIS +and +.Sx DESCRIPTION +are mandatory. +The +headers are +discussed in +.Sx PAGE STRUCTURE DOMAIN , +after +presentation of +.Sx MANUAL DOMAIN . +Several content macros are used to demonstrate page layout macros; +reading about content macros before page layout macros is +recommended. +.Sh TITLE MACROS +The title macros are the first portion of the page structure +domain, but are presented first and separate for someone who +wishes to start writing a man page yesterday. +Three header macros designate the document title or manual page title, +the operating system, +and the date of authorship. +These macros are one called once at the very beginning of the document +and are used to construct the headers and footers only. +.Bl -tag -width 6n +.It Li \&.Dt DOCUMENT_TITLE section# [volume] +The document title is the +subject of the man page and must be in +.Tn CAPITALS +due to troff +limitations. +The section number may be 1,\ ...,\ 8, +and if it is specified, +the volume title may be omitted. +A volume title may be arbitrary or one of the following: +.\" .Cl +.\" USD UNIX User's Supplementary Documents +.\" .Cl +.\" PS1 UNIX Programmer's Supplementary Documents +.Pp +.Bl -column SMM -offset indent -compact +.It Li AMD UNIX Ancestral Manual Documents +.It Li SMM UNIX System Manager's Manual +.It Li URM UNIX Reference Manual +.It Li PRM UNIX Programmer's Manual +.El +.Pp +The default volume labeling is +.Li URM +for sections 1, 6, and 7; +.Li SMM +for section 8; +.Li PRM +for sections 2, 3, 4, and 5. +.\" .Cl +.\" MMI UNIX Manual Master Index +.\" .Cl +.\" CON UNIX Contributed Software Manual +.\" .Cl +.\" LOC UNIX Local Manual +.It Li \&.Os operating_system release# +The name of the operating system +should be the common acronym, e.g. +.Tn BSD +or +.Tn ATT . +The release should be the standard release +nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3, +V.4. +Unrecognized arguments are displayed as given in the page footer. +For instance, a typical footer might be: +.Pp +.Dl \&.Os BSD 4.3 +.Pp +or for a locally produced set +.Pp +.Dl \&.Os CS Department +.Pp +The Berkeley default, +.Ql \&.Os +without an argument, has been defined as +.Tn BSD +Experimental in the +site specific file +.Pa /usr/src/share/tmac/doc-common . +It really should default to +.Tn LOCAL . +Note, if the +.Ql \&.Os +macro is not present, the bottom left corner of the page +will be ugly. +.It Li \&.Dd month day, year +The date should be written formally: +.Pp +.ne 5 +.Dl January 25, 1989 +.El +.Sh MANUAL DOMAIN +.Ss What's in a name... +The manual domain macro names are derived from the day to day +informal language used to describe commands, subroutines and related +files. +Slightly +different variations of this language are used to describe +the three different aspects of writing a man page. +First, there is the description of +.Nm \-mdoc +macro request usage. +Second is the description of a +.Ux +command +.Em with +.Nm \-mdoc +macros and third, +the +description of a command to a user in the verbal sense; +that is, discussion of a command in the text of a man page. +.Pp +In the first case, +.Xr troff 1 +macros are themselves a type of command; +the general syntax for a troff command is: +.Bd -filled -offset indent +\&.Va argument1 argument2 ... argument9 +.Ed +.Pp +The +.Ql \&.Va +is a macro command or request, and anything following it is an argument to +be processed. +In the second case, +the description of a +.Ux +command using the content macros is a +bit more involved; +a typical +.Sx SYNOPSIS +command line might be displayed as: +.Bd -filled -offset indent +.Nm filter +.Op Fl flag +.Ar infile outfile +.Ed +.Pp +Here, +.Nm filter +is the command name and the +bracketed string +.Fl flag +is a +.Em flag +argument designated as optional by the option brackets. +In +.Nm \-mdoc +terms, +.Ar infile +and +.Ar outfile +are +called +.Em arguments . +The macros which formatted the above example: +.Bd -literal -offset indent +\&.Nm filter +\&.Op \&Fl flag +\&.Ar infile outfile +.Ed +.Pp +In the third case, discussion of commands and command syntax +includes both examples above, but may add more detail. +The +arguments +.Ar infile +and +.Ar outfile +from the example above might be referred to as +.Em operands +or +.Em file arguments . +Some command line argument lists are quite long: +.Bl -tag -width make -offset indent +.It Nm make +.Op Fl eiknqrstv +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl f Ar makefile +.Bk -words +.Op Fl I Ar directory +.Ek +.Op Fl j Ar max_jobs +.Op Ar variable=value +.Bk -words +.Op Ar target ... +.Ek +.El +.Pp +Here one might talk about the command +.Nm make +and qualify the argument +.Ar makefile , +as an argument to the flag, +.Fl f , +or discuss the optional +file +operand +.Ar target . +In the verbal context, such detail can prevent confusion, +however the +.Nm \-mdoc +package +does not have a macro for an argument +.Em to +a flag. +Instead the +.Ql \&Ar +argument macro is used for an operand or file argument like +.Ar target +as well as an argument to a flag like +.Ar variable . +The make command line was produced from: +.Bd -literal -offset indent +\&.Nm make +\&.Op Fl eiknqrstv +\&.Op Fl D Ar variable +\&.Op Fl d Ar flags +\&.Op Fl f Ar makefile +\&.Op Fl I Ar directory +\&.Op Fl j Ar max_jobs +\&.Op Ar variable=value +\&.Bk -words +\&.Op Ar target ... +\&.Ek +.Ed +.Pp +The +.Ql \&.Bk +and +.Ql \&.Ek +macros are explained in +.Sx Keeps . +.Ss General Syntax +The manual domain and general text domain macros share a similar +syntax with a few minor deviations: +.Ql \&.Ar , +.Ql \&.Fl , +.Ql \&.Nm , +and +.Ql \&.Pa +differ only when called without arguments; +.Ql \&.Fn +and +.Ql \&.Xr +impose an order on their argument lists +and the +.Ql \&.Op +and +.Ql \&.Fn +macros +have nesting limitations. +All content macros +are capable of recognizing and properly handling punctuation, +provided each punctuation character is separated by a leading space. +If an request is given: +.Pp +.Dl \&.Li sptr, ptr), +.Pp +The result is: +.Pp +.Dl Li sptr, ptr), +.Pp +The punctuation is not recognized and all is output in the +literal font. If the punctuation is separated by a leading +white space: +.Pp +.Dl \&.Li "sptr , ptr ) ," +.Pp +The result is: +.Pp +.Dl Li sptr , ptr ) , +.Pp +The punctuation is now recognized and is output in the +default font distinguishing it from the strings in literal font. +.Pp +To remove the special meaning from a punctuation character +escape it with +.Ql \e& . +.Xr Troff +is limited as a macro language, and has difficulty +when presented with a string containing +a member of the mathematical, logical or +quotation set: +.Bd -literal -offset indent-two +\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"} +.Ed +.Pp +The problem is that +.Xr troff +may assume it is supposed to actually perform the operation +or evaluation suggested by the characters. To prevent +the accidental evaluation of these characters, +escape them with +.Ql \e& . +Typical syntax is shown in the first content macro displayed +below, +.Ql \&.Ad . +.Ss Address Macro +The address macro identifies an address construct +of the form addr1[,addr2[,addr3]]. +.Pp +.Dl Usage: .Ad address ... \*(Pu +.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n +.It Li \&.Ad addr1 +.Ad addr1 +.It Li \&.Ad addr1\ . +.Ad addr1 . +.It Li \&.Ad addr1\ , file2 +.Ad addr1 , file2 +.It Li \&.Ad f1\ , f2\ , f3\ : +.Ad f1 , f2 , f3 : +.It Li \&.Ad addr\ )\ )\ , +.Ad addr ) ) , +.El +.Pp +It is an error to call +.Li \&.Ad +without arguments. +.Li \&.Ad +is callable by other macros and is parsed. +.Ss Argument Macro +The +.Li \&.Ar +argument macro may be used whenever +a command line argument is referenced. +.Pp +.Dl Usage: .Ar argument ... \*(Pu +.Bl -tag -width ".Ar file1 file2" -compact -offset 15n +.It Li \&.Ar +.Ar +.It Li \&.Ar file1 +.Ar file1 +.It Li \&.Ar file1\ . +.Ar file1 . +.It Li \&.Ar file1 file2 +.Ar file1 file2 +.It Li \&.Ar f1 f2 f3\ : +.Ar f1 f2 f3 : +.It Li \&.Ar file\ )\ )\ , +.Ar file ) ) , +.El +.Pp +If +.Li \&.Ar +is called without arguments +.Ql Ar +is assumed. +The +.Li \&.Ar +macro is parsed and is callable. +.Ss Configuration Declaration (section four only) +The +.Ql \&.Cd +macro is used to demonstrate a +.Xr config 8 +declaration for a device interface in a section four manual. +This macro accepts quoted arguments (double quotes only). +.Pp +.Bl -tag -width "device le0 at scode?" -offset indent +.It Cd "device le0 at scode?" +produced by: +.Ql ".Cd device le0 at scode?" . +.El +.Ss Command Modifier +The command modifier is identical to the +.Ql \&.Fl +(flag) command with the exception +the +.Ql \&.Cm +macro does not assert a dash +in front of every argument. +Traditionally flags are marked by the +preceding dash, some commands or subsets of commands do not use them. +Command modifiers may also be specified in conjunction with interactive +commands such as editor commands. +See +.Sx Flags . +.Ss Defined Variables +A variable which is defined in an include file is specified +by the macro +.Ql \&.Dv . +.Pp +.Dl Usage: .Dv defined_variable ... \*(Pu +.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n +.It Li ".Dv MAXHOSTNAMELEN" +.Dv MAXHOSTNAMELEN +.It Li ".Dv TIOCGPGRP )" +.Dv TIOCGPGRP ) +.El +.Pp +It is an error to call +.Ql \&.Dv +without arguments. +.Ql \&.Dv +is parsed and is callable. +.Ss Errno's (Section two only) +The +.Ql \&.Er +errno macro specifies the error return value +for section two library routines. +The second example +below shows +.Ql \&.Er +used with the +.Ql \&.Bq +general text domain macro, as it would be used in +a section two manual page. +.Pp +.Dl Usage: .Er ERRNOTYPE ... \*(Pu +.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n +.It Li \&.Er ENOENT +.Er ENOENT +.It Li \&.Er ENOENT\ )\ ; +.Er ENOENT ) ; +.It Li \&.Bq \&Er ENOTDIR +.Bq Er ENOTDIR +.El +.Pp +It is an error to call +.Ql \&.Er +without arguments. +The +.Ql \&.Er +macro is parsed and is callable. +.Ss Environment Variables +The +.Ql \&.Ev +macro specifies an environment variable. +.Pp +.Dl Usage: .Ev argument ... \*(Pu +.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n +.It Li \&.Ev DISPLAY +.Ev DISPLAY +.It Li \&.Ev PATH\ . +.Ev PATH . +.It Li \&.Ev PRINTER\ )\ )\ , +.Ev PRINTER ) ) , +.El +.Pp +It is an error to call +.Ql \&.Ev +without arguments. +The +.Ql \&.Ev +macro is parsed and is callable. +.Ss Function Argument +The +.Ql \&.Fa +macro is used to refer to function arguments (parameters) +outside of the +.Sx SYNOPSIS +section of the manual or inside +the +.Sx SYNOPSIS +section should a parameter list be too +long for the +.Ql \&.Fn +macro and the enclosure macros +.Ql \&.Fo +and +.Ql \&.Fc +must be used. +.Ql \&.Fa +may also be used to refer to structure members. +.Pp +.Dl Usage: .Fa function_argument ... \*(Pu +.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n +.It Li \&.Fa d_namlen\ )\ )\ , +.Fa d_namlen ) ) , +.It Li \&.Fa iov_len +.Fa iov_len +.El +.Pp +It is an error to call +.Ql \&.Fa +without arguments. +.Ql \&.Fa +is parsed and is callable. +.Ss Function Declaration +The +.Ql \&.Fd +macro is used in the +.Sx SYNOPSIS +section with section two or three +functions. +The +.Ql \&.Fd +macro does not call other macros and is not callable by other +macros. +.Pp +.Dl Usage: .Fd include_file (or defined variable) +.Pp +In the +.Sx SYNOPSIS +section a +.Ql \&.Fd +request causes a line break if a function has already been presented +and a break has not occurred. +This leaves a nice vertical space +in between the previous function call and the declaration for the +next function. +.Ss Flags +The +.Ql \&.Fl +macro handles command line flags. +It prepends +a dash, +.Ql \- , +to the flag. +For interactive command flags, which +are not prepended with a dash, the +.Ql \&.Cm +(command modifier) +macro is identical, but without the dash. +.Pp +.Dl Usage: .Fl argument ... \*(Pu +.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n +.It Li \&.Fl +.Fl +.It Li \&.Fl cfv +.Fl cfv +.It Li \&.Fl cfv\ . +.Fl cfv . +.It Li \&.Fl s v t +.Fl s v t +.It Li \&.Fl -\ , +.Fl - , +.It Li \&.Fl xyz\ )\ , +.Fl xyz ) , +.El +.Pp +The +.Ql \&.Fl +macro without any arguments results +in a dash representing stdin/stdout. +Note that giving +.Ql \&.Fl +a single dash, will result in two dashes. +The +.Ql \&.Fl +macro is parsed and is callable. +.Ss Functions (library routines) +The .Fn macro is modeled on ANSI C conventions. +.Bd -literal +Usage: .Fn [type] function [[type] parameters ... \*(Pu] +.Ed +.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact +.It Li "\&.Fn getchar" +.Fn getchar +.It Li "\&.Fn strlen ) ," +.Fn strlen ) , +.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , +.Fn "int align" "const * char *sptrs" , +.El +.Pp +It is an error to call +.Ql \&.Fn +without any arguments. +The +.Ql \&.Fn +macro +is parsed and is callable, +note that any call to another macro signals the end of +the +.Ql \&.Fn +call (it will close-parenthesis at that point). +.Pp +For functions that have more than eight parameters (and this +is rare), the +macros +.Ql \&.Fo +(function open) +and +.Ql \&.Fc +(function close) +may be used with +.Ql \&.Fa +(function argument) +to get around the limitation. For example: +.Bd -literal -offset indent +\&.Fo "int res_mkquery" +\&.Fa "int op" +\&.Fa "char *dname" +\&.Fa "int class" +\&.Fa "int type" +\&.Fa "char *data" +\&.Fa "int datalen" +\&.Fa "struct rrec *newrr" +\&.Fa "char *buf" +\&.Fa "int buflen" +\&.Fc +.Ed +.Pp +Produces: +.Bd -filled -offset indent +.Fo "int res_mkquery" +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Ed +.Pp +The +.Ql \&.Fo +and +.Ql \&.Fc +macros are parsed and are callable. +In the +.Sx SYNOPSIS +section, the function will always begin at +the beginning of line. +If there is more than one function +presented in the +.Sx SYNOPSIS +section and a function type has not been +given, a line break will occur, leaving a nice vertical space +between the current function name and the one prior. +At the moment, +.Ql \&.Fn +does not check its word boundaries +against troff line lengths and may split across a newline +ungracefully. +This will be fixed in the near future. +.Ss Function Type +This macro is intended for the +.Sx SYNOPSIS +section. +It may be used +anywhere else in the man page without problems, but its main purpose +is to present the function type in kernel normal form for the +.Sx SYNOPSIS +of sections two and three +(it causes a page break allowing the function name to appear +on the next line). +.Pp +.Dl Usage: .Ft type ... \*(Pu +.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact +.It Li \&.Ft struct stat +.Ft struct stat +.El +.Pp +The +.Ql \&.Ft +request is not callable by other macros. +.Ss Interactive Commands +The +.Ql \&.Ic +macro designates an interactive or internal command. +.Pp +.Dl Usage: .Li argument ... \*(Pu +.Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n +.It Li \&.Ic :wq +.Ic :wq +.It Li \&.Ic do while {...} +.Ic do while {...} +.It Li \&.Ic setenv\ , unsetenv +.Ic setenv , unsetenv +.El +.Pp +It is an error to call +.Ql \&.Ic +without arguments. +The +.Ql \&.Ic +macro is parsed and is callable. +.Ss Literals +The +.Ql \&.Li +literal macro may be used for special characters, +variable constants, anything which should be displayed as it +would be typed. +.Pp +.Dl Usage: .Li argument ... \*(Pu +.Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n +.It Li \&.Li \een +.Li \en +.It Li \&.Li M1 M2 M3\ ; +.Li M1 M2 M3 ; +.It Li \&.Li cntrl-D\ )\ , +.Li cntrl-D ) , +.It Li \&.Li 1024\ ... +.Li 1024 ... +.El +.Pp +The +.Ql \&.Li +macro is parsed and is callable. +.Ss Name Macro +The +.Ql \&.Nm +macro is used for the document title or subject name. +It has the peculiarity of remembering the first +argument it was called with, which should +always be the subject name of the page. +When called without +arguments, +.Ql \&.Nm +regurgitates this initial name for the sole purpose +of making less work for the author. +Note: +a section two +or three document function name is addressed with the +.Ql \&.Nm +in the +.Sx NAME +section, and with +.Ql \&.Fn +in the +.Sx SYNOPSIS +and remaining sections. +For interactive commands, such as the +.Ql while +command keyword in +.Xr csh 1 , +the +.Ql \&.Ic +macro should be used. +While the +.Ql \&.Ic +is nearly identical +to +.Ql \&.Nm , +it can not recall the first argument it was invoked with. +.Pp +.Dl Usage: .Nm argument ... \*(Pu +.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n +.It Li \&.Nm mdoc.sample +.Nm mdoc.sample +.It Li \&.Nm \e-mdoc +.Nm \-mdoc . +.It Li \&.Nm foo\ )\ )\ , +.Nm foo ) ) , +.It Li \&.Nm +.Nm +.El +.Pp +The +.Ql \&.Nm +macro is parsed and is callable. +.Ss Options +The +.Ql \&.Op +macro +places option brackets around the any remaining arguments on the command +line, and places any +trailing punctuation outside the brackets. +The macros +.Ql \&.Oc +and +.Ql \&.Oo +may be used across one or more lines. +.Pp +.Dl Usage: .Op options ... \*(Pu +.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent +.It Li \&.Op +.Op +.It Li ".Op Fl k" +.Op Fl k +.It Li ".Op Fl k ) ." +.Op Fl k ) . +.It Li ".Op Fl k Ar kookfile" +.Op Fl k Ar kookfile +.It Li ".Op Fl k Ar kookfile ," +.Op Fl k Ar kookfile , +.It Li ".Op Ar objfil Op Ar corfil" +.Op Ar objfil Op Ar corfil +.It Li ".Op Fl c Ar objfil Op Ar corfil ," +.Op Fl c Ar objfil Op Ar corfil , +.It Li \&.Op word1 word2 +.Op word1 word2 +.El +.Pp +The +.Ql \&.Oc +and +.Ql \&.Oo +macros: +.Bd -literal -offset indent +\&.Oo +\&.Op \&Fl k \&Ar kilobytes +\&.Op \&Fl i \&Ar interval +\&.Op \&Fl c \&Ar count +\&.Oc +.Ed +.Pp +Produce: +.Oo +.Op Fl k Ar kilobytes +.Op Fl i Ar interval +.Op Fl c Ar count +.Oc +.Pp +The macros +.Ql \&.Op , +.Ql \&.Oc +and +.Ql \&.Oo +are parsed and are callable. +.Ss Pathnames +The +.Ql \&.Pa +macro formats path or file names. +.Pp +.Dl Usage: .Pa pathname \*(Pu +.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n +.It Li \&.Pa /usr/share +.Pa /usr/share +.It Li \&.Pa /tmp/fooXXXXX\ )\ . +.Pa /tmp/fooXXXXX ) . +.El +.Pp +The +.Ql \&.Pa +macro is parsed and is callable. +.Ss Variables +Generic variable reference: +.Pp +.Dl Usage: .Va variable ... \*(Pu +.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n +.It Li \&.Va count +.Va count +.It Li \&.Va settimer , +.Va settimer , +.It Li \&.Va int\ *prt\ )\ : +.Va int\ *prt ) : +.It Li \&.Va char\ s\ ]\ )\ )\ , +.Va char\ s ] ) ) , +.El +.Pp +It is an error to call +.Ql \&.Va +without any arguments. +The +.Ql \&.Va +macro is parsed and is callable. +.Ss Manual Page Cross References +The +.Ql \&.Xr +macro expects the first argument to be +a manual page name, and the second argument, if it exists, +to be either a section page number or punctuation. +Any +remaining arguments are assumed to be punctuation. +.Pp +.Dl Usage: .Xr man_page [1,...,8] \*(Pu +.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n +.It Li \&.Xr mdoc +.Xr mdoc +.It Li \&.Xr mdoc\ , +.Xr mdoc , +.It Li \&.Xr mdoc 7 +.Xr mdoc 7 +.It Li \&.Xr mdoc 7\ )\ )\ , +.Xr mdoc 7 ) ) , +.El +.Pp +The +.Ql \&.Xr +macro is parsed and is callable. +It is an error to call +.Ql \&.Xr +without +any arguments. +.Sh GENERAL TEXT DOMAIN +.Ss AT&T Macro +.Bd -literal -offset indent -compact +Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu +.Ed +.Bl -tag -width ".At v6 ) ," -compact -offset 14n +.It Li ".At" +.At +.It Li ".At v6 ." +.At v6 . +.El +.Pp +The +.Ql \&.At +macro is +.Em not +parsed and +.Em not +callable. It accepts at most two arguments. +.Ss BSD Macro +.Dl Usage: .Bx [Version/release] ... \*(Pu +.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n +.It Li ".Bx" +.Bx +.It Li ".Bx 4.3 ." +.Bx 4.3 . +.El +.Pp +The +.Ql \&.Bx +macro is parsed and is callable. +.Ss UNIX Macro +.Dl Usage: .Ux ... \*(Pu +.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n +.It Li ".Ux" +.Ux +.El +.Pp +The +.Ql \&.Ux +macro is parsed and is callable. +.Ss Emphasis Macro +Text may be stressed or emphasized with the +.Ql \&.Em +macro. +The usual font for emphasis is italic. +.Pp +.Dl Usage: .Em argument ... \*(Pu +.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n +.It Li ".Em does not" +.Em does not +.It Li ".Em exceed 1024 ." +.Em exceed 1024 . +.It Li ".Em vide infra ) ) ," +.Em vide infra ) ) , +.El +.\" .Pp +.\" The emphasis can be forced across several lines of text by using +.\" the +.\" .Ql \&.Bf +.\" macro discussed in +.\" .Sx Modes +.\" under +.\" .Sx PAGE STRUCTURE DOMAIN . +.\" .Pp +.\" .Bf -emphasis +.\" We are certain the reason most people desire a Harvard MBA +.\" so they can become to be successful philanthropists. Only +.\" mathematicians and physicists go to graduate school strictly +.\" to acquire infinite wealthy and fame. Its that inifinity +.\" word that does it to them. Ruins them. +.\" .Ef +.Pp +The +.Ql \&.Em +macro is parsed and is callable. +It is an error to call +.Ql \&.Em +without arguments. +.Ss Enclosure and Quoting Macros +The concept of enclosure is similar to quoting. +The object being to enclose one or more strings between +a pair of characters like quotes or parentheses. +The terms quoting and enclosure are used +interchangeably throughout this document. +Most of the +one line enclosure macros end +in small letter +.Ql q +to give a hint of quoting, but there are a few irregularities. +For each enclosure macro +there is also a pair of open and close macros which end +in small letters +.Ql o +and +.Ql c +respectively. +These can be used across one or more lines of text +and while they have nesting limitations, the one line quote macros +can be used inside +of them. +.Pp +.ne 5 +.Bd -filled -offset indent +.Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX +.Em " Quote Close Open Function Result" +\&.Aq .Ac .Ao Angle Bracket Enclosure <string> +\&.Bq .Bc .Bo Bracket Enclosure [string] +\&.Dq .Dc .Do Double Quote ``string'' + .Ec .Eo Enclose String (in XX) XXstringXX +\&.Pq .Pc .Po Parenthesis Enclosure (string) +\&.Ql Quoted Literal `st' or string +\&.Qq .Qc .Qo Straight Double Quote "string" +\&.Sq .Sc .So Single Quote `string' +.El +.Ed +.Pp +Except for the irregular macros noted below, all +of the quoting macros are parsed and callable. +All handle punctuation properly, as long as it +is presented one character at a time and separated by spaces. +The quoting macros examine opening and closing punctuation +to determine whether it comes before or after the +enclosing string. This makes some nesting possible. +.Bl -tag -width xxx,xxxx +.It Li \&.Ec , \&.Eo +These macros expect the first argument to be the +opening and closing strings respectively. +.It Li \&.Ql +The quoted literal macro behaves differently for +.Xr troff +than +.Xr nroff . +If formatted with +.Xr nroff , +a quoted literal is always quoted. If formatted with +troff, an item is only quoted if the width +of the item is less than three constant width characters. +This is to make short strings more visible where the font change +to literal (constant width) is less noticeable. +.It Li \&.Pf +The prefix macro is not callable, but it is parsed: +.Bl -tag -width "(namexx" -offset indent +.It Li ".Pf ( Fa name2" +becomes +.Pf ( Fa name2 . +.El +.Pp +The +.Ql \&.Ns +(no space) macro performs the analogous suffix function. +.El +.Pp +.ne 4 +Examples of quoting: +.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent +.It Li \&.Aq +.Aq +.It Li \&.Aq \&Ar ctype.h\ )\ , +.Aq Ar ctype.h ) , +.It Li \&.Bq +.Bq +.It Li \&.Bq \&Em Greek \&, French \&. +.Bq Em Greek , French . +.It Li \&.Dq +.Dq +.It Li ".Dq string abc ." +.Dq string abc . +.It Li ".Dq \'^[A-Z]\'" +.Dq \'^[A-Z]\' +.It Li "\&.Ql man mdoc" +.Ql man mdoc +.It Li \&.Qq +.Qq +.It Li "\&.Qq string ) ," +.Qq string ) , +.It Li "\&.Qq string Ns )," +.Qq string Ns ), +.It Li \&.Sq +.Sq +.It Li "\&.Sq string +.Sq string +.El +.Pp +For a good example of nested enclosure macros, see the +.Ql \&.Op +option macro. +It was created from the same +underlying enclosure macros as those presented in the list +above. +The +.Ql \&.Xo +and +.Ql \&.Xc +extended argument list macros +were also built from the same underlying routines and are a good +example of +.Nm \-mdoc +macro usage at its worst. +.Ss No\-Op or Normal Text Macro +The macro +.Li \&.No +is +a hack for words in a macro command line which should +.Em not +be formatted and follows the conventional syntax +for content macros. +.Ss No Space Macro +The +.Ql \&.Ns +macro eliminates unwanted spaces in between macro requests. +It is useful for old style argument lists where there is no space +between the flag and argument: +.Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent +.It Li ".Op Fl I Ns Ar directory" +produces +.Op Fl I Ns Ar directory +.El +.Pp +Note: the +.Ql \&.Ns +macro always invokes the +.Ql \&.No +macro after eliminating the space unless another macro name +follows it. +The macro +.Ql \&.Ns +is parsed and is callable. +.Ss Section Cross References +The +.Ql \&.Sx +macro designates a reference to a section header +within the same document. +It is parsed and is callable. +.Pp +.Bl -tag -width "Li \&.Sx FILES" -offset 14n +.It Li \&.Sx FILES +.Sx FILES +.El +.Ss Symbolic +The symbolic emphasis macro is generally a boldface macro in +either the symbolic sense or the traditional English usage. +.Pp +.Dl Usage: .Sy symbol ... \*(Pu +.Bl -tag -width ".Sy Important Noticex" -compact -offset 14n +.It Li \&.Sy Important Notice +.Sy Important Notice +.El +.Pp +The +.Ql \&.Sy +macro is parsed and is callable. +Arguments to +.Ql \&.Sy +may be quoted. +.Ss References and Citations +The following macros make a modest attempt to handle references. +At best, the macros make it convenient to manually drop in a subset of +refer style references. +.Pp +.Bl -tag -width 6n -offset indent -compact +.It Li ".Rs" +Reference Start. +Causes a line break and begins collection +of reference information until the +reference end macro is read. +.It Li ".Re" +Reference End. +The reference is printed. +.It Li ".%A" +Reference author name, one name per invocation. +.It Li ".%B" +Book title. +.It Li ".\&%C" +City/place. +.It Li ".\&%D" +Date. +.It Li ".%J" +Journal name. +.It Li ".%N" +Issue number. +.It Li ".%O" +Optional information. +.It Li ".%P" +Page number. +.It Li ".%R" +Report name. +.It Li ".%T" +Title of article. +.It Li ".%V" +Volume(s). +.El +.Pp +The macros beginning with +.Ql % +are not callable, and are parsed only for the trade name macro which +returns to its caller. +(And not very predictably at the moment either.) +The purpose is to allow trade names +to be pretty printed in +.Xr troff Ns / Ns Xr ditroff +output. +.Ss Trade Names (or Acronyms and Type Names) +The trade name macro is generally a small caps macro for +all upper case words longer than two characters. +.Pp +.Dl Usage: .Tn symbol ... \*(Pu +.Bl -tag -width ".Tn ASCII" -compact -offset 14n +.It Li \&.Tn DEC +.Tn DEC +.It Li \&.Tn ASCII +.Tn ASCII +.El +.Pp +The +.Ql \&.Tn +macro +is parsed and is callable by other macros. +.Ss Extended Arguments +The +.Li \&.Xo +and +.Li \&.Xc +macros allow one to extend an argument list +on a macro boundary. +Argument lists cannot +be extended within a macro +which expects all of its arguments on one line such +as +.Ql \&.Op . +.Pp +Here is an example of +.Ql \&.Xo +using the space mode macro to turn spacing off: +.Bd -literal -offset indent +\&.Sm off +\&.It Xo Sy I Ar operation +\&.No \een Ar count No \een +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Xo Sy I Ar operation +.No \en Ar count No \en +.Xc +.Sm on +.El +.Ed +.Pp +Another one: +.Bd -literal -offset indent +\&.Sm off +\&.It Cm S No \&/ Ar old_pattern Xo +\&.No \&/ Ar new_pattern +\&.No \&/ Op Cm g +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Cm S No \&/ Ar old_pattern Xo +.No \&/ Ar new_pattern +.No \&/ Op Cm g +.Xc +.Sm on +.El +.Ed +.Pp +Another example of +.Ql \&.Xo +and using enclosure macros: +Test the value of an variable. +.Bd -literal -offset indent +\&.It Xo +\&.Ic .ifndef +\&.Oo \e&! Oc Ns Ar variable +\&.Op Ar operator variable ... +\&.Xc +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.It Xo +.Ic .ifndef +.Oo \&! Oc Ns Ar variable +.Op Ar operator variable ... +.Xc +.El +.Ed +.Pp +All of the above examples have used the +.Ql \&.Xo +macro on the argument list of the +.Ql \&.It +(list-item) +macro. +The extend macros are not used very often, and when they are +it is usually to extend the list-item argument list. +Unfortunately, this is also where the extend macros are the +most finicky. +In the first two examples, spacing was turned off; +in the third, spacing was desired in part of the output but +not all of it. +To make these macros work in this situation make sure +the +.Ql \&.Xo +and +.Ql \&.Xc +macros are placed as shown in the third example. +If the +.Ql \&.Xo +macro is not alone on the +.Ql \&.It +argument list, spacing will be unpredictable. +The +.Ql \&.Ns +(no space macro) +must not occur as the first or last macro on a line +in this situation. +Out of 900 manual pages (about 1500 actual pages) +currently released with +.Bx +only fifteen use the +.Ql \&.Xo +macro. +.Sh PAGE STRUCTURE DOMAIN +.Ss Section Headers +The first three +.Ql \&.Sh +section header macros +list below are required in every +man page. +The remaining section headers +are recommended at the discretion of the author +writing the manual page. +The +.Ql \&.Sh +macro can take up to nine arguments. +It is parsed and but is not callable. +.Bl -tag -width ".Sh SYNOPSIS" +.It \&.Sh NAME +The +.Ql \&.Sh NAME +macro is mandatory. +If not specified, +the headers, footers and page layout defaults +will not be set and things will be rather unpleasant. +The +.Sx NAME +section consists of at least three items. +The first is the +.Ql \&.Nm +name macro naming the subject of the man page. +The second is the Name Description macro, +.Ql \&.Nd , +which separates the subject +name from the third item, which is the description. +The +description should be the most terse and lucid possible, +as the space available is small. +.It \&.Sh SYNOPSIS +The +.Sx SYNOPSIS +section describes the typical usage of the +subject of a man page. +The macros required +are either +.Ql ".Nm" , +.Ql ".Cd" , +.Ql ".Fn" , +(and possibly +.Ql ".Fo" , +.Ql ".Fc" , +.Ql ".Fd" , +.Ql ".Ft" +macros). +The function name +macro +.Ql ".Fn" +is required +for manual page sections 2 and 3, the command and general +name macro +.Ql \&.Nm +is required for sections 1, 5, 6, 7, 8. +Section 4 manuals require a +.Ql ".Nm" , ".Fd" +or a +.Ql ".Cd" +configuration device usage macro. +Several other macros may be necessary to produce +the synopsis line as shown below: +.Pp +.Bd -filled -offset indent +.Nm cat +.Op Fl benstuv +.Op Fl +.Ar +.Ed +.Pp +The following macros were used: +.Pp +.Dl \&.Nm cat +.Dl \&.Op \&Fl benstuv +.Dl \&.Op \&Fl +.Dl \&.Ar +.Pp +.Sy Note : +The macros +.Ql \&.Op , +.Ql \&.Fl , +and +.Ql \&.Ar +recognize the pipe bar character +.Ql \*(Ba , +so a command line such as: +.Pp +.Dl ".Op Fl a | Fl b" +.Pp +will not go orbital. +.Xr Troff +normally interprets a \*(Ba as a special operator. +See +.Sx PREDEFINED STRINGS +for a usable \*(Ba +character in other situations. +.It \&.Sh DESCRIPTION +In most cases the first text in the +.Sx DESCRIPTION +section +is a brief paragraph on the command, function or file, +followed by a lexical list of options and respective +explanations. +To create such a list, the +.Ql \&.Bl +begin-list, +.Ql \&.It +list-item and +.Ql \&.El +end-list +macros are used (see +.Sx Lists and Columns +below). +.El +.Pp +The following +.Ql \&.Sh +section headers are part of the +preferred manual page layout and must be used appropriately +to maintain consistency. +They are listed in the order +in which they would be used. +.Bl -tag -width SYNOPSIS +.It \&.Sh ENVIRONMENT +The +.Sx ENVIRONMENT +section should reveal any related +environment +variables and clues to their behavior and/or usage. +.It \&.Sh EXAMPLES +There are several ways to create examples. +See +the +.Sx EXAMPLES +section below +for details. +.It \&.Sh FILES +Files which are used or created by the man page subject +should be listed via the +.Ql \&.Pa +macro in the +.Sx FILES +section. +.It \&.Sh SEE ALSO +References to other material on the man page topic and +cross references to other relevant man pages should +be placed in the +.Sx SEE ALSO +section. +Cross references +are specified using the +.Ql \&.Xr +macro. +At this time +.Xr refer 1 +style references are not accommodated. +.It \&.Sh STANDARDS +If the command, library function or file adheres to a +specific implementation such as +.St -p1003.2 +or +.St -ansiC +this should be noted here. +If the +command does not adhere to any standard, its history +should be noted in the +.Sx HISTORY +section. +.It \&.Sh HISTORY +Any command which does not adhere to any specific standards +should be outlined historically in this section. +.It \&.Sh AUTHORS +Credits, if need be, should be placed here. +.It \&.Sh DIAGNOSTICS +Diagnostics from a command should be placed in this section. +.It \&.Sh ERRORS +Specific error handling, especially from library functions +(man page sections 2 and 3) should go here. +The +.Ql \&.Er +macro is used to specify an errno. +.It \&.Sh BUGS +Blatant problems with the topic go here... +.El +.Pp +User specified +.Ql \&.Sh +sections may be added, +for example, this section was set with: +.Bd -literal -offset 14n +\&.Sh PAGE LAYOUT MACROS +.Ed +.Ss Paragraphs and Line Spacing. +.Bl -tag -width 6n +.It \&.Pp +The \&.Pp paragraph command may +be used to specify a line space where necessary. +The macro is not necessary after a +.Ql \&.Sh +or +.Ql \&.Ss +macro or before +a +.Ql \&.Bl +macro. +(The +.Ql \&.Bl +macro asserts a vertical distance unless the -compact flag is given). +.El +.\" This worked with version one, need to redo for version three +.\" .Pp +.\" .Ds I +.\" .Cw (ax+bx+c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va ax +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va ax +.\" .Cx + +.\" .Va by +.\" .Cx + +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Va by +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" This example shows the same equation in a different format. +.\" The spaces +.\" around the +.\" .Li \&+ +.\" signs were forced with +.\" .Li \e : +.\" .Pp +.\" .Ds I +.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va a +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy x +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va a +.\" .Sy x +.\" .Cx \ +\ \& +.\" .Va b +.\" .Sy y +.\" .Cx \ +\ \& +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cl Cx \t\t +.\" .Li \&.Va b +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy y +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" The incantation below was +.\" lifted from the +.\" .Xr adb 1 +.\" manual page: +.\" .Pp +.\" .Ds I +.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by +.\" .Cl Cx \t\t +.\" .Li \&.Cx Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Nm m +.\" .Cx +.\" .Cl Cx Op Sy ?/ +.\" .Nm m +.\" .Ad \ b1 e1 f1 +.\" .Op Sy ?/ +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Ar \e\ b1 e1 f1 +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.Ss Keeps +The only keep that is implemented at this time is for words. +The macros are +.Ql \&.Bk +(begin-keep) +and +.Ql \&.Ek +(end-keep). +The only option that +.Ql \&.Bl +accepts is +.Fl words +and is useful for preventing line breaks in the middle of options. +In the example for the make command line arguments (see +.Sx What's in a name ) , +the keep prevented +.Xr nroff +from placing up the +flag and the argument +on separate lines. +(Actually, the option macro used to prevent this from occurring, +but was dropped when the decision (religious) was made to force +right justified margins in +.Xr troff +as options in general look atrocious when spread across a sparse +line. +More work needs to be done with the keep macros, a +.Fl line +option needs to be added.) +.Ss Examples and Displays +There are five types of displays, a quickie one line indented display +.Ql \&.D1 , +a quickie one line literal display +.Ql \&.Dl , +and a block literal, block filled and block ragged which use +the +.Ql \&.Bd +begin-display +and +.Ql \&.Ed +end-display macros. +.Pp +.Bl -tag -width \&.Dlxx +.It Li \&.D1 +(D-one) Display one line of indented text. +This macro is parsed, but it is not callable. +.Pp +.Dl Fl ldghfstru +.Pp +The above was produced by: +.Li \&.Dl Fl ldghfstru . +.It Li \&.Dl +(D-ell) +Display one line of indented +.Em literal +text. +The +.Ql \&.Dl +example macro has been used throughout this +file. +It allows +the indent (display) of one line of text. +Its default font is set to +constant width (literal) however +it is parsed and will recognized other macros. +It is not callable however. +.Pp +.Dl % ls -ldg /usr/local/bin +.Pp +The above was produced by +.Li \&.Dl % ls -ldg /usr/local/bin . +.It Li \&.Bd +Begin-display. +The +.Ql \&.Bd +display must be ended with the +.Ql \&.Ed +macro. +Displays may be nested within displays and +lists. +.Ql \&.Bd +has the following syntax: +.Pp +.Dl ".Bd display-type [-offset offset_value] [-compact]" +.Pp +The display-type must be one of the following four types and +may have an offset specifier for indentation: +.Ql \&.Bd . +.Pp +.Bl -tag -width "file file_name " -compact +.It Fl ragged +Display a block of text as typed, +right (and left) margin edges are left ragged. +.It Fl filled +Display a filled (formatted) block. +The block of text is formatted (the edges are filled \- +not left unjustified). +.It Fl literal +Display a literal block, useful for source code or +simple tabbed or spaced text. +.It Fl file Ar file_name +The file name following the +.Fl file +flag is read and displayed. +Literal mode is +asserted and tabs are set at 8 constant width character +intervals, however any +.Xr troff/ Ns Nm \-mdoc +commands in file will be processed. +.It Fl offset Ar string +If +.Fl offset +is specified with one of the following strings, the string +is interpreted to indicate the level of indentation for the +forthcoming block of text: +.Pp +.Bl -tag -width "indent-two" -compact +.It Ar left +Align block on the current left margin, +this is the default mode of +.Ql \&.Bd . +.It Ar center +Supposedly center the block. +At this time +unfortunately, the block merely gets +left aligned about an imaginary center margin. +.It Ar indent +Indents by one default indent value or tab. +The default +indent value is also used for the +.Ql \&.D1 +display so one is guaranteed the two types of displays +will line up. +This indent is normally set to 6n or about two +thirds of an inch (six constant width characters). +.It Ar indent-two +Indents two times the default indent value. +.It Ar right +This +.Em left +aligns the block about two inches from +the right side of the page. +This macro needs +work and perhaps may never do the right thing by +.Xr troff . +.El +.El +.It ".Ed" +End-display. +.El +.Ss Tagged Lists and Columns +There are several types of lists which may be initiated with the +.Ql ".Bl" +begin-list macro. +Items within the list +are specified with the +.Ql ".It" +item macro and +each list must end with the +.Ql ".El" +macro. +Lists may be nested within themselves and within displays. +Columns may be used inside of lists, but lists are unproven +inside of columns. +.Pp +In addition, several list attributes may be specified such as +the width of a tag, the list offset, and compactness +(blank lines between items allowed or disallowed). +Most of this document has been formatted with a tag style list +.Pq Fl tag . +For a change of pace, the list-type used to present the list-types +is an over-hanging list +.Pq Fl ohang . +This type of list is quite popular with +.Tn TeX +users, but might look a bit funny after having read many pages of +tagged lists. +The following list types are accepted by +.Ql ".Bl" : +.Pp +.Bl -ohang -compact +.It Fl bullet +.It Fl item +.It Fl enum +These three are the simplest types of lists. +Once the +.Ql ".Bl" +macro has been given, items in the list are merely +indicated by a line consisting solely of the +.Ql ".It" +macro. +For example, the source text for a simple enumerated list +would look like: +.Bd -literal -offset indent-two +\&.Bl -enum -compact +\&.It +\&Item one goes here. +\&.It +\&And item two here. +\&.It +\&Lastly item three goes here. +\&.El +.Ed +.Pp +The results: +.Pp +.Bl -enum -offset indent-two -compact +.It +Item one goes here. +.It +And item two here. +.It +Lastly item three goes here. +.El +.Pp +A simple bullet list construction: +.Bd -literal -offset indent-two +\&.Bl -bullet -compact +\&.It +\&Bullet one goes here. +\&.It +\&Bullet two here. +\&.El +.Ed +.Pp +Produces: +.Bl -bullet -offset indent-two -compact +.It +Bullet one goes here. +.It +Bullet two here. +.El +.Pp +.It Fl tag +.It Fl diag +.It Fl hang +.It Fl ohang +.It Fl inset +These list-types collect arguments specified with the +.Ql \&.It +macro and create a label which may be +.Em inset +into the forthcoming text, +.Em hanged +from the forthcoming text, +.Em overhanged +from above and not indented or +.Em tagged . +This +list was constructed with the +.Ql Fl ohang +list-type. +The +.Ql \&.It +macro is parsed only for the inset, hang +and tag list-types and is not callable. +Here is an example of inset labels: +.Bl -inset -offset indent +.It Em Tag +The tagged list (also called a tagged paragraph) is the +most common type of list used in the Berkeley manuals. +.It Em Diag +Diag lists create section four diagnostic lists +and are similar to inset lists except callable +macros are ignored. +.It Em Hang +Hanged labels are a matter of taste. +.It Em Ohang +Overhanging labels are nice when space is constrained. +.It Em Inset +Inset labels are useful for controlling blocks of +paragraphs and are valuable for converting +.Nm \-mdoc +manuals to other formats. +.El +.Pp +Here is the source text which produced the above example: +.Bd -literal -offset indent +\&.Bl -inset -offset indent +\&.It Em Tag +\&The tagged list (also called a tagged paragraph) is the +\&most common type of list used in the Berkeley manuals. +\&.It Em Diag +\&Diag lists create section four diagnostic lists +\&and are similar to inset lists except callable +\¯os are ignored. +\&.It Em Hang +\&Hanged labels are a matter of taste. +\&.It Em Ohang +\&Overhanging labels are nice when space is constrained. +\&.It Em Inset +\&Inset labels are useful for controlling blocks of +\¶graphs and are valuable for converting +\&.Nm \-mdoc +\&manuals to other formats. +\&.El +.Ed +.Pp +Here is a hanged list with just one item: +.Bl -hang -offset indent +.It Em Hanged +labels appear similar to tagged lists when the +label is smaller than the label width. +.It Em Longer hanged list labels +blend in to the paragraph unlike +tagged paragraph labels. +.El +.Pp +And the unformatted text which created it: +.Bd -literal -offset indent +\&.Bl -hang -offset indent +\&.It Em Hanged +\&labels appear similar to tagged lists when the +\&label is smaller than the label width. +\&.It Em Longer hanged list labels +\&blend in to the paragraph unlike +\&tagged paragraph labels. +\&.El +.Ed +.Pp +The tagged list which follows uses an optional width specifier to control +the width of the tag. +.Pp +.Bl -tag -width "PAGEIN" -compact -offset indent +.It SL +sleep time of the process (seconds blocked) +.It PAGEIN +number of disk +.Tn I/O Ns 's +resulting from references +by the process to pages not loaded in core. +.It UID +numerical user-id of process owner +.It PPID +numerical id of parent of process process priority +(non-positive when in non-interruptible wait) +.El +.Pp +The raw text: +.Bd -literal -offset indent +\&.Bl -tag -width "PAGEIN" -compact -offset indent +\&.It SL +\&sleep time of the process (seconds blocked) +\&.It PAGEIN +\&number of disk +\&.Tn I/O Ns 's +\&resulting from references +\&by the process to pages not loaded in core. +\&.It UID +\&numerical user-id of process owner +\&.It PPID +\&numerical id of parent of process process priority +\&(non-positive when in non-interruptible wait) +\&.El +.Ed +.Pp +Acceptable width specifiers: +.Bl -tag -width Ar -offset indent +.It Fl width Ar "\&Fl" +sets the width to the default width for a flag. +All callable +macros have a default width value. +The +.Ql \&.Fl , +value is presently +set to ten constant width characters or about five sixth of +an inch. +.It Fl width Ar "24n" +sets the width to 24 constant width characters or about two +inches. +The +.Ql n +is absolutely necessary for the scaling to work correctly. +.It Fl width Ar "ENAMETOOLONG" +sets width to the constant width length of the +string given. +.It Fl width Ar "\\*qint mkfifo\\*q" +again, the width is set to the constant width of the string +given. +.El +.Pp +If a width is not specified for the tag list type, the first +time +.Ql \&.It +is invoked, an attempt is made to determine an appropriate +width. +If the first argument to +.Ql ".It" +is a callable macro, the default width for that macro will be used +as if the macro name had been supplied as the width. +However, +if another item in the list is given with a different callable +macro name, a new and nested list is assumed. +.Sh PREDEFINED STRINGS +The following strings are predefined as may be used by +preceding with the troff string interpreting sequence +.Ql \&\e*(xx +where +.Em xx +is the name of the defined string or as +.Ql \&\e*x +where +.Em x +is the name of the string. +The interpreting sequence may be used any where in the text. +.Pp +.Bl -column "String " "Nroff " "Troff " -offset indent +.It Sy "String Nroff Troff" +.It Li "<=" Ta \&<\&= Ta \*(<= +.It Li ">=" Ta \&>\&= Ta \*(>= +.It Li "Rq" Ta "''" Ta \*(Rq +.It Li "Lq" Ta "``" Ta \*(Lq +.It Li "ua" Ta ^ Ta \*(ua +.It Li "aa" Ta ' Ta \*(aa +.It Li "ga" Ta \` Ta \*(ga +.\" .It Li "sL" Ta ` Ta \*(sL +.\" .It Li "sR" Ta ' Ta \*(sR +.It Li "q" Ta \&" Ta \*q +.It Li "Pi" Ta pi Ta \*(Pi +.It Li "Ne" Ta != Ta \*(Ne +.It Li "Le" Ta <= Ta \*(Le +.It Li "Ge" Ta >= Ta \*(Ge +.It Li "Lt" Ta < Ta \*(Gt +.It Li "Gt" Ta > Ta \*(Lt +.It Li "Pm" Ta +- Ta \*(Pm +.It Li "If" Ta infinity Ta \*(If +.It Li "Na" Ta \fINaN\fP Ta \*(Na +.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba +.El +.Pp +.Sy Note : +The string named +.Ql q +should be written as +.Ql \e*q +since it is only one char. +.Sh DIAGNOSTICS +The debugging facilities for +.Nm \-mdoc +are limited, but can help detect subtle errors such +as the collision of an argument name with an internal +register or macro name. +(A what?) +A register is an arithmetic storage class for +.Xr troff +with a one or two character name. +All registers internal to +.Nm \-mdoc +for +.Xr troff +and +.Xr ditroff +are two characters and +of the form <upper_case><lower_case> such as +.Ql \&Ar , +<lower_case><upper_case> as +.Ql \&aR +or +<upper or lower letter><digit> as +.Ql \&C\&1 . +And adding to the muddle, +.Xr troff +has its own internal registers all of which are either +two lower case characters or a dot plus a letter or meta-character +character. +In one of the introduction examples, it was shown how to +prevent the interpretation of a macro name with the escape sequence +.Ql \e& . +This is sufficient for the internal register names also. +.Pp +.\" Every callable macro name has a corresponding register +.\" of the same name (<upper_case><lower_case>). +.\" There are also specific registers which have +.\" been used for stacks and arrays and are listed in the +.\" .Sx Appendix . +.\" .Bd -ragged -offset 4n +.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') +.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') +.\" C[0-9] argument types (example C1) +.\" O[0-9] offset stack (displays) +.\" h[0-9] horizontal spacing stack (lists) +.\" o[0-9] offset (stack) (lists) +.\" t[0-9] tag stack (lists) +.\" v[0-9] vertical spacing stack (lists) +.\" w[0-9] width tag/label stack +.\" .Ed +.\" .Pp +If a non-escaped register name is given in the argument list of a request +unpredictable behavior will occur. +In general, any time huge portions +of text do not appear where expected in the output, or small strings +such as list tags disappear, chances are there is a misunderstanding +about an argument type in the argument list. +Your mother never intended for you to remember this evil stuff - so here +is a way to find out whether or not your arguments are valid: The +.Ql \&.Db +(debug) +macro displays the interpretation of the argument list for most +macros. +Macros such as the +.Ql \&.Pp +(paragraph) +macro do not contain debugging information. +All of the callable macros do, +and it is strongly advised whenever in doubt, +turn on the +.Ql \&.Db +macro. +.Pp +.Dl Usage: \&.Db [on | off] +.Pp +An example of a portion of text with +the debug macro placed above and below an +artificially created problem (a flag argument +.Ql \&aC +which should be +.Ql \e&aC +in order to work): +.Bd -literal -offset indent +\&.Db on +\&.Op Fl aC Ar file ) +\&.Db off +.Ed +.Pp +The resulting output: +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(argv) MACRO: `.Op' Line #: 2 + Argc: 1 Argv: `Fl' Length: 2 + Space: `' Class: Executable + Argc: 2 Argv: `aC' Length: 2 + Space: `' Class: Executable + Argc: 3 Argv: `Ar' Length: 2 + Space: `' Class: Executable + Argc: 4 Argv: `file' Length: 4 + Space: ` ' Class: String + Argc: 5 Argv: `)' Length: 1 + Space: ` ' Class: Closing Punctuation or suffix + MACRO REQUEST: .Op Fl aC Ar file ) +DEBUGGING OFF +.Ed +.Pp +The first line of information tells the name of the calling +macro, here +.Ql \&.Op , +and the line number it appears on. +If one or more files are involved +(especially if text from another file is included) the line number +may be bogus. +If there is only one file, it should be accurate. +The second line gives the argument count, the argument +.Pq Ql \&Fl +and its length. +If the length of an argument is two characters, the +argument is tested to see if it is executable (unfortunately, any +register which contains a non-zero value appears executable). +The third line gives the space allotted for a class, and the +class type. +The problem here is the argument aC should not be +executable. +The four types of classes are string, executable, closing +punctuation and opening punctuation. +The last line shows the entire +argument list as it was read. +In this next example, the offending +.Ql \&aC +is escaped: +.Bd -literal -offset indent +\&.Db on +\&.Em An escaped \e&aC +\&.Db off +.Ed +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(fargv) MACRO: `.Em' Line #: 2 + Argc: 1 Argv: `An' Length: 2 + Space: ` ' Class: String + Argc: 2 Argv: `escaped' Length: 7 + Space: ` ' Class: String + Argc: 3 Argv: `aC' Length: 2 + Space: ` ' Class: String + MACRO REQUEST: .Em An escaped &aC +DEBUGGING OFF +.Ed +.Pp +The argument +.Ql \e&aC +shows up with the same length of 2 as the +.Ql \e& +sequence produces a zero width, but a register +named +.Ql \e&aC +was not found and the type classified as string. +.Pp +Other diagnostics consist of usage statements and are self explanatory. +.Sh GROFF, TROFF AND NROFF +The +.Nm \-mdoc +package does not need compatibility mode with +.Xr groff . +.Pp +The package inhibits page breaks, and the headers and footers +which normally occur at those breaks with +.Xr nroff , +to make the manual more efficient for viewing on-line. +At the moment, +.Xr groff +with +.Fl T Ns Ar ascii +does eject the imaginary remainder of the page at end of file. +The inhibiting of the page breaks makes +.Xr nroff Ns 'd +files unsuitable for hardcopy. +There is a register named +.Ql \&cR +which can be set to zero in the site dependent style file +.Pa /usr/src/share/tmac/doc-nroff +to restore the old style behavior. +.Sh FILES +.Bl -tag -width /usr/share/man0/template.doc -compact +.It Pa /usr/share/tmac/tmac.doc +manual macro package +.It Pa /usr/share/man0/template.doc +template for writing a man page +.El +.Sh SEE ALSO +.Xr mdoc 7 , +.Xr man 1 , +.Xr troff 1 +.Sh BUGS +Undesirable hyphenation on the dash of a flag +argument is not yet resolved, and causes +occasional mishaps in the +.Sx DESCRIPTION +section. +(line break on the hyphen). +.Pp +Predefined strings are not declared in documentation. +.Pp +Section 3f has not been added to the header routines. +.Pp +.Ql \&.Nm +font should be changed in +.Sx NAME +section. +.Pp +.Ql \&.Fn +needs to have a check to prevent splitting up +if the line length is too short. +Occasionally it +separates the last parenthesis, and sometimes +looks ridiculous if a line is in fill mode. +.Pp +The method used to prevent header and footer page +breaks (other than the initial header and footer) when using +nroff occasionally places an unsightly partially filled line (blank) +at the would be bottom of the page. +.Pp +The list and display macros to not do any keeps +and certainly should be able to. +.\" Note what happens if the parameter list overlaps a newline +.\" boundary. +.\" to make sure a line boundary is crossed: +.\" .Bd -literal +.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" nudge +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . +.\" .Pp +.\" If double quotes are used, for example: +.\" .Bd -literal +.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . +.\" .Pp +.\" Not a pretty sight... +.\" In a paragraph, a long parameter containing unpaddable spaces as +.\" in the former example will cause +.\" .Xr troff +.\" to break the line and spread +.\" the remaining words out. +.\" The latter example will adjust nicely to +.\" justified margins, but may break in between an argument and its +.\" declaration. +.\" In +.\" .Xr nroff +.\" the right margin adjustment is normally ragged and the problem is +.\" not as severe. diff --git a/share/man/man7/operator.7 b/share/man/man7/operator.7 new file mode 100644 index 0000000..64954f5 --- /dev/null +++ b/share/man/man7/operator.7 @@ -0,0 +1,65 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 June 9, 1993 +.Dt OPERATOR 7 +.Os +.Sh NAME +.Nm operator +.Nd C operator precedence and order of evaluation +.Sh DESCRIPTION +.Bd -ragged -offset indent -compact +.Bl -column "Operator Associativity " +.It Operator Associativity +.It -------- ------------- +.It \&() [] -> . left to right +.It "! ~ ++ -- - (type) * & sizeof" right to left +.It \&* / % left to right +.It \&+ - left to right +.It \&<< >> left to right +.It \&< <= > >= left to right +.It \&== != left to right +.It \&& left to right +.It \&^ left to right +.It \&| left to right +.It \&&& left to right +.It \&|| left to right +.It \&?: right to left +.It \&= += -= etc. right to left +.It \&, left to right +.El +.Ed +.Sh FILES +.Bl -tag -width /usr/share/misc/operator -compact +.It Pa /usr/share/misc/operator +.El |
