diff options
| author | Keith M Wesolowski <wesolows@foobazco.org> | 2014-07-21 17:21:13 +0000 |
|---|---|---|
| committer | Keith M Wesolowski <wesolows@foobazco.org> | 2014-07-21 21:34:55 +0000 |
| commit | d1e9a943f54c1cb91f507cc05b2d9cac695b3f4f (patch) | |
| tree | bfcb906ab5024d2dde1f652908aed08f1251cedf /usr/src/man | |
| parent | a95d065b67ca639905027ce885cb12446ee13bb2 (diff) | |
| parent | 7ab4e62e3b5c454f248a38bec0d489e8f5543324 (diff) | |
| download | illumos-joyent-d1e9a943f54c1cb91f507cc05b2d9cac695b3f4f.tar.gz | |
[illumos-gate merge]
commit 7ab4e62e3b5c454f248a38bec0d489e8f5543324
3346 svc-hostid uses perl stupidly
commit 95c635efb7c3b86efc493e0447eaec7aecca3f0f
5025 import and use mandoc
commit 81d43577d1b5e76e6016ba642ecc1a76fde43021
5004 load average should be virtualized for zones
commit 944b13ecd074fe0d43ed6f80c816ca862c3cd6eb
4956 zonecfg won't use a valid pager
commit e03914f9208eb53e6c8a6d5a436953ad983642b0
4696 allowed-ips should let you specify prefixes
commit 31c6d826a7f7a4ee7d83c8e99f25d82a4a248076
4922 all calloc() implementations should check for overflow
commit d9c5840bd764434fd93f85a52eb4cbc24bff03da
4959 completely discarded merged string sections will corrupt output objects
commit 2e4c998613148111f2fc5371085331ffb39122ff
4976 zfs should only avoid writing to a failing non-redundant top-level vdev
4977 mdb error in ::spa_space from space_cb() if a metaslab's ms_sm is NULL
4978 ztest fails in get_metaslab_refcount()
4979 extend free space histogram to device and pool
4980 metaslabs should have a fragmentation metric
4981 remove fragmented ops vector from block allocator
4982 space_map object should proactively upgrade when feature is enabled
4983 need to collect metaslab information via mdb
4984 device selection should use fragmentation metric
commit 1a41ca239310955ae95b2569b707432432a58580
5013 add support for multiple mac addresses per client
commit 680047a5d0ef56480110f0de516145ba0efd5caa
474 tcp_strong_iss should be 2 instead of 1 (missing file)
commit 6400a6be1817a40f3dbefdd3df7b7d87bcebef30
474 tcp_strong_iss should be 2 instead of 1
commit dcb12fb726d8dd4ff80ea255dc3f53b5692c75e5
5014 etherstubs confuse min mtu with min sdu
commit c9030f6c93613fe30ee0c16f92b96da7816ac052
5008 lock contention (rrw_exit) while running a read only load
Conflicts:
usr/src/uts/common/sys/zone.h
usr/src/uts/common/sys/vnic_impl.h
usr/src/uts/common/sys/mac.h
usr/src/uts/common/os/zone.c
usr/src/uts/common/io/vnic/vnic_dev.c
usr/src/uts/common/io/mac/mac_protect.c
usr/src/uts/common/io/mac/mac_client.c
usr/src/tools/scripts/git-pbchk.py
usr/src/tools/onbld/hgext/cdm.py
usr/src/test/util-tests/tests/Makefile
usr/src/pkg/manifests/developer-build-onbld.mf
usr/src/man/man5/Makefile
usr/src/lib/libdladm/common/linkprop.c
usr/src/cmd/zonecfg/zonecfg.c
usr/src/cmd/Makefile
usr/src/man/man1/column.1
usr/src/man/man1/crontab.1
usr/src/man/man1m/dladm.1m
usr/src/man/man1m/flowadm.1m
usr/src/man/man1m/snoop.1m
usr/src/man/man1m/vfsstat.1m
usr/src/man/man1m/vndadm.1m
usr/src/man/man1m/zfs.1m
usr/src/man/man1m/zonecfg.1m
usr/src/man/man1m/zpool.1m
usr/src/man/man3c/epoll_create.3c
usr/src/man/man3c/epoll_ctl.3c
usr/src/man/man3c/epoll_wait.3c
usr/src/man/man3lib/libvnd.3lib
usr/src/man/man3vnd/vnd_frameio_read.3vnd
usr/src/man/man3vnd/vnd_prop_get.3vnd
usr/src/man/man3vnd/vnd_prop_iter.3vnd
usr/src/man/man3vnd/vnd_walk.3vnd
usr/src/man/man5/epoll.5
usr/src/man/man7d/vnd.7d
usr/src/man/man7fs/bootfs.7fs
usr/src/man/man7fs/lxproc.7fs
Manifests:
usr/src/pkg/manifests/text-doctools.mf
usr/src/pkg/manifests/system-man.mf
Diffstat (limited to 'usr/src/man')
69 files changed, 7262 insertions, 1687 deletions
diff --git a/usr/src/man/Makefile b/usr/src/man/Makefile index 56d72ee3c0..5842e8ef0d 100644 --- a/usr/src/man/Makefile +++ b/usr/src/man/Makefile @@ -11,7 +11,7 @@ # # Copyright 2011, Richard Lowe -# Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2014 Nexenta Systems, Inc. All rights reserved. # SUBDIRS= man1 \ @@ -103,8 +103,9 @@ all := TARGET = all clean := TARGET = clean clobber := TARGET = clobber install := TARGET = install +check := TARGET = check -all clean clobber install: $(SUBDIRS) +all check clean clobber install: $(SUBDIRS) $(SUBDIRS): FRC @cd $@; pwd; $(MAKE) $(TARGET) diff --git a/usr/src/man/Makefile.man b/usr/src/man/Makefile.man index 17bc3cc297..270c4698cf 100644 --- a/usr/src/man/Makefile.man +++ b/usr/src/man/Makefile.man @@ -11,12 +11,12 @@ # # Copyright 2011, Richard Lowe -# Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2014 Nexenta Systems, Inc. All rights reserved. # +MANDOC= $(ONBLD_TOOLS)/bin/${MACH}/mandoc ROOTMAN= $(ROOT)/usr/share/man ROOTHASMAN= $(ROOT)/usr/has/man - FILEMODE= 0444 # The manual section being built, client Makefiles must set this to, for e.g. @@ -24,6 +24,7 @@ FILEMODE= 0444 # # MANSECT= +MANCHECKS= $(MANFILES:%=%.check) ROOTMANFILES= $(MANFILES:%=$(ROOTMAN)/man$(MANSECT)/%) ROOTMANLINKS= $(MANLINKS:%=$(ROOTMAN)/man$(MANSECT)/%) @@ -33,6 +34,10 @@ $(ROOTMAN)/man$(MANSECT) $(ROOTHASMAN)/man$(MANSECT): $(ROOTMAN)/man$(MANSECT)/% $(ROOTHASMAN)/man$(MANSECT)/%: % $(ROOTMAN)/man$(MANSECT) $(ROOTHASMAN)/man$(MANSECT) $(INS.file) +$(MANCHECKS): + @$(ECHO) "checking $(@:%.check=%)"; \ + $(MANDOC) -Tlint $(@:%.check=%) + $(MANLINKS): $(RM) $@; $(SYMLINK) $(LINKSRC) $@ @@ -41,6 +46,8 @@ $(ROOTMANLINKS): $(MANLINKS) $(ROOTMAN)/man$(MANSECT) all: +check: $(MANCHECKS) + clean: clobber: diff --git a/usr/src/man/man1/Makefile b/usr/src/man/man1/Makefile index 21b0b0aa69..62d2baa11e 100644 --- a/usr/src/man/man1/Makefile +++ b/usr/src/man/man1/Makefile @@ -12,6 +12,7 @@ # # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2014 Garrett D'Amore <garrett@damore.org> # include $(SRC)/Makefile.master @@ -229,6 +230,7 @@ MANFILES= acctcom.1 \ mailx.1 \ makekey.1 \ man.1 \ + mandoc.1 \ mconnect.1 \ mcs.1 \ mdb.1 \ @@ -411,7 +413,6 @@ MANFILES= acctcom.1 \ w.1 \ wait.1 \ wc.1 \ - whatis.1 \ which.1 \ who.1 \ whocalls.1 \ @@ -556,12 +557,15 @@ MANLINKS= batch.1 \ valyorn.1 \ vax.1 \ vedit.1 \ + whatis.1 \ whence.1 \ while.1 \ zcat.1 intro.1 := LINKSRC = Intro.1 +whatis.1 := LINKSRC = apropos.1 + unalias.1 := LINKSRC = alias.1 batch.1 := LINKSRC = at.1 diff --git a/usr/src/man/man1/apropos.1 b/usr/src/man/man1/apropos.1 index 5a998a86d2..2ef316cbe5 100644 --- a/usr/src/man/man1/apropos.1 +++ b/usr/src/man/man1/apropos.1 @@ -1,142 +1,130 @@ -'\" te +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH APROPOS 1 "Dec 20, 1996" -.SH NAME -apropos \- locate commands by keyword lookup -.SH SYNOPSIS -.LP -.nf -\fBapropos\fR \fIkeyword\fR... -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBapropos\fR utility displays the man page name, section number, and a -short description for each man page whose \fBNAME\fR line contains -\fIkeyword\fR. This information is contained in the \fB/usr/share/man/windex\fR -database created by \fBcatman\fR(1M). If \fBcatman\fR(1M) was not run, or was -run with the \fB-n\fR option, \fBapropos\fR fails. Each word is considered +.Dd "Jul 20, 2014" +.Dt APROPOS 1 +.Os +.Sh NAME +.Nm apropos, whatis +.Nd locate commands by keyword lookup +.Sh SYNOPSIS +.Nm apropos +.Op Fl M Ar path +.Op Fl s Ar section +.Ar keyword ... +.Nm whatis +.Op Fl M Ar path +.Op Fl s Ar section +.Ar keyword ... +.Sh DESCRIPTION +The +.Nm apropos +utility displays the man page name, section number, and a +short description for each man page whose +.Em NAME +line contains +.Ar keyword . +This information is contained in the +.Nm whatis +database created by the +.Fl w +option used with +.Xr man 1 . +If this database is not present, +.Nm apropos +and +.Nm whatis +fail. +.Lp +Each word is considered separately and the case of letters is ignored. Words which are part of other -words are considered; for example, when looking for `compile', \fBapropos\fR -finds all instances of `compiler' also. -.sp -.LP -\fBapropos\fR is actually just the \fB-k\fR option to the \fBman\fR(1) command. -.SH EXAMPLES -.LP -\fBExample 1 \fRTo find a man page whose NAME line contains a keyword -.sp -.LP +words are considered; for example, when looking for +.Sq compile , +.Nm apropos +finds all instances of +.Sq compiler +also. +.Lp +The +.Nm whatis +command performs the same search, but only matches whole words. In the above +example, +.Nm whatis +would not match the instances of +.Sq compiler +when +.Ar keyword +is +.Sq compile . +.Lp +The +.Nm apropos +command is actually just the +.Fl k +option to the +.Xr man 1 +command. +.Sh OPTIONS +.Bl -tag -width "-s section" +.It Fl M Ar path +Force a specific colon separated manual path instead of the +default search path. Overrides the MANPATH environment variable. +.It Fl s Ar section +Restrict search to specified section. +.El +.Sh ENVIRONMENT +.Bl -tag -width "MANPATH, PATH" +.It Ev MANPATH , PATH +Used to find the location of the +.Nm whatis +database. +.El +.Sh FILES +.Bl -tag -width "/usr/share/man/whatis" +.It Pa /usr/share/man/whatis +table of contents and keyword database +.El +.Sh EXAMPLES +.Ss Example 1 To find a man page whose NAME line contains a keyword Try - -.sp -.in +2 -.nf -example% \fBapropos password\fR -.fi -.in -2 -.sp - -.sp -.LP -and - -.sp -.in +2 -.nf -example% \fBapropos editor\fR -.fi -.in -2 -.sp - -.sp -.LP -If the line starts `\fIfilename\fR(\fIsection\fR) .\|.\|.' you can run - -.sp -.in +2 -.nf -man -s \fIsection filename\fR -.fi -.in -2 -.sp - -.sp -.LP +.Lp +.Dl example% apropos password +.Lp +If the line starts +.So Ar filename Ns Po Ar section Pc .\|.\|. Sc +you can run +.Lp +.Dl % Nm man Fl s Ar section Ar filename +.Lp to display the man page for \fIfilename\fR. - -.LP -\fBExample 2 \fRTo find the man page for the subroutine \fBprintf()\fR -.sp -.LP +.Ss Example 2 To find the man page for the subroutine \fBprintf() Try - -.sp -.in +2 -.nf -example% \fBapropos format\fR -.fi -.in -2 -.sp - -.sp -.LP +.Lp +.Dl example% Nm apropos Li format +.Lp and then - -.sp -.in +2 -.nf -example% \fBman -s 3s printf\fR -.fi -.in -2 -.sp - -.sp -.LP -to get the manual page on the subroutine \fBprintf()\fR. - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/share/man/windex\fR \fR -.ad -.RS 26n -table of contents and keyword database -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -CSI Enabled -.TE - -.SH SEE ALSO -.sp -.LP -\fBman\fR(1), \fBwhatis\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5) -.SH DIAGNOSTICS -.sp -.ne 2 -.na -\fB\f(CW/usr/share/man/windex: No such file or directory\fR\fR -.ad -.sp .6 -.RS 4n -This database does not exist. \fBcatman\fR(1M) must be run to create it. -.RE - +.Lp +.Dl example% Nm man Fl s Ar 3C Li printf +.Lp +to get the manual page on the subroutine +.Xr printf 3C . +.Sh DIAGNOSTICS +.Bl -tag -width Ds +.It "/usr/share/man/whatis: No such file or directory" +The +.Nm whatis +database does not exist. +The command +.Nm man +.Fl w +must be run to create it. +.El +.Sh CODE SET INDEPENDENCE +Enabled. +.Sh INTERFACE STABILITY +.Nm Committed . +.Sh SEE ALSO +.Xr man 1 , +.Xr catman 1M diff --git a/usr/src/man/man1/column.1 b/usr/src/man/man1/column.1 index 38d9af86c5..a8c23310ba 100644 --- a/usr/src/man/man1/column.1 +++ b/usr/src/man/man1/column.1 @@ -39,7 +39,7 @@ column \- columnate lists \fBcolumn\fR [\fB-tx\fR] [\fB-c\fR \fIcolumns\fR] [\fB-s\fR \fIsep\fR] [\fIfile\fR ... ] .fi -.Sh DESCRIPTION +.SH DESCRIPTION .sp .LP The \fBcolumn\fR diff --git a/usr/src/man/man1/crontab.1 b/usr/src/man/man1/crontab.1 index 927b5345c4..1008b63a21 100644 --- a/usr/src/man/man1/crontab.1 +++ b/usr/src/man/man1/crontab.1 @@ -617,13 +617,11 @@ list of denied users \fB\fB/etc/cron.d/crontabs\fR\fR .ad .RS 28n -.rt system spool area for \fBcrontab\fR .RE .sp .ne 2 -.mk .na \fB\fB/var/cron/log\fR\fR .ad diff --git a/usr/src/man/man1/head.1 b/usr/src/man/man1/head.1 index ff818f891f..bf423612c3 100644 --- a/usr/src/man/man1/head.1 +++ b/usr/src/man/man1/head.1 @@ -11,7 +11,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH HEAD 1 "Mar 4, 2013" +.TH HEAD 1 "Mar 4, 2013" .SH NAME head \- display first few lines of files .SH SYNOPSIS diff --git a/usr/src/man/man1/ld.1 b/usr/src/man/man1/ld.1 index afc6a8d1ce..4ebe033dce 100644 --- a/usr/src/man/man1/ld.1 +++ b/usr/src/man/man1/ld.1 @@ -1036,7 +1036,7 @@ Enable use of direct binding Suggests that \fB-z direct\fR or \fB-B direct\fR be present prior to any specified dependency. This allows predictable symbol binding at runtime. -Can be disabled with \fB-z guidance=nodirect\fR +Can be disabled with \fB-z guidance=nodirect\fR .RE .sp @@ -1105,7 +1105,7 @@ removed from the link-editor command line. Can be disabled with \fB-z guidance=nounused\fR. .RE -.RE +.RE .sp .ne 2 diff --git a/usr/src/man/man1/man.1 b/usr/src/man/man1/man.1 index ca20dd7b3b..4bba713397 100644 --- a/usr/src/man/man1/man.1 +++ b/usr/src/man/man1/man.1 @@ -1,664 +1,401 @@ -'\" te +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright (c) 1980 Regents of the University of California. The Berkeley software License Agreement specifies the terms and conditions for redistribution. -.TH MAN 1 "May 8, 2008" -.SH NAME -man \- find and display reference manual pages -.SH SYNOPSIS -.LP -.nf -\fBman\fR [\fB-\fR] [\fB-adFlrt\fR] [\fB-M\fR \fIpath\fR] [\fB-T\fR \fImacro-package\fR] [\fB-s\fR \fIsection\fR] \fIname\fR... -.fi - -.LP -.nf -\fBman\fR [\fB-M\fR \fIpath\fR] \fB-k\fR \fIkeyword\fR... -.fi - -.LP -.nf -\fBman\fR [\fB-M\fR \fIpath\fR] \fB-f\fR \fIfile\fR... -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBman\fR command displays information from the reference manuals. It -displays complete manual pages that you select by \fIname\fR, or one-line -summaries selected either by \fIkeyword\fR (\fB-k\fR), or by the name of an -associated file (\fB-f\fR). If no manual page is located, \fBman\fR prints an -error message. -.SS "Source Format" -.sp -.LP -Reference Manual pages are marked up with either \fBnroff\fR (see -\fBnroff\fR(1)) or \fBSGML\fR (Standard Generalized Markup Language) tags (see -\fBsgml\fR(5)). The \fBman\fR command recognizes the type of markup and -processes the file accordingly. The various source files are kept in separate -directories depending on the type of markup. -.SS "Location of Manual Pages" -.sp -.LP +.\" Copyright (c) 1980 Regents of the University of California. +.\" The Berkeley software License Agreement specifies the terms and conditions +.\" for redistribution. +.Dd Jul 18, 2014 +.Dt MAN 1 +.Os +.Sh NAME +.Nm man +.Nd find and display reference manual pages +.Sh SYNOPSIS +.Nm +.Op Fl +.Op Fl adFlrt +.Op Fl T Ar macro-package +.Op Fl M Ar path +.Op Fl s Ar section +.Ar name ... +.Nm +.Op Fl M Ar path +.Op Fl s Ar section +.Fl k +.Ar keyword +.Ar ... +.Nm +.Op Fl M Ar path +.Op Fl s Ar section +.Fl f +.Ar +.Nm +.Op Fl M Ar path +.Fl w +.Sh DESCRIPTION +The +.Nm +command displays information from the reference manuals. It +displays complete manual pages that you select by +.Ar name , +or one-line summaries selected either by +.Ar keyword +.Pq Fl k , +or by the name of an associated file +.Pq Fl f . +If no manual page is located, +.Nm +prints an error message. +.Ss "Source Format" +Reference Manual pages are marked up with either +.Xr man 5 , +or +.Xr mdoc 5 +language tags. The +.Nm +command recognizes the type of markup and +processes the file accordingly. +. +.Ss "Location of Manual Pages" +. The online Reference Manual page directories are conventionally located in -\fB/usr/share/man\fR. The nroff sources are located in the -\fB/usr/share/man/man\fR* directories. The \fBSGML\fR sources are located in -the \fB/usr/share/man/sman\fR* directories. Each directory corresponds to a +.Pa /usr/share/man . +Each directory corresponds to a section of the manual. Since these directories are optionally installed, they -might not reside on your host. You might have to mount \fB/usr/share/man\fR +might not reside on your host. You might have to mount +.Pa /usr/share/man from a host on which they do reside. -.sp -.LP -If there are preformatted, up-to-date versions in the corresponding \fBcat\fR* -or \fBfmt\fR* directories, \fBman\fR simply displays or prints those versions. -If the preformatted version of interest is out of date or missing, \fBman\fR -reformats it prior to display and stores the preformatted version if \fBcat\fR* -or \fBfmt\fR* is writable. The \fBwindex\fR database is not updated. See -\fBcatman\fR(1M). If directories for the preformatted versions are not -provided, \fBman\fR reformats a page whenever it is requested. \fBman\fR uses a -temporary file to store the formatted text during display. -.sp -.LP -If the standard output is not a terminal, or if the `\fB-\fR' flag is given, -\fBman\fR pipes its output through \fBcat\fR(1). Otherwise, \fBman\fR pipes its -output through \fBmore\fR(1) to handle paging and underlining on the screen. -.SH OPTIONS -.sp -.LP +The +.Nm +command reformats a page whenever it is requested. +.Pp +If the standard output is not a terminal, or if the +.Fl +flag is given, +.Nm +pipes its output through +.Xr cat 1 . +Otherwise, +.Nm +pipes its output through a pager such as +.Xr more 1 +to handle paging and underlining on the screen. +.Sh OPTIONS The following options are supported: -.sp -.ne 2 -.na -\fB\fB-a\fR\fR -.ad -.RS 20n -Shows all manual pages matching \fIname\fR within the \fBMANPATH\fR search -path. Manual pages are displayed in the order found. -.RE - -.sp -.ne 2 -.na -\fB\fB-d\fR\fR -.ad -.RS 20n +.Bl -tag -width indent +.It Fl a +Shows all manual pages matching +.Ar name +within the +.Ev MANPATH +search path. Manual pages are displayed in the order found. +.It Fl d Debugs. Displays what a section-specifier evaluates to, method used for -searching, and paths searched by \fBman\fR. -.RE - -.sp -.ne 2 -.na -\fB\fB-f\fR \fIfile ...\fR\fR -.ad -.RS 20n -\fBman\fR attempts to locate manual pages related to any of the given -\fIfile\fRs. It strips the leading path name components from each \fIfile\fR, +searching, and paths searched by +.Nm . +.It Fl f Ar file ... +Attempts to locate manual pages related to any of the given +.Ar file +names. It strips the leading path name components from each +.Ar file , and then prints one-line summaries containing the resulting basename or names. -This option also uses the \fBwindex\fR database. -.RE - -.sp -.ne 2 -.na -\fB\fB-F\fR\fR -.ad -.RS 20n -Forces \fBman\fR to search all directories specified by \fBMANPATH\fR or the -\fBman.cf\fR file, rather than using the \fBwindex\fR lookup database. This -option is useful if the database is not up to date and it has been made the -default behavior of the \fBman\fR command. The option therefore does not have -to be invoked and is documented here for reference only. -.RE - -.sp -.ne 2 -.na -\fB\fB-k\fR \fIkeyword ...\fR\fR -.ad -.RS 20n -Prints out one-line summaries from the \fBwindex\fR database (table of -contents) that contain any of the given \fIkeyword\fRs. The \fBwindex\fR -database is created using \fBcatman\fR(1M). -.RE - -.sp -.ne 2 -.na -\fB\fB-l\fR\fR -.ad -.RS 20n -Lists all manual pages found matching \fIname\fR within the search path. -.RE - -.sp -.ne 2 -.na -\fB\fB-M\fR \fIpath\fR\fR -.ad -.RS 20n -Specifies an alternate search path for manual pages. \fIpath\fR is a -colon-separated list of directories that contain manual page directory -subtrees. For example, if \fIpath\fR is \fB/usr/share/man:/usr/local/man\fR, -\fBman\fR searches for \fIname\fR in the standard location, and then -\fB/usr/local/man\fR. When used with the \fB-k\fR or \fB-f\fR options, the -\fB-M\fR option must appear first. Each directory in the \fIpath\fR is assumed -to contain subdirectories of the form \fBman\fR* or \fBsman\fR* , one for each -section. This option overrides the \fBMANPATH\fR environment variable. -.RE - -.sp -.ne 2 -.na -\fB\fB-r\fR\fR -.ad -.RS 20n -Reformats the manual page, but does not display it. This replaces the \fBman\fR -\fB-\fR \fB-t\fR \fIname\fR combination. -.RE - -.sp -.ne 2 -.na -\fB\fB-s\fR \fIsection ...\fR\fR -.ad -.RS 20n -Specifies sections of the manual for \fBman\fR to search. The directories -searched for \fIname\fR are limited to those specified by \fIsection\fR. -\fIsection\fR can be a numerical digit, perhaps followed by one or more letters -to match the desired section of the manual, for example, "\fB3libucb\fR". Also, -\fIsection\fR can be a word, for example, \fBlocal\fR, \fBnew\fR, \fBold\fR, -\fBpublic\fR. \fIsection\fR can also be a letter. To specify multiple sections, -separate each section with a comma. This option overrides the \fBMANPATH\fR -environment variable and the \fBman.cf\fR file. See \fBSearch\fR \fBPath\fR -below for an explanation of how \fBman\fR conducts its search. -.RE - -.sp -.ne 2 -.na -\fB\fB-t\fR\fR -.ad -.RS 20n -\fBman\fR arranges for the specified manual pages to be \fBtroff\fRed to a -suitable raster output device (see \fBtroff\fR(1)). If both the \fB-\fR and -\fB-t\fR flags are given, \fBman\fR updates the \fBtroff\fRed versions of each -named \fIname\fR (if necessary), but does not display them. -.RE - -.sp -.ne 2 -.na -\fB\fB-T\fR \fImacro-package\fR\fR -.ad -.RS 20n -Formats manual pages using \fImacro-package\fR rather than the standard -\fB-man\fR macros defined in \fB/usr/share/lib/tmac/an\fR. See \fBSearch -Path\fR under USAGE for a complete explanation of the default search path -order. -.RE - -.SH OPERANDS -.sp -.LP +This option also uses the +.Pa whatis +database. +.It Fl F +This option is present for backwards compatibility and is documented +here for reference only. It performs no function. +.It Fl k Ar keyword ... +Prints out one-line summaries from the +.Pa whatis +database (table of contents) that contain any of the given +.Ar keyword . +The +.Pa whatis +database is created using the +.Fl w +option. +.It Fl l +Lists all manual pages found matching +.Ar name +within the search path. +.It Fl M Ar path +Specifies an alternate search path for manual pages. The +.Ar path +is a colon-separated list of directories that contain manual page directory +subtrees. For example, if +.Ar path +is +.Pa /usr/share/man:/usr/local/man , +.Nm +searches for +.Ar name +in the standard location, and then +.Pa /usr/local/man . +When used with the +.Fl k , +.Fl f , +or +.Fl w +options, the +.Fl M +option must appear first. Each directory in the +.Ar path +is assumed to contain subdirectories of the form +.Pa man* , +one for each section. This option overrides the +.Ev MANPATH +environment variable. +.It Fl r +Reformats the manual page, checking for formatting errors, but does not +display it. +.It Fl s Ar section +Specifies sections of the manual for +.Nm +to search. The directories searched for +.Ar name +are limited to those specified by +.Ar section . +.Ar section +can be a numerical digit, perhaps followed by one or more letters +to match the desired section of the manual, for example, +.Li "3libucb". +Also, +.Ar section +can be a word, for example, +.Li local , +.Li new , +.Li old , +.Li public . +.Ar section +can also be a letter. To specify multiple sections, +separate each section with a comma. This option overrides the +.Ev MANPATH +environment variable and the +.Pa man.cf +file. See +.Sx Search Path +below for an explanation of how +.Nm +conducts its search. +.It Fl t +Arranges for the specified manual pages to be sent to the default +printer as PostScript. +.It Fl T Ar macro-package +This option is present for backwards compatibility and is documented +here for reference only. It performs no function. +.It Fl w +Updates the +.Nm whatis +database. +.El +.Sh OPERANDS The following operand is supported: -.sp -.ne 2 -.na -\fB\fIname\fR\fR -.ad -.RS 8n +.Bl -tag -width indent +.It Ar name The name of a standard utility or a keyword. -.RE - -.SH USAGE -.sp -.LP -The usage of \fBman\fR is described below: -.SS "Manual Page Sections" -.sp -.LP -Entries in the reference manuals are organized into \fIsection\fRs. A section +.El +.Sh USAGE +The usage of +.Nm +is described below: +. +.Ss "Manual Page Sections" +. +Entries in the reference manuals are organized into +.Em sections . +A section name consists of a major section name, typically a single digit, optionally followed by a subsection name, typically one or more letters. An unadorned -major section name, for example, "\fB9\fR", does not act as an abbreviation for -the subsections of that name, such as "\fB9e\fR", "\fB9f\fR", or "\fB9s\fR". -That is, each subsection must be searched separately by \fBman\fR \fB-s\fR. +major section name, for example, +.Qq 9 , +does not act as an abbreviation for +the subsections of that name, such as +.Qq 9e , +.Qq 9f , +or +.Qq 9s . +That is, each subsection must be searched separately by +.Nm +.Fl s . Each section contains descriptions apropos to a particular reference category, -with subsections refining these distinctions. See the \fBintro\fR manual pages -for an explanation of the classification used in this release. -.SS "Search Path" -.sp -.LP -Before searching for a given \fIname\fR, \fBman\fR constructs a list of -candidate directories and sections. \fBman\fR searches for \fIname\fR in the -directories specified by the \fBMANPATH\fR environment variable. -.sp -.LP -In the absence of \fBMANPATH\fR, \fBman\fR constructs its search path based -upon the \fBPATH\fR environment variable, primarily by substituting \fBman\fR -for the last component of the \fBPATH\fR element. Special provisions are added -to account for unique characteristics of directories such as \fB/sbin\fR, -\fB/usr/ucb\fR, \fB/usr/xpg4/bin\fR, and others. If the file argument contains -a \fB/\fR character, the \fIdirname\fR portion of the argument is used in place -of \fBPATH\fR elements to construct the search path. -.sp -.LP -Within the manual page directories, \fBman\fR confines its search to the +with subsections refining these distinctions. See the +.Em intro +manual pages for an explanation of the classification used in this release. +. +.Ss "Search Path" +. +Before searching for a given +.Ar name , +.Nm +constructs a list of candidate directories and sections. +It searches for +.Ar name +in the directories specified by the +.Ev MANPATH +environment variable. +.Lp +In the absence of +.Ev MANPATH , +.Nm +constructs its search path based upon the +.Ev PATH +environment variable, primarily by substituting +.Li man +for the last component of the +.Ev PATH +element. Special provisions are added +to account for unique characteristics of directories such as +.Pa /sbin , +.Pa /usr/ucb , +.Pa /usr/xpg4/bin , +and others. If the file argument contains +a +.Qq / +character, the +.Em dirname +portion of the argument is used in place of +.Ev PATH +elements to construct the search path. +.Lp +Within the manual page directories, +.Nm +confines its search to the sections specified in the following order: -.RS +4 -.TP -.ie t \(bu -.el o -\fIsection\fRs specified on the command line with the \fB-s\fR option -.RE -.RS +4 -.TP -.ie t \(bu -.el o -\fIsection\fRs embedded in the \fBMANPATH\fR environment variable -.RE -.RS +4 -.TP -.ie t \(bu -.el o -\fIsection\fRs specified in the \fBman.cf\fR file for each directory specified -in the \fBMANPATH\fR environment variable -.RE -.sp -.LP -If none of the above exist, \fBman\fR searches each directory in the manual +.Bl -bullet +.It +.Ar sections +specified on the command line with the +.Fl s +option +.It +.Ar sections +embedded in the +.Ev MANPATH +environment variable +.It +.Ar sections +specified in the +.Pa man.cf +file for each directory specified in the +.Ev MANPATH +environment variable +.El +If none of the above exist, +.Nm +searches each directory in the manual page path, and displays the first matching manual page found. -.sp -.LP -The \fBman.cf\fR file has the following format: -.sp -.in +2 -.nf -MANSECTS=\fIsection\fR[,\fIsection\fR]... -.fi -.in -2 -.sp - -.sp -.LP -Lines beginning with `\fB#\fR' and blank lines are considered comments, and are -ignored. Each directory specified in \fBMANPATH\fR can contain a manual page +.Lp +The +.Pa man.cf +file has the following format: +.Lp +.Dl Pf MANSECTS= Ar section , Ns Op Ar section... +.Lp +Lines beginning with +.Sq Li # +and blank lines are considered comments, and are +ignored. Each directory specified in +.Ev MANPATH +can contain a manual page configuration file, specifying the default search order for that directory. -.SH FORMATTING MANUAL PAGES -.sp -.LP -Manual pages are marked up in \fBnroff\fR(1) or \fBsgml\fR(5). Nroff manual -pages are processed by \fBnroff\fR(1) or \fBtroff\fR(1) with the \fB-man\fR -macro package. Please refer to \fBman\fR(5) for information on macro usage. -\fBSGML\fR\(emtagged manual pages are processed by an \fBSGML\fR parser and -passed to the formatter. -.SS "Preprocessing Nroff Manual Pages" -.sp -.LP -When formatting an nroff manual page, \fBman\fR examines the first line to -determine whether it requires special processing. If the first line is a string -of the form: -.sp -.in +2 -.nf -\&'\e" \fIX\fR -.fi -.in -2 -.sp - -.sp -.LP -where \fIX\fR is separated from the `\fB"\fR' by a single SPACE and consists of -any combination of characters in the following list, \fBman\fR pipes its input -to \fBtroff\fR(1) or \fBnroff\fR(1) through the corresponding preprocessors. -.sp -.ne 2 -.na -\fB\fBe\fR\fR -.ad -.RS 5n -\fBeqn\fR(1), or \fBneqn\fR for \fBnroff\fR -.RE - -.sp -.ne 2 -.na -\fB\fBr\fR\fR -.ad -.RS 5n -\fBrefer\fR(1) -.RE - -.sp -.ne 2 -.na -\fB\fBt\fR\fR -.ad -.RS 5n -\fBtbl\fR(1) -.RE - -.sp -.ne 2 -.na -\fB\fBv\fR\fR -.ad -.RS 5n -\fBvgrind\fR(1) -.RE - -.sp -.LP -If \fBeqn\fR or \fBneqn\fR is invoked, it automatically reads the file -\fB/usr/pub/eqnchar\fR (see \fBeqnchar\fR(5)). If \fBnroff\fR(1) is invoked, -\fBcol\fR(1) is automatically used. -.SS "Referring to Other nroff Manual Pages" -.sp -.LP -If the first line of the nroff manual page is a reference to another manual +.Sh "Referring to Other Manual Pages" +If the first line of the manual page is a reference to another manual page entry fitting the pattern: -.sp -.in +2 -.nf -\&.so man*/\fIsourcefile\fR -.fi -.in -2 -.sp - -.sp -.LP -\fBman\fR processes the indicated file in place of the current one. The +.Lp +.Dl \&.so man*/\fIsourcefile\fR +.Lp +.Nm +processes the indicated file in place of the current one. The reference must be expressed as a path name relative to the root of the manual page directory subtree. -.sp -.LP +.Lp When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual manner. -.SS "Processing SGML Manual Pages" -.sp -.LP -Manual pages are identified as being marked up in SGML by the presence of the -string \fB<!DOCTYPE\fR\&. If the file also contains the string -\fBSHADOW_PAGE\fR, the file refers to another manual page for the content. The -reference is made with a file entity reference to the manual page that contains -the text. This is similar to the \fB\&.so\fR mechanism used in the nroff -formatted man pages. -.SH ENVIRONMENT VARIABLES -.sp -.LP -See \fBenviron\fR(5) for descriptions of the following environment variables -that affect the execution of \fBman\fR: \fBLANG\fR, \fBLC_ALL\fR, -\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR. -.sp -.ne 2 -.na -\fB\fBMANPATH\fR\fR -.ad -.RS 11n +.Sh ENVIRONMENT VARIABLES +See +.Xr environ 5 +for descriptions of the following environment variables +that affect the execution of +.Nm man : +.Ev LANG , +.Ev LC_ALL , +.Ev LC_CTYPE , +.Ev LC_MESSAGES , +and +.Ev NLSPATH . +.Bl -tag -width indent +.It Ev MANPATH A colon-separated list of directories; each directory can be followed by a comma-separated list of sections. If set, its value overrides \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in turn, override these values.) -.RE - -.sp -.ne 2 -.na -\fB\fBPAGER\fR\fR -.ad -.RS 11n -A program to use for interactively delivering \fBman\fR's output to the screen. -If not set, `\fBmore\fR \fB-s\fR' is used. See \fBmore\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fBTCAT\fR\fR -.ad -.RS 11n -The name of the program to use to display \fBtroff\fRed manual pages. -.RE - -.sp -.ne 2 -.na -\fB\fBTROFF\fR\fR -.ad -.RS 11n -The name of the formatter to use when the \fB-t\fR flag is given. If not set, -\fBtroff\fR(1) is used. -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRCreating a PostScript Version of a man page -.sp -.LP -The following example creates the \fBpipe\fR(2) man page in postscript for csh, -tcsh, ksh and sh users: - -.sp -.in +2 -.nf - % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps -.fi -.in -2 -.sp - -.sp -.LP -This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to -the default printer, if the user wants a postscript file version of the man -page. - -.LP -\fBExample 2 \fRCreating a Text Version of a man page -.sp -.LP -The following example creates the \fBpipe\fR(2) man page in ascii text: - -.sp -.in +2 -.nf -man pipe.2 | col -x -b > pipe.text -.fi -.in -2 -.sp - -.sp -.LP -This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to -the default printer, if the user wants a text file version of the man page. - -.SH EXIT STATUS -.sp -.LP -The following exit values are returned: -.sp -.ne 2 -.na -\fB\fB0\fR\fR -.ad -.RS 6n -Successful completion. -.RE - -.sp -.ne 2 -.na -\fB\fB>0\fR\fR -.ad -.RS 6n -An error occurred. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/share/man\fR\fR -.ad -.sp .6 -.RS 4n +.It Ev PAGER +A program to use for interactively delivering +output to the screen. If not set, +.Sq Nm more Fl s +is used. See +.Xr more 1 . +.El +.Sh FILES +.Bl -tag -width indent +.It Pa /usr/share/man Root of the standard manual page directory subtree -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/man?/*\fR\fR -.ad -.sp .6 -.RS 4n -Unformatted nroff manual entries -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/sman?/*\fR\fR -.ad -.sp .6 -.RS 4n -Unformatted \fBSGML\fR manual entries -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/cat?/*\fR\fR -.ad -.sp .6 -.RS 4n -\fBnroff\fRed manual entries -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/fmt?/*\fR\fR -.ad -.sp .6 -.RS 4n -\fBtroff\fRed manual entries -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/windex\fR\fR -.ad -.sp .6 -.RS 4n +.It Pa /usr/share/man/man?/* +Unformatted manual entries +.It Pa /usr/share/man/whatis Table of contents and keyword database -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/tmac/an\fR\fR -.ad -.sp .6 -.RS 4n -Standard \fB-man\fR macro package -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/sgml/locale/C/dtd/*\fR\fR -.ad -.sp .6 -.RS 4n -\fBSGML\fR document type definition files -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/sgml/locale/C/solbook/*\fR\fR -.ad -.sp .6 -.RS 4n -\fBSGML\fR style sheet and entity definitions directories -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/pub/eqnchar\fR\fR -.ad -.sp .6 -.RS 4n -Standard definitions for \fBeqn\fR and \fBneqn\fR -.RE - -.sp -.ne 2 -.na -\fB\fBman.cf\fR\fR -.ad -.sp .6 -.RS 4n +.It Pa man.cf Default search order by section -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -CSI Enabled, see \fBNOTES\fR. -_ -Interface Stability Committed -_ -Standard See \fBstandards\fR(5). -.TE - -.SH SEE ALSO -.sp -.LP -\fBapropos\fR(1), \fBcat\fR(1), \fBcol\fR(1), \fBdpost\fR(1), \fBeqn\fR(1), -\fBmore\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), \fBtroff\fR(1), -\fBvgrind\fR(1), \fBwhatis\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5), -\fBenviron\fR(5), \fBeqnchar\fR(5), \fBman\fR(5), \fBsgml\fR(5), -\fBstandards\fR(5) -.SH NOTES -.sp -.LP -The \fB-f\fR and \fB-k\fR options use the \fBwindex\fR database, which is -created by \fBcatman\fR(1M). -.sp -.LP -The \fBman\fR command is CSI-capable. However, some utilities invoked by the -\fBman\fR command, namely, \fBtroff\fR, \fBeqn\fR, \fBneqn\fR, \fBrefer\fR, -\fBtbl\fR, and \fBvgrind\fR, are not verified to be CSI-capable. Because of -this, the man command with the \fB-t\fR option can not handle non-EUC data. -Also, using the \fBman\fR command to display man pages that require special -processing through \fBeqn\fR, \fBneqn\fR, \fBrefer\fR, \fBtbl\fR, or -\fBvgrind\fR can not be CSI-capable. -.SH BUGS -.sp -.LP +.El +.Sh EXIT STATUS +.Ex -std man +.Sh EXAMPLES +. +.Ss Example 1: Creating a PostScript Version of a man page +. +The following example spools the +.Xr pipe 2 +man page in PostScript to the default printer: +.Pp +.Dl % man -t -s 2 pipe +.Pp +Note that +.Xr mandoc 1 +can be used to obtain the PostScript content directly. +.Ss Example 2: Creating a Text Version of a man page +The following example creates the +.Xr pipe 2 +man page in ASCII text: +.Pp +.Dl % man pipe.2 | col -x -b > pipe.text +.Sh CODE SET INDEPENDENCE +Enabled. +.Sh INTERFACE STABILITY +.Nm Committed . +.Sh SEE ALSO +.Xr apropos 1 , +.Xr cat 1 , +.Xr col 1 , +.Xr mandoc 1 , +.Xr more 1 , +.Xr whatis 1 , +.Xr environ 5 , +.Xr man 5 , +.Xr mdoc 5 +.Sh NOTES +The +.Fl f +and +.Fl k +options use the +.Nm whatis +database, which is +created with the +.Fl w +option. +.Sh BUGS The manual is supposed to be reproducible either on a phototypesetter or on an -\fBASCII\fR terminal. However, on a terminal some information (indicated by +ASCII terminal. However, on a terminal some information (indicated by font changes, for instance) is lost. -.sp -.LP -Some dumb terminals cannot process the vertical motions produced by the \fBe\fR -(see \fBeqn\fR(1)) preprocessing flag. To prevent garbled output on these -terminals, when you use \fBe\fR, also use \fBt\fR, to invoke \fBcol\fR(1) -implicitly. This workaround has the disadvantage of eliminating superscripts -and subscripts, even on those terminals that can display them. Control-q clears -a terminal that gets confused by \fBeqn\fR(1) output. diff --git a/usr/src/man/man1/mandoc.1 b/usr/src/man/man1/mandoc.1 new file mode 100644 index 0000000000..e1d7638d86 --- /dev/null +++ b/usr/src/man/man1/mandoc.1 @@ -0,0 +1,678 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" +.Dd Jul 16, 2014 +.Dt MANDOC 1 +.Os +.Sh NAME +.Nm mandoc +.Nd format and display UNIX manuals +.Sh SYNOPSIS +.Nm mandoc +.Op Fl V +.Op Fl m Ns Ar format +.Op Fl O Ns Ar option +.Op Fl T Ns Ar output +.Op Fl W Ns Ar level +.Op Ar +.Sh DESCRIPTION +The +.Nm +utility formats +.Ux +manual pages for display. +.Pp +By default, +.Nm +reads +.Xr mdoc 5 +or +.Xr man 5 +text from stdin, implying +.Fl m Ns Cm andoc , +and produces +.Fl T Ns Cm ascii +output. +.Pp +The arguments are as follows: +.Bl -tag -width Ds +.It Fl m Ns Ar format +Input format. +See +.Sx Input Formats +for available formats. +Defaults to +.Fl m Ns Cm andoc . +.It Fl O Ns Ar option +Comma-separated output options. +.It Fl T Ns Ar output +Output format. +See +.Sx Output Formats +for available formats. +Defaults to +.Fl T Ns Cm ascii . +.It Fl V +Print version and exit. +.It Fl W Ns Ar level +Specify the minimum message +.Ar level +to be reported on the standard error output and to affect the exit status. +The +.Ar level +can be +.Cm warning , +.Cm error , +or +.Cm fatal . +The default is +.Fl W Ns Cm fatal ; +.Fl W Ns Cm all +is an alias for +.Fl W Ns Cm warning . +See +.Sx EXIT STATUS +and +.Sx DIAGNOSTICS +for details. +.Pp +The special option +.Fl W Ns Cm stop +tells +.Nm +to exit after parsing a file that causes warnings or errors of at least +the requested level. +No formatted output will be produced from that file. +If both a +.Ar level +and +.Cm stop +are requested, they can be joined with a comma, for example +.Fl W Ns Cm error , Ns Cm stop . +.It Ar file +Read input from zero or more files. +If unspecified, reads from stdin. +If multiple files are specified, +.Nm +will halt with the first failed parse. +.El +.Ss Input Formats +The +.Nm +utility accepts +.Xr mdoc 5 +and +.Xr man 5 +input with +.Fl m Ns Cm doc +and +.Fl m Ns Cm an , +respectively. +The +.Xr mdoc 5 +format is +.Em strongly +recommended; +.Xr man 5 +should only be used for legacy manuals. +.Pp +A third option, +.Fl m Ns Cm andoc , +which is also the default, determines encoding on-the-fly: if the first +non-comment macro is +.Sq \&Dd +or +.Sq \&Dt , +the +.Xr mdoc 5 +parser is used; otherwise, the +.Xr man 5 +parser is used. +.Pp +If multiple +files are specified with +.Fl m Ns Cm andoc , +each has its file-type determined this way. +If multiple files are +specified and +.Fl m Ns Cm doc +or +.Fl m Ns Cm an +is specified, then this format is used exclusively. +.Ss Output Formats +The +.Nm +utility accepts the following +.Fl T +arguments, which correspond to output modes: +.Bl -tag -width "-Tlocale" +.It Fl T Ns Cm ascii +Produce 7-bit ASCII output. +This is the default. +See +.Sx ASCII Output . +.It Fl T Ns Cm html +Produce strict CSS1/HTML-4.01 output. +See +.Sx HTML Output . +.It Fl T Ns Cm lint +Parse only: produce no output. +Implies +.Fl W Ns Cm warning . +.It Fl T Ns Cm locale +Encode output using the current locale. +See +.Sx Locale Output . +.It Fl T Ns Cm man +Produce +.Xr man 5 +format output. +See +.Sx Man Output . +.It Fl T Ns Cm pdf +Produce PDF output. +See +.Sx PDF Output . +.It Fl T Ns Cm ps +Produce PostScript output. +See +.Sx PostScript Output . +.It Fl T Ns Cm tree +Produce an indented parse tree. +.It Fl T Ns Cm utf8 +Encode output in the UTF\-8 multi-byte format. +See +.Sx UTF\-8 Output . +.It Fl T Ns Cm xhtml +Produce strict CSS1/XHTML-1.0 output. +See +.Sx XHTML Output . +.El +.Pp +If multiple input files are specified, these will be processed by the +corresponding filter in-order. +.Ss ASCII Output +Output produced by +.Fl T Ns Cm ascii , +which is the default, is rendered in standard 7-bit ASCII documented in +.Xr ascii 5 . +.Pp +Font styles are applied by using back-spaced encoding such that an +underlined character +.Sq c +is rendered as +.Sq _ Ns \e[bs] Ns c , +where +.Sq \e[bs] +is the back-space character number 8. +Emboldened characters are rendered as +.Sq c Ns \e[bs] Ns c . +.Pp +The special characters documented in +.Xr mandoc_char 5 +are rendered best-effort in an ASCII equivalent. +If no equivalent is found, +.Sq \&? +is used instead. +.Pp +Output width is limited to 78 visible columns unless literal input lines +exceed this limit. +.Pp +The following +.Fl O +arguments are accepted: +.Bl -tag -width Ds +.It Cm indent Ns = Ns Ar indent +The left margin for normal text is set to +.Ar indent +blank characters instead of the default of five for +.Xr mdoc 5 +and seven for +.Xr man 5 . +Increasing this is not recommended; it may result in degraded formatting, +for example overfull lines or ugly line breaks. +.It Cm width Ns = Ns Ar width +The output width is set to +.Ar width , +which will normalise to \(>=60. +.El +.Ss HTML Output +Output produced by +.Fl T Ns Cm html +conforms to HTML-4.01 strict. +.Pp +The +.Pa example.style.css +file documents style-sheet classes available for customising output. +If a style-sheet is not specified with +.Fl O Ns Ar style , +.Fl T Ns Cm html +defaults to simple output readable in any graphical or text-based web +browser. +.Pp +Special characters are rendered in decimal-encoded UTF\-8. +.Pp +The following +.Fl O +arguments are accepted: +.Bl -tag -width Ds +.It Cm fragment +Omit the +.Aq !DOCTYPE +declaration and the +.Aq html , +.Aq head , +and +.Aq body +elements and only emit the subtree below the +.Aq body +element. +The +.Cm style +argument will be ignored. +This is useful when embedding manual content within existing documents. +.It Cm includes Ns = Ns Ar fmt +The string +.Ar fmt , +for example, +.Ar ../src/%I.html , +is used as a template for linked header files (usually via the +.Sq \&In +macro). +Instances of +.Sq \&%I +are replaced with the include filename. +The default is not to present a +hyperlink. +.It Cm man Ns = Ns Ar fmt +The string +.Ar fmt , +for example, +.Ar ../html%S/%N.%S.html , +is used as a template for linked manuals (usually via the +.Sq \&Xr +macro). +Instances of +.Sq \&%N +and +.Sq %S +are replaced with the linked manual's name and section, respectively. +If no section is included, section 1 is assumed. +The default is not to +present a hyperlink. +.It Cm style Ns = Ns Ar style.css +The file +.Ar style.css +is used for an external style-sheet. +This must be a valid absolute or +relative URI. +.El +.Ss Locale Output +Locale-depending output encoding is triggered with +.Fl T Ns Cm locale . +This option is not available on all systems: systems without locale +support, or those whose internal representation is not natively UCS-4, +will fall back to +.Fl T Ns Cm ascii . +See +.Sx ASCII Output +for font style specification and available command-line arguments. +.Ss Man Output +Translate input format into +.Xr man 5 +output format. +This is useful for distributing manual sources to legacy systems +lacking +.Xr mdoc 5 +formatters. +.Pp +If +.Xr mdoc 5 +is passed as input, it is translated into +.Xr man 5 . +If the input format is +.Xr man 5 , +the input is copied to the output, expanding any +.Xr mandoc_roff 5 +.Sq so +requests. +The parser is also run, and as usual, the +.Fl W +level controls which +.Sx DIAGNOSTICS +are displayed before copying the input to the output. +.Ss PDF Output +PDF-1.1 output may be generated by +.Fl T Ns Cm pdf . +See +.Sx PostScript Output +for +.Fl O +arguments and defaults. +.Ss PostScript Output +PostScript +.Qq Adobe-3.0 +Level-2 pages may be generated by +.Fl T Ns Cm ps . +Output pages default to letter sized and are rendered in the Times font +family, 11-point. +Margins are calculated as 1/9 the page length and width. +Line-height is 1.4m. +.Pp +Special characters are rendered as in +.Sx ASCII Output . +.Pp +The following +.Fl O +arguments are accepted: +.Bl -tag -width Ds +.It Cm paper Ns = Ns Ar name +The paper size +.Ar name +may be one of +.Ar a3 , +.Ar a4 , +.Ar a5 , +.Ar legal , +or +.Ar letter . +You may also manually specify dimensions as +.Ar NNxNN , +width by height in millimetres. +If an unknown value is encountered, +.Ar letter +is used. +.El +.Ss UTF\-8 Output +Use +.Fl T Ns Cm utf8 +to force a UTF\-8 locale. +See +.Sx Locale Output +for details and options. +.Ss XHTML Output +Output produced by +.Fl T Ns Cm xhtml +conforms to XHTML-1.0 strict. +.Pp +See +.Sx HTML Output +for details; beyond generating XHTML tags instead of HTML tags, these +output modes are identical. +.Sh EXIT STATUS +The +.Nm +utility exits with one of the following values, controlled by the message +.Ar level +associated with the +.Fl W +option: +.Pp +.Bl -tag -width Ds -compact +.It 0 +No warnings or errors occurred, or those that did were ignored because +they were lower than the requested +.Ar level . +.It 2 +At least one warning occurred, but no error, and +.Fl W Ns Cm warning +was specified. +.It 3 +At least one parsing error occurred, but no fatal error, and +.Fl W Ns Cm error +or +.Fl W Ns Cm warning +was specified. +.It 4 +A fatal parsing error occurred. +.It 5 +Invalid command line arguments were specified. +No input files have been read. +.It 6 +An operating system error occurred, for example memory exhaustion or an +error accessing input files. +Such errors cause +.Nm +to exit at once, possibly in the middle of parsing or formatting a file. +.El +.Pp +Note that selecting +.Fl T Ns Cm lint +output mode implies +.Fl W Ns Cm warning . +.Sh EXAMPLES +To page manuals to the terminal: +.Pp +.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less +.Dl $ mandoc mandoc.1 mdoc.5 | less +.Pp +To produce HTML manuals with +.Ar style.css +as the style-sheet: +.Pp +.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.5 \*(Gt mdoc.5.html +.Pp +To check over a large set of manuals: +.Pp +.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` +.Pp +To produce a series of PostScript manuals for A4 paper: +.Pp +.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.5 man.5 \*(Gt manuals.ps +.Pp +Convert a modern +.Xr mdoc 5 +manual to the older +.Xr man 5 +format, for use on systems lacking an +.Xr mdoc 5 +parser: +.Pp +.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man +.Sh DIAGNOSTICS +Standard error messages reporting parsing errors are prefixed by +.Pp +.Sm off +.D1 Ar file : line : column : \ level : +.Sm on +.Pp +where the fields have the following meanings: +.Bl -tag -width "column" +.It Ar file +The name of the input file causing the message. +.It Ar line +The line number in that input file. +Line numbering starts at 1. +.It Ar column +The column number in that input file. +Column numbering starts at 1. +If the issue is caused by a word, the column number usually +points to the first character of the word. +.It Ar level +The message level, printed in capital letters. +.El +.Pp +Message levels have the following meanings: +.Bl -tag -width "warning" +.It Cm fatal +The parser is unable to parse a given input file at all. +No formatted output is produced from that input file. +.It Cm error +An input file contains syntax that cannot be safely interpreted, +either because it is invalid or because +.Nm +does not implement it yet. +By discarding part of the input or inserting missing tokens, +the parser is able to continue, and the error does not prevent +generation of formatted output, but typically, preparing that +output involves information loss, broken document structure +or unintended formatting. +.It Cm warning +An input file uses obsolete, discouraged or non-portable syntax. +All the same, the meaning of the input is unambiguous and a correct +rendering can be produced. +Documents causing warnings may render poorly when using other +formatting tools instead of +.Nm . +.El +.Pp +Messages of the +.Cm warning +and +.Cm error +levels are hidden unless their level, or a lower level, is requested using a +.Fl W +option or +.Fl T Ns Cm lint +output mode. +.Pp +The +.Nm +utility may also print messages related to invalid command line arguments +or operating system errors, for example when memory is exhausted or +input files cannot be read. +Such messages do not carry the prefix described above. +.Sh COMPATIBILITY +This section summarises +.Nm +compatibility with GNU troff. +Each input and output format is separately noted. +.Ss ASCII Compatibility +.Bl -bullet -compact +.It +Unrenderable unicode codepoints specified with +.Sq \e[uNNNN] +escapes are printed as +.Sq \&? +in mandoc. +In GNU troff, these raise an error. +.It +The +.Sq \&Bd \-literal +and +.Sq \&Bd \-unfilled +macros of +.Xr mdoc 5 +in +.Fl T Ns Cm ascii +are synonyms, as are \-filled and \-ragged. +.It +In historic GNU troff, the +.Sq \&Pa +.Xr mdoc 5 +macro does not underline when scoped under an +.Sq \&It +in the FILES section. +This behaves correctly in +.Nm . +.It +A list or display following the +.Sq \&Ss +.Xr mdoc 5 +macro in +.Fl T Ns Cm ascii +does not assert a prior vertical break, just as it doesn't with +.Sq \&Sh . +.It +The +.Sq \&na +.Xr man 5 +macro in +.Fl T Ns Cm ascii +has no effect. +.It +Words aren't hyphenated. +.El +.Ss HTML/XHTML Compatibility +.Bl -bullet -compact +.It +The +.Sq \efP +escape will revert the font to the previous +.Sq \ef +escape, not to the last rendered decoration, which is now dictated by +CSS instead of hard-coded. +It also will not span past the current scope, +for the same reason. +Note that in +.Sx ASCII Output +mode, this will work fine. +.It +The +.Xr mdoc 5 +.Sq \&Bl \-hang +and +.Sq \&Bl \-tag +list types render similarly (no break following overreached left-hand +side) due to the expressive constraints of HTML. +.It +The +.Xr man 5 +.Sq IP +and +.Sq TP +lists render similarly. +.El +.Sh INTERFACE STABILITY +The +.Nm +utility is +.Nm Committed , +but the details of specific output formats other than ASCII are +.Nm Uncommitted . +.Sh SEE ALSO +.Xr eqn 5 , +.Xr man 5 , +.Xr mandoc_char 5 , +.Xr mdoc 5 , +.Xr mandoc_roff 5 , +.Xr tbl 5 +.Sh AUTHORS +The +.Nm +utility was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . +.Sh CAVEATS +In +.Fl T Ns Cm html +and +.Fl T Ns Cm xhtml , +the maximum size of an element attribute is determined by +.Dv BUFSIZ , +which is usually 1024 bytes. +Be aware of this when setting long link +formats such as +.Fl O Ns Cm style Ns = Ns Ar really/long/link . +.Pp +Nesting elements within next-line element scopes of +.Fl m Ns Cm an , +such as +.Sq br +within an empty +.Sq B , +will confuse +.Fl T Ns Cm html +and +.Fl T Ns Cm xhtml +and cause them to forget the formatting of the prior next-line scope. +.Pp +The +.Sq \(aq +control character is an alias for the standard macro control character +and does not emit a line-break as stipulated in GNU troff. diff --git a/usr/src/man/man1/printf.1 b/usr/src/man/man1/printf.1 index 549628ab2e..24ba63bf91 100644 --- a/usr/src/man/man1/printf.1 +++ b/usr/src/man/man1/printf.1 @@ -128,7 +128,7 @@ precision specifiers. The special character \fB*\fR may be used instead of a string of decimal digits to indicate a minimum field width or a precision. In this case the next available argument is used (or the \fIn\fRth if the form \fIn\fR\fB$\fR is -used), treating its value as a decimal string. +used), treating its value as a decimal string. .RE .RS +4 .TP diff --git a/usr/src/man/man1/tar.1 b/usr/src/man/man1/tar.1 index 0829a9c1c3..ccc5ba4ace 100644 --- a/usr/src/man/man1/tar.1 +++ b/usr/src/man/man1/tar.1 @@ -1182,7 +1182,7 @@ Interface Stability Committed .sp .LP \fBar\fR(1), \fBbasename\fR(1), \fBbzip2\fR(1), \fBcd\fR(1), \fBchown\fR(1), -\fBcompress\fR)(1), \fBcpio\fR(1), \fBcsh\fR(1), \fBdirname\fR(1), +\fBcompress\fR)(1), \fBcpio\fR(1), \fBcsh\fR(1), \fBdirname\fR(1), \fBfind\fR(1), \fBgzip\fR(1), \fBls\fR(1), \fBmt\fR(1), \fBpax\fR(1), \fBsetfacl\fR(1), \fBumask\fR(1), \fBxz\fR(1), \fBmknod\fR(1M), \fBarchives.h\fR(3HEAD), \fBattributes\fR(5), \fBenviron\fR(5), diff --git a/usr/src/man/man1/whatis.1 b/usr/src/man/man1/whatis.1 deleted file mode 100644 index 73435fb5cb..0000000000 --- a/usr/src/man/man1/whatis.1 +++ /dev/null @@ -1,61 +0,0 @@ -'\" te -.\" Copyright (c) 1992, Sun Microsystems, Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH WHATIS 1 "Sep 14, 1992" -.SH NAME -whatis \- display a one-line summary about a keyword -.SH SYNOPSIS -.LP -.nf -\fBwhatis\fR \fIcommand\fR... -.fi - -.SH DESCRIPTION -.sp -.LP -\fBwhatis\fR looks up a given \fIcommand\fR and displays the header line from -the manual section. You can then run the \fBman\fR(1) command to get more -information. If the line starts \fBname(\fIsection\fR)\fR.\|.\|. you can do -\fBman\fR \fB-s\fR\fB\fIsection\fR name\fR to get the documentation for it. -Try \fBwhatis ed\fR and then you should do \fBman\fR \fB-s\fR \fB1 ed\fR to get -the manual page for \fBed\fR(1). -.sp -.LP -\fBwhatis\fR is actually just the \fB-f\fR option to the \fBman\fR(1) command. -.sp -.LP -\fBwhatis\fR uses the \fB/usr/share/man/windex\fR database. This database is -created by \fBcatman\fR(1M). If this database does not exist, \fBwhatis\fR will -fail. -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/share/man/windex\fR\fR -.ad -.RS 25n -Table of contents and keyword database -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -CSI Enabled -.TE - -.SH SEE ALSO -.sp -.LP -\fBapropos\fR(1), \fBman\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5) diff --git a/usr/src/man/man1m/arcstat.1m b/usr/src/man/man1m/arcstat.1m index 585f84baf9..e4a0eca43e 100644 --- a/usr/src/man/man1m/arcstat.1m +++ b/usr/src/man/man1m/arcstat.1m @@ -460,7 +460,7 @@ Display only \fIcount\fR reports. Specify the sampling interval in seconds. .RE -.SH AUTHORS +.SH AUTHORS .sp .LP arcstat was originally written by Neelakanth Nadgir and supported only ZFS ARC statistics. diff --git a/usr/src/man/man1m/catman.1m b/usr/src/man/man1m/catman.1m index eea9348121..aba601c583 100644 --- a/usr/src/man/man1m/catman.1m +++ b/usr/src/man/man1m/catman.1m @@ -1,373 +1,72 @@ -'\" te -.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH CATMAN 1M "Feb 27, 1998" -.SH NAME -catman \- create the formatted files for the reference manual -.SH SYNOPSIS -.LP -.nf -\fB/usr/bin/catman\fR [\fB-c\fR] [\fB-n\fR] [\fB-p\fR] [\fB-t\fR] [\fB-w\fR] [\fB-M\fR \fIdirectory\fR] - [\fB-T\fR \fImacro-package\fR] [\fIsections\fR] -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBcatman\fR utility creates the preformatted versions of the on-line -manual from the \fBnroff\fR(1) or \fBsgml\fR(5) input files. This feature -allows easy distribution of the preformatted manual pages among a group of -associated machines (for example, with \fBrdist\fR(1)), since it makes the -directories of preformatted manual pages self-contained and independent of the -unformatted entries. -.sp -.LP -\fBcatman\fR also creates the \fBwindex\fR database file in the directories -specified by the \fBMANPATH\fR or the \fB-M\fR option. The \fBwindex\fR -database file is a three column list consisting of a keyword, the reference -page that the keyword points to, and a line of text that describes the purpose -of the utility or interface documented on the reference page. Each keyword is -taken from the comma separated list of words on the \fBNAME\fR line before the -`\(mi' (dash). The reference page that the keyword points to is the first word -on the \fBNAME\fR line. The text after the \(mi on the \fBNAME\fR line is the -descriptive text in the third column. The \fBNAME\fR line must be immediately -preceded by the page heading line created by the \fB\&.TH\fR macro (see -\fBNOTES\fR for required format). -.sp -.LP -Each manual page is examined and those whose preformatted versions are missing -or out of date are recreated. If any changes are made, \fBcatman\fR recreates -the \fBwindex\fR database. -.sp -.LP -If a manual page is a \fIshadow\fR page, that is, it sources another manual -page for its contents, a symbolic link is made in the \fBcat\fR\fIx\fR or -\fBfmt\fR\fIx\fR directory to the appropriate preformatted manual page. -.sp -.LP -Shadow files in an unformatted nroff source file are identified by the first -line being of the form \fB\&.so man\fR\fIx\fR\fB/yyy.\fR\fIx\fR\fB\&.\fR -.sp -.LP -Shadow files in the \fBSGML\fR sources are identified by the string -\fBSHADOW_PAGE\fR. The file entity declared in the shadow file identifies the -file to be sourced. -.SH OPTIONS -.sp -.LP -The following options are supported: -.sp -.ne 2 -.na -\fB\fB-c\fR\fR -.ad -.RS 20n -Create unformatted nroff source files in the appropriate \fBman\fR -subdirectories from the \fBSGML\fR sources. This option will overwrite any -existing file in the \fBman\fR directory of the same name as the \fBSGML\fR -file. -.RE - -.sp -.ne 2 -.na -\fB\fB-n\fR\fR -.ad -.RS 20n -Do not create (or recreate) the \fBwindex\fR database. If the \fB-n\fR option -is specified, the \fBwindex\fR database is not created and the \fBapropos\fR, -\fBwhatis\fR, \fBman\fR \fB-f\fR, and \fBman\fR \fB-k\fR commands will fail. -.RE - -.sp -.ne 2 -.na -\fB\fB-p\fR\fR -.ad -.RS 20n -Print what would be done instead of doing it. -.RE - -.sp -.ne 2 -.na -\fB\fB-t\fR\fR -.ad -.RS 20n -Create \fBtroff\fRed entries in the appropriate \fBfmt\fR subdirectories -instead of \fBnroff\fRing into the \fBcat\fR subdirectories. -.RE - -.sp -.ne 2 -.na -\fB\fB-w\fR\fR -.ad -.RS 20n -Only create the \fBwindex\fR database that is used by \fBwhatis\fR(1) and the -\fBman\fR(1) \fB-f\fR and \fB-k\fR options. No manual reformatting is done. -.RE - -.sp -.ne 2 -.na -\fB\fB-M\fR\fI directory\fR\fR -.ad -.RS 20n -Update manual pages located in the specified \fIdirectory\fR, -(\fB/usr/share/man\fR by default). If the \fB-M\fR option is specified, the -directory argument must not contain a `,' (comma), since a comma is used to -delineate section numbers. See \fBman\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fB-T\fR\fI macro-package\fR\fR -.ad -.RS 20n -Use \fImacro-package\fR in place of the standard manual page macros, ( -\fBman\fR(5) by default). -.RE - -.SH OPERANDS -.sp -.LP -The following operand is supported: -.sp -.ne 2 -.na -\fB\fIsections\fR\fR -.ad -.RS 12n -If there is one parameter not starting with a `\fB\(mi\fR\&', it is taken to be -a space separated list of manual sections to be processed by \fBcatman\fR. If -this operand is specified, only the manual sections in the list will be -processed. For example, -.sp -.in +2 -.nf -\fBcatman 1 2 3\fR -.fi -.in -2 -.sp - -only updates manual sections \fB1\fR, \fB2\fR, and \fB3\fR. If specific -sections are not listed, all sections in the \fBman\fR directory specified by -the environment variable \fBMANPATH\fR are processed. -.RE - -.SH ENVIRONMENT VARIABLES -.sp -.ne 2 -.na -\fB\fBTROFF\fR\fR -.ad -.RS 11n -The name of the formatter to use when the \fB-t\fR flag is given. If not set, -\fBtroff\fR(1) is used. -.RE - -.sp -.ne 2 -.na -\fB\fBMANPATH\fR\fR -.ad -.RS 11n -A colon-separated list of directories that are processed by \fBcatman\fR and -\fBman\fR(1). Each directory can be followed by a comma-separated list of -sections. If set, its value overrides \fB/usr/share/man\fR as the default -directory search path, and the \fBman.cf\fR file as the default section search -path. The \fB-M\fR and \fB-s\fR flags, in turn, override these values. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/share/man\fR\fR -.ad -.RS 28n -default manual directory location -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/man*/*.*\fR\fR -.ad -.RS 28n -raw nroff input files -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/sman*/*.*\fR\fR -.ad -.RS 28n -raw \fBSGML\fR input files -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/cat*/*.*\fR\fR -.ad -.RS 28n -preformatted \fBnroff\fRed manual pages -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/fmt*/*.*\fR\fR -.ad -.RS 28n -preformatted \fBtroff\fRed manual pages -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/windex\fR\fR -.ad -.RS 28n -table of contents and keyword database -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/lib/makewhatis\fR\fR -.ad -.RS 28n -command script to make \fBwindex\fR database -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/tmac/an\fR\fR -.ad -.RS 28n -default macro package -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -CSI Enabled -.TE - -.SH SEE ALSO -.sp -.LP -\fBapropos\fR(1), \fBman\fR(1), \fBnroff\fR(1), \fBrdist\fR(1), \fBrm\fR(1), -\fBtroff\fR(1), \fBwhatis\fR(1), \fBattributes\fR(5), \fBman\fR(5), -\fBsgml\fR(5) -.SH DIAGNOSTICS -.sp -.ne 2 -.na -\fB\fBman?/xxx.? (.so'ed from man?/yyy.?): No such file or directory\fR\fR -.ad -.sp .6 -.RS 4n -The file outside the parentheses is missing, and is referred to by the file -inside them. -.RE - -.sp -.ne 2 -.na -\fB\fBtarget of .so in man?/xxx.? must be relative to /usr/man\fR\fR -.ad -.sp .6 -.RS 4n -\fBcatman\fR only allows references to filenames that are relative to the -directory \fB/usr/man\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBopendir:man?:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR -\fBdirectory\fR\fR -.ad -.sp .6 -.RS 4n -A harmless warning message indicating that one of the directories \fBcatman\fR -normally looks for is missing. -.RE - -.sp -.ne 2 -.na -\fB\fB*.*:\fR \fBNo\fR \fBsuch\fR \fBfile\fR \fBor\fR \fBdirectory\fR\fR -.ad -.sp .6 -.RS 4n -A harmless warning message indicating \fBcatman\fR came across an empty -directory. -.RE - -.SH WARNINGS -.sp -.LP -If a user, who has previously run \fBcatman\fR to install the \fBcat*\fR -directories, upgrades the operating system, the entire \fBcat*\fR directory -structure should be removed prior to running \fBcatman\fR. See \fBrm\fR(1). -.sp -.LP -Do not re-run \fBcatman\fR to re-build the \fBwhatis\fR database unless the -complete set of \fBman*\fR directories is present. \fBcatman\fR builds this -\fBwindex\fR file based on the \fBman*\fR directories. -.SH NOTES -.sp -.LP -To generate a valid windex index file, \fBcatman\fR has certain requirements. -Within the individual man page file, \fBcatman\fR requires two macro lines to -have a specific format. These are the \fB\&.TH \fRpage heading line and the -\fB\&.SH NAME \fRline. -.sp -.LP -The \fB\&.TH \fRmacro requires at least the first three arguments, that is, the -filename, section number, and the date. The \fB\&.TH \fRline starts off with -the \fB\&.TH \fRmacro, followed by a space, the man page filename, a single -space, the section number, another single space, and the date. The date should -appear in double quotes and is specified as "day month year," with the month -always abbreviated to the first three letters (Jan, Feb, Mar, and so forth). -.sp -.LP -The \fB\&.SH NAME \fRmacro, also known as the \fBNAME \fRline, must immediately -follow the \fB\&.TH \fRline, with nothing in between those lines. No font -changes are permitted in the \fBNAME \fRline. The \fBNAME \fRline is -immediately followed by a line containing the man page filename; then shadow -page names, if applicable, separated by commas; a dash; and a brief summary -statement. These elements should all be on one line; no carriage returns are -permitted. -.sp -.LP -An example of proper coding of these lines is: -.sp -.in +2 -.nf -\&.TH NISMATCH 1M "Apr "10, 1998"" -\&.SH NAME -nismatch, nisgrep \e- utilities for searching NIS+ tables -.fi -.in -2 - +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" +.Dd Jul 19, 2014 +.Dt CATMAN 1M +.Os +.Sh NAME +.Nm catman +.Nd generate +.Nm whatis +database files +.Sh SYNOPSIS +.Nm +.Op Fl M Ar path +.Op Fl w +.Sh DESCRIPTION +The +.Nm +utility generates a set of +.Nm whatis +database files suitable for use with +.Xr apropos 1 +and +.Xr whatis 1 . +It is supplied for compatibility reasons. The same databases can +be generated using the +.Fl w +option with +.Xr man 1 , +and that command should be used instead. +.Sh OPTIONS +.Bl -tag -width ".Fl d" +.It Fl M Ar path +Generate the +.Nm whatis +database files within the specified colon separated manual paths. +Overrides the +.Ev MANPATH +environment variable. +.It Fl w +This option is present for backwards compatibility, and is ignored. +.El +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev MANPATH" +.It Ev MANPATH +Used to specify a colon seperated list of manual paths within +which to generate +.Nm whatis +database files. +.El +.Sh EXIT STATUS +.Ex -std +.Sh INTERFACE STABILITY +.Nm "Obsolete Committed" . +.Sh CODE SET INDEPENDENCE +Enabled. +.Sh SEE ALSO +.Xr apropos 1 , +.Xr man 1 , +.Xr whatis 1 diff --git a/usr/src/man/man1m/dd.1m b/usr/src/man/man1m/dd.1m index 99dae520ff..a9b8e18a60 100644 --- a/usr/src/man/man1m/dd.1m +++ b/usr/src/man/man1m/dd.1m @@ -410,8 +410,6 @@ writes will be synchronous. For more information on \fBO_SYNC\fR see \fBfcntl.h\fR(3HEAD). .RE -.RE - .sp .LP If operands other than \fBconv=\fR and \fBoflag=\fR are specified more than once, diff --git a/usr/src/man/man1m/dladm.1m b/usr/src/man/man1m/dladm.1m index c773ae570f..cd993ffa63 100644 --- a/usr/src/man/man1m/dladm.1m +++ b/usr/src/man/man1m/dladm.1m @@ -9,7 +9,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH DLADM 1M "Sep 23, 2009" +.TH DLADM 1M "Jul 17, 2014" .SH NAME dladm \- administer data links .SH SYNOPSIS @@ -593,7 +593,6 @@ See "Options," above. .sp .ne 2 -.mk .na \fB\fB-z\fR \fIzonename\fR .ad @@ -3189,7 +3188,6 @@ Operate on a link that has been delegated to the specified zone. .sp .ne 2 -.mk .na \fB\fB-p\fR \fIprop\fR=\fIvalue\fR[,...], \fB--prop\fR \fIprop\fR=\fIvalue\fR[,...]\fR @@ -3251,7 +3249,6 @@ Operate on a link that has been delegated to the specified zone. .sp .ne 2 -.mk .na \fB\fB-p\fR \fIprop, ...\fR, \fB--prop\fR=\fIprop, ...\fR\fR .ad @@ -3394,7 +3391,6 @@ Operate on a link that has been delegated to the specified zone. .sp .ne 2 -.mk .na \fB\fB-p\fR \fIprop, ...\fR, \fB--prop\fR=\fIprop, ...\fR\fR .ad @@ -3741,7 +3737,6 @@ See "Options," above. .sp .ne 2 -.mk .na \fB\fB-z\fR \fIzonenme\fR .ad @@ -3900,7 +3895,6 @@ Display information for all VNICs on the named link. .sp .ne 2 -.mk .na \fB\fB-z\fR \fIzonenme\fR .ad diff --git a/usr/src/man/man1m/flowadm.1m b/usr/src/man/man1m/flowadm.1m index a64a703612..c9d5b846d5 100644 --- a/usr/src/man/man1m/flowadm.1m +++ b/usr/src/man/man1m/flowadm.1m @@ -225,7 +225,6 @@ named flow. .sp .ne 2 -.mk .na \fB\fB-z\fR \fIzonename\fR .ad @@ -286,7 +285,6 @@ Operate on a link that has been delegated to the specified zone. .sp .ne 2 -.mk .na \fB\fB-l\fR \fIlink\fR, \fB--link\fR=\fIlink\fR\fR .ad @@ -359,7 +357,6 @@ Operate on a link that has been delegated to the specified zone. .sp .ne 2 -.mk .na \fB\fB-l\fR \fIlink\fR | \fIflow\fR, \fB--link\fR=\fIlink\fR | \fIflow\fR\fR .ad diff --git a/usr/src/man/man1m/ipadm.1m b/usr/src/man/man1m/ipadm.1m index e2452695df..01a0b428a2 100644 --- a/usr/src/man/man1m/ipadm.1m +++ b/usr/src/man/man1m/ipadm.1m @@ -419,7 +419,6 @@ the setting applies to. .sp .RE -.RE .sp .ne 2 diff --git a/usr/src/man/man1m/lofiadm.1m b/usr/src/man/man1m/lofiadm.1m index e1ea5d0055..259a269f1c 100644 --- a/usr/src/man/man1m/lofiadm.1m +++ b/usr/src/man/man1m/lofiadm.1m @@ -81,7 +81,6 @@ file be encrypted later. In the global zone, \fBlofiadm\fR can be used on both the global zone devices and all devices owned by other non-global zones on the system. .sp -.LP .SH OPTIONS .sp .LP diff --git a/usr/src/man/man1m/root_archive.1m b/usr/src/man/man1m/root_archive.1m index f4b53fe0ae..1b59d93e78 100644 --- a/usr/src/man/man1m/root_archive.1m +++ b/usr/src/man/man1m/root_archive.1m @@ -21,7 +21,7 @@ root_archive \- manage bootable miniroot archives .SH DESCRIPTION .sp .LP -The \fBroot_archive\fR utility is used to manipulate boot archives. +The \fBroot_archive\fR utility is used to manipulate boot archives. The utility can pack and unpack boot archives and image miniroots. Both \fBufs\fR and \fBhsfs\fR (\fBiso9660\fR) format archives can be unpacked, although only \fBufs\fR format is generated when packing. diff --git a/usr/src/man/man1m/snoop.1m b/usr/src/man/man1m/snoop.1m index 29d9485a9c..4184c66e10 100644 --- a/usr/src/man/man1m/snoop.1m +++ b/usr/src/man/man1m/snoop.1m @@ -310,9 +310,8 @@ Open an earlier datalink specified via .B -d or .B -I -in the specified zone -.I zonename -. This option is only meaningful in the global zone and +in the specified zone \fIzonename\fR. +This option is only meaningful in the global zone and allows the global zone to inspect datalinks of non-global zones. .RE diff --git a/usr/src/man/man1m/vfsstat.1m b/usr/src/man/man1m/vfsstat.1m index 702291a19d..aef8431a09 100644 --- a/usr/src/man/man1m/vfsstat.1m +++ b/usr/src/man/man1m/vfsstat.1m @@ -11,7 +11,7 @@ .\" .\" Copyright 2014 Joyent, Inc. All rights reserved. .\" -.TH "VFSSTAT" "1m" "May 2014" "" "" +.TH "VFSSTAT" "1m" "May 1, 2014" "" "" . .SH "NAME" \fBvfsstat\fR \-\- Report VFS read and write activity @@ -75,34 +75,65 @@ The vfsstat utility reports the following information: .IP "" 4 . .nf -r/s reads per second +r/s +.RS +reads per second +.RE -w/s writes per second +w/s +.RS +writes per second +.RE -kr/s kilobytes read per second +kr/s +.RS +kilobytes read per second +.RE -kw/s kilobytes written per second +kw/s +.RS +kilobytes written per second +.RE -ractv average number of read operations actively being - serviced by the VFS layer +ractv +.RS +average number of read operations actively being serviced by the VFS layer +.RE -wactv average number of write operations actively being - serviced by the VFS layer +wactv +.RS +average number of write operations actively being serviced by the VFS layer +.RE -read_t average VFS read latency, in microseconds +read_t +.RS +average VFS read latency, in microseconds +.RE -writ_t average VFS write latency, in microseconds +writ_t +.RS +average VFS write latency, in microseconds +.RE -%r percent of time there is a VFS read operation - pending +%r +.RS +percent of time there is a VFS read operation pending +.RE -%w percent of time there is a VFS write operation - pending +%w +.RS +percent of time there is a VFS write operation pending +.RE -d/s VFS operations per second delayed by the ZFS I/O - throttle +d/s +.RS +VFS operations per second delayed by the ZFS I/O throttle +.RE -del_t average ZFS I/O throttle delay, in microseconds +del_t +.RS +average ZFS I/O throttle delay, in microseconds +.RE . .fi . @@ -112,23 +143,40 @@ del_t average ZFS I/O throttle delay, in microseconds The following options are supported: . .P -\-h Show help message and exit +\-h +.RS +Show help message and exit +.RE . .P -\-I Print results per interval, rather than per second (where - applicable) +\-I +.RS +Print results per interval, rather than per second (where applicable) +.RE . .P -\-M Print results in MB/s instead of KB/s +\-M +.RS +Print results in MB/s instead of KB/s +.RE . .P -\-r Show results in a comma\-separated format +\-r +.RS +Show results in a comma\-separated format +.RE . .P -\-z Hide zones with no VFS activity +\-z +.RS +Hide zones with no VFS activity +.RE . .P -\-Z Print results for all zones, not just the current zone +\-Z +.RS +Print results for all zones, not just the current zone +.RE . .SH "OPERANDS" interval diff --git a/usr/src/man/man1m/vndadm.1m b/usr/src/man/man1m/vndadm.1m index 63fb63f9df..253518a88a 100644 --- a/usr/src/man/man1m/vndadm.1m +++ b/usr/src/man/man1m/vndadm.1m @@ -49,7 +49,6 @@ series of alphanumeric ascii characters which typically match the name of the underlying data link. A given vnd device name must be unique in a given zone, but the same name can be used across zones. .sp -.LP .SH OPTIONS .sp .LP diff --git a/usr/src/man/man1m/zdb.1m b/usr/src/man/man1m/zdb.1m index c7d7f38f5b..7ec98908f6 100644 --- a/usr/src/man/man1m/zdb.1m +++ b/usr/src/man/man1m/zdb.1m @@ -19,8 +19,8 @@ \fBzdb\fR - Display zpool debugging and consistency information .SH "SYNOPSIS" -\fBzdb\fR [-CumdibcsDvhLXFPA] [-e [-p \fIpath\fR...]] [-t \fItxg\fR] - [-U \fIcache\fR] [-M \fIinflight I/Os\fR] [-x \fIdumpdir\fR] +\fBzdb\fR [-CumdibcsDvhLMXFPA] [-e [-p \fIpath\fR...]] [-t \fItxg\fR] + [-U \fIcache\fR] [-I \fIinflight I/Os\fR] [-x \fIdumpdir\fR] [\fIpoolname\fR [\fIobject\fR ...]] .P @@ -28,7 +28,7 @@ \fIdataset\fR [\fIobject\fR ...] .P -\fBzdb\fR -m [-LXFPA] [-t \fItxg\fR] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] +\fBzdb\fR -m [-MLXFPA] [-t \fItxg\fR] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] \fIpoolname\fR [\fIvdev\fR [\fImetaslab\fR ...]] .P @@ -194,6 +194,21 @@ verifies that all non-free blocks are referenced, which can be very expensive. .sp .6 .RS 4n Display the offset, spacemap, and free space of each metaslab. +When specified twice, also display information about the on-disk free +space histogram associated with each metaslab. When specified three time, +display the maximum contiguous free space, the in-core free space histogram, +and the percentage of free space in each space map. When specified +four times display every spacemap record. +.RE + +.sp +.ne 2 +.na +\fB-M\fR +.ad +.sp .6 +.RS 4n +Display the offset, spacemap, and free space of each metaslab. When specified twice, also display information about the maximum contiguous free space and the percentage of free space in each space map. When specified three times display every spacemap record. @@ -380,7 +395,7 @@ transactions. .sp .ne 2 .na -\fB-M \fIinflight I/Os\fR \fR +\fB-I \fIinflight I/Os\fR \fR .ad .sp .6 .RS 4n diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m index 2fcf129852..98fc8e7491 100644 --- a/usr/src/man/man1m/zfs.1m +++ b/usr/src/man/man1m/zfs.1m @@ -2380,7 +2380,6 @@ For example, specifying \fB-t snapshot\fR displays only snapshots. .sp .ne 2 -.mk .na \fB\fB-p\fR\fR .ad diff --git a/usr/src/man/man1m/zonecfg.1m b/usr/src/man/man1m/zonecfg.1m index e76d658740..c7d1ace8e5 100644 --- a/usr/src/man/man1m/zonecfg.1m +++ b/usr/src/man/man1m/zonecfg.1m @@ -166,7 +166,6 @@ Network interface. Resource control. .RE -.RE .SS "Properties" .sp .LP @@ -348,7 +347,6 @@ The following properties are supported: .sp .ne 2 -.mk .na \fB\fBfs\fR\fR .ad @@ -891,7 +889,6 @@ control and is related to the \fBzone.cpu-cap\fR resource control. See .sp .ne 2 -.mk .na \fBglobal: \fBfs-allowed\fR\fR .ad @@ -913,7 +910,6 @@ is not supported. .sp .ne 2 -.mk .na \fBglobal: \fBzfs-io-priority\fR\fR .ad @@ -1175,7 +1171,6 @@ cannot be used. .sp .ne 2 -.mk .na \fB\fB-u\fR \fIuuid\fR\fR .ad diff --git a/usr/src/man/man1m/zpool.1m b/usr/src/man/man1m/zpool.1m index c317f7e0a5..e14a72b7e3 100644 --- a/usr/src/man/man1m/zpool.1m +++ b/usr/src/man/man1m/zpool.1m @@ -2,7 +2,7 @@ .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved. .\" Copyright 2011, Nexenta Systems, Inc. All Rights Reserved. -.\" Copyright (c) 2012 by Delphix. All rights reserved. +.\" Copyright (c) 2013 by Delphix. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development .\" and Distribution License (the "License"). You may not use this file except .\" in compliance with the License. You can obtain a copy of the license at @@ -574,6 +574,15 @@ any space on an EFI labeled vdev which has not been brought online .sp .ne 2 .na +\fB\fBfragmentation\fR\fR +.ad +.RS 20n +The amount of fragmentation in the pool. +.RE + +.sp +.ne 2 +.na \fB\fBfree\fR\fR .ad .RS 20n @@ -1206,7 +1215,6 @@ is the default value. .sp .ne 2 -.mk .na \fB\fBzpool history\fR [\fB-il\fR] [\fIpool\fR] ...\fR .ad @@ -1650,7 +1658,7 @@ Display numbers in parsable (exact) values. .RS 12n Comma-separated list of properties to display. See the "Properties" section for a list of valid properties. The default list is "name, size, used, available, -expandsize, capacity, dedupratio, health, altroot" +fragmentation, expandsize, capacity, dedupratio, health, altroot" .RE .sp @@ -1665,12 +1673,10 @@ the pool, in addition to the pool-wise statistics. .sp .ne 2 -.mk .na \fB\fB-p\fR\fR .ad .RS 12n -.rt Display numbers in parseable (exact) values. .RE @@ -2048,10 +2054,10 @@ The results from this command are similar to the following: .in +2 .nf # \fBzpool list\fR - NAME SIZE ALLOC FREE EXPANDSZ CAP DEDUP HEALTH ALTROOT - rpool 19.9G 8.43G 11.4G - 42% 1.00x ONLINE - - tank 61.5G 20.0G 41.5G - 32% 1.00x ONLINE - - zion - - - - - - FAULTED - +NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT +rpool 19.9G 8.43G 11.4G 33% - 42% 1.00x ONLINE - +tank 61.5G 20.0G 41.5G 48% - 32% 1.00x ONLINE - +zion - - - - - - - FAULTED - .fi .in -2 .sp @@ -2272,7 +2278,7 @@ The command to remove the mirrored log \fBmirror-2\fR is: .LP The following command dipslays the detailed information for the \fIdata\fR pool. This pool is comprised of a single \fIraidz\fR vdev where one of its -devices increased its capacity by 1GB. In this example, the pool will not +devices increased its capacity by 10GB. In this example, the pool will not be able to utilized this extra capacity until all the devices under the \fIraidz\fR vdev have been expanded. @@ -2280,12 +2286,12 @@ be able to utilized this extra capacity until all the devices under the .in +2 .nf # \fBzpool list -v data\fR - NAME SIZE ALLOC FREE EXPANDSZ CAP DEDUP HEALTH ALTROOT - data 17.9G 174K 17.9G - 0% 1.00x ONLINE - - raidz1 17.9G 174K 17.9G - - c4t2d0 - - - 1G - c4t3d0 - - - - - c4t4d0 - - - - +NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT +data 23.9G 14.6G 9.30G 48% - 61% 1.00x ONLINE - + raidz1 23.9G 14.6G 9.30G 48% - + c1t1d0 - - - - - + c1t2d0 - - - - 10G + c1t3d0 - - - - - .fi .in -2 diff --git a/usr/src/man/man2/pipe.2 b/usr/src/man/man2/pipe.2 index 88b625bf52..5323c65d3b 100644 --- a/usr/src/man/man2/pipe.2 +++ b/usr/src/man/man2/pipe.2 @@ -41,7 +41,6 @@ descriptors. \fBpipe2()\fR called with a \fIflags\fR value of 0 will behave identically to \fBpipe()\fR. Values for \fIflags\fR are constructed by a bitwise-inclusive-OR of flags from the following list, defined in <\fBfcntl.h\fR>. -.RE .sp .ne 2 diff --git a/usr/src/man/man3c/btowc.3c b/usr/src/man/man3c/btowc.3c index 56dc9e19a2..8bdc513aaf 100644 --- a/usr/src/man/man3c/btowc.3c +++ b/usr/src/man/man3c/btowc.3c @@ -35,7 +35,7 @@ state. .LP The behavior of \fBbtowc()\fR is affected by the \fBLC_CTYPE\fR category of the current locale. See \fBenviron\fR(5). The function \fBbtowc_l()\fR does -not use the current locale, and instead operates on the locale +not use the current locale, and instead operates on the locale specified by \fIloc\fR. .SH RETURN VALUES .LP diff --git a/usr/src/man/man3c/epoll_create.3c b/usr/src/man/man3c/epoll_create.3c index 87d0a85c38..3dd9abf5f7 100644 --- a/usr/src/man/man3c/epoll_create.3c +++ b/usr/src/man/man3c/epoll_create.3c @@ -88,7 +88,6 @@ The maximum allowable number of files is currently open in the system. .RE .sp -.LP .SH NOTES .sp .LP @@ -98,7 +97,6 @@ compatibility for Linux-borne applications; native applications should continue to prefer using event ports via the \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. -.RE .SH SEE ALSO .sp diff --git a/usr/src/man/man3c/epoll_ctl.3c b/usr/src/man/man3c/epoll_ctl.3c index 0cce6affa4..ccf3139396 100644 --- a/usr/src/man/man3c/epoll_ctl.3c +++ b/usr/src/man/man3c/epoll_ctl.3c @@ -33,7 +33,7 @@ Valid values for \fIop\fR: \fBEPOLL_CTL_ADD\fR .ad .RS 12n -For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, associate the file descriptor specified by \fIfd\fR with the event specified by \fIevent\fR. .RE @@ -44,7 +44,7 @@ by \fIevent\fR. \fBEPOLL_CTL_DEL\fR .ad .RS 12n -For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, remove all event associations for the file descriptor specified by \fIfd\fR. \fIevent\fR is ignored, and may be NULL. .RE @@ -80,8 +80,8 @@ struct epoll_event { .in -4 The \fIdata\fR field specifies the datum to -be associated with the event and -will be returned via \fBepoll_wait\fR(3C). +be associated with the event and +will be returned via \fBepoll_wait\fR(3C). The \fIevents\fR field denotes both the desired events (when specified via \fBepoll_ctl()\fR) and the events that have occurred (when returned via \fBepoll_wait\fR(3C)). @@ -93,7 +93,6 @@ of any combination of the following event flags: .ne 2 .na \fBEPOLLIN\fR -.as .RS 14n Data other than high priority data may be read without blocking. For streams, this flag is set in the returned \fIevents\fR even if the message is of @@ -104,7 +103,6 @@ zero length. .ne 2 .na \fBEPOLLPRI\fR -.as .RS 14n Normal data (priority band equals 0) may be read without blocking. For streams, this flag is set in the returned \fIevents\fR even if the message is of zero @@ -115,7 +113,6 @@ length. .ne 2 .na \fBEPOLLOUT\fR -.as .RS 14n Normal data (priority band equals 0) may be written without blocking. .RE @@ -124,7 +121,6 @@ Normal data (priority band equals 0) may be written without blocking. .ne 2 .na \fBEPOLLRDNORM\fR -.as .RS 14n Normal data (priority band equals 0) may be read without blocking. For streams, this flag is set in the returned \fIrevents\fR even if the message is of @@ -135,7 +131,6 @@ zero length. .ne 2 .na \fBEPOLLRDBAND\fR -.as .RS 14n Data from a non-zero priority band may be read without blocking. For streams, this flag is set in the returned \fIrevents\fR even if the message is of @@ -146,7 +141,6 @@ zero length. .ne 2 .na \fBEPOLLWRNORM\fR -.as .RS 14n The same as \fBEPOLLOUT\fR. .RE @@ -155,7 +149,6 @@ The same as \fBEPOLLOUT\fR. .ne 2 .na \fBEPOLLWRBAND\fR -.as .RS 14n Priority data (priority band > 0) may be written. This event only examines bands that have been written to at least once. @@ -165,7 +158,6 @@ bands that have been written to at least once. .ne 2 .na \fBEPOLLMSG\fR -.as .RS 14n This exists only for backwards binary and source compatibility with Linux; it has no meaning and is ignored. @@ -175,7 +167,6 @@ it has no meaning and is ignored. .ne 2 .na \fBEPOLLERR\fR -.as .RS 14n An error has occurred on the device or stream. This flag is only valid in the returned \fIevents\fR field. @@ -185,7 +176,6 @@ returned \fIevents\fR field. .ne 2 .na \fBEPOLLHUP\fR -.as .RS 14n A hangup has occurred on the stream. This event and \fBEPOLLOUT\fR are mutually exclusive; a stream can never be writable if a hangup has occurred. However, @@ -200,7 +190,6 @@ in the \fIevents\fR field specified via \fBepoll_ctl()\fR. .ne 2 .na \fBEPOLLRDHUP\fR -.as .RS 14n The stream socket peer shutdown the writing half of the connection and no further data will be readable via the socket. This event is not mutually @@ -211,7 +200,6 @@ exclusive with \fBEPOLLIN\fR. .ne 2 .na \fBEPOLLWAKEUP\fR -.as .RS 14n This exists only for backwards binary and source compatibility with Linux; it has no meaning and is ignored. @@ -221,7 +209,6 @@ it has no meaning and is ignored. .ne 2 .na \fBEPOLLONESHOT\fR -.as .RS 14n Sets the specified event to be in one-shot mode, whereby the event association with the \fBepoll\fR(5) instance specified by \fIepfd\fR is removed atomically @@ -234,7 +221,6 @@ races inherent in multithreaded use of \fBepoll_wait\fR(3C). .ne 2 .na \fBEPOLLET\fR -.as .RS 14n Sets the specified event to be edge-triggered mode instead of the default mode of level-triggered. In this mode, events will be induced by @@ -296,7 +282,6 @@ specified \fBepoll\fR(5) instance. .RE .sp -.LP .SH NOTES .sp .LP @@ -306,7 +291,6 @@ compatibility for Linux-borne applications; native applications should continue to prefer using event ports via the \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. -.RE .SH SEE ALSO .sp diff --git a/usr/src/man/man3c/epoll_wait.3c b/usr/src/man/man3c/epoll_wait.3c index 6405c30b5d..670eebe89c 100644 --- a/usr/src/man/man3c/epoll_wait.3c +++ b/usr/src/man/man3c/epoll_wait.3c @@ -39,7 +39,7 @@ number of milliseconds to wait for an event if none is pending. A \fItimeout\fR of -1 denotes an infinite timeout. The \fBepoll_pwait()\fR is similar to \fBepoll_wait()\fR, but takes an -additional \fIsigmask\fR argument that specifies the desired signal mask +additional \fIsigmask\fR argument that specifies the desired signal mask when \fBepoll_pwait()\fR is blocked. It is equivalent to atomically setting the signal mask, calling \fBepoll_wait()\fR, and restoring the signal mask upon return, and is therefore similar to the relationship @@ -95,7 +95,6 @@ is not greater than zero. .RE .sp -.LP .SH NOTES .sp .LP @@ -105,11 +104,10 @@ compatibility for Linux-borne applications; native applications should continue to prefer using event ports via the \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. -.RE .SH SEE ALSO .sp .LP \fBepoll_create\fR(3C), \fBepoll_ctl\fR(3C), -\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), \fBpselect\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man3c/fgetwc.3c b/usr/src/man/man3c/fgetwc.3c index 8b75c6cc55..6044683813 100644 --- a/usr/src/man/man3c/fgetwc.3c +++ b/usr/src/man/man3c/fgetwc.3c @@ -36,7 +36,7 @@ character (if present) from the input stream pointed to by \fIstream\fR, convert that to the corresponding wide-character code and advance the associated file position indicator for the stream (if defined). Whereas \fBfgetwc()\fR uses the current locale, \fBfgetwc_l()\fR uses the -locale specified by \fIloc\R. +locale specified by \fIloc\fR. .LP If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. diff --git a/usr/src/man/man3c/fopen.3c b/usr/src/man/man3c/fopen.3c index 2eaaf4dd87..0dfdcb4cc0 100644 --- a/usr/src/man/man3c/fopen.3c +++ b/usr/src/man/man3c/fopen.3c @@ -34,7 +34,7 @@ base sequences: .sp .ne 2 .na -\fB\fBr\fR\fR +\fB\fBr\fR\fR .ad .RS 20n Open file for reading. diff --git a/usr/src/man/man3c/iswctype.3c b/usr/src/man/man3c/iswctype.3c index 9da9eef82a..d29414833e 100644 --- a/usr/src/man/man3c/iswctype.3c +++ b/usr/src/man/man3c/iswctype.3c @@ -42,7 +42,7 @@ These functions are defined on and wide-character codes corresponding to the valid character encodings in the current locale (or .I loc -for +for .BR iswctype_l() .) If the .I wc diff --git a/usr/src/man/man3c/mbrtowc.3c b/usr/src/man/man3c/mbrtowc.3c index 55e053570e..60f54b1925 100644 --- a/usr/src/man/man3c/mbrtowc.3c +++ b/usr/src/man/man3c/mbrtowc.3c @@ -81,7 +81,7 @@ is a null pointer, these functions use their own internal .B mbstate_t object, which is initialized at program startup to the -initial conversion state. Otherwise, the +initial conversion state. Otherwise, the .B mbstate_t object pointed to by .I ps diff --git a/usr/src/man/man3c/mbsrtowcs.3c b/usr/src/man/man3c/mbsrtowcs.3c index b645fe4942..f53f871343 100644 --- a/usr/src/man/man3c/mbsrtowcs.3c +++ b/usr/src/man/man3c/mbsrtowcs.3c @@ -135,7 +135,7 @@ The .B mbsnrtowcs() and .B mbsrtowcs() -functions are Standard. The +functions are Standard. The .B mbsnrtowcs_l() and .B mbsrtowcs_l() diff --git a/usr/src/man/man3c/newlocale.3c b/usr/src/man/man3c/newlocale.3c index 7fa9048211..3f0c652d5a 100644 --- a/usr/src/man/man3c/newlocale.3c +++ b/usr/src/man/man3c/newlocale.3c @@ -76,7 +76,7 @@ An alternate name fo the locale "C". Indicates that the locale should be processed based in the values in the environment. See .BR setlocale (3C) -and +and .BR environ (5) for more information. .LP diff --git a/usr/src/man/man3c/strcoll.3c b/usr/src/man/man3c/strcoll.3c index d1a3de385b..2cca905ec2 100644 --- a/usr/src/man/man3c/strcoll.3c +++ b/usr/src/man/man3c/strcoll.3c @@ -69,8 +69,6 @@ collating sequence. .SH FILES .IP \fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_COLLATE/*\fR collation database for \fIlocale\fR -.RE - .SH ATTRIBUTES .LP See \fBattributes\fR(5) for descriptions of the following attributes: diff --git a/usr/src/man/man3c/string.3c b/usr/src/man/man3c/string.3c index cd2dacbedf..4c31ca5f81 100644 --- a/usr/src/man/man3c/string.3c +++ b/usr/src/man/man3c/string.3c @@ -174,7 +174,7 @@ versions of \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below. The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions compare two strings byte-by-byte, after converting each upper-case character to lower-case (as determined by the -\fBLC_CTYPE\fR category of the current locale). Note that neither the contents +\fBLC_CTYPE\fR category of the current locale). Note that neither the contents pointed to by \fIs1\fR nor \fIs2\fR are modified. .LP The functions return an integer diff --git a/usr/src/man/man3c/towlower.3c b/usr/src/man/man3c/towlower.3c index e0024720b4..f642d222a0 100644 --- a/usr/src/man/man3c/towlower.3c +++ b/usr/src/man/man3c/towlower.3c @@ -26,7 +26,7 @@ towlower, towlower_l \- transliterate upper-case wide characters to lower-case .LP .nf \fBwint_t\fR \fBtowlower_l\fR(\fBwint_t\fR \fIwc\fR, \fBlocale_t\fR \fIloc\fR); -.nf +.fi .SH DESCRIPTION The function .BR towlower() diff --git a/usr/src/man/man3c/uselocale.3c b/usr/src/man/man3c/uselocale.3c index ca2d034c6e..a97bfec114 100644 --- a/usr/src/man/man3c/uselocale.3c +++ b/usr/src/man/man3c/uselocale.3c @@ -34,7 +34,7 @@ a thread is created, it uses the global locale as specified by calls to .LP If .BR (locale_t) 0 -is supplied for +is supplied for .IR loc , then no change is made to the thread's locale setting. This can be used to query the thread's locale without making any change. diff --git a/usr/src/man/man3c/wcscoll.3c b/usr/src/man/man3c/wcscoll.3c index f7d88a7519..59f8d18800 100644 --- a/usr/src/man/man3c/wcscoll.3c +++ b/usr/src/man/man3c/wcscoll.3c @@ -50,7 +50,7 @@ integer greater than, equal to, or less than 0, depending upon whether the wide character string pointed to by \fIws1\fR is greater than, equal to, or less than the wide character string pointed to by \fIws2\fR, when both are interpreted as appropriate to the the current locale, or the locale -specified by \fIloc\fR. On error, +specified by \fIloc\fR. On error, they set \fBerrno\fR, but no return value is reserved to indicate an error. .SH ERRORS .LP diff --git a/usr/src/man/man3c/wcsrtombs.3c b/usr/src/man/man3c/wcsrtombs.3c index 4068427f8a..87c6f4c78e 100644 --- a/usr/src/man/man3c/wcsrtombs.3c +++ b/usr/src/man/man3c/wcsrtombs.3c @@ -24,6 +24,7 @@ wcsnrtombs, wcsnrtombs_l, wcsrtombs, wcsrtombs_l \- convert a wide-character str .nf \fBsize_t\fR \fBwcsnrtombs\fR(\fBchar *restrict\fR \fIdst\fR, \fBconst wchar_t **restrict\fR \fIsrc\fR, \fBsize_t\fR \fInwc\fR, \fBsize_t\fR \fIlen\fR, \fBmbstate_t *restrict\fR \fIps\fR); +.fi .LP .nf #include <wchar.h> diff --git a/usr/src/man/man3lib/libc.3lib b/usr/src/man/man3lib/libc.3lib index 8c75f79bfb..ab8eb92f24 100644 --- a/usr/src/man/man3lib/libc.3lib +++ b/usr/src/man/man3lib/libc.3lib @@ -434,7 +434,7 @@ l l . \fBmutex_destroy\fR \fBmutex_init\fR \fBmutex_lock\fR \fBmutex_trylock\fR \fBmutex_unlock\fR \fBnanosleep\fR -\fBnextafter\fR \fBnewlocale\fR +\fBnextafter\fR \fBnewlocale\fR \fBnfs_getfh\fR \fBnftw\fR \fBngettext\fR \fBnice\fR \fBnl_langinfo\fR \fBnl_langinfo_l\fR diff --git a/usr/src/man/man3lib/libvnd.3lib b/usr/src/man/man3lib/libvnd.3lib index a4d47670f0..ead69ff82e 100644 --- a/usr/src/man/man3lib/libvnd.3lib +++ b/usr/src/man/man3lib/libvnd.3lib @@ -527,7 +527,7 @@ property. 27 VND_E_BUFTOOSMALL .ad .RS 23n -requested buffer size is too small +requested buffer size is too small .sp The requested buffer size is less than the minimum buffer size. This generally occurs when making the buffer size less than the maximum @@ -623,7 +623,7 @@ capabilities invalid, pass-through module detected .sp While negotiating capabilities, a pass-through module was detected and the capability had to be discarded. Because of this, the data path could -not be initialized. +not be initialized. .RE diff --git a/usr/src/man/man3vnd/vnd_frameio_read.3vnd b/usr/src/man/man3vnd/vnd_frameio_read.3vnd index df317c7cf3..5fc65c96a3 100644 --- a/usr/src/man/man3vnd/vnd_frameio_read.3vnd +++ b/usr/src/man/man3vnd/vnd_frameio_read.3vnd @@ -46,7 +46,7 @@ with readv(2) and writev(2). vnd_frameio_read performs a framed I/O read of the device represented by the handle vhp, with the framed I/O data described by fiop. vnd_frameio_write works in the same manner, except performing a write -instead of a read. +instead of a read. .LP The basic vector component of the frameio_t is the framevec_t. Each @@ -548,7 +548,7 @@ main(void) /* Do proper memory cleanup */ return (0); } -.nf +.fi .in -2 .LP diff --git a/usr/src/man/man3vnd/vnd_prop_get.3vnd b/usr/src/man/man3vnd/vnd_prop_get.3vnd index 4170a4aca5..e47698c85e 100644 --- a/usr/src/man/man3vnd/vnd_prop_get.3vnd +++ b/usr/src/man/man3vnd/vnd_prop_get.3vnd @@ -44,21 +44,21 @@ libvnd(3LIB) manual page. .SH RETURN VALUES -.LP +.LP On success, the vnd_prop_get and vnd_prop_set functions return zero. On failure, they return -1 and additional error information is available through vnd_errno(3VND) and vnd_syserrno(3VND). -.LP +.LP When vnd_prop_get returns successfully, the contents of buf are filled in with the value of the corresponding property. The contents of buf should not change across a call to vnd_prop_set. .SH EXAMPLES -.LP +.LP Example 1 Getting the value of the rxbuf property -.LP +.LP The following sample C program retrieves the value of the rxbuf property and prints it to standard out. @@ -219,7 +219,6 @@ main(void) vnd_close(vnd); return (0); } -.nf .fi .SH ATTRIBUTES diff --git a/usr/src/man/man3vnd/vnd_prop_iter.3vnd b/usr/src/man/man3vnd/vnd_prop_iter.3vnd index 18485950cf..29221734c5 100644 --- a/usr/src/man/man3vnd/vnd_prop_iter.3vnd +++ b/usr/src/man/man3vnd/vnd_prop_iter.3vnd @@ -63,7 +63,7 @@ instead return one. In the case of library failure, vnd_prop_iter will return -1. In such cases, the vnd and system errors will be updated and available via vnd_errno(3VND) and vnd_syserrno(3VND). -.SHEXAMPLES +.SH EXAMPLES .LP Example 1 Print writeable properties diff --git a/usr/src/man/man3vnd/vnd_walk.3vnd b/usr/src/man/man3vnd/vnd_walk.3vnd index 0c7197f656..bed53130d3 100644 --- a/usr/src/man/man3vnd/vnd_walk.3vnd +++ b/usr/src/man/man3vnd/vnd_walk.3vnd @@ -87,7 +87,7 @@ top of. .LP The vnd_walk function will return zero on success. If the consumer supplied callback function returned non-zero, then the vnd_walk -function will return 1. If an error occurred, -1 is returned, and if +function will return 1. If an error occurred, -1 is returned, and if vnderr and syserr are non-null, they are filled in with their respective error values. See vnd_errno(3VND) for more information on these errors. diff --git a/usr/src/man/man4/init.4 b/usr/src/man/man4/init.4 index c9f301a8c0..ffc17dad95 100644 --- a/usr/src/man/man4/init.4 +++ b/usr/src/man/man4/init.4 @@ -5,7 +5,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH init 4 "Mar 15, 2014" +.TH INIT 4 "Mar 15, 2014" .SH NAME init \- set default system time zone and locale .SH SYNOPSIS @@ -25,7 +25,7 @@ locale-related environment variables \fBLANG\fR, \fBLC_COLLATE\fR, .LP \fB/etc/TIMEZONE\fR is a symbolic link to \fB/etc/default/init\fR. This link exists for compatibility with legacy software, is obsolete, and may -be removed in a future release. +be removed in a future release. .sp .LP The number of environment variables that can be set from diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile index 8e805da008..1b54ca3a30 100644 --- a/usr/src/man/man5/Makefile +++ b/usr/src/man/man5/Makefile @@ -13,6 +13,7 @@ # Copyright 2011, Richard Lowe # Copyright (c) 2012 by Delphix. All rights reserved. # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2014 Garrett D'Amore <garrett@damore.org> # Copyright (c) 2014, Joyent, Inc. All rights reserved. # @@ -43,6 +44,7 @@ MANFILES= Intro.5 \ dhcp_modules.5 \ environ.5 \ epoll.5 \ + eqn.5 \ eqnchar.5 \ extendedFILE.5 \ filesystem.5 \ @@ -66,7 +68,9 @@ MANFILES= Intro.5 \ lfcompile64.5 \ locale.5 \ man.5 \ - mansun.5 \ + mandoc_char.5 \ + mandoc_roff.5 \ + mdoc.5 \ me.5 \ mech_spnego.5 \ mm.5 \ @@ -112,6 +116,7 @@ MANFILES= Intro.5 \ smf_template.5 \ standards.5 \ sticky.5 \ + tbl.5 \ tecla.5 \ term.5 \ threads.5 \ diff --git a/usr/src/man/man5/epoll.5 b/usr/src/man/man5/epoll.5 index bba13e15d2..94314861d9 100644 --- a/usr/src/man/man5/epoll.5 +++ b/usr/src/man/man5/epoll.5 @@ -10,7 +10,7 @@ .\" http://www.illumos.org/license/CDDL. .TH EPOLL 5 "Apr 17, 2014" .SH NAME -epoll \- Linux-compatible I/O event notification facility +epoll \- Linux-compatible I/O event notification facility .SH SYNOPSIS .LP @@ -22,7 +22,7 @@ epoll \- Linux-compatible I/O event notification facility .sp .LP -\fBepoll\fR is a facility for efficient event-oriented I/O that has a +\fBepoll\fR is a facility for efficient event-oriented I/O that has a similar model to \fBpoll\fR(2), but does not necessitate rescanning a set of file descriptors to wait for an event. \fBepoll\fR is of Linux origins, and this facility is designed to be binary-compatible with @@ -70,7 +70,6 @@ to waiting for events. .RE .sp -.LP .SH NOTES .sp .LP @@ -79,14 +78,14 @@ The \fBepoll\fR facility is implemented for purposes of offering compatibility to and portability of Linux-borne applications; native applications should continue to prefer using event ports via the \fBport_create\fR(3C), -\fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces. +\fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces. In particular, use of \fBepoll\fR in a multithreaded environment is fraught with peril; even when using \fBEPOLLONESHOT\fR for one-shot events, there are race conditions with respect to \fBclose\fR(2) that are unresolvable. (For more details, see the aborted effort in Linux to resolve this via the proposed \fBEPOLL_CTL_DISABLE\fR operation.) -The event port facility -- like the BSD kqueue facility that inspired it -- +The event port facility -- like the BSD kqueue facility that inspired it -- is designed to deal with such issues via explicit event source dissociation. While a best effort has been made to mimic the Linux semantics, there @@ -100,16 +99,15 @@ any events generated in the child on the implicitly duplicated file descriptor will continue to be delivered to the parent -- despite the fact that the parent itself no longer has any notion of the file description! This \fBepoll\fR facility refuses to honor -these semantics; closing the \fBEPOLL_CTL_ADD\fR'd file descriptor +these semantics; closing the \fBEPOLL_CTL_ADD\fR'd file descriptor will always result in no further events being generated for that event description. -.RE .SH SEE ALSO .sp .LP \fBepoll_create\fR(3C), \fBepoll_create1\fR(3C), \fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll_pwait\fR(3C), \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_dissociate\fR(3C), -\fBport_get\fR(3C), +\fBport_get\fR(3C), \fBpselect\fR(3C) diff --git a/usr/src/man/man5/eqn.5 b/usr/src/man/man5/eqn.5 new file mode 100644 index 0000000000..cb25ee2759 --- /dev/null +++ b/usr/src/man/man5/eqn.5 @@ -0,0 +1,297 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" +.Dd Jul 19, 2014 +.Dt EQN 5 +.Os +.Sh NAME +.Nm eqn +.Nd eqn language reference for mandoc +.Sh DESCRIPTION +The +.Nm eqn +language is an equation-formatting language. +It is used within +.Xr mdoc 5 +and +.Xr man 5 +.Ux +manual pages. +It describes the +.Em structure +of an equation, not its mathematical meaning. +This manual describes the +.Nm +language accepted by the +.Xr mandoc 1 +utility, which corresponds to the Second Edition eqn specification (see +.Sx SEE ALSO +for references). +.Pp +Equations within +.Xr mdoc 5 +or +.Xr man 5 +documents are enclosed by the standalone +.Sq \&.EQ +and +.Sq \&.EN +tags. +Equations are multi-line blocks consisting of formulas and control +statements. +.Sh EQUATION STRUCTURE +Each equation is bracketed by +.Sq \&.EQ +and +.Sq \&.EN +strings. +.Em Note : +these are not the same as +.Xr roff 5 +macros, and may only be invoked as +.Sq \&.EQ . +.Pp +The equation grammar is as follows, where quoted strings are +case-sensitive literals in the input: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | \*q{\*q eqn \*q}\*q + | \*qdefine\*q text text + | \*qndefine\*q text text + | \*qtdefine\*q text text + | \*qgfont\*q text + | \*qgsize\*q text + | \*qset\*q text text + | \*qundef\*q text + | box pos box + | box mark + | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]* + | pile \*q{\*q list \*q}\*q + | font box + | \*qsize\*q text box + | \*qleft\*q text eqn [\*qright\*q text] +col : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q +text : [^space\e\*q]+ | \e\*q.*\e\*q +pile : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q +pos : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q +mark : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q + | \*qdyad\*q | \*qbar\*q | \*qunder\*q +font : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q +list : eqn + | list \*qabove\*q eqn +space : [\e^~ \et] +.Ed +.Pp +White-space consists of the space, tab, circumflex, and tilde +characters. +If within a quoted string, these space characters are retained. +Quoted strings are also not scanned for replacement definitions. +.Pp +The following text terms are translated into a rendered glyph, if +available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, +lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, +upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, +THETA, UPSILON, XI, inter (intersection), union (union), prod (product), +int (integral), sum (summation), grad (gradient), del (vector +differential), times (multiply), cdot (centre-dot), nothing (zero-width +space), approx (approximately equals), prime (prime), half (one-half), +partial (partial differential), inf (infinity), >> (much greater), << +(much less), \-> (left arrow), <\- (right arrow), += (plus-minus), != +(not equal), == (equivalence), <= (less-than-equal), and >= +(more-than-equal). +.Pp +The following control statements are available: +.Bl -tag -width Ds +.It Cm define +Replace all occurrences of a key with a value. +Its syntax is as follows: +.Pp +.D1 define Ar key cvalc +.Pp +The first character of the value string, +.Ar c , +is used as the delimiter for the value +.Ar val . +This allows for arbitrary enclosure of terms (not just quotes), such as +.Pp +.D1 define Ar foo 'bar baz' +.D1 define Ar foo cbar bazc +.Pp +It is an error to have an empty +.Ar key +or +.Ar val . +Note that a quoted +.Ar key +causes errors in some +.Nm +implementations and should not be considered portable. +It is not expanded for replacements. +Definitions may refer to other definitions; these are evaluated +recursively when text replacement occurs and not when the definition is +created. +.Pp +Definitions can create arbitrary strings, for example, the following is +a legal construction. +.Bd -literal -offset indent +define foo 'define' +foo bar 'baz' +.Ed +.Pp +Self-referencing definitions will raise an error. +The +.Cm ndefine +statement is a synonym for +.Cm define , +while +.Cm tdefine +is discarded. +.It Cm gfont +Set the default font of subsequent output. +Its syntax is as follows: +.Pp +.D1 gfont Ar font +.Pp +In +.Xr mandoc 1 , +this value is discarded. +.It Cm gsize +Set the default size of subsequent output. +Its syntax is as follows: +.Pp +.D1 gsize Ar size +.Pp +The +.Ar size +value should be an integer. +.It Cm set +Set an equation mode. +In +.Xr mandoc 1 , +both arguments are thrown away. +Its syntax is as follows: +.Pp +.D1 set Ar key val +.Pp +The +.Ar key +and +.Ar val +are not expanded for replacements. +This statement is a GNU extension. +.It Cm undef +Unset a previously-defined key. +Its syntax is as follows: +.Pp +.D1 define Ar key +.Pp +Once invoked, the definition for +.Ar key +is discarded. +The +.Ar key +is not expanded for replacements. +This statement is a GNU extension. +.El +.Sh COMPATIBILITY +This section documents the compatibility of +.Xr mandoc 1 +.Nm +and the +.Xr troff 1 +.Nm +implementation (including GNU troff). +.Pp +.Bl -dash -compact +.It +The text string +.Sq \e\*q +is interpreted as a literal quote in +.Xr troff 1 . +In +.Xr mandoc 1 , +this is interpreted as a comment. +.It +In +.Xr troff 1 , +The circumflex and tilde white-space symbols map to +fixed-width spaces. +In +.Xr mandoc 1 , +these characters are synonyms for the space character. +.It +The +.Xr troff 1 , +implementation of +.Nm +allows for equation alignment with the +.Cm mark +and +.Cm lineup +tokens. +.Xr mandoc 1 +discards these tokens. +The +.Cm back Ar n , +.Cm fwd Ar n , +.Cm up Ar n , +and +.Cm down Ar n +commands are also ignored. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 5 , +.Xr mandoc_char 5 , +.Xr mdoc 5 , +.Xr roff 5 +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T System for Typesetting Mathematics +.%J Communications of the ACM +.%V 18 +.%P 151\(en157 +.%D March, 1975 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide +.%D 1976 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide (Second Edition) +.%D 1978 +.Re +.Sh HISTORY +The eqn utility, a preprocessor for troff, was originally written by +Brian W. Kernighan and Lorinda L. Cherry in 1975. +The GNU reimplementation of eqn, part of the GNU troff package, was +released in 1989 by James Clark. +The eqn component of +.Xr mandoc 1 +was added in 2011. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/usr/src/man/man5/man.5 b/usr/src/man/man5/man.5 index 291c439895..819a68bdb7 100644 --- a/usr/src/man/man5/man.5 +++ b/usr/src/man/man5/man.5 @@ -1,342 +1,254 @@ -'\" te +.\" Copryight 2014 Garrett D'Amore <garrett@damore.org> .\" Copyright (c) 1995, Sun Microsystems, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MAN 5 "Jan 30, 1995" -.SH NAME -man \- macros to format Reference Manual pages -.SH SYNOPSIS -.LP -.nf -\fBnroff\fR \fB-man\fR \fIfilename\fR... -.fi - -.LP -.nf -\fBtroff\fR \fB-man\fR \fIfilename\fR... -.fi - -.SH DESCRIPTION -.sp -.LP +.Dd "Jul 19, 2014" +.Dt MAN 5 +.Os +.Sh NAME +.Nm man +.Nd macros to format Reference Manual pages +.Sh SYNOPSIS +.Nm mandoc +.Fl T Ar man +.Ar +.Nm nroff +.Fl man +.Ar +.Nm troff +.Fl man +.Ar +.Sh DESCRIPTION These macros are used to lay out the reference pages in this manual. Note: if -\fIfilename\fR contains format input for a preprocessor, the commands shown +.Ar file +contains format input for a preprocessor, the commands shown above must be piped through the appropriate preprocessor. This is handled -automatically by the \fBman\fR(1) command. See the ``Conventions'' section. -.sp -.LP -Any text argument \fIt\fR may be zero to six words. Quotes may be used to -include SPACE characters in a "word". If \fItext\fR is empty, the special +automatically by the +.Xr man 1 +command. See the +.Sx Conventions +section. +.Lp +Any text argument +.Ar t +may be zero to six words. Quotes may be used to +include SPACE characters in a +.Qq word . +If +.Ar text +is empty, the special treatment is applied to the next input line with text to be printed. In this -way \fB\&.I\fR may be used to italicize a whole line, or \fB\&.SB\fR may be -used to make small bold letters. -.sp -.LP +way +.Nm \&.I +may be used to italicize a whole line, or +.Nm \&.SB +may be used to make small bold letters. +.Lp A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default value upon reaching a non-indented -paragraph. Default units for indents \fIi\fR are ens. -.sp -.LP +paragraph. Default units for indents +.Nm i +are ens. +.Lp Type font and size are reset to default values before each paragraph, and after processing font and size setting macros. -.sp -.LP -These strings are predefined by \fB-man\fR: -.sp -.ne 2 -.na -\fB\fB\e*R\fR\fR -.ad -.RS 8n -`\(rg', `(Reg)' in \fBnroff\fR. -.RE - -.sp -.ne 2 -.na -\fB\fB\e*S\fR\fR -.ad -.RS 8n +.Pp +These strings are predefined by +.Nm -man : +.Bl -tag -width Ds +.It Nm \e*R +.Sq \(rg , +.Sq (Reg) +in +.Nm nroff . +.It Nm \e*S Change to default type size. -.RE - -.SS "Requests" -.sp -.LP +.El +.Sh "Requests" * n.t.l. = next text line; p.i. = prevailing indent -.sp - -.sp -.TS -c c c c -c c c c . -\fIRequest\fR \fICause\fR \fIIf no\fR \fIExplanation\fR - \fIBreak\fR \fIArgument\fR -\fB\&.B \fR\fIt\fR no \fIt\fR=n.t.l.* Text is in bold font. -\fB\&.BI \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating bold and italic. -\fB\&.BR \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating bold and roman. -\fB\&.DT\fR no \&.5i 1i... Restore default tabs. -\fB\&.HP \fR\fIi\fR yes \fIi\fR=p.i.* T{ -Begin paragraph with hanging indent. Set prevailing indent to \fIi\fR. -T} -\fB\&.I \fR\fIt\fR no \fIt\fR=n.t.l. Text is italic. -\fB\&.IB \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating italic and bold. -\fB\&.IP \fR\fIx i\fR yes \fIx\fR="" Same as \fB\&.TP\fR with tag \fIx\fR. -\fB\&.IR \fR\fIt\fR no \fIt\fR=n.t.l. T{ -Join words, alternating italic and roman. -T} -\fB\&.IX \fR\fIt\fR no - Index macro, for SunSoft internal use. -\fB\&.LP\fR yes - T{ -Begin left-aligned paragraph. Set prevailing indent to .5i. -T} -\fB\&.P\fR yes - Same as \fB\&.LP\fR. -\fB\&.PD \fR\fId\fR no \fId\fR=.4v T{ -Set vertical distance between paragraphs. -T} -\fB\&.PP\fR yes - Same as \fB\&.LP\fR. -\fB\&.RE\fR yes - T{ -End of relative indent. Restores prevailing indent. -T} -\fB\&.RB \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating roman and bold. -\fB\&.RI \fR\fIt\fR no \fIt\fR=n.t.l. T{ -Join words, alternating roman and italic. -T} -\fB\&.RS \fR\fIi\fR yes \fIi\fR=p.i. T{ -Start relative indent, increase indent by \fIi\fR. Sets prevailing indent to .5i for nested indents. -T} -\fB\&.SB \fR\fIt\fR no - T{ -Reduce size of text by 1 point, make text bold. -T} -\fB\&.SH \fR\fIt\fR yes - Section Heading. -\fB\&.SM \fR\fIt\fR no \fIt\fR=n.t.l. Reduce size of text by 1 point. -\fB\&.SS \fR\fIt\fR yes \fIt\fR=n.t.l. Section Subheading. -\fB\&.TH \FR\FIN S "f d, m\fR" -\fB\&.TH \fR\fIn s d f m\fR yes - T{ -Begin reference page \fIn\fR, of of section \fIs\fR; \fId\fR is the date of the most recent change. If present, \fIf\fR is the left page footer; \fIm\fR is the main page (center) header. Sets prevailing indent and tabs to .5i. -T} -\fB\&.TP \fR\fIi\fR yes \fIi\fR=p.i. T{ -Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to \fIi\fR. -T} -\fB\&.TX \fR\fIt \fR\fIp\fR no - T{ -Resolve the title abbreviation \fIt\fR; join to punctuation mark (or text) \fIp\fR. -T} -.TE - -.SS "Conventions" -.sp -.LP -When formatting a manual page, \fBman\fR examines the first line to determine +.Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds +.It Sy Request Sy Cause Sy "If No" Sy Explanation +.It "" Sy Break Sy "Argument" "" +.It Nm \&.B Ar "t" no Ar t Ns =n.t.l.* Text is in bold font. +.It Nm \&.BI Ar t no Ar t Ns =n.t.l. Join words, alternating bold and italic. +.It Nm \&.BR Ar t no Ar t Ns =n.t.l. Join words, alternating bold and roman. +.It Nm \&.DT no Li \&.5i 1i... Restore default tabs. +.It Nm \&.HP Ar i yes Ar i Ns =p.i.* "Begin paragraph with hanging indent. Set prevailing indent to" Ar i . +.It Nm \&.I Ar t no Ar t Ns =n.t.l. Text is italic. +.It Nm \&.IB Ar t no Ar t Ns =n.t.l. Join words, altenrating italic and bold. +.It Nm \&.IP Ar x Ar i yes Ar x Ns ="" Same as +.Nm \&.TP +with tag +.Ar x . +.It Nm \&.IR Ar t no Ar t Ns =n.t.l. Join words, alternating italic and roman. +.It Nm \&.IX Ar t no - Index macro, not used (obsolete). +.It Nm \&.LP yes - Begin left-aligned paragraph. Set prevailing indent to .5i. +.It Nm \&.P yes - Same as +.Nm \&.LP . +.It Nm \&.PD Ar d no Ar d Ns =.4v Set vertical distance between paragraphs. +.It Nm \&.PP yes - Same as +.Nm \&.LP . +.It Nm \&.RE yes - End of relative indent. Restores prevailing indent. +.It Nm \&.RB Ar t no Ar t Ns =n.t.l. Join words, alternating roman and bold. +.It Nm \&.RI Ar t no Ar t Ns =n.t.l. Join words, alternating roman and italic. +.It Nm \&.RS Ar i yes Ar i Ns =p.i. Start relative indent, increase indent by Ar i . +Sets prevailing indent to .5i for nested indents. +.It Nm \&.SB Ar t no - Reduce size of text by 1 point, make text bold. +.It Nm \&.SH Ar t yes - Section Heading. +.It Nm \&.SM Ar t no Ar t Ns =n.t.l. Reduce size of text by 1 point. +.It Nm \&.SS Ar t yes Ar t Ns =n.t.l. Section Subheading. +.It Nm \&.TH Ar n s d f m yes - Begin reference page Ar n , No of section Ar s ; Ar d No is the date of the most recent change. If present, Ar f No is the left page footer; Ar m No is the main page (center) header. Sets prevailing indent and tabs to .5i. +.It Nm \&.TP Ar i yes Ar i Ns =p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to +.Ar i . +.It Nm \&.TX Ar t p no - Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p . +.El +.Ss "Conventions" +When formatting a manual page, +.Nm +examines the first line to determine whether it requires special processing. For example a first line consisting of: -.sp -.LP -\fB\&'\e" t\fR -.sp -.LP -indicates that the manual page must be run through the \fBtbl\fR(1) +.Lp +.Dl \&'\e" t +.Lp +indicates that the manual page must be run through the +.Xr tbl 1 preprocessor. -.sp -.LP +.Lp A typical manual page for a command or function is laid out as follows: -.sp -.ne 2 -.na -\fB\&.TH\fI TITLE \FR[1-9]\FR " , " -.ad -.RS 23n +.Bl -tag -width ".SH RETURN VALUES" +. +.It Nm \&.TH Ar title Op "1-9" +. The name of the command or function, which serves as the title of the manual page. This is followed by the number of the section in which it appears. -.RE - -.sp -.ne 2 -.na -\fB\&.SH NAME\fR -.ad -.RS 23n +. +.It Nm SH NAME +. The name, or list of names, by which the command is called, followed by a dash and then a one-line summary of the action performed. All in roman font, this -section contains no \fBtroff\fR(1) commands or escapes, and no macro requests. -It is used to generate the \fBwindex\fR database, which is used by the -\fBwhatis\fR(1) command. -.RE - -.sp -.ne 2 -.na -\fB\&.SH SYNOPSIS\fR -.ad -.RS 23n -.sp -.ne 2 -.na -\fBCommands:\fR -.ad -.RS 13n +section contains no +.Xr troff 1 +commands or escapes, and no macro requests. +It is used to generate the database used by the +.Xr whatis 1 +command. +. +.It Nm SH SYNOPSIS +.Bl -tag -width "Functions:" +.It Sy Commands: The syntax of the command and its arguments, as typed on the command line. When in boldface, a word must be typed exactly as printed. When in italics, a word can be replaced with an argument that you supply. References to bold or italicized items are not capitalized in other sections, even when they begin a sentence. -.sp +.Lp Syntactic symbols appear in roman face: -.sp -.ne 2 -.na -\fB[ ]\fR -.ad -.RS 13n +.Bl -tag -width " " +.It Op " " An argument, when surrounded by brackets is optional. -.RE - -.sp -.ne 2 -.na -\fB|\fR -.ad -.RS 13n +.It | Arguments separated by a vertical bar are exclusive. You can supply only one item from such a list. -.RE - -.sp -.ne 2 -.na -\fB\&.\|.\|.\fR -.ad -.RS 13n +.It \&.\|.\|. Arguments followed by an ellipsis can be repeated. When an ellipsis follows a bracketed set, the expression within the brackets can be repeated. -.RE - -.RE - -.sp -.ne 2 -.na -\fBFunctions:\fR -.ad -.RS 14n -If required, the data declaration, or \fB#include\fR directive, is shown first, +.El +.It Sy Functions: +If required, the data declaration, or +.Li #include +directive, is shown first, followed by the function declaration. Otherwise, the function declaration is shown. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\&.SH DESCRIPTION\fR -.ad -.RS 23n +.El +. +.It Nm \&.SH DESCRIPTION +. A narrative overview of the command or function's external behavior. This includes how it interacts with files or data, and how it handles the standard input, standard output and standard error. Internals and implementation details are normally omitted. This section attempts to provide a succinct overview in answer to the question, "what does it do?" -.sp +.Lp Literal text from the synopsis appears in constant width, as do literal filenames and references to items that appear elsewhere in the reference manuals. Arguments are italicized. -.sp +.Lp If a command interprets either subcommands or an input grammar, its command -interface or input grammar is normally described in a \fBUSAGE\fR section, -which follows the \fBOPTIONS\fR section. The \fBDESCRIPTION\fR section only +interface or input grammar is normally described in a +.Nm USAGE +section, which follows the +.Nm OPTIONS +section. The +.Nm DESCRIPTION +section only describes the behavior of the command itself, not that of subcommands. -.RE - -.sp -.ne 2 -.na -\fB\&.SH OPTIONS\fR -.ad -.RS 23n +. +.It Nm \&.SH OPTIONS +. The list of options along with a description of how each affects the command's operation. -.RE - -.sp -.ne 2 -.na -\fB\&.SH RETURN VALUES\fR -.ad -.RS 23n +. +.It Nm \&.SH RETURN VALUES +. A list of the values the library routine will return to the calling program and the conditions that cause these values to be returned. -.RE - -.sp -.ne 2 -.na -\fB\&.SH EXIT STATUS\fR -.ad -.RS 23n +. +.It Nm \&.SH EXIT STATUS +. A list of the values the utility will return to the calling program or shell, and the conditions that cause these values to be returned. -.RE - -.sp -.ne 2 -.na -\fB\&.SH FILES\fR -.ad -.RS 23n +. +.It Nm \&.SH FILES +. A list of files associated with the command or function. -.RE - -.sp -.ne 2 -.na -\fB\&.SH SEE ALSO\fR -.ad -.RS 23n +. +.It Nm \&.SH SEE ALSO +. A comma-separated list of related manual pages, followed by references to other published materials. -.RE - -.sp -.ne 2 -.na -\fB\&.SH DIAGNOSTICS\fR -.ad -.RS 23n +. +.It Nm \&.SH DIAGNOSTICS +. A list of diagnostic messages and an explanation of each. -.RE - -.sp -.ne 2 -.na -\fB\&.SH BUGS\fR -.ad -.RS 23n +. +.It Nm \&.SH BUGS +. A description of limitations, known defects, and possible problems associated with the command or function. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/share/lib/tmac/an\fR \fR -.ad -.RS 27n - -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/share/man/windex\fR\fR -.ad -.RS 27n - -.RE - -.SH SEE ALSO -.sp -.LP -\fBman\fR(1), \fBnroff\fR(1), \fBtroff\fR(1), \fBwhatis\fR(1) -.sp -.LP -Dale Dougherty and Tim O'Reilly, \fIUnix\fR \fIText\fR \fIProcessing\fR +.El +.Sh FILES +.Pa /usr/share/man/whatis +.Sh NOTES +The +.Nm +package should not be used for new documentation. The +.Xr mdoc 5 , +package is preferred, as it uses semantic markup rather than physical markup. +.Sh CODE SET INDEPENDENCE +When processed with +.Xr mandoc 1 , +this package is Code Set Independent. However, when processed with +legacy tools such as +.Xr nroff 1 +and +.Xr troff 1 , +the use of multi-byte characters may not be supported. +.Sh INTERFACE STABILITY +.Nm Obsolete Committed . +The +.Xr mdoc 5 +package should be used instead. +.Sh SEE ALSO +.Xr eqn 1 , +.Xr man 1 , +.Xr mandoc 1 , +.Xr nroff 1 , +.Xr troff 1 , +.Xr tbl 1 , +.Xr whatis 1 , +.Xr mdoc 5 , +.Rs +.%A Dale Dougherty and Tim O'Reilly +.%B Unix Text Processing +.Re diff --git a/usr/src/man/man5/mandoc_char.5 b/usr/src/man/man5/mandoc_char.5 new file mode 100644 index 0000000000..15b421474d --- /dev/null +++ b/usr/src/man/man5/mandoc_char.5 @@ -0,0 +1,744 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org> +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" +.Dd Nov 23, 2011 +.Dt MANDOC_CHAR 5 +.Os +.Sh NAME +.Nm mandoc_char +.Nd mandoc special characters +.Sh DESCRIPTION +This page documents the +.Xr roff 5 +escape sequences accepted by +.Xr mandoc 1 +to represent special characters in +.Xr mdoc 5 +and +.Xr man 5 +documents. +.Pp +The rendering depends on the +.Xr mandoc 1 +output mode; in ASCII output, most characters are completely +unintelligible. +For that reason, using any of the special characters documented here, +except those discussed in the +.Sx DESCRIPTION , +is strongly discouraged; they are supported merely for backwards +compatibility with existing documents. +.Pp +In particular, in English manual pages, do not use special-character +escape sequences to represent national language characters in author +names; instead, provide ASCII transcriptions of the names. +.Ss Dashes and Hyphens +In typography there are different types of dashes of various width: +the hyphen (-), +the minus sign (\-), +the en-dash (\(en), +and the em-dash (\(em). +.Pp +Hyphens are used for adjectives; +to separate the two parts of a compound word; +or to separate a word across two successive lines of text. +The hyphen does not need to be escaped: +.Bd -unfilled -offset indent +blue-eyed +lorry-driver +.Ed +.Pp +The mathematical minus sign is used for negative numbers or subtraction. +It should be written as +.Sq \e- : +.Bd -unfilled -offset indent +a = 3 \e- 1; +b = \e-2; +.Ed +.Pp +The en-dash is used to separate the two elements of a range, +or can be used the same way as an em-dash. +It should be written as +.Sq \e(en : +.Bd -unfilled -offset indent +pp. 95\e(en97. +Go away \e(en or else! +.Ed +.Pp +The em-dash can be used to show an interruption +or can be used the same way as colons, semi-colons, or parentheses. +It should be written as +.Sq \e(em : +.Bd -unfilled -offset indent +Three things \e(em apples, oranges, and bananas. +This is not that \e(em rather, this is that. +.Ed +.Pp +Note: +hyphens, minus signs, and en-dashes look identical under normal ASCII output. +Other formats, such as PostScript, render them correctly, +with differing widths. +.Ss Spaces +To separate words in normal text, for indenting and alignment +in literal context, and when none of the following special cases apply, +just use the normal space character +.Pq Sq \ . +.Pp +When filling text, lines may be broken between words, i.e. at space +characters. +To prevent a line break between two particular words, +use the non-breaking space escape sequence +.Pq Sq \e~ +instead of the normal space character. +For example, the input string +.Dq number\e~1 +will be kept together as +.Dq number\~1 +on the same output line. +.Pp +On request and macro lines, the normal space character serves as an +argument delimiter. +To include whitespace into arguments, quoting is usually the best choice. +In some cases, using either the non-breaking +.Pq Sq \e~ +or the breaking +.Pq Sq \e\ \& +space escape sequence may be preferable. +To escape macro names and to protect whitespace at the end +of input lines, the zero-width space +.Pq Sq \e& +is often useful. +For example, in +.Xr mdoc 5 , +a normal space character can be displayed in single quotes in either +of the following ways: +.Pp +.Dl .Sq \(dq \(dq +.Dl .Sq \e \e& +.Ss Quotes +On request and macro lines, the double-quote character +.Pq Sq \(dq +is handled specially to allow quoting. +One way to prevent this special handling is by using the +.Sq \e(dq +escape sequence. +.Pp +Note that on text lines, literal double-quote characters can be used +verbatim. +All other quote-like characters can be used verbatim as well, +even on request and macro lines. +.Ss Periods +The period +.Pq Sq \&. +is handled specially at the beginning of an input line, +where it introduces a +.Xr roff 5 +request or a macro, and when appearing alone as a macro argument in +.Xr mdoc 5 . +In such situations, prepend a zero-width space +.Pq Sq \e&. +to make it behave like normal text. +.Pp +Do not use the +.Sq \e. +escape sequence. +It does not prevent special handling of the period. +.Ss Backslashes +To include a literal backslash +.Pq Sq \e +into the output, use the +.Pq Sq \ee +escape sequence. +.Pp +Note that doubling it +.Pq Sq \e\e +is not the right way to output a backslash. +Because +.Xr mandoc 1 +does not implement full +.Xr roff 5 +functionality, it may work with +.Xr mandoc 1 , +but it may have weird effects on complete +.Xr roff 5 +implementations. +.Sh SPECIAL CHARACTERS +Special characters are encoded as +.Sq \eX +.Pq for a one-character escape , +.Sq \e(XX +.Pq two-character , +and +.Sq \e[N] +.Pq N-character . +For details, see the +.Em Special Characters +subsection of the +.Xr roff 5 +manual. +.Pp +Spacing: +.Bl -column "Input" "Description" -offset indent -compact +.It Em Input Ta Em Description +.It \e~ Ta non-breaking, non-collapsing space +.It \e Ta breaking, non-collapsing n-width space +.It \e^ Ta zero-width space +.It \e% Ta zero-width space +.It \e& Ta zero-width space +.It \e| Ta zero-width space +.It \e0 Ta breaking, non-collapsing digit-width space +.It \ec Ta removes any trailing space (if applicable) +.El +.Pp +Lines: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ba Ta \(ba Ta bar +.It \e(br Ta \(br Ta box rule +.It \e(ul Ta \(ul Ta underscore +.It \e(rl Ta \(rl Ta overline +.It \e(bb Ta \(bb Ta broken bar +.It \e(sl Ta \(sl Ta forward slash +.It \e(rs Ta \(rs Ta backward slash +.El +.Pp +Text markers: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ci Ta \(ci Ta circle +.It \e(bu Ta \(bu Ta bullet +.It \e(dd Ta \(dd Ta double dagger +.It \e(dg Ta \(dg Ta dagger +.It \e(lz Ta \(lz Ta lozenge +.It \e(sq Ta \(sq Ta white square +.It \e(ps Ta \(ps Ta paragraph +.It \e(sc Ta \(sc Ta section +.It \e(lh Ta \(lh Ta left hand +.It \e(rh Ta \(rh Ta right hand +.It \e(at Ta \(at Ta at +.It \e(sh Ta \(sh Ta hash (pound) +.It \e(CR Ta \(CR Ta carriage return +.It \e(OK Ta \(OK Ta check mark +.El +.Pp +Legal symbols: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(co Ta \(co Ta copyright +.It \e(rg Ta \(rg Ta registered +.It \e(tm Ta \(tm Ta trademarked +.El +.Pp +Punctuation: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(em Ta \(em Ta em-dash +.It \e(en Ta \(en Ta en-dash +.It \e(hy Ta \(hy Ta hyphen +.It \ee Ta \e Ta back-slash +.It \e. Ta \. Ta period +.It \e(r! Ta \(r! Ta upside-down exclamation +.It \e(r? Ta \(r? Ta upside-down question +.El +.Pp +Quotes: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Bq Ta \(Bq Ta right low double-quote +.It \e(bq Ta \(bq Ta right low single-quote +.It \e(lq Ta \(lq Ta left double-quote +.It \e(rq Ta \(rq Ta right double-quote +.It \e(oq Ta \(oq Ta left single-quote +.It \e(cq Ta \(cq Ta right single-quote +.It \e(aq Ta \(aq Ta apostrophe quote (text) +.It \e(dq Ta \(dq Ta double quote (text) +.It \e(Fo Ta \(Fo Ta left guillemet +.It \e(Fc Ta \(Fc Ta right guillemet +.It \e(fo Ta \(fo Ta left single guillemet +.It \e(fc Ta \(fc Ta right single guillemet +.El +.Pp +Brackets: +.Bl -column "xxbracketrightbpx" Rendered Description -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(lB Ta \(lB Ta left bracket +.It \e(rB Ta \(rB Ta right bracket +.It \e(lC Ta \(lC Ta left brace +.It \e(rC Ta \(rC Ta right brace +.It \e(la Ta \(la Ta left angle +.It \e(ra Ta \(ra Ta right angle +.It \e(bv Ta \(bv Ta brace extension +.It \e[braceex] Ta \[braceex] Ta brace extension +.It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket +.It \e[bracketleftbp] Ta \[bracketleftbp] Ta bottom-left hooked bracket +.It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension +.It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket +.It \e[bracketrightbp] Ta \[bracketrightbp] Ta bottom-right hooked bracket +.It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension +.It \e(lt Ta \(lt Ta top-left hooked brace +.It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace +.It \e(lk Ta \(lk Ta mid-left hooked brace +.It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace +.It \e(lb Ta \(lb Ta bottom-left hooked brace +.It \e[braceleftbp] Ta \[braceleftbp] Ta bottom-left hooked brace +.It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension +.It \e(rt Ta \(rt Ta top-left hooked brace +.It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace +.It \e(rk Ta \(rk Ta mid-right hooked brace +.It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace +.It \e(rb Ta \(rb Ta bottom-right hooked brace +.It \e[bracerightbp] Ta \[bracerightbp] Ta bottom-right hooked brace +.It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension +.It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis +.It \e[parenleftbp] Ta \[parenleftbp] Ta bottom-left hooked parenthesis +.It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension +.It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis +.It \e[parenrightbp] Ta \[parenrightbp] Ta bottom-right hooked parenthesis +.It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension +.El +.Pp +Arrows: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(<- Ta \(<- Ta left arrow +.It \e(-> Ta \(-> Ta right arrow +.It \e(<> Ta \(<> Ta left-right arrow +.It \e(da Ta \(da Ta down arrow +.It \e(ua Ta \(ua Ta up arrow +.It \e(va Ta \(va Ta up-down arrow +.It \e(lA Ta \(lA Ta left double-arrow +.It \e(rA Ta \(rA Ta right double-arrow +.It \e(hA Ta \(hA Ta left-right double-arrow +.It \e(uA Ta \(uA Ta up double-arrow +.It \e(dA Ta \(dA Ta down double-arrow +.It \e(vA Ta \(vA Ta up-down double-arrow +.El +.Pp +Logical: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(AN Ta \(AN Ta logical and +.It \e(OR Ta \(OR Ta logical or +.It \e(no Ta \(no Ta logical not +.It \e[tno] Ta \[tno] Ta logical not (text) +.It \e(te Ta \(te Ta existential quantifier +.It \e(fa Ta \(fa Ta universal quantifier +.It \e(st Ta \(st Ta such that +.It \e(tf Ta \(tf Ta therefore +.It \e(3d Ta \(3d Ta therefore +.It \e(or Ta \(or Ta bitwise or +.El +.Pp +Mathematical: +.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(pl Ta \(pl Ta plus +.It \e(mi Ta \(mi Ta minus +.It \e- Ta \- Ta minus (text) +.It \e(-+ Ta \(-+ Ta minus-plus +.It \e(+- Ta \(+- Ta plus-minus +.It \e[t+-] Ta \[t+-] Ta plus-minus (text) +.It \e(pc Ta \(pc Ta centre-dot +.It \e(mu Ta \(mu Ta multiply +.It \e[tmu] Ta \[tmu] Ta multiply (text) +.It \e(c* Ta \(c* Ta circle-multiply +.It \e(c+ Ta \(c+ Ta circle-plus +.It \e(di Ta \(di Ta divide +.It \e[tdi] Ta \[tdi] Ta divide (text) +.It \e(f/ Ta \(f/ Ta fraction +.It \e(** Ta \(** Ta asterisk +.It \e(<= Ta \(<= Ta less-than-equal +.It \e(>= Ta \(>= Ta greater-than-equal +.It \e(<< Ta \(<< Ta much less +.It \e(>> Ta \(>> Ta much greater +.It \e(eq Ta \(eq Ta equal +.It \e(!= Ta \(!= Ta not equal +.It \e(== Ta \(== Ta equivalent +.It \e(ne Ta \(ne Ta not equivalent +.It \e(=~ Ta \(=~ Ta congruent +.It \e(-~ Ta \(-~ Ta asymptotically congruent +.It \e(ap Ta \(ap Ta asymptotically similar +.It \e(~~ Ta \(~~ Ta approximately similar +.It \e(~= Ta \(~= Ta approximately equal +.It \e(pt Ta \(pt Ta proportionate +.It \e(es Ta \(es Ta empty set +.It \e(mo Ta \(mo Ta element +.It \e(nm Ta \(nm Ta not element +.It \e(sb Ta \(sb Ta proper subset +.It \e(nb Ta \(nb Ta not subset +.It \e(sp Ta \(sp Ta proper superset +.It \e(nc Ta \(nc Ta not superset +.It \e(ib Ta \(ib Ta reflexive subset +.It \e(ip Ta \(ip Ta reflexive superset +.It \e(ca Ta \(ca Ta intersection +.It \e(cu Ta \(cu Ta union +.It \e(/_ Ta \(/_ Ta angle +.It \e(pp Ta \(pp Ta perpendicular +.It \e(is Ta \(is Ta integral +.It \e[integral] Ta \[integral] Ta integral +.It \e[sum] Ta \[sum] Ta summation +.It \e[product] Ta \[product] Ta product +.It \e[coproduct] Ta \[coproduct] Ta coproduct +.It \e(gr Ta \(gr Ta gradient +.It \e(sr Ta \(sr Ta square root +.It \e[sqrt] Ta \[sqrt] Ta square root +.It \e(lc Ta \(lc Ta left-ceiling +.It \e(rc Ta \(rc Ta right-ceiling +.It \e(lf Ta \(lf Ta left-floor +.It \e(rf Ta \(rf Ta right-floor +.It \e(if Ta \(if Ta infinity +.It \e(Ah Ta \(Ah Ta aleph +.It \e(Im Ta \(Im Ta imaginary +.It \e(Re Ta \(Re Ta real +.It \e(pd Ta \(pd Ta partial differential +.It \e(-h Ta \(-h Ta Planck constant over 2\(*p +.It \e[12] Ta \[12] Ta one-half +.It \e[14] Ta \[14] Ta one-fourth +.It \e[34] Ta \[34] Ta three-fourths +.El +.Pp +Ligatures: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ff Ta \(ff Ta ff ligature +.It \e(fi Ta \(fi Ta fi ligature +.It \e(fl Ta \(fl Ta fl ligature +.It \e(Fi Ta \(Fi Ta ffi ligature +.It \e(Fl Ta \(Fl Ta ffl ligature +.It \e(AE Ta \(AE Ta AE +.It \e(ae Ta \(ae Ta ae +.It \e(OE Ta \(OE Ta OE +.It \e(oe Ta \(oe Ta oe +.It \e(ss Ta \(ss Ta German eszett +.It \e(IJ Ta \(IJ Ta IJ ligature +.It \e(ij Ta \(ij Ta ij ligature +.El +.Pp +Accents: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(a" Ta \(a" Ta Hungarian umlaut +.It \e(a- Ta \(a- Ta macron +.It \e(a. Ta \(a. Ta dotted +.It \e(a^ Ta \(a^ Ta circumflex +.It \e(aa Ta \(aa Ta acute +.It \e' Ta \' Ta acute +.It \e(ga Ta \(ga Ta grave +.It \e` Ta \` Ta grave +.It \e(ab Ta \(ab Ta breve +.It \e(ac Ta \(ac Ta cedilla +.It \e(ad Ta \(ad Ta dieresis +.It \e(ah Ta \(ah Ta caron +.It \e(ao Ta \(ao Ta ring +.It \e(a~ Ta \(a~ Ta tilde +.It \e(ho Ta \(ho Ta ogonek +.It \e(ha Ta \(ha Ta hat (text) +.It \e(ti Ta \(ti Ta tilde (text) +.El +.Pp +Accented letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e('A Ta \('A Ta acute A +.It \e('E Ta \('E Ta acute E +.It \e('I Ta \('I Ta acute I +.It \e('O Ta \('O Ta acute O +.It \e('U Ta \('U Ta acute U +.It \e('a Ta \('a Ta acute a +.It \e('e Ta \('e Ta acute e +.It \e('i Ta \('i Ta acute i +.It \e('o Ta \('o Ta acute o +.It \e('u Ta \('u Ta acute u +.It \e(`A Ta \(`A Ta grave A +.It \e(`E Ta \(`E Ta grave E +.It \e(`I Ta \(`I Ta grave I +.It \e(`O Ta \(`O Ta grave O +.It \e(`U Ta \(`U Ta grave U +.It \e(`a Ta \(`a Ta grave a +.It \e(`e Ta \(`e Ta grave e +.It \e(`i Ta \(`i Ta grave i +.It \e(`o Ta \(`i Ta grave o +.It \e(`u Ta \(`u Ta grave u +.It \e(~A Ta \(~A Ta tilde A +.It \e(~N Ta \(~N Ta tilde N +.It \e(~O Ta \(~O Ta tilde O +.It \e(~a Ta \(~a Ta tilde a +.It \e(~n Ta \(~n Ta tilde n +.It \e(~o Ta \(~o Ta tilde o +.It \e(:A Ta \(:A Ta dieresis A +.It \e(:E Ta \(:E Ta dieresis E +.It \e(:I Ta \(:I Ta dieresis I +.It \e(:O Ta \(:O Ta dieresis O +.It \e(:U Ta \(:U Ta dieresis U +.It \e(:a Ta \(:a Ta dieresis a +.It \e(:e Ta \(:e Ta dieresis e +.It \e(:i Ta \(:i Ta dieresis i +.It \e(:o Ta \(:o Ta dieresis o +.It \e(:u Ta \(:u Ta dieresis u +.It \e(:y Ta \(:y Ta dieresis y +.It \e(^A Ta \(^A Ta circumflex A +.It \e(^E Ta \(^E Ta circumflex E +.It \e(^I Ta \(^I Ta circumflex I +.It \e(^O Ta \(^O Ta circumflex O +.It \e(^U Ta \(^U Ta circumflex U +.It \e(^a Ta \(^a Ta circumflex a +.It \e(^e Ta \(^e Ta circumflex e +.It \e(^i Ta \(^i Ta circumflex i +.It \e(^o Ta \(^o Ta circumflex o +.It \e(^u Ta \(^u Ta circumflex u +.It \e(,C Ta \(,C Ta cedilla C +.It \e(,c Ta \(,c Ta cedilla c +.It \e(/L Ta \(/L Ta stroke L +.It \e(/l Ta \(/l Ta stroke l +.It \e(/O Ta \(/O Ta stroke O +.It \e(/o Ta \(/o Ta stroke o +.It \e(oA Ta \(oA Ta ring A +.It \e(oa Ta \(oa Ta ring a +.El +.Pp +Special letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(-D Ta \(-D Ta Eth +.It \e(Sd Ta \(Sd Ta eth +.It \e(TP Ta \(TP Ta Thorn +.It \e(Tp Ta \(Tp Ta thorn +.It \e(.i Ta \(.i Ta dotless i +.It \e(.j Ta \(.j Ta dotless j +.El +.Pp +Currency: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Do Ta \(Do Ta dollar +.It \e(ct Ta \(ct Ta cent +.It \e(Eu Ta \(Eu Ta Euro symbol +.It \e(eu Ta \(eu Ta Euro symbol +.It \e(Ye Ta \(Ye Ta yen +.It \e(Po Ta \(Po Ta pound +.It \e(Cs Ta \(Cs Ta Scandinavian +.It \e(Fn Ta \(Fn Ta florin +.El +.Pp +Units: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(de Ta \(de Ta degree +.It \e(%0 Ta \(%0 Ta per-thousand +.It \e(fm Ta \(fm Ta minute +.It \e(sd Ta \(sd Ta second +.It \e(mc Ta \(mc Ta micro +.El +.Pp +Greek letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(*A Ta \(*A Ta Alpha +.It \e(*B Ta \(*B Ta Beta +.It \e(*G Ta \(*G Ta Gamma +.It \e(*D Ta \(*D Ta Delta +.It \e(*E Ta \(*E Ta Epsilon +.It \e(*Z Ta \(*Z Ta Zeta +.It \e(*Y Ta \(*Y Ta Eta +.It \e(*H Ta \(*H Ta Theta +.It \e(*I Ta \(*I Ta Iota +.It \e(*K Ta \(*K Ta Kappa +.It \e(*L Ta \(*L Ta Lambda +.It \e(*M Ta \(*M Ta Mu +.It \e(*N Ta \(*N Ta Nu +.It \e(*C Ta \(*C Ta Xi +.It \e(*O Ta \(*O Ta Omicron +.It \e(*P Ta \(*P Ta Pi +.It \e(*R Ta \(*R Ta Rho +.It \e(*S Ta \(*S Ta Sigma +.It \e(*T Ta \(*T Ta Tau +.It \e(*U Ta \(*U Ta Upsilon +.It \e(*F Ta \(*F Ta Phi +.It \e(*X Ta \(*X Ta Chi +.It \e(*Q Ta \(*Q Ta Psi +.It \e(*W Ta \(*W Ta Omega +.It \e(*a Ta \(*a Ta alpha +.It \e(*b Ta \(*b Ta beta +.It \e(*g Ta \(*g Ta gamma +.It \e(*d Ta \(*d Ta delta +.It \e(*e Ta \(*e Ta epsilon +.It \e(*z Ta \(*z Ta zeta +.It \e(*y Ta \(*y Ta eta +.It \e(*h Ta \(*h Ta theta +.It \e(*i Ta \(*i Ta iota +.It \e(*k Ta \(*k Ta kappa +.It \e(*l Ta \(*l Ta lambda +.It \e(*m Ta \(*m Ta mu +.It \e(*n Ta \(*n Ta nu +.It \e(*c Ta \(*c Ta xi +.It \e(*o Ta \(*o Ta omicron +.It \e(*p Ta \(*p Ta pi +.It \e(*r Ta \(*r Ta rho +.It \e(*s Ta \(*s Ta sigma +.It \e(*t Ta \(*t Ta tau +.It \e(*u Ta \(*u Ta upsilon +.It \e(*f Ta \(*f Ta phi +.It \e(*x Ta \(*x Ta chi +.It \e(*q Ta \(*q Ta psi +.It \e(*w Ta \(*w Ta omega +.It \e(+h Ta \(+h Ta theta variant +.It \e(+f Ta \(+f Ta phi variant +.It \e(+p Ta \(+p Ta pi variant +.It \e(+e Ta \(+e Ta epsilon variant +.It \e(ts Ta \(ts Ta sigma terminal +.El +.Sh PREDEFINED STRINGS +Predefined strings are inherited from the macro packages of historical +troff implementations. +They are +.Em not recommended +for use, as they differ across implementations. +Manuals using these predefined strings are almost certainly not +portable. +.Pp +Their syntax is similar to special characters, using +.Sq \e*X +.Pq for a one-character escape , +.Sq \e*(XX +.Pq two-character , +and +.Sq \e*[N] +.Pq N-character . +For details, see the +.Em Predefined Strings +subsection of the +.Xr roff 5 +manual. +.Bl -column "Input" "Rendered" "Description" -offset indent +.It Em Input Ta Em Rendered Ta Em Description +.It \e*(Ba Ta \*(Ba Ta vertical bar +.It \e*(Ne Ta \*(Ne Ta not equal +.It \e*(Ge Ta \*(Ge Ta greater-than-equal +.It \e*(Le Ta \*(Le Ta less-than-equal +.It \e*(Gt Ta \*(Gt Ta greater-than +.It \e*(Lt Ta \*(Lt Ta less-than +.It \e*(Pm Ta \*(Pm Ta plus-minus +.It \e*(If Ta \*(If Ta infinity +.It \e*(Pi Ta \*(Pi Ta pi +.It \e*(Na Ta \*(Na Ta NaN +.It \e*(Am Ta \*(Am Ta ampersand +.It \e*R Ta \*R Ta restricted mark +.It \e*(Tm Ta \*(Tm Ta trade mark +.It \e*q Ta \*q Ta double-quote +.It \e*(Rq Ta \*(Rq Ta right-double-quote +.It \e*(Lq Ta \*(Lq Ta left-double-quote +.It \e*(lp Ta \*(lp Ta right-parenthesis +.It \e*(rp Ta \*(rp Ta left-parenthesis +.It \e*(lq Ta \*(lq Ta left double-quote +.It \e*(rq Ta \*(rq Ta right double-quote +.It \e*(ua Ta \*(ua Ta up arrow +.It \e*(va Ta \*(va Ta up-down arrow +.It \e*(<= Ta \*(<= Ta less-than-equal +.It \e*(>= Ta \*(>= Ta greater-than-equal +.It \e*(aa Ta \*(aa Ta acute +.It \e*(ga Ta \*(ga Ta grave +.It \e*(Px Ta \*(Px Ta POSIX standard name +.It \e*(Ai Ta \*(Ai Ta ANSI standard name +.El +.Sh UNICODE CHARACTERS +The escape sequence +.Pp +.Dl \e[uXXXX] +.Pp +is interpreted as a Unicode codepoint. +The codepoint must be in the range above U+0080 and less than U+10FFFF. +For compatibility, points must be zero-padded to four characters; if +greater than four characters, no zero padding is allowed. +Unicode surrogates are not allowed. +.\" .Pp +.\" Unicode glyphs attenuate to the +.\" .Sq \&? +.\" character if invalid or not rendered by current output media. +.Sh NUMBERED CHARACTERS +For backward compatibility with existing manuals, +.Xr mandoc 1 +also supports the +.Pp +.Dl \eN\(aq Ns Ar number Ns \(aq +.Pp +escape sequence, inserting the character +.Ar number +from the current character set into the output. +Of course, this is inherently non-portable and is already marked +as deprecated in the Heirloom roff manual. +For example, do not use \eN'34', use \e(dq, or even the plain +.Sq \(dq +character where possible. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . +.Pp +.Bl -dash -compact +.It +The \eN\(aq\(aq escape sequence is limited to printable characters; in +groff, it accepts arbitrary character numbers. +.It +In +.Fl T Ns Cm ascii , +the +\e(ss, \e(nm, \e(nb, \e(nc, \e(ib, \e(ip, \e(pp, \e[sum], \e[product], +\e[coproduct], \e(gr, \e(\-h, and \e(a. special characters render +differently between mandoc and groff. +.It +In +.Fl T Ns Cm html +and +.Fl T Ns Cm xhtml , +the \e(~=, \e(nb, and \e(nc special characters render differently +between mandoc and groff. +.It +The +.Fl T Ns Cm ps +and +.Fl T Ns Cm pdf +modes format like +.Fl T Ns Cm ascii +instead of rendering glyphs as in groff. +.It +The \e[radicalex], \e[sqrtex], and \e(ru special characters have been omitted +from mandoc either because they are poorly documented or they have no +known representation. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 5 , +.Xr mdoc 5 , +.Xr roff 5 +.Sh AUTHORS +The +.Nm +manual page was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . +.Sh CAVEATS +The +.Sq \e*(Ba +escape mimics the behaviour of the +.Sq \&| +character in +.Xr mdoc 5 ; +thus, if you wish to render a vertical bar with no side effects, use +the +.Sq \e(ba +escape. diff --git a/usr/src/man/man5/mandoc_roff.5 b/usr/src/man/man5/mandoc_roff.5 new file mode 100644 index 0000000000..731f93e134 --- /dev/null +++ b/usr/src/man/man5/mandoc_roff.5 @@ -0,0 +1,991 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" +.Dd Jul 13, 2014 +.Dt MANDOC_ROFF 5 +.Os +.Sh NAME +.Nm mandoc_roff +.Nd roff language reference for mandoc +.Sh DESCRIPTION +The +.Nm roff +language is a general purpose text formatting language. +Since traditional implementations of the +.Xr mdoc 5 +and +.Xr man 5 +manual formatting languages are based on it, +many real-world manuals use small numbers of +.Nm +requests intermixed with their +.Xr mdoc 5 +or +.Xr man 5 +code. +To properly format such manuals, the +.Xr mandoc 1 +utility supports a tiny subset of +.Nm +requests. +Only these requests supported by +.Xr mandoc 1 +are documented in the present manual, +together with the basic language syntax shared by +.Nm , +.Xr mdoc 5 , +and +.Xr man 5 . +For complete +.Nm +manuals, consult the +.Sx SEE ALSO +section. +.Pp +Input lines beginning with the control character +.Sq \&. +are parsed for requests and macros. +Such lines are called +.Dq request lines +or +.Dq macro lines , +respectively. +Requests change the processing state and manipulate the formatting; +some macros also define the document structure and produce formatted +output. +The single quote +.Pq Qq \(aq +is accepted as an alternative control character, +treated by +.Xr mandoc 1 +just like +.Ql \&. +.Pp +Lines not beginning with control characters are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context. +.Sh LANGUAGE SYNTAX +.Nm +documents may contain only graphable 7-bit ASCII characters, the space +character, and, in certain circumstances, the tab character. +The back-space character +.Sq \e +indicates the start of an escape sequence for +.Sx Comments , +.Sx Special Characters , +.Sx Predefined Strings , +and +user-defined strings defined using the +.Sx ds +request. +.Ss Comments +Text following an escaped double-quote +.Sq \e\(dq , +whether in a request, macro, or text line, is ignored to the end of the line. +A request line beginning with a control character and comment escape +.Sq \&.\e\(dq +is also ignored. +Furthermore, request lines with only a control character and optional +trailing whitespace are stripped from input. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.\e\(dq This is a comment line. +\&.\e\(dq The next line is ignored: +\&. +\&.Sh EXAMPLES \e\(dq This is a comment, too. +\&example text \e\(dq And so is this. +.Ed +.Ss Special Characters +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in request, macro, and text lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis +.Sq \&( +for two-character sequences; an open-bracket +.Sq \&[ +for n-character sequences (terminated at a close-bracket +.Sq \&] ) ; +or a single one character sequence. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e(em +Two-letter em dash escape. +.It Li \ee +One-letter backslash escape. +.El +.Pp +See +.Xr mandoc_char 5 +for a complete list. +.Ss Text Decoration +Terms may be text-decorated using the +.Sq \ef +escape followed by an indicator: B (bold), I (italic), R (regular), or P +(revert to previous mode). +A numerical representation 3, 2, or 1 (bold, italic, and regular, +respectively) may be used instead. +The indicator or numerical representative may be preceded by C +(constant-width), which is ignored. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \efBbold\efR +Write in bold, then switch to regular font mode. +.It Li \efIitalic\efP +Write in italic, then return to previous font mode. +.El +.Pp +Text decoration is +.Em not +recommended for +.Xr mdoc 5 , +which encourages semantic annotation. +.Ss Predefined Strings +Predefined strings, like +.Sx Special Characters , +mark special output glyphs. +Predefined strings are escaped with the slash-asterisk, +.Sq \e* : +single-character +.Sq \e*X , +two-character +.Sq \e*(XX , +and N-character +.Sq \e*[N] . +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e*(Am +Two-letter ampersand predefined string. +.It Li \e*q +One-letter double-quote predefined string. +.El +.Pp +Predefined strings are not recommended for use, +as they differ across implementations. +Those supported by +.Xr mandoc 1 +are listed in +.Xr mandoc_char 5 . +Manuals using these predefined strings are almost certainly not portable. +.Ss Whitespace +Whitespace consists of the space character. +In text lines, whitespace is preserved within a line. +In request and macro lines, whitespace delimits arguments and is discarded. +.Pp +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a blank character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp +Literal space characters can be produced in the output +using escape sequences. +In macro lines, they can also be included in arguments using quotation; see +.Sx MACRO SYNTAX +for details. +.Pp +Blank text lines, which may include whitespace, are only permitted +within literal contexts. +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Scaling Widths +Many requests and macros support scaled widths for their arguments. +The syntax for a scaled width is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or followed by at least one digit. +Negative numbers, while accepted, are truncated to zero. +.Pp +The following scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. +See +.Sx COMPATIBILITY . +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Pp +Examples: +.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact +.It Li \&.Bl -tag -width 2i +two-inch tagged list indentation in +.Xr mdoc 5 +.It Li \&.HP 2i +two-inch tagged list indentation in +.Xr man 5 +.It Li \&.sp 2v +two vertical spaces +.El +.Ss Sentence Spacing +Each sentence should terminate at the end of an input line. +By doing this, a formatter will be able to apply the proper amount of +spacing after the end of sentence (unescaped) period, exclamation mark, +or question mark followed by zero or more non-sentence closing +delimiters +.Po +.Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" +.Pc . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line. +.Pp +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A macro would end like this: +\&.Xr mandoc 1 \&. +.Ed +.Sh REQUEST SYNTAX +A request or macro line consists of: +.Pp +.Bl -enum -compact +.It +the control character +.Sq \&. +or +.Sq \(aq +at the beginning of the line, +.It +optionally an arbitrary amount of whitespace, +.It +the name of the request or the macro, which is one word of arbitrary +length, terminated by whitespace, +.It +and zero or more arguments delimited by whitespace. +.El +.Pp +Thus, the following request lines are all equivalent: +.Bd -literal -offset indent +\&.ig end +\&.ig end +\&. ig end +.Ed +.Sh MACRO SYNTAX +Macros are provided by the +.Xr mdoc 5 +and +.Xr man 5 +languages and can be defined by the +.Sx \&de +request. +When called, they follow the same syntax as requests, except that +macro arguments may optionally be quoted by enclosing them +in double quote characters +.Pq Sq \(dq . +Quoted text, even if it contains whitespace or would cause +a macro invocation when unquoted, is always considered literal text. +Inside quoted text, pairs of double quote characters +.Pq Sq Qq +resolve to single double quote characters. +.Pp +To be recognised as the beginning of a quoted argument, the opening +quote character must be preceded by a space character. +A quoted argument extends to the next double quote character that is not +part of a pair, or to the end of the input line, whichever comes earlier. +Leaving out the terminating double quote character at the end of the line +is discouraged. +For clarity, if more arguments follow on the same input line, +it is recommended to follow the terminating double quote character +by a space character; in case the next character after the terminating +double quote character is anything else, it is regarded as the beginning +of the next, unquoted argument. +.Pp +Both in quoted and unquoted arguments, pairs of backslashes +.Pq Sq \e\e +resolve to single backslashes. +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li .Fn strlen \(dqconst char *s\(dq +Group arguments +.Qq const char *s +into one function argument. +If unspecified, +.Qq const , +.Qq char , +and +.Qq *s +would be considered separate arguments. +.It Li .Op \(dqFl a\(dq +Consider +.Qq \&Fl a +as literal text instead of a flag macro. +.El +.Sh REQUEST REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following requests. +Note that the +.Nm +language defines many more requests not implemented in +.Xr mandoc 1 . +.Ss \&ad +Set line adjustment mode. +This line-scoped request is intended to have one argument to select +normal, left, right, or centre adjustment for subsequent text. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. +.Ss \&am +Append to a macro definition. +The syntax of this request is the same as that of +.Sx \&de . +It is currently ignored by +.Xr mandoc 1 , +as are its children. +.Ss \&ami +Append to a macro definition, specifying the macro name indirectly. +The syntax of this request is the same as that of +.Sx \&dei . +It is currently ignored by +.Xr mandoc 1 , +as are its children. +.Ss \&am1 +Append to a macro definition, switching roff compatibility mode off +during macro execution. +The syntax of this request is the same as that of +.Sx \&de1 . +It is currently ignored by +.Xr mandoc 1 , +as are its children. +.Ss \&de +Define a +.Nm +macro. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&de Ar name +.Ar macro definition +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&de Ar name Ar end +.Ar macro definition +.Pf . Ar end +.Ed +.Pp +Both forms define or redefine the macro +.Ar name +to represent the +.Ar macro definition , +which may consist of one or more input lines, including the newline +characters terminating each line, optionally containing calls to +.Nm +requests, +.Nm +macros or high-level macros like +.Xr man 5 +or +.Xr mdoc 5 +macros, whichever applies to the document in question. +.Pp +Specifying a custom +.Ar end +macro works in the same way as for +.Sx \&ig ; +namely, the call to +.Sq Pf . Ar end +first ends the +.Ar macro definition , +and after that, it is also evaluated as a +.Nm +request or +.Nm +macro, but not as a high-level macro. +.Pp +The macro can be invoked later using the syntax +.Pp +.D1 Pf . Ar name Op Ar argument Op Ar argument ... +.Pp +Regarding argument parsing, see +.Sx MACRO SYNTAX +above. +.Pp +The line invoking the macro will be replaced +in the input stream by the +.Ar macro definition , +replacing all occurrences of +.No \e\e$ Ns Ar N , +where +.Ar N +is a digit, by the +.Ar N Ns th Ar argument . +For example, +.Bd -literal -offset indent +\&.de ZN +\efI\e^\e\e$1\e^\efP\e\e$2 +\&.. +\&.ZN XtFree . +.Ed +.Pp +produces +.Pp +.D1 \efI\e^XtFree\e^\efP. +.Pp +in the input stream, and thus in the output: \fI\^XtFree\^\fP. +.Pp +Since macros and user-defined strings share a common string table, +defining a macro +.Ar name +clobbers the user-defined string +.Ar name , +and the +.Ar macro definition +can also be printed using the +.Sq \e* +string interpolation syntax described below +.Sx ds , +but this is rarely useful because every macro definition contains at least +one explicit newline character. +.Pp +In order to prevent endless recursion, both groff and +.Xr mandoc 1 +limit the stack depth for expanding macros and strings +to a large, but finite number. +Do not rely on the exact value of this limit. +.Ss \&dei +Define a +.Nm +macro, specifying the macro name indirectly. +The syntax of this request is the same as that of +.Sx \&de . +It is currently ignored by +.Xr mandoc 1 , +as are its children. +.Ss \&de1 +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution. +This is a GNU extension not available in traditional +.Nm +implementations and not even in older versions of groff. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&de . +.Ss \&ds +Define a user-defined string. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string +.Pp +The +.Ar name +and +.Ar string +arguments are space-separated. +If the +.Ar string +begins with a double-quote character, that character will not be part +of the string. +All remaining characters on the input line form the +.Ar string , +including whitespace and double-quote characters, even trailing ones. +.Pp +The +.Ar string +can be interpolated into subsequent text by using +.No \e* Ns Bq Ar name +for a +.Ar name +of arbitrary length, or \e*(NN or \e*N if the length of +.Ar name +is two or one characters, respectively. +Interpolation can be prevented by escaping the leading backslash; +that is, an asterisk preceded by an even number of backslashes +does not trigger string interpolation. +.Pp +Since user-defined strings and macros share a common string table, +defining a string +.Ar name +clobbers the macro +.Ar name , +and the +.Ar name +used for defining a string can also be invoked as a macro, +in which case the following input line will be appended to the +.Ar string , +forming a new input line passed to the +.Nm +parser. +For example, +.Bd -literal -offset indent +\&.ds badidea .S +\&.badidea +H SYNOPSIS +.Ed +.Pp +invokes the +.Cm SH +macro when used in a +.Xr man 5 +document. +Such abuse is of course strongly discouraged. +.Ss \&el +The +.Qq else +half of an if/else conditional. +Pops a result off the stack of conditional evaluations pushed by +.Sx \&ie +and uses it as its conditional. +If no stack entries are present (e.g., due to no prior +.Sx \&ie +calls) +then false is assumed. +The syntax of this request is similar to +.Sx \&if +except that the conditional is missing. +.Ss \&EN +End an equation block. +See +.Sx \&EQ . +.Ss \&EQ +Begin an equation block. +See +.Xr eqn 5 +for a description of the equation language. +.Ss \&hy +Set automatic hyphenation mode. +This line-scoped request is currently ignored. +.Ss \&ie +The +.Qq if +half of an if/else conditional. +The result of the conditional is pushed into a stack used by subsequent +invocations of +.Sx \&el , +which may be separated by any intervening input (or not exist at all). +Its syntax is equivalent to +.Sx \&if . +.Ss \&if +Begins a conditional. +Right now, the conditional evaluates to true +if and only if it starts with the letter +.Sy n , +indicating processing in nroff style as opposed to troff style. +If a conditional is false, its children are not processed, but are +syntactically interpreted to preserve the integrity of the input +document. +Thus, +.Pp +.D1 \&.if t .ig +.Pp +will discard the +.Sq \&.ig , +which may lead to interesting results, but +.Pp +.D1 \&.if t .if t \e{\e +.Pp +will continue to syntactically interpret to the block close of the final +conditional. +Sub-conditionals, in this case, obviously inherit the truth value of +the parent. +This request has the following syntax: +.Bd -literal -offset indent +\&.if COND \e{\e +BODY... +\&.\e} +.Ed +.Bd -literal -offset indent +\&.if COND \e{ BODY +BODY... \e} +.Ed +.Bd -literal -offset indent +\&.if COND \e{ BODY +BODY... +\&.\e} +.Ed +.Bd -literal -offset indent +\&.if COND \e +BODY +.Ed +.Pp +COND is a conditional statement. +roff allows for complicated conditionals; mandoc is much simpler. +At this time, mandoc supports only +.Sq n , +evaluating to true; +and +.Sq t , +.Sq e , +and +.Sq o , +evaluating to false. +All other invocations are read up to the next end of line or space and +evaluate as false. +.Pp +If the BODY section is begun by an escaped brace +.Sq \e{ , +scope continues until a closing-brace escape sequence +.Sq \.\e} . +If the BODY is not enclosed in braces, scope continues until +the end of the line. +If the COND is followed by a BODY on the same line, whether after a +brace or not, then requests and macros +.Em must +begin with a control character. +It is generally more intuitive, in this case, to write +.Bd -literal -offset indent +\&.if COND \e{\e +\&.foo +bar +\&.\e} +.Ed +.Pp +than having the request or macro follow as +.Pp +.D1 \&.if COND \e{ .foo +.Pp +The scope of a conditional is always parsed, but only executed if the +conditional evaluates to true. +.Pp +Note that the +.Sq \e} +is converted into a zero-width escape sequence if not passed as a +standalone macro +.Sq \&.\e} . +For example, +.Pp +.D1 \&.Fl a \e} b +.Pp +will result in +.Sq \e} +being considered an argument of the +.Sq \&Fl +macro. +.Ss \&ig +Ignore input. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&ig +.Ar ignored text +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&ig Ar end +.Ar ignored text +.Pf . Ar end +.Ed +.Pp +In the first case, input is ignored until a +.Sq \&.. +request is encountered on its own line. +In the second case, input is ignored until the specified +.Sq Pf . Ar end +macro is encountered. +Do not use the escape character +.Sq \e +anywhere in the definition of +.Ar end ; +it would cause very strange behaviour. +.Pp +When the +.Ar end +macro is a roff request or a roff macro, like in +.Pp +.D1 \&.ig if +.Pp +the subsequent invocation of +.Sx \&if +will first terminate the +.Ar ignored text , +then be invoked as usual. +Otherwise, it only terminates the +.Ar ignored text , +and arguments following it or the +.Sq \&.. +request are discarded. +.Ss \&ne +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +This line-scoped request is currently ignored. +.Ss \&nh +Turn off automatic hyphenation mode. +This line-scoped request is currently ignored. +.Ss \&rm +Remove a request, macro or string. +This request is intended to have one argument, +the name of the request, macro or string to be undefined. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. +.Ss \&nr +Define a register. +A register is an arbitrary string value that defines some sort of state, +which influences parsing and/or formatting. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&nr Ar name Ar value +.Pp +The +.Ar value +may, at the moment, only be an integer. +So far, only the following register +.Ar name +is recognised: +.Bl -tag -width Ds +.It Cm nS +If set to a positive integer value, certain +.Xr mdoc 5 +macros will behave in the same way as in the +.Em SYNOPSIS +section. +If set to 0, these macros will behave in the same way as outside the +.Em SYNOPSIS +section, even when called within the +.Em SYNOPSIS +section itself. +Note that starting a new +.Xr mdoc 5 +section with the +.Cm \&Sh +macro will reset this register. +.El +.Ss \&ns +Turn on no-space mode. +This line-scoped request is intended to take no arguments. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. +.Ss \&ps +Change point size. +This line-scoped request is intended to take one numerical argument. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. +.Ss \&so +Include a source file. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&so Ar file +.Pp +The +.Ar file +will be read and its contents processed as input in place of the +.Sq \&.so +request line. +To avoid inadvertent inclusion of unrelated files, +.Xr mandoc 1 +only accepts relative paths not containing the strings +.Qq ../ +and +.Qq /.. . +.Pp +This request requires +.Xr man 1 +to change to the right directory before calling +.Xr mandoc 1 , +per convention to the root of the manual tree. +Typical usage looks like: +.Pp +.Dl \&.so man3/Xcursor.3 +.Pp +As the whole concept is rather fragile, the use of +.Sx \&so +is discouraged. +Use +.Xr ln 1 +instead. +.Ss \&ta +Set tab stops. +This line-scoped request can take an arbitrary number of arguments. +Currently, it is ignored including its arguments. +.Ss \&tr +Output character translation. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&tr Ar [ab]+ +.Pp +Pairs of +.Ar ab +characters are replaced +.Ar ( a +for +.Ar b ) . +Replacement (or origin) characters may also be character escapes; thus, +.Pp +.Dl tr \e(xx\e(yy +.Pp +replaces all invocations of \e(xx with \e(yy. +.Ss \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Sx \&TS . +.Ss \&TE +End a table context. +See +.Sx \&TS . +.Ss \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 5 +for a description of the tbl language. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other other +.Nm +implementations, at this time limited to GNU troff +.Pq Qq groff . +The term +.Qq historic groff +refers to groff version 1.15. +.Pp +.Bl -dash -compact +.It +In mandoc, the +.Sx \&EQ , +.Sx \&TE , +.Sx \&TS , +and +.Sx \&T& , +macros are considered regular macros. +In all other +.Nm +implementations, these are special macros that must be specified without +spacing between the control character (which must be a period) and the +macro name. +.It +The +.Cm nS +register is only compatible with OpenBSD's groff-1.15. +.It +Historic groff did not accept white-space before a custom +.Ar end +macro for the +.Sx \&ig +request. +.It +The +.Sx \&if +and family would print funny white-spaces with historic groff when +using the next-line syntax. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr eqn 5 , +.Xr man 5 , +.Xr mandoc_char 5 , +.Xr mdoc 5 , +.Xr tbl 5 +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%I AT&T Bell Laboratories +.%T Troff User's Manual +.%R Computing Science Technical Report +.%N 54 +.%C Murray Hill, New Jersey +.%D 1976 and 1992 +.%U http://www.kohala.com/start/troff/cstr54.ps +.Re +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%A Gunnar Ritter +.%T Heirloom Documentation Tools Nroff/Troff User's Manual +.%D September 17, 2007 +.%U http://heirloom.sourceforge.net/doctools/troff.pdf +.Re +.Sh HISTORY +The RUNOFF typesetting system, whose input forms the basis for +.Nm , +was written in MAD and FAP for the CTSS operating system by Jerome E. +Saltzer in 1964. +Doug McIlroy rewrote it in BCPL in 1969, renaming it +.Nm . +Dennis M. Ritchie rewrote McIlroy's +.Nm +in PDP-11 assembly for +.At v1 , +Joseph F. Ossanna improved roff and renamed it nroff +for +.At v2 , +then ported nroff to C as troff, which Brian W. Kernighan released with +.At v7 . +In 1989, James Clarke re-implemented troff in C++, naming it groff. +.Sh AUTHORS +.An -nosplit +This +.Nm +reference was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv ; +and +.An Ingo Schwarze , +.Mt schwarze@openbsd.org . diff --git a/usr/src/man/man5/mdoc.5 b/usr/src/man/man5/mdoc.5 new file mode 100644 index 0000000000..901a2848cd --- /dev/null +++ b/usr/src/man/man5/mdoc.5 @@ -0,0 +1,3207 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" Copyright 2014 Garrett D'Amore <garrett@dmaore.org> +.\" +.Dd Jul 19, 2014 +.Dt MDOC 5 +.Os +.Sh NAME +.Nm mdoc +.Nd semantic markup language for formatting manual pages +.Sh DESCRIPTION +The +.Nm mdoc +language supports authoring of manual pages for the +.Xr man 1 +utility by allowing semantic annotations of words, phrases, +page sections and complete manual pages. +Such annotations are used by formatting tools to achieve a uniform +presentation across all manuals written in +.Nm , +and to support hyperlinking if supported by the output medium. +.Pp +This reference document describes the structure of manual pages +and the syntax and usage of the +.Nm +language. +The reference implementation of a parsing and formatting tool is +.Xr mandoc 1 ; +the +.Sx COMPATIBILITY +section describes compatibility with other implementations. +.Pp +In an +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It consists of two or three letters. +Most macro names begin with a capital letter. +For a list of available macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro, optionally +including the names of other, callable macros; see +.Sx MACRO SYNTAX +for details. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.Sh Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 5 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr roff 5 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +However, using +.Xr roff 5 +requests in +.Nm +documents is discouraged; +.Xr mandoc 1 +supports some of them merely for backward compatibility. +.Sh MANUAL STRUCTURE +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. +.Pp +The prologue, which consists of the +.Sx \&Dd , +.Sx \&Dt , +and +.Sx \&Os +macros in that order, is required for every document. +.Pp +The first section (sections are denoted by +.Sx \&Sh ) +must be the NAME section, consisting of at least one +.Sx \&Nm +followed by +.Sx \&Nd . +.Pp +Following that, convention dictates specifying at least the +.Em SYNOPSIS +and +.Em DESCRIPTION +sections, although this varies between manual sections. +.Pp +The following is a well-formed skeleton +.Nm +file for a utility +.Qq progname : +.Bd -literal -offset indent +\&.Dd Jan 1, 1970 +\&.Dt PROGNAME section +\&.Os +\&.Sh NAME +\&.Nm progname +\&.Nd one line description +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, & 9 only. +\&.Sh SYNOPSIS +\&.Nm progname +\&.Op Fl options +\&.Ar +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, & 9 only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 1M, and 5. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 1M, and 5. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, & 9 only. +\&.\e\(dq .Sh ARCHITECTURE +\&.\e\(dq .Sh CODE SET INDEPENDENCE +\&.\e\(dq For sections 1, 1M, & 3 only. +\&.\e\(dq .Sh INTERFACE STABILITY +\&.\e\(dq .Sh MT-LEVEL +\&.\e\(dq For sections 2 & 3 only. +\&.\e\(dq .Sh SECURITY +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +.Ed +.Pp +The sections in an +.Nm +document are conventionally ordered as they appear above. +Sections should be composed as follows: +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a one line description of the documented material. +The syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 , +\&.Nm name1 , +\&.Nm name2 +\&.Nd a one line description +.Ed +.Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp +The +.Sx \&Nm +macro(s) must precede the +.Sx \&Nd +macro. +.Pp +See +.Sx \&Nm +and +.Sx \&Nd . +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2, 3, or 9 manual. +The syntax for this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Sx \&Lb . +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1 and 1M), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +Commands should be ordered alphabetically. +.Pp +For the second, function calls (sections 2, 3, 7I, 7P, 9): +.Bd -literal -offset indent +\&.In header.h +\&.Vt extern const char *global; +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +Ordering of +.Sx \&In , +.Sx \&Vt , +.Sx \&Fn , +and +.Sx \&Fo +macros should follow C header-file conventions. +.Pp +And for the third, configurations (section 7D): +.Bd -literal -offset indent +\&.Pa /dev/device_node +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.Pp +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Sx \&Nm , +.Sx \&Cd , +.Sx \&Fd , +.Sx \&Fn , +.Sx \&Fo , +.Sx \&In , +.Sx \&Vt , +and +.Sx \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pairwise invoked (except for +.Sx \&Ft +before +.Sx \&Fo +or +.Sx \&Fn ) , +they are separated by a vertical space, unless in the case of +.Sx \&Fo , +.Sx \&Fn , +and +.Sx \&Ft , +which are always separated by vertical space. +.Pp +When text and macros following an +.Sx \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Sx \&Nm +macro, up to the next +.Sx \&Nm , +.Sx \&Sh , +or +.Sx \&Ss +macro or the end of an enclosing block, whichever comes first. +.It Em DESCRIPTION +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The arguments are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +.Pp +Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Sx \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Sx \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. +This is useful when implementing standard functions that may have side +effects or notable algorithmic implications. +.It Em RETURN VALUES +This section documents the +return values of functions in sections 2, 3, and 9. +.Pp +See +.Sx \&Rv . +.It Em ENVIRONMENT +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 5 +manual provides examples of typical content and formatting. +.Pp +See +.Sx \&Ev . +.It Em FILES +Documents files used. +It's helpful to document both the file name and a short description of how +the file is used (created, modified, etc.). +.Pp +See +.Sx \&Pa . +.It Em EXIT STATUS +This section documents the +command exit status for sections 1 and 1M. +Historically, this information was described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Sx \&Ex . +.It Em EXAMPLES +Example usages. +This often contains snippets of well-formed, well-tested invocations. +Make sure that examples work properly! +.It Em DIAGNOSTICS +Documents error and diagnostic messages displayed to the user or +sent to logs. Note that exit +status and return values should be documented in the +.Em EXIT STATUS +and +.Em RETURN VALUES +sections. +.Pp +See +.Sx \&Bl +.Fl diag . +.It Em ERRORS +Documents error handling in sections 2, 3, and 9. +.Pp +See +.Sx \&Er . +.It Em ARCHITECTURE +This section is usually absent, but will be present when the +interface is specific to one or more architectures. +.It Em CODE SET INDEPENDENCE +Indicates whether the interface operates correctly with various different +code sets. True independent code sets will support not only ASCII and +Extended UNIX Codesets (EUC), but also other multi-byte encodings such as +UTF-8 and GB2312. +.Pp +Generally there will be some limitations that are fairly standard. See +.Xr standards 5 for more information about some of these. Most interfaces +should support at least UTF-8 in addition to ASCII. +.It Em INTERFACE STABILITY +Indicates the level of commitment to the interface. Interfaces can be described +with in the following ways: +.Bl -tag -width Ds +.It Nm Standard +Indicates that the interface is defined by one or more standards bodies. +Generally, changes to the interface will be carefully managed to conform +to the relevant standards. These interfaces are generally the most suitable +for use in portable programs. +.It Nm Committed +Indicates that the interface is intended to be preserved for the long-haul, and +will rarely, if ever change, and never without notification (barring +extraordinary and extenuating circumstances). These interfaces are +preferred over other interfaces with the exeception of +.Nm Standard +interfaces. +.It Nm Uncommitted +Indicates that the interface may change. Generally, changes to these interfaces +should be infrequent, and some effort will be made to address compatibility +considerations when changing or removing such interfaces. However, there is +no firm commitment to the preservation of the interface. Most often this +is applied to interfaces where operational experience with the interface +is still limited and some need to change may be anticipated. +.Pp +Consumers should expect to revalidate any +.Nm Uncommitted +interfaces when crossing release boundaries. Products intended for +use on many releases or intended to support compatibility with future +releases should avoid these interfaces. +.It Nm Volatile +The interface can change at any time for any reason. Often this relates to +interfaces that are part of external software components that are still evolving +rapidly. Consumers should not expect that the interface (either binary or +source level) will be unchanged from one release to the next. +.It Nm Not-an-Interface +Describes something that is specifically not intended for programmatic +consumption. For example, specific human-readable output, or the layout +of graphical items on a user interface, may be described this way. Generally +programmatic alternatives to these will be available, and should be used +when programmatic consumption is needed. +.It Nm Private +This is an internal interface. Generally these interfaces should only be +used within the project, and should not be used by other programs or modules. +The interface can and will change without notice as the project needs, at +any time. +.Pp +Most often, Private interfaces will lack any documentation whatsoever, and +generally any undocumented interface can be assumed to be Private. +.It Nm Obsolete +The interface is not intended for use in new projects or programs, and may +be removed at a future date. The +.Nm Obsolete +word is a modifier that can +be applied to other commitment levels. For example an +.Nm Obsolete Committed +interface is unlikely to be removed or changed, but nonetheless new use +is discouraged (perhaps a better newer alternative is present). +.El +.It Em MT-LEVEL +This section describes considerations for the interface when used within +programs that use multiple threads. More discussion of these considerations +is made in the MT-Level section of +.Xr attributes 5 . +The interface can be described in the following ways. +.Bl -tag -width Ds +.It Nm Safe +Indicates the interface is safe for use within multiple threads. There +may be additional caveats that apply, in which case those will be +described. Note that some interfaces have semantics which may affect +other threads, but these should be an intrinsic part of the interface +rather than an unexpected side effect. For example, closing a file in +one thread will cause that file to be closed in all threads. +.It Nm Unsafe +Indicates the interface is unsuitable for concurrent use within multiple +threads. A threaded application may still make use of the interface, but +will be required to provide external synchronization means to ensure that +only a single thread calls the interface at a time. +.It Nm MT-Safe +Indicates that the interface is not only safe for concurrent use, but is +designed for such use. For example, a +.Nm Safe +interface may make use of a global lock to provide safety, but at reduced +internal concurrency, whereas an +.Nm MT-Safe +interface will be designed to be efficient even when used concurrently. +.It Nm Async-Signal-Safe +Indicates that the library is safe for use within a signal handler. An +.Nm MT-Safe +interface can be made +.Nm Async-Signal-Safe +by ensuring that it blocks signals when acquiring locks. +.It Nm Safe with Exections +As for +.Nm Safe +but with specific exceptions noted. +.It Nm MT-Safe with Exections +As for +.Nm MT-Safe +but with specific exceptions noted. +.El +.It Em SECURITY +Documents any security precautions that operators should consider. +.It Em SEE ALSO +References other manuals with related topics. +This section should exist for most manuals. +Cross-references should conventionally be ordered first by section, then +alphabetically. +.Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp +See +.Sx \&Rs +and +.Sx \&Xr . +.It Em STANDARDS +References any standards implemented or used. +If not adhering to any standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Sx \&St . +.It Em HISTORY +A brief history of the subject, including where it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. +.It Em AUTHORS +Credits to the person or persons who wrote the code and/or documentation. +Authors should generally be noted by both name and email address. +.Pp +See +.Sx \&An . +.It Em CAVEATS +Common misuses and misunderstandings should be explained +in this section. +.It Em BUGS +Known bugs, limitations, and work-arounds should be described +in this section. +.El +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together, to help find the best macro for any given purpose. +Deprecated macros are not included in the overview, but can be found below +in the alphabetical +.Sx MACRO REFERENCE . +.Ss Document preamble and NAME section macros +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Dd Ta document date: Ar month day , year +.It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar volume | arch +.It Sx \&Os Ta operating system version: Op Ar system Op Ar version +.It Sx \&Nm Ta document name (one argument) +.It Sx \&Nd Ta document description (one line) +.El +.Ss Sections and cross references +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Sh Ta section header (one line) +.It Sx \&Ss Ta subsection header (one line) +.It Sx \&Sx Ta internal cross reference to a section or subsection +.It Sx \&Xr Ta cross reference to another manual page: Ar name section +.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments) +.El +.Ss Displays and lists +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Bd , \&Ed Ta display block: +.Fl Ar type +.Op Fl offset Ar width +.Op Fl compact +.It Sx \&D1 Ta indented display (one line) +.It Sx \&Dl Ta indented literal display (one line) +.It Sx \&Bl , \&El Ta list block: +.Fl Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.It Sx \&It Ta list item (syntax depends on Fl Ar type ) +.It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists +.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references) +.El +.Ss Spacing control +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Pf Ta prefix, no following horizontal space (one argument) +.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments) +.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) +.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off +.It Sx \&Bk , \&Ek Ta keep block: Fl words +.It Sx \&br Ta force output line break in text mode (no arguments) +.It Sx \&sp Ta force vertical space: Op Ar height +.El +.Ss Semantic markup for command line utilities: +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility +.It Sx \&Fl Ta command line options (flags) (>=0 arguments) +.It Sx \&Cm Ta command modifier (>0 arguments) +.It Sx \&Ar Ta command arguments (>=0 arguments) +.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) +.It Sx \&Ic Ta internal or interactive command (>0 arguments) +.It Sx \&Ev Ta environmental variable (>0 arguments) +.It Sx \&Pa Ta file system path (>=0 arguments) +.El +.Ss Semantic markup for function libraries: +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Lb Ta function library (one argument) +.It Sx \&In Ta include file (one argument) +.It Sx \&Ft Ta function type (>0 arguments) +.It Sx \&Fo , \&Fc Ta function block: Ar funcname +.It Sx \&Fn Ta function name: +.Op Ar functype +.Ar funcname +.Oo +.Op Ar argtype +.Ar argname +.Oc +.It Sx \&Fa Ta function argument (>0 arguments) +.It Sx \&Vt Ta variable type (>0 arguments) +.It Sx \&Va Ta variable name (>0 arguments) +.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments) +.It Sx \&Er Ta error constant (>0 arguments) +.It Sx \&Ev Ta environmental variable (>0 arguments) +.El +.Ss Various semantic markup: +.Bl -column "Brq, Bro, Brc" description +.It Sx \&An Ta author name (>0 arguments) +.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name +.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address +.It Sx \&Cd Ta kernel configuration declaration (>0 arguments) +.It Sx \&Ad Ta memory address (>0 arguments) +.It Sx \&Ms Ta mathematical symbol (>0 arguments) +.It Sx \&Tn Ta tradename (>0 arguments) +.El +.Ss Physical markup +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments) +.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments) +.It Sx \&Li Ta typewriter font (literal) (>0 arguments) +.It Sx \&No Ta return to roman font (normal) (no arguments) +.It Sx \&Bf , \&Ef Ta font block: +.Op Fl Ar type | Cm \&Em | \&Li | \&Sy +.El +.Ss Physical enclosures +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text +.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text +.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text +.It Sx \&Ql Ta single-quoted literal text: Ql text +.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text +.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text +.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text +.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text +.It Sx \&Eo , \&Ec Ta generic enclosure +.El +.Ss Text production +.Bl -column "Brq, Bro, Brc" description +.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ... +.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ... +.It Sx \&St Ta reference to a standards document (one argument) +.It Sx \&Ux Ta Ux +.It Sx \&At Ta At +.It Sx \&Bx Ta Bx +.It Sx \&Bsx Ta Bsx +.It Sx \&Nx Ta Nx +.It Sx \&Fx Ta Fx +.It Sx \&Ox Ta Ox +.It Sx \&Dx Ta Dx +.El +.Sh MACRO REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Ss \&%A +Author name of an +.Sx \&Rs +block. +Multiple authors should each be accorded their own +.Sx \%%A +line. +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.Ss \&%B +Book title of an +.Sx \&Rs +block. +This macro may also be used in a non-bibliographic context when +referring to book titles. +.Ss \&%C +Publication city or location of an +.Sx \&Rs +block. +.Ss \&%D +Publication date of an +.Sx \&Rs +block. +Recommended formats of arguments are +.Ar month day , year +or just +.Ar year . +.Ss \&%I +Publisher or issuer name of an +.Sx \&Rs +block. +.Ss \&%J +Journal name of an +.Sx \&Rs +block. +.Ss \&%N +Issue number (usually for journals) of an +.Sx \&Rs +block. +.Ss \&%O +Optional information of an +.Sx \&Rs +block. +.Ss \&%P +Book or journal page number of an +.Sx \&Rs +block. +.Ss \&%Q +Institutional author (school, government, etc.) of an +.Sx \&Rs +block. +Multiple institutional authors should each be accorded their own +.Sx \&%Q +line. +.Ss \&%R +Technical report name of an +.Sx \&Rs +block. +.Ss \&%T +Article title of an +.Sx \&Rs +block. +This macro may also be used in a non-bibliographical context when +referring to article titles. +.Ss \&%U +URI of reference document. +.Ss \&%V +Volume number of an +.Sx \&Rs +block. +.Ss \&Ac +Close an +.Sx \&Ao +block. +Does not have any tail arguments. +.Ss \&Ad +Memory address. +Do not use this for postal addresses. +.Pp +Examples: +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 +.Ss \&An +Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. +Requires either the name of an author or one of the following arguments: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact +.It Fl split +Start a new output line before each subsequent invocation of +.Sx \&An . +.It Fl nosplit +The opposite of +.Fl split . +.El +.Pp +The default is +.Fl nosplit . +The effect of selecting either of the +.Fl split +modes ends at the beginning of the +.Em AUTHORS +section. +In the +.Em AUTHORS +section, the default is +.Fl nosplit +for the first author listing and +.Fl split +for all other author listings. +.Pp +Examples: +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv +.Ss \&Ao +Begin a block enclosed by angle brackets. +Does not have any head arguments. +.Pp +Examples: +.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac +.Pp +See also +.Sx \&Aq . +.Ss \&Ap +Inserts an apostrophe without any surrounding whitespace. +This is generally used as a grammatical device when referring to the verb +form of a function. +.Pp +Examples: +.Dl \&.Fn execve \&Ap d +.Ss \&Aq +Encloses its arguments in angle brackets. +.Pp +Examples: +.Dl \&.Fl -key= \&Ns \&Aq \&Ar val +.Pp +.Em Remarks : +this macro is often abused for rendering URIs, which should instead use +.Sx \&Lk +or +.Sx \&Mt , +or to note pre-processor +.Dq Li #include +statements, which should use +.Sx \&In . +.Pp +See also +.Sx \&Ao . +.Ss \&Ar +Command arguments. +If an argument is not provided, the string +.Dq file ...\& +is used as a default. +.Pp +Examples: +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Sx \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Sx \&Fl +or +.Sx \&Cm . +.Ss \&At +Formats an AT&T version. +Accepts one optional argument: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact +.It Cm v[1-7] | 32v +A version of +.At . +.It Cm III +.At III . +.It Cm V[.[1-4]]? +A version of +.At V . +.El +.Pp +Note that these arguments do not begin with a hyphen. +.Pp +Examples: +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 +.Pp +See also +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Bc +Close a +.Sx \&Bo +block. +Does not have any tail arguments. +.Ss \&Bd +Begin a display block. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bd +.Fl Ns Ar type +.Op Fl offset Ar width +.Op Fl compact +.Ed +.Pp +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and text lines. +By default, a display block is preceded by a vertical space. +.Pp +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Produce one output line from each input line, and centre-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. +.It Fl filled +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. +.It Fl literal +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. +.It Fl ragged +Change the positions of line breaks to fill each line, and left-justify +the resulting block. +.It Fl unfilled +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. +.El +.Pp +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: +.Bl -item +.It +One of the pre-defined strings +.Cm indent , +the width of a standard indentation (six constant width characters); +.Cm indent-two , +twice +.Cm indent ; +.Cm left , +which has no effect; +.Cm right , +which justifies to the right margin; or +.Cm center , +which aligns around an imagined centre axis. +.It +A macro invocation, which selects a predefined width +associated with that macro. +The most popular is the imaginary macro +.Ar \&Ds , +which resolves to +.Sy 6n . +.It +A width using the syntax described in +.Sx Scaling Widths . +.It +An arbitrary string, which indents by the length of this string. +.El +.Pp +When the argument is missing, +.Fl offset +is ignored. +.It Fl compact +Do not assert vertical space before the display. +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent \-compact + Hello world. +\&.Ed +.Ed +.Pp +See also +.Sx \&D1 +and +.Sx \&Dl . +.Ss \&Bf +Change the font mode for a scoped block of text. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bf +.Oo +.Fl emphasis | literal | symbolic | +.Cm \&Em | \&Li | \&Sy +.Oc +.Ed +.Pp +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy , +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Sx \&Ef +is encountered. +.Pp +See also +.Sx \&Li , +.Sx \&Ef , +.Sx \&Em , +and +.Sx \&Sy . +.Ss \&Bk +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. +The syntax is as follows: +.Pp +.D1 Pf \. Sx \&Bk Fl words +.Pp +The +.Fl words +argument is required; additional arguments are ignored. +.Pp +The following example will not break within each +.Sx \&Op +macro line: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op Fl f Ar flags +\&.Op Fl o Ar output +\&.Ek +.Ed +.Pp +Be careful in using over-long lines within a keep block! +Doing so will clobber the right margin. +.Ss \&Bl +Begin a list. +Lists consist of items specified using the +.Sx \&It +macro, containing a head or a body or both. +The list syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bl +.Fl Ns Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op HEAD ... +.Ed +.Pp +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept +.Sx Scaling Widths +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp +A list must specify one of the following list types: +.Bl -tag -width 12n -offset indent +.It Fl bullet +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the +.Fl width +argument. +.It Fl column +A columnated list. +The +.Fl width +argument has no effect; instead, each argument specifies the width +of one column, using either the +.Sx Scaling Widths +syntax or the string length of the argument. +If the first line of the body of a +.Fl column +list is not an +.Sx \&It +macro line, +.Sx \&It +contexts spanning one input line each are implied until an +.Sx \&It +macro line is encountered, at which point items start being interpreted as +described in the +.Sx \&It +documentation. +.It Fl dash +Like +.Fl bullet , +except that dashes are used in place of bullets. +.It Fl diag +Like +.Fl inset , +except that item heads are not parsed for macro invocations. +Most often used in the +.Em DIAGNOSTICS +section with error constants in the item heads. +.It Fl enum +A numbered list. +No item heads can be specified. +Formatted like +.Fl bullet , +except that cardinal numbers are used in place of bullets, +starting at 1. +.It Fl hang +Like +.Fl tag , +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl item +No item heads can be specified, and none are printed. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl ohang +Item bodies start on the line following item heads and are not indented. +The +.Fl width +argument is ignored. +.It Fl tag +Item bodies are indented according to the +.Fl width +argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. +.El +.Pp +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.Pp +See also +.Sx \&El +and +.Sx \&It . +.Ss \&Bo +Begin a block enclosed by square brackets. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bo 1 , +\&.Dv BUFSIZ \&Bc +.Ed +.Pp +See also +.Sx \&Bq . +.Ss \&Bq +Encloses its arguments in square brackets. +.Pp +Examples: +.Dl \&.Bq 1 , \&Dv BUFSIZ +.Pp +.Em Remarks : +this macro is sometimes abused to emulate optional arguments for +commands; the correct macros to use for this purpose are +.Sx \&Op , +.Sx \&Oo , +and +.Sx \&Oc . +.Pp +See also +.Sx \&Bo . +.Ss \&Brc +Close a +.Sx \&Bro +block. +Does not have any tail arguments. +.Ss \&Bro +Begin a block enclosed by curly braces. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bro 1 , ... , +\&.Va n \&Brc +.Ed +.Pp +See also +.Sx \&Brq . +.Ss \&Brq +Encloses its arguments in curly braces. +.Pp +Examples: +.Dl \&.Brq 1 , ... , \&Va n +.Pp +See also +.Sx \&Bro . +.Ss \&Bsx +Format the BSD/OS version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Bsx 1.0 +.Dl \&.Bsx +.Pp +See also +.Sx \&At , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Bt +Prints +.Dq is currently in beta test. +.Ss \&Bx +Format the BSD version provided as an argument, or a default value if no +argument is provided. +.Pp +Examples: +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Cd +Kernel configuration declaration. It is found in pages for +.Bx +and not used here. +.Pp +Examples: +.Dl \&.Cd device le0 at scode? +.Pp +.Em Remarks : +this macro is commonly abused by using quoted literals to retain +whitespace and align consecutive +.Sx \&Cd +declarations. +This practise is discouraged. +.Ss \&Cm +Command modifiers. +Typically used for fixed strings passed as arguments, unless +.Sx \&Fl +is more appropriate. +Also useful when specifying configuration options or keys. +.Pp +Examples: +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" +.Dl ".Cm LogLevel Dv DEBUG" +.Ss \&D1 +One-line indented display. +This is formatted by the default rules and is useful for simple indented +statements. +It is followed by a newline. +.Pp +Examples: +.Dl \&.D1 \&Fl abcdefgh +.Pp +See also +.Sx \&Bd +and +.Sx \&Dl . +.Ss \&Db +Switch debugging mode. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Db Cm on | off +.Pp +This macro is ignored by +.Xr mandoc 1 . +.Ss \&Dc +Close a +.Sx \&Do +block. +Does not have any tail arguments. +.Ss \&Dd +Document date. +This is the mandatory first macro of any +.Nm +manual. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Dd Ar month day , year +.Pp +The +.Ar month +is the full English month name, the +.Ar day +is an optionally zero-padded numeral, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of +.Xr cvs 1 , +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +A few alternative date formats are accepted as well +and converted to the standard form. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El +.Pp +Examples: +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 21 2007$ +.Dl \&.Dd July 21, 2007 +.Pp +See also +.Sx \&Dt +and +.Sx \&Os . +.Ss \&Dl +One-line intended display. +This is formatted as literal text and is useful for commands and +invocations. +It is followed by a newline. +.Pp +Examples: +.Dl \&.Dl % mandoc mdoc.5 \e(ba less +.Pp +See also +.Sx \&Bd +and +.Sx \&D1 . +.Ss \&Do +Begin a block enclosed by double quotes. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Do +April is the cruellest month +\&.Dc +\e(em T.S. Eliot +.Ed +.Pp +See also +.Sx \&Dq . +.Ss \&Dq +Encloses its arguments in +.Dq typographic +double-quotes. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Dq April is the cruellest month +\e(em T.S. Eliot +.Ed +.Pp +See also +.Sx \&Qq , +.Sx \&Sq , +and +.Sx \&Do . +.Ss \&Dt +Document title. +This is the mandatory second macro of any +.Nm +file. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Dt +.Oo +.Ar title +.Oo +.Ar section +.Op Ar volume +.Op Ar arch +.Oc +.Oc +.Ed +.Pp +Its arguments are as follows: +.Bl -tag -width Ds -offset Ds +.It Ar title +The document's title (name), defaulting to +.Dq UNKNOWN +if unspecified. +It should be capitalised. +.It Ar section +The manual section. It should correspond to the manual's filename suffix +and defaults to +.Dq 1 +if unspecified. +.It Ar volume +This overrides the volume inferred from +.Ar section . +This field is optional. +.It Ar arch +This specifies the machine architecture a manual page applies to, +where relevant. +.El +.Ss \&Dv +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. +.Pp +Examples: +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO +.Pp +See also +.Sx \&Er +and +.Sx \&Ev +for special-purpose constants and +.Sx \&Va +for variable symbols. +.Ss \&Dx +Format the DragonFly BSD version provided as an argument, or a default +value if no argument is provided. +.Pp +Examples: +.Dl \&.Dx 2.4.1 +.Dl \&.Dx +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Ec +Close a scope started by +.Sx \&Eo . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ec Op Ar TERM +.Pp +The +.Ar TERM +argument is used as the enclosure tail, for example, specifying \e(rq +will emulate +.Sx \&Dc . +.Ss \&Ed +End a display context started by +.Sx \&Bd . +.Ss \&Ef +End a font mode context started by +.Sx \&Bf . +.Ss \&Ek +End a keep context started by +.Sx \&Bk . +.Ss \&El +End a list context started by +.Sx \&Bl . +.Pp +See also +.Sx \&Bl +and +.Sx \&It . +.Ss \&Em +Denotes text that should be +.Em emphasised . +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +Depending on the output device, this is usually represented +using an italic font or underlined characters. +.Pp +Examples: +.Dl \&.Em Warnings! +.Dl \&.Em Remarks : +.Pp +See also +.Sx \&Bf , +.Sx \&Li , +.Sx \&No , +and +.Sx \&Sy . +.Ss \&En +This macro is obsolete and not implemented in +.Xr mandoc 1 . +.Ss \&Eo +An arbitrary enclosure. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Eo Op Ar TERM +.Pp +The +.Ar TERM +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Sx \&Do . +.Ss \&Er +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. +.Pp +Examples: +.Dl \&.Er EPERM +.Dl \&.Er ENOENT +.Pp +See also +.Sx \&Dv +for general constants. +.Ss \&Es +This macro is obsolete and not implemented. +.Ss \&Ev +Environmental variables such as those specified in +.Xr environ 5 . +.Pp +Examples: +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Sx \&Dv +for general constants. +.Ss \&Ex +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1 and 1M manual pages. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... +.Pp +If +.Ar utility +is not specified, the document's name set by +.Sx \&Nm +is used. +Multiple +.Ar utility +arguments are treated as separate utilities. +.Pp +See also +.Sx \&Rv . +.Ss \&Fa +Function argument. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Fa +.Op Cm argtype +.Cm argname +.Ed +.Pp +This may be invoked for names with or without the corresponding type. +It is also used to specify the field name of a structure. +Most often, the +.Sx \&Fa +macro is used in the +.Em SYNOPSIS +within +.Sx \&Fo +section when documenting multi-line function prototypes. +If invoked with multiple arguments, the arguments are separated by a +comma. +Furthermore, if the following macro is another +.Sx \&Fa , +the last argument will also have a trailing comma. +.Pp +Examples: +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa foo +.Pp +See also +.Sx \&Fo . +.Ss \&Fc +End a function context started by +.Sx \&Fo . +.Ss \&Fd +Historically used to document include files. +This usage has been deprecated in favour of +.Sx \&In . +Do not use this macro. +.Pp +See also +.Sx MANUAL STRUCTURE +and +.Sx \&In . +.Ss \&Fl +Command-line flag or option. +Used when listing arguments to command-line utilities. +Prints a fixed-width hyphen +.Sq \- +directly followed by each argument. +If no arguments are provided, a hyphen is printed followed by a space. +If the argument is a macro, a hyphen is prefixed to the subsequent macro +output. +.Pp +Examples: +.Dl ".Fl R Op Fl H | L | P" +.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Fl type Cm d Fl name Pa CVS" +.Dl ".Fl Ar signal_number" +.Dl ".Fl o Fl" +.Pp +See also +.Sx \&Cm . +.Ss \&Fn +A function name. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Ns Sx \&Fn +.Op Ar functype +.Ar funcname +.Op Oo Ar argtype Oc Ar argname +.Ed +.Pp +Function arguments are surrounded in parenthesis and +are delimited by commas. +If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. +.Pp +Examples: +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq +.Dl \&.Fn funcname arg0 +.Pp +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +When referring to a function documented in another manual page, use +.Sx \&Xr +instead. +See also +.Sx MANUAL STRUCTURE , +.Sx \&Fo , +and +.Sx \&Ft . +.Ss \&Fo +Begin a function block. +This is a multi-line version of +.Sx \&Fn . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Fo Ar funcname +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Sx \&Ft Ar functype +.br +.Pf \. Sx \&Fo Ar funcname +.br +.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname +.br +\&.\.\. +.br +.Pf \. Sx \&Fc +.Ed +.Pp +A +.Sx \&Fo +scope is closed by +.Sx \&Fc . +.Pp +See also +.Sx MANUAL STRUCTURE , +.Sx \&Fa , +.Sx \&Fc , +and +.Sx \&Ft . +.Ss \&Fr +This macro is obsolete and not implemented in +.Xr mandoc 1 . +.Pp +It was used to show function return values. +The syntax was: +.Pp +.Dl Pf . Sx \&Fr Ar value +.Ss \&Ft +A function type. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ft Ar functype +.Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp +Examples: +.Dl \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx MANUAL STRUCTURE , +.Sx \&Fn , +and +.Sx \&Fo . +.Ss \&Fx +Format the +.Fx +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Fx 7.1 +.Dl \&.Fx +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Hf +This macro is not implemented in +.Xr mandoc 1 . +.Pp +It was used to include the contents of a (header) file literally. +The syntax was: +.Pp +.Dl Pf . Sx \&Hf Ar filename +.Ss \&Ic +Designate an internal or interactive command. +This is similar to +.Sx \&Cm +but used for instructions rather than values. +.Pp +Examples: +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias +.Pp +Note that using +.Sx \&Bd Fl literal +or +.Sx \&D1 +is preferred for displaying code; the +.Sx \&Ic +macro is used when referring to specific instructions. +.Ss \&In +An +.Dq include +file. +When invoked as the first macro on an input line in the +.Em SYNOPSIS +section, the argument is displayed in angle brackets +and preceded by +.Dq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +This is most often used in section 2, 3, and 9 manual pages. +.Pp +Examples: +.Dl \&.In sys/types.h +.Pp +See also +.Sx MANUAL STRUCTURE . +.Ss \&It +A list item. +The syntax of this macro depends on the list type. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following syntax: +.Pp +.D1 Pf \. Sx \&It Ar args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following syntax: +.Pp +.D1 Pf \. Sx \&It +.Pp +with subsequent lines interpreted within the scope of the +.Sx \&It +until either a closing +.Sx \&El +or another +.Sx \&It . +.Pp +The +.Fl tag +list has the following syntax: +.Pp +.D1 Pf \. Sx \&It Op Cm args +.Pp +Subsequent lines are interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... +.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... +.Pp +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by tabs or by the special +.Sx \&Ta +block macro. +The tab cell delimiter may only be used within the +.Sx \&It +line itself; on following lines, only the +.Sx \&Ta +macro can be used to delimit cells, and +.Sx \&Ta +is only recognised as a macro when called by other macros, +not as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an +.Sx \&It +line. +For example, +.Pp +.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; +.Pp +will preserve the semicolon whitespace except for the last. +.Pp +See also +.Sx \&Bl . +.Ss \&Lb +Specify a library. +The syntax is as follows: +.Pp +.D1 Pf \. Sx \&Lb Ar library +.Pp +The +.Ar library +parameter may be a system library, such as +.Cm libz +or +.Cm libpam , +in which case a small library description is printed next to the linker +invocation; or a custom library, in which case the library name is +printed in quotes. +This is most commonly used in the +.Em SYNOPSIS +section as described in +.Sx MANUAL STRUCTURE . +.Pp +Examples: +.Dl \&.Lb libz +.Dl \&.Lb mdoc +.Ss \&Li +Denotes text that should be in a +.Li literal +font mode. +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +.Pp +On terminal output devices, this is often indistinguishable from +normal text. +.Pp +See also +.Sx \&Bf , +.Sx \&Em , +.Sx \&No , +and +.Sx \&Sy . +.Ss \&Lk +Format a hyperlink. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Lk Ar uri Op Ar name +.Pp +Examples: +.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq +.Dl \&.Lk http://bsd.lv +.Pp +See also +.Sx \&Mt . +.Ss \&Lp +Synonym for +.Sx \&Pp . +.Ss \&Ms +Display a mathematical symbol. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ms Ar symbol +.Pp +Examples: +.Dl \&.Ms sigma +.Dl \&.Ms aleph +.Ss \&Mt +Format a +.Dq mailto: +hyperlink. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Mt Ar address +.Pp +Examples: +.Dl \&.Mt discuss@manpages.bsd.lv +.Ss \&Nd +A one line description of the manual's content. +This may only be invoked in the +.Em SYNOPSIS +section subsequent the +.Sx \&Nm +macro. +.Pp +Examples: +.Dl Pf . Sx \&Nd mdoc language reference +.Dl Pf . Sx \&Nd format and display UNIX manuals +.Pp +The +.Sx \&Nd +macro technically accepts child macros and terminates with a subsequent +.Sx \&Sh +invocation. +Do not assume this behaviour: some +.Xr whatis 1 +database generators are not smart enough to parse more than the line +arguments and will display macros verbatim. +.Pp +See also +.Sx \&Nm . +.Ss \&Nm +The name of the manual page, or \(em in particular in section 1 +and 1M pages \(em of an additional command or feature documented in +the manual page. +When first invoked, the +.Sx \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Sx \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Sx \&Fn +macro rather than +.Sx \&Nm +to mark up the name of the manual page. +.Ss \&No +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Sx \&Em +or +.Sx \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. +.Pp +Examples: +.Dl ".Em italic , Sy bold , No and roman" +.Pp +.Bd -literal -offset indent -compact +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed +.Pp +See also +.Sx \&Em , +.Sx \&Li , +and +.Sx \&Sy . +.Ss \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Sx \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp +Examples: +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".Fl o Ns Ar output" +.Pp +See also +.Sx \&No +and +.Sx \&Sm . +.Ss \&Nx +Format the +.Nx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Nx 5.01 +.Dl \&.Nx +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Ox , +and +.Sx \&Ux . +.Ss \&Oc +Close multi-line +.Sx \&Oo +context. +.Ss \&Oo +Multi-line version of +.Sx \&Op . +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Oo +\&.Op Fl flag Ns Ar value +\&.Oc +.Ed +.Ss \&Op +Optional part of a command line. +Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 1M manual pages. +.Pp +Examples: +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b +.Pp +See also +.Sx \&Oo . +.Ss \&Os +Document operating system version. +This is the mandatory third macro of +any +.Nm +file. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Os Op Ar system Op Ar version +.Pp +The optional +.Ar system +parameter specifies the relevant operating system or environment. +Left unspecified, it defaults to the local operating system version. +This is the suggested form. +.Pp +Examples: +.Dl \&.Os +.Dl \&.Os KTH/CSC/TCS +.Dl \&.Os BSD 4.3 +.Pp +See also +.Sx \&Dd +and +.Sx \&Dt . +.Ss \&Ot +This macro is obsolete and not implemented in +.Xr mandoc 1 . +.Pp +Historical +.Xr mdoc 5 +packages described it as +.Dq "old function type (FORTRAN)" . +.Ss \&Ox +Format the +.Ox +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Ox 4.5 +.Dl \&.Ox +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +and +.Sx \&Ux . +.Ss \&Pa +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. +.Pp +Examples: +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man5/mdoc.5 +.Pp +See also +.Sx \&Lk . +.Ss \&Pc +Close parenthesised context opened by +.Sx \&Po . +.Ss \&Pf +Removes the space between its argument +.Pq Dq prefix +and the following macro. +Its syntax is as follows: +.Pp +.D1 .Pf Ar prefix macro arguments ... +.Pp +This is equivalent to: +.Pp +.D1 .No Ar prefix No \&Ns Ar macro arguments ... +.Pp +Examples: +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Sx \&Ns +and +.Sx \&Sm . +.Ss \&Po +Multi-line version of +.Sx \&Pq . +.Ss \&Pp +Break a paragraph. +This will assert vertical space between prior and subsequent macros +and/or text. +.Pp +Paragraph breaks are not needed before or after +.Sx \&Sh +or +.Sx \&Ss +macros or before displays +.Pq Sx \&Bd +or lists +.Pq Sx \&Bl +unless the +.Fl compact +flag is given. +.Ss \&Pq +Parenthesised enclosure. +.Pp +See also +.Sx \&Po . +.Ss \&Qc +Close quoted context opened by +.Sx \&Qo . +.Ss \&Ql +Format a single-quoted literal. +See also +.Sx \&Qq +and +.Sx \&Sq . +.Ss \&Qo +Multi-line version of +.Sx \&Qq . +.Ss \&Qq +Encloses its arguments in +.Qq typewriter +double-quotes. +Consider using +.Sx \&Dq . +.Pp +See also +.Sx \&Dq , +.Sx \&Sq , +and +.Sx \&Qo . +.Ss \&Re +Close an +.Sx \&Rs +block. +Does not have any tail arguments. +.Ss \&Rs +Begin a bibliographic +.Pq Dq reference +block. +Does not have any head arguments. +The block macro may only contain +.Sx \&%A , +.Sx \&%B , +.Sx \&%C , +.Sx \&%D , +.Sx \&%I , +.Sx \&%J , +.Sx \&%N , +.Sx \&%O , +.Sx \&%P , +.Sx \&%Q , +.Sx \&%R , +.Sx \&%T , +.Sx \&%U , +and +.Sx \&%V +child macros (at least one must be specified). +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusettes +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Sx \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Ss \&Rv +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Rv Fl std Op Ar function ... +.Pp +If +.Ar function +is not specified, the document's name set by +.Sx \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. +.Pp +See also +.Sx \&Ex . +.Ss \&Sc +Close single-quoted context opened by +.Sx \&So . +.Ss \&Sh +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +These sections should be used unless it's absolutely necessary that +custom sections be used. +.Pp +Section names should be unique so that they may be keyed by +.Sx \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Ss , +and +.Sx \&Sx . +.Ss \&Sm +Switches the spacing mode for output generated from macros. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Sm Cm on | off +.Pp +By default, spacing is +.Cm on . +When switched +.Cm off , +no white space is inserted between macro arguments and between the +output generated from adjacent macros, but text lines +still get normal spacing between words and sentences. +.Ss \&So +Multi-line version of +.Sx \&Sq . +.Ss \&Sq +Encloses its arguments in +.Sq typewriter +single-quotes. +.Pp +See also +.Sx \&Dq , +.Sx \&Qq , +and +.Sx \&So . +.Ss \&Ss +Begin a new subsection. +Unlike with +.Sx \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +the conventional sections described in +.Sx MANUAL STRUCTURE +rarely have subsections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Sx \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Sh , +and +.Sx \&Sx . +.Ss \&St +Replace an abbreviation for a standard with the full form. +The following standards are recognised: +.Pp +.Bl -tag -width "-p1003.1g-2000X" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1-90 +.St -p1003.1-90 +.It \-p1003.1-96 +.St -p1003.1-96 +.It \-p1003.1-2001 +.St -p1003.1-2001 +.It \-p1003.1-2004 +.St -p1003.1-2004 +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-p1003.1 +.St -p1003.1 +.It \-p1003.1b +.St -p1003.1b +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1c-95 +.St -p1003.1c-95 +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.It \-p1003.1i-95 +.St -p1003.1i-95 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-p1003.2a-92 +.St -p1003.2a-92 +.It \-p1387.2-95 +.St -p1387.2-95 +.It \-p1003.2 +.St -p1003.2 +.It \-p1387.2 +.St -p1387.2 +.It \-isoC +.St -isoC +.It \-isoC-90 +.St -isoC-90 +.It \-isoC-amd1 +.St -isoC-amd1 +.It \-isoC-tcor1 +.St -isoC-tcor1 +.It \-isoC-tcor2 +.St -isoC-tcor2 +.It \-isoC-99 +.St -isoC-99 +.It \-isoC-2011 +.St -isoC-2011 +.It \-iso9945-1-90 +.St -iso9945-1-90 +.It \-iso9945-1-96 +.St -iso9945-1-96 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 +.It \-ansiC-99 +.St -ansiC-99 +.It \-ieee754 +.St -ieee754 +.It \-iso8802-3 +.St -iso8802-3 +.It \-iso8601 +.St -iso8601 +.It \-ieee1275-94 +.St -ieee1275-94 +.It \-xpg3 +.St -xpg3 +.It \-xpg4 +.St -xpg4 +.It \-xpg4.2 +.St -xpg4.2 +.It \-xpg4.3 +.St -xpg4.3 +.It \-xbd5 +.St -xbd5 +.It \-xcu5 +.St -xcu5 +.It \-xsh5 +.St -xsh5 +.It \-xns5 +.St -xns5 +.It \-xns5.2 +.St -xns5.2 +.It \-xns5.2d2.0 +.St -xns5.2d2.0 +.It \-xcurses4.2 +.St -xcurses4.2 +.It \-susv2 +.St -susv2 +.It \-susv3 +.St -susv3 +.It \-svid4 +.St -svid4 +.El +.Ss \&Sx +Reference a section or subsection in the same manual page. +The referenced section or subsection name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Sx \&Sh +and +.Sx \&Ss . +.Ss \&Sy +Format enclosed arguments in symbolic +.Pq Dq boldface . +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +.Pp +See also +.Sx \&Bf , +.Sx \&Em , +.Sx \&Li , +and +.Sx \&No . +.Ss \&Ta +Table cell separator in +.Sx \&Bl Fl column +lists; can only be used below +.Sx \&It . +.Ss \&Tn +Format a tradename. +.Pp +Since this macro is often implemented to use a small caps font, +it has historically been used for acronyms (like ASCII) as well. +Such usage is not recommended because it would use the same macro +sometimes for semantical annotation, sometimes for physical formatting. +.Pp +Examples: +.Dl \&.Tn IBM +.Ss \&Ud +Prints out +.Dq currently under development. +.Ss \&Ux +Format the UNIX name. +Accepts no argument. +.Pp +Examples: +.Dl \&.Ux +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +and +.Sx \&Ox . +.Ss \&Va +A variable name. +.Pp +Examples: +.Dl \&.Va foo +.Dl \&.Va const char *bar ; +.Ss \&Vt +A variable type. +This is also used for indicating global variables in the +.Em SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro on an input line in the +.Em SYNOPSIS +section, else it accepts ordinary +.Sx In-line +syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. +.Pp +Note that this should not be confused with +.Sx \&Ft , +which is used for function return types. +.Pp +Examples: +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; +.Pp +See also +.Sx MANUAL STRUCTURE +and +.Sx \&Va . +.Ss \&Xc +Close a scope opened by +.Sx \&Xo . +.Ss \&Xo +Extend the header of an +.Sx \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 5 . +.Ss \&Xr +Link to another manual +.Pq Qq cross-reference . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Xr Ar name section +.Pp +The +.Ar name +and +.Ar section +are the name and section of the linked manual. +If +.Ar section +is followed by non-punctuation, an +.Sx \&Ns +is inserted into the token stream. +This behaviour is for compatibility with +GNU troff. +.Pp +Examples: +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour +.Ss \&br +Emits a line-break. +This macro should not be used; it is implemented for compatibility with +historical manuals. +.Pp +Consider using +.Sx \&Pp +in the event of natural paragraph breaks. +.Ss \&sp +Emits vertical space. +This macro should not be used; it is implemented for compatibility with +historical manuals. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&sp Op Ar height +.Pp +The +.Ar height +argument must be formatted as described in +.Sx Scaling Widths . +If unspecified, +.Sx \&sp +asserts a single vertical space. +.Sh MACRO SYNTAX +The syntax of a macro depends on its classification. +In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. +.Pp +The +.Em Callable +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +.Pp +The +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. +.Pp +The +.Em Scope +column, if applicable, describes closure rules. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only +.Sx \&Bf +and +.Pq optionally +.Sx \&Bl +contain a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed +.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef +.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek +.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El +.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd +.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf +.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk +.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl +.El +.Ss Block full-implicit +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some +.Po +.Sx \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +don't have heads; only one +.Po +.Sx \&It +in +.Sx \&Bl Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El +.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh +.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss +.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh +.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss +.El +.Pp +Note that the +.Sx \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head +.Po +.Sx \&Fo , +.Sx \&Eo +.Pc +and/or tail +.Pq Sx \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao +.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac +.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo +.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc +.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro +.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc +.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do +.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc +.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo +.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec +.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo +.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc +.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo +.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc +.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po +.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc +.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo +.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc +.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs +.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re +.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So +.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc +.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo +.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc +.El +.Ss Block partial-implicit +Like block full-implicit, but with single-line scope closed by the +end of the line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed +.It Sx \&Aq Ta Yes Ta Yes +.It Sx \&Bq Ta Yes Ta Yes +.It Sx \&Brq Ta Yes Ta Yes +.It Sx \&D1 Ta \&No Ta \&Yes +.It Sx \&Dl Ta \&No Ta Yes +.It Sx \&Dq Ta Yes Ta Yes +.It Sx \&Op Ta Yes Ta Yes +.It Sx \&Pq Ta Yes Ta Yes +.It Sx \&Ql Ta Yes Ta Yes +.It Sx \&Qq Ta Yes Ta Yes +.It Sx \&Sq Ta Yes Ta Yes +.It Sx \&Vt Ta Yes Ta Yes +.El +.Pp +Note that the +.Sx \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Special block macro +The +.Sx \&Ta +macro can only be used below +.Sx \&It +in +.Sx \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It +.El +.Ss In-line +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments +.It Sx \&%A Ta \&No Ta \&No Ta >0 +.It Sx \&%B Ta \&No Ta \&No Ta >0 +.It Sx \&%C Ta \&No Ta \&No Ta >0 +.It Sx \&%D Ta \&No Ta \&No Ta >0 +.It Sx \&%I Ta \&No Ta \&No Ta >0 +.It Sx \&%J Ta \&No Ta \&No Ta >0 +.It Sx \&%N Ta \&No Ta \&No Ta >0 +.It Sx \&%O Ta \&No Ta \&No Ta >0 +.It Sx \&%P Ta \&No Ta \&No Ta >0 +.It Sx \&%Q Ta \&No Ta \&No Ta >0 +.It Sx \&%R Ta \&No Ta \&No Ta >0 +.It Sx \&%T Ta \&No Ta \&No Ta >0 +.It Sx \&%U Ta \&No Ta \&No Ta >0 +.It Sx \&%V Ta \&No Ta \&No Ta >0 +.It Sx \&Ad Ta Yes Ta Yes Ta >0 +.It Sx \&An Ta Yes Ta Yes Ta >0 +.It Sx \&Ap Ta Yes Ta Yes Ta 0 +.It Sx \&Ar Ta Yes Ta Yes Ta n +.It Sx \&At Ta Yes Ta Yes Ta 1 +.It Sx \&Bsx Ta Yes Ta Yes Ta n +.It Sx \&Bt Ta \&No Ta \&No Ta 0 +.It Sx \&Bx Ta Yes Ta Yes Ta n +.It Sx \&Cd Ta Yes Ta Yes Ta >0 +.It Sx \&Cm Ta Yes Ta Yes Ta >0 +.It Sx \&Db Ta \&No Ta \&No Ta 1 +.It Sx \&Dd Ta \&No Ta \&No Ta n +.It Sx \&Dt Ta \&No Ta \&No Ta n +.It Sx \&Dv Ta Yes Ta Yes Ta >0 +.It Sx \&Dx Ta Yes Ta Yes Ta n +.It Sx \&Em Ta Yes Ta Yes Ta >0 +.It Sx \&En Ta \&No Ta \&No Ta 0 +.It Sx \&Er Ta Yes Ta Yes Ta >0 +.It Sx \&Es Ta \&No Ta \&No Ta 0 +.It Sx \&Ev Ta Yes Ta Yes Ta >0 +.It Sx \&Ex Ta \&No Ta \&No Ta n +.It Sx \&Fa Ta Yes Ta Yes Ta >0 +.It Sx \&Fd Ta \&No Ta \&No Ta >0 +.It Sx \&Fl Ta Yes Ta Yes Ta n +.It Sx \&Fn Ta Yes Ta Yes Ta >0 +.It Sx \&Fr Ta \&No Ta \&No Ta n +.It Sx \&Ft Ta Yes Ta Yes Ta >0 +.It Sx \&Fx Ta Yes Ta Yes Ta n +.It Sx \&Hf Ta \&No Ta \&No Ta n +.It Sx \&Ic Ta Yes Ta Yes Ta >0 +.It Sx \&In Ta \&No Ta \&No Ta 1 +.It Sx \&Lb Ta \&No Ta \&No Ta 1 +.It Sx \&Li Ta Yes Ta Yes Ta >0 +.It Sx \&Lk Ta Yes Ta Yes Ta >0 +.It Sx \&Lp Ta \&No Ta \&No Ta 0 +.It Sx \&Ms Ta Yes Ta Yes Ta >0 +.It Sx \&Mt Ta Yes Ta Yes Ta >0 +.It Sx \&Nm Ta Yes Ta Yes Ta n +.It Sx \&No Ta Yes Ta Yes Ta 0 +.It Sx \&Ns Ta Yes Ta Yes Ta 0 +.It Sx \&Nx Ta Yes Ta Yes Ta n +.It Sx \&Os Ta \&No Ta \&No Ta n +.It Sx \&Ot Ta \&No Ta \&No Ta n +.It Sx \&Ox Ta Yes Ta Yes Ta n +.It Sx \&Pa Ta Yes Ta Yes Ta n +.It Sx \&Pf Ta Yes Ta Yes Ta 1 +.It Sx \&Pp Ta \&No Ta \&No Ta 0 +.It Sx \&Rv Ta \&No Ta \&No Ta n +.It Sx \&Sm Ta \&No Ta \&No Ta 1 +.It Sx \&St Ta \&No Ta Yes Ta 1 +.It Sx \&Sx Ta Yes Ta Yes Ta >0 +.It Sx \&Sy Ta Yes Ta Yes Ta >0 +.It Sx \&Tn Ta Yes Ta Yes Ta >0 +.It Sx \&Ud Ta \&No Ta \&No Ta 0 +.It Sx \&Ux Ta Yes Ta Yes Ta n +.It Sx \&Va Ta Yes Ta Yes Ta n +.It Sx \&Vt Ta Yes Ta Yes Ta >0 +.It Sx \&Xr Ta Yes Ta Yes Ta >0 +.It Sx \&br Ta \&No Ta \&No Ta 0 +.It Sx \&sp Ta \&No Ta \&No Ta 1 +.El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&. +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. +.Ss Font handling +In +.Nm +documents, usage of semantic markup is recommended in order to have +proper fonts automatically selected; only when no fitting semantic markup +is available, consider falling back to +.Sx Physical markup +macros. +Whenever any +.Nm +macro switches the +.Xr roff 5 +font mode, it will automatically restore the previous font when exiting +its scope. +Manually switching the font using the +.Xr roff 5 +.Ql \ef +font escape sequences is never required. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . +The term +.Qq historic groff +refers to groff versions before 1.17, +which featured a significant update of the +.Pa doc.tmac +file. +.Pp +Heirloom troff, the other significant troff implementation accepting +\-mdoc, is similar to historic groff. +.Pp +The following problematic behaviour is found in groff: +.ds hist (Historic groff only.) +.Pp +.Bl -dash -compact +.It +Display macros +.Po +.Sx \&Bd , +.Sx \&Dl , +and +.Sx \&D1 +.Pc +may not be nested. +\*[hist] +.It +.Sx \&At +with unknown arguments produces no output at all. +\*[hist] +Newer groff and mandoc print +.Qq AT&T UNIX +and the arguments. +.It +.Sx \&Bl Fl column +does not recognise trailing punctuation characters when they immediately +precede tabulator characters, but treats them as normal text and +outputs a space before them. +.It +.Sx \&Bd Fl ragged compact +does not start a new line. +\*[hist] +.It +.Sx \&Dd +with non-standard arguments behaves very strangely. +When there are three arguments, they are printed verbatim. +Any other number of arguments is replaced by the current date, +but without any arguments the string +.Dq Epoch +is printed. +.It +.Sx \&Fl +does not print a dash for an empty argument. +\*[hist] +.It +.Sx \&Fn +does not start a new line unless invoked as the line macro in the +.Em SYNOPSIS +section. +\*[hist] +.It +.Sx \&Fo +with +.Pf non- Sx \&Fa +children causes inconsistent spacing between arguments. +In mandoc, a single space is always inserted between arguments. +.It +.Sx \&Ft +in the +.Em SYNOPSIS +causes inconsistent vertical spacing, depending on whether a prior +.Sx \&Fn +has been invoked. +See +.Sx \&Ft +and +.Sx \&Fn +for the normalised behaviour in mandoc. +.It +.Sx \&In +ignores additional arguments and is not treated specially in the +.Em SYNOPSIS . +\*[hist] +.It +.Sx \&It +sometimes requires a +.Fl nested +flag. +\*[hist] +In new groff and mandoc, any list may be nested by default and +.Fl enum +lists will restart the sequence only for the sub-list. +.It +.Sx \&Li +followed by a delimiter is incorrectly used in some manuals +instead of properly quoting that character, which sometimes works with +historic groff. +.It +.Sx \&Lk +only accepts a single link-name argument; the remainder is misformatted. +.It +.Sx \&Pa +does not format its arguments when used in the FILES section under +certain list types. +.It +.Sx \&Ta +can only be called by other macros, but not at the beginning of a line. +.It +.Sx \&%C +is not implemented. +.It +Historic groff only allows up to eight or nine arguments per macro input +line, depending on the exact situation. +Providing more arguments causes garbled output. +The number of arguments on one input line is not limited with mandoc. +.It +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are callable +in new groff and mandoc. +.It +.Sq \(ba +(vertical bar) is not fully supported as a delimiter. +\*[hist] +.It +.Sq \ef +.Pq font face +and +.Sq \ef +.Pq font family face +.Sx Text Decoration +escapes behave irregularly when specified within line-macro scopes. +.It +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact +.It +.Sx \&Bd +.Fl file Ar file . +.It +.Sx \&Bd +.Fl offset Ar center +and +.Fl offset Ar right . +Groff does not implement centred and flush-right rendering either, +but produces large indentations. +.It +The +.Sq \eh +.Pq horizontal position , +.Sq \ev +.Pq vertical position , +.Sq \em +.Pq text colour , +.Sq \eM +.Pq text filling colour , +.Sq \ez +.Pq zero-length character , +.Sq \ew +.Pq string length , +.Sq \ek +.Pq horizontal position marker , +.Sq \eo +.Pq text overstrike , +and +.Sq \es +.Pq text size +escape sequences are all discarded in mandoc. +.It +The +.Sq \ef +scaling unit is accepted by mandoc, but rendered as the default unit. +.It +In quoted literals, groff allows pairwise double-quotes to produce a +standalone double-quote in formatted output. +This is not supported by mandoc. +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 5 , +.Xr man 5 , +.Xr mandoc_char 5 , +.Xr roff 5 , +.Xr tbl 5 +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . +.Sh AUTHORS +The +.Nm +reference was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/usr/src/man/man5/tbl.5 b/usr/src/man/man5/tbl.5 new file mode 100644 index 0000000000..fe142208e8 --- /dev/null +++ b/usr/src/man/man5/tbl.5 @@ -0,0 +1,349 @@ +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. +.\" +.Dd Sep 3, 2011 +.Dt TBL 5 +.Os +.Sh NAME +.Nm tbl +.Nd tbl language reference for mandoc +.Sh DESCRIPTION +The +.Nm tbl +language is a table-formatting language. +It is used within +.Xr mdoc 5 +and +.Xr man 5 +.Ux +manual pages. +This manual describes the subset of the +.Nm +language accepted by the +.Xr mandoc 1 +utility. +.Pp +Tables within +.Xr mdoc 5 +or +.Xr man 5 +are enclosed by the +.Sq TS +and +.Sq TE +macro tags, whose precise syntax is documented in +.Xr roff 5 . +Tables consist of a series of options on a single line, followed by the +table layout, followed by data. +.Pp +For example, the following creates a boxed table with digits centred in +the cells. +.Bd -literal -offset indent +\&.TS +tab(:) box; +c5 c5 c5. +1:2:3 +4:5:6 +\&.TE +.Ed +.Pp +When formatted, the following output is produced: +.Bd -filled -offset indent -compact +.TS +tab(:) box; +c5 c5 c5. +1:2:3 +4:5:6 +.TE +.Ed +.Pp +The +.Nm +implementation in +.Xr mandoc 1 +is +.Ud +.Sh TABLE STRUCTURE +Tables are enclosed by the +.Sq TS +and +.Sq TE +.Xr roff 5 +macros. +A table consists of an optional single line of table +.Sx Options +terminated by a semicolon, followed by one or more lines of +.Sx Layout +specifications terminated by a period, then +.Sx Data . +All input must be 7-bit ASCII. +Example: +.Bd -literal -offset indent +\&.TS +box tab(:); +c | c +| c | c. +1:2 +3:4 +\&.TE +.Ed +.Pp +Table data is +.Em pre-processed , +that is, data rows are parsed then inserted into the underlying stream +of input data. +This allows data rows to be interspersed by arbitrary +.Xr roff 5 , +.Xr mdoc 5 , +and +.Xr man 5 +macros such as +.Bd -literal -offset indent +\&.TS +tab(:); +c c c. +1:2:3 +\&.Ao +3:2:1 +\&.Ac +\&.TE +.Ed +.Pp +in the case of +.Xr mdoc 5 +or +.Bd -literal -offset indent +\&.TS +tab(:); +c c c. +\&.ds ab 2 +1:\e*(ab:3 +\&.I +3:2:1 +\&.TE +.Ed +.Pp +in the case of +.Xr man 5 . +.Ss Options +The first line of a table consists of space-separated option keys and +modifiers terminated by a semicolon. +If the first line does not have a terminating semicolon, it is assumed +that no options are specified and instead a +.Sx Layout +is processed. +Some options accept arguments enclosed by parenthesis. +The following case-insensitive options are available: +.Bl -tag -width Ds +.It Cm center +This option is not supported by +.Xr mandoc 1 . +This may also be invoked with +.Cm centre . +.It Cm delim +Accepts a two-character argument. +This option is not supported by +.Xr mandoc 1 . +.It Cm expand +This option is not supported by +.Xr mandoc 1 . +.It Cm box +Draw a single-line box around the table. +This may also be invoked with +.Cm frame . +.It Cm doublebox +Draw a double-line box around the table. +This may also be invoked with +.Cm doubleframe . +.It Cm allbox +This option is not supported by +.Xr mandoc 1 . +.It Cm tab +Accepts a single-character argument. +This character is used as a delimiter between data cells, which otherwise +defaults to the tab character. +.It Cm linesize +Accepts a natural number (all digits). +This option is not supported by +.Xr mandoc 1 . +.It Cm nokeep +This option is not supported by +.Xr mandoc 1 . +.It Cm decimalpoint +Accepts a single-character argument. +This character will be used as the decimal point with the +.Cm n +layout key. +.It Cm nospaces +This option is not supported by +.Xr mandoc 1 . +.El +.Ss Layout +The table layout follows +.Sx Options +or a +.Sq \&T& +macro invocation. +Layout specifies how data rows are displayed on output. +Each layout line corresponds to a line of data; the last layout line +applies to all remaining data lines. +Layout lines may also be separated by a comma. +Each layout cell consists of one of the following case-insensitive keys: +.Bl -tag -width Ds +.It Cm c +Centre a literal string within its column. +.It Cm r +Right-justify a literal string within its column. +.It Cm l +Left-justify a literal string within its column. +.It Cm n +Justify a number around its last decimal point. +If the decimal point is not found on the number, it's assumed to trail +the number. +.It Cm s +Horizontally span columns from the last +.No non- Ns Cm s +data cell. +It is an error if spanning columns follow a +.Cm \- +or +.Cm \(ba +cell, or come first. +This option is not supported by +.Xr mandoc 1 . +.It Cm a +Left-justify a literal string and pad with one space. +.It Cm ^ +Vertically span rows from the last +.No non- Ns Cm ^ +data cell. +It is an error to invoke a vertical span on the first layout row. +Unlike a horizontal spanner, you must specify an empty cell (if it not +empty, the data is discarded) in the corresponding data cell. +.It Cm \- +Replace the data cell (its contents will be lost) with a single +horizontal line. +This may also be invoked with +.Cm _ . +.It Cm = +Replace the data cell (its contents will be lost) with a double +horizontal line. +.It Cm \(ba +Emit a vertical bar instead of data. +.It Cm \(ba\(ba +Emit a double-vertical bar instead of data. +.El +.Pp +Keys may be followed by a set of modifiers. +A modifier is either a modifier key or a natural number for specifying +the minimum width of a column. +The following case-insensitive modifier keys are available: +.Cm z , +.Cm u , +.Cm e , +.Cm t , +.Cm d , +.Cm b , +.Cm i , +.Cm r , +and +.Cm f +.Po +followed by +.Cm b , +.Cm i , +.Cm r , +.Cm 3 , +.Cm 2 , +or +.Cm 1 +.Pc . +All of these are ignored by +.Xr mandoc 1 . +.Pp +For example, the following layout specifies a centre-justified column of +minimum width 10, followed by vertical bar, followed by a left-justified +column of minimum width 10, another vertical bar, then a column +justified about the decimal point in numbers: +.Pp +.Dl c10 | l10 | n +.Ss Data +The data section follows the last layout row. +By default, cells in a data section are delimited by a tab. +This behaviour may be changed with the +.Cm tab +option. +If +.Cm _ +or +.Cm = +is specified, a single or double line, respectively, is drawn across the +data field. +If +.Cm \e- +or +.Cm \e= +is specified, a line is drawn within the data field (i.e. terminating +within the cell and not draw to the border). +If the last cell of a line is +.Cm T{ , +all subsequent lines are included as part of the cell until +.Cm T} +is specified as its own data cell. +It may then be followed by a tab +.Pq or as designated by Cm tab +or an end-of-line to terminate the row. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other +.Nm +implementations, at this time limited to GNU tbl. +.Pp +.Bl -dash -compact +.It +In GNU tbl, comments and macros are disallowed prior to the data block +of a table. +The +.Xr mandoc 1 +implementation allows them. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 5 , +.Xr mandoc_char 5 , +.Xr mdoc 5 , +.Xr roff 5 +.Rs +.%A M. E. Lesk +.%T Tbl\(emA Program to Format Tables +.%D June 11, 1976 +.Re +.Sh HISTORY +The tbl utility, a preprocessor for troff, was originally written by M. +E. Lesk at Bell Labs in 1975. +The GNU reimplementation of tbl, part of the groff package, was released +in 1990 by James Clark. +A standalone tbl implementation was written by Kristaps Dzonsons in +2010. +This formed the basis of the implementation that is part of the +.Xr mandoc 1 +utility. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/usr/src/man/man7d/cpqary3.7d b/usr/src/man/man7d/cpqary3.7d index d87e42c928..5f52d849a6 100644 --- a/usr/src/man/man7d/cpqary3.7d +++ b/usr/src/man/man7d/cpqary3.7d @@ -13,9 +13,7 @@ .\" .TH CPQARY3 7D Aug 26, 2013" .SH NAME -.LP cpqary3 - provides disk and SCSI tape support for HP Smart Array controllers -.LP .SH DESCRIPTION .LP The cpqary3 module provides low-level interface routines between the common @@ -78,7 +76,6 @@ then target ID entries for tape drives from 65 to 65+N must be added in .BR driver.conf (4), .BR sd (7D), .BR st (7D) -.LP .SH NOTES .LP The Smart Array controllers supported by the current version of the diff --git a/usr/src/man/man7d/nv_sata.7d b/usr/src/man/man7d/nv_sata.7d index def2a2cb4d..29f2b145a6 100644 --- a/usr/src/man/man7d/nv_sata.7d +++ b/usr/src/man/man7d/nv_sata.7d @@ -4,7 +4,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH nv_sata 7D "25 Sep 2011" +.TH NV_SATA 7D "Sep 25, 2011" .SH NAME nv_sata \- NVIDIA CK804/MCP04/MCP51/MCP55/MCP61 SATA controller driver .SH SYNOPSIS @@ -16,7 +16,7 @@ nv_sata \- NVIDIA CK804/MCP04/MCP51/MCP55/MCP61 SATA controller driver .SH DESCRIPTION .sp .LP -The \fBnv_sata\fR driver is a SATA HBA driver that supports NVIDIA CK804/MCP04 +The \fBnv_sata\fR driver is a SATA HBA driver that supports NVIDIA CK804/MCP04 and MCP51/MCP55/MCP61 SATA HBA controllers. Note that while these controllers support standard SATA features including SATA-II drives, NCQ, hotplug and ATAPI drives, the driver currently does not support NCQ features. diff --git a/usr/src/man/man7d/pcn.7d b/usr/src/man/man7d/pcn.7d index 2ae5d00638..dcbc85c99d 100644 --- a/usr/src/man/man7d/pcn.7d +++ b/usr/src/man/man7d/pcn.7d @@ -43,7 +43,7 @@ the AMD PCnet family of Ethernet controllers\. .SH "APPLICATION PROGRAMMING INTERFACE" The \fBpcn\fR driver can be used as either a "style 1" or a "style 2" Data Link Service Provider\. Physical points of attachment (PPAs) are interpreted as the -instance number of the \fBpcn\fR controller as assigned by the Illumos +instance number of the \fBpcn\fR controller as assigned by the operating environment\. .sp .LP @@ -58,7 +58,7 @@ Maximum SDU is 1500\. .TP .ie t \(bu .el o -Minimum SDU is 0\. +Minimum SDU is 0\. .RE .RS +4 .TP @@ -76,7 +76,7 @@ MAC type is \fBDL_ETHER\fR\. .TP .ie t \(bu .el o -SAP length is \-2\. The 6\-byte physical address is immediately followed by a +SAP length is \-2\. The 6\-byte physical address is immediately followed by a 2\-byte SAP\. .RE .RS +4 @@ -89,7 +89,7 @@ Service mode is \fBDL_CLDLS\fR\. .TP .ie t \(bu .el o -The broadcast address is the 6\-byte Ethernet broadcast address +The broadcast address is the 6\-byte Ethernet broadcast address (\fBff:ff:ff:ff:ff:ff\fR)\. .SH "CONFIGURATION" .sp diff --git a/usr/src/man/man7d/vnd.7d b/usr/src/man/man7d/vnd.7d index 4cc0d8f9bf..d311c4dc08 100644 --- a/usr/src/man/man7d/vnd.7d +++ b/usr/src/man/man7d/vnd.7d @@ -20,9 +20,9 @@ vnd \- virtual layer two network driver .nf .LP /dev/vnd/ctl -.nf .LP /dev/vnd/* +.fi .SH DESCRIPTION .sp @@ -61,10 +61,9 @@ or named devices are private to the implementation. Instead, libvnd(3LIB) provides a stable interfaces for using, creating, and manipulating vnd devices. .sp -.LP .SH FILES .sp -.n3 2 +.ne 2 .na /dev/vnd/ctl .ad @@ -73,7 +72,7 @@ vnd self-cloning control node .RE .sp -.n3 2 +.ne 2 .na /dev/vnd/%link .ad @@ -84,7 +83,7 @@ in the current zone. .RE .sp -.n3 2 +.ne 2 .na /dev/vnd/zone/%zone/%link .ad diff --git a/usr/src/man/man7fs/bootfs.7fs b/usr/src/man/man7fs/bootfs.7fs index 9aea119370..130530a1f6 100644 --- a/usr/src/man/man7fs/bootfs.7fs +++ b/usr/src/man/man7fs/bootfs.7fs @@ -22,7 +22,7 @@ The .B bootfs file system is a read-only file system that provides access to any boot-time modules that were passed in to the system loader which were -tagged with the type +tagged with the type .IR file . .B bootfs does not display any boot-time modules that were tagged as type @@ -78,7 +78,7 @@ name: bootfs class: fs .LP The field .B ndiscard -lists the number of boot-time modules that were discarded due to naming conflicts. The field +lists the number of boot-time modules that were discarded due to naming conflicts. The field .B ndup lists the number of duplicate entries that were found and therefore not displayed in the file system. .sp diff --git a/usr/src/man/man7fs/lxproc.7fs b/usr/src/man/man7fs/lxproc.7fs index fe8a0d6d35..7ef10ce343 100644 --- a/usr/src/man/man7fs/lxproc.7fs +++ b/usr/src/man/man7fs/lxproc.7fs @@ -17,7 +17,7 @@ lxproc \- a loosely Linux-compatible /proc .LP \fBlxproc\fR is an implementation of the \fB/proc\fR filesystem that loosely matches the Linux semantics of providing human-readable text files -that correspond to elements of the system. +that correspond to elements of the system. As with both \fBproc\fR(4) and Linux \fB/proc\fR, \fBlxproc\fR makes available a directory for every process, with each directory containing a number of files; like Linux \fB/proc\fR but unlike \fBproc\fR(4), \fBlxproc\fR also @@ -33,31 +33,31 @@ somehow fool a consumer into believing that it is operating within a Linux environment. As such, \fBlxproc\fR should only be used by Linux-specific programs that are willing to trade precision in understanding the system in return for Linux compatibility. To programmatically understand -the system precisely and in terms of its native constructs, +the system precisely and in terms of its native constructs, one should not use \fBlxproc\fR, but rather \fBproc\fR(4) or -\fBkstat\fR(3KSTAT). +\fBkstat\fR(3KSTAT). To understand a process or group of processes from either a shell script or the command line, -one should not use \fBlxproc\fR, but rather \fBproc\fR(4)-based tools like -\fBprstat\fR(1M), -\fBpfiles\fR(1), -\fBpargs\fR(1), -\fBpmap\fR(1), -\fBptree\fR(1), -\fBplimit\fR(1), -\fBpflags\fR(1), -\fBpcred\fR(1), -\fBpstack\fR(1), -\fBpldd\fR(1), -\fBpsig\fR(1), +one should not use \fBlxproc\fR, but rather \fBproc\fR(4)-based tools like +\fBprstat\fR(1M), +\fBpfiles\fR(1), +\fBpargs\fR(1), +\fBpmap\fR(1), +\fBptree\fR(1), +\fBplimit\fR(1), +\fBpflags\fR(1), +\fBpcred\fR(1), +\fBpstack\fR(1), +\fBpldd\fR(1), +\fBpsig\fR(1), or \fBpwdx\fR(1). To understand system-wide constructs from either a shell script or the command line, one should not use \fBlxproc\fR, but rather \fBkstat\fR(3KSTAT)-based tools like -\fBkstat\fR(1M), -\fBmpstat\fR(1M), -\fBiostat\fR(1M), +\fBkstat\fR(1M), +\fBmpstat\fR(1M), +\fBiostat\fR(1M), \fBnetstat\fR(1M) or \fBpsrinfo\fR(1M). .sp @@ -78,26 +78,26 @@ mount it by default, this will (or should) generally be the mount point. .SH SEE ALSO .sp .LP -\fBdf\fR(1M), -\fBiostat\fR(1M), -\fBkstat\fR(1M), -\fBmpstat\fR(1M), +\fBdf\fR(1M), +\fBiostat\fR(1M), +\fBkstat\fR(1M), +\fBmpstat\fR(1M), \fBmount\fR(1M), \fBnetstat\fR(1M), -\fBpargs\fR(1), -\fBpcred\fR(1), -\fBpfiles\fR(1), -\fBpflags\fR(1), -\fBpldd\fR(1), -\fBplimit\fR(1), -\fBpmap\fR(1), -\fBprstat\fR(1M), -\fBpsig\fR(1), +\fBpargs\fR(1), +\fBpcred\fR(1), +\fBpfiles\fR(1), +\fBpflags\fR(1), +\fBpldd\fR(1), +\fBplimit\fR(1), +\fBpmap\fR(1), +\fBprstat\fR(1M), +\fBpsig\fR(1), \fBpsrinfo\fR(1M), -\fBpstack\fR(1), -\fBptree\fR(1), +\fBpstack\fR(1), +\fBptree\fR(1), \fBpwdx\fR(1), -\fBmount\fR(2), \fBumount\fR(2), \fBkstat\fR(3KSTAT), \fBproc\fR(4), +\fBmount\fR(2), \fBumount\fR(2), \fBkstat\fR(3KSTAT), \fBproc\fR(4), \fBkstat\fR(9S) .SH NOTES diff --git a/usr/src/man/man9f/ddi_dmae.9f b/usr/src/man/man9f/ddi_dmae.9f index 0f04ec6c0b..27f045114c 100644 --- a/usr/src/man/man9f/ddi_dmae.9f +++ b/usr/src/man/man9f/ddi_dmae.9f @@ -133,7 +133,7 @@ A pointer to a \fBDMA\fR engine request structure. See \fBddi_dmae_req\fR(9S). \fB\fIcookiep\fR\fR .ad .RS 12n -A pointer to a \fBddi_dma_cookie\fR(9S) object, +A pointer to a \fBddi_dma_cookie\fR(9S) object, which contains the address and count. .RE diff --git a/usr/src/man/man9f/rwlock.9f b/usr/src/man/man9f/rwlock.9f index 1ff7ea4f03..5186d4aa54 100644 --- a/usr/src/man/man9f/rwlock.9f +++ b/usr/src/man/man9f/rwlock.9f @@ -140,7 +140,7 @@ destroyed. .sp .LP The \fBrw_enter()\fR function acquires the lock, and blocks if necessary. If -\fIenter_type\fR is \fBRW_WRITER\fR, the caller blocks if any thread holds +\fIenter_type\fR is \fBRW_WRITER\fR, the caller blocks if any thread holds the lock. If \fIenter_type\fR is \fBRW_READER\fR, the caller blocks if there is a writer or a thread attempting to enter for writing. If \fIenter_type\fR is \fBRW_READER_STARVEWRITER\fR, the caller blocks only if there is a writer; diff --git a/usr/src/man/man9f/scsi_hba_attach_setup.9f b/usr/src/man/man9f/scsi_hba_attach_setup.9f index dd303f3bc4..dfe56db9f4 100644 --- a/usr/src/man/man9f/scsi_hba_attach_setup.9f +++ b/usr/src/man/man9f/scsi_hba_attach_setup.9f @@ -259,7 +259,7 @@ individual HBA man pages for any HBA-specific information .SS "scsi_hba_detach(\|)" .sp .LP -The \fBscsi_hba_detach()\fR function removes the reference to the DMA +The \fBscsi_hba_detach()\fR function removes the reference to the DMA attributes structure and the transport vector for the given instance of an HBA driver. .SH RETURN VALUES |