===================================================================
RCS file: /cvs/mandoc/man.1,v
retrieving revision 1.12
retrieving revision 1.34
diff -u -p -r1.12 -r1.34
--- mandoc/man.1	2015/01/20 21:16:51	1.12
+++ mandoc/man.1	2018/11/22 11:30:23	1.34
@@ -1,9 +1,9 @@
-.\"	$Id: man.1,v 1.12 2015/01/20 21:16:51 schwarze Exp $
+.\"	$Id: man.1,v 1.34 2018/11/22 11:30:23 schwarze Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
-.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -31,7 +31,7 @@
 .\"
 .\"     @(#)man.1	8.2 (Berkeley) 1/2/94
 .\"
-.Dd $Mdocdate: January 20 2015 $
+.Dd $Mdocdate: November 22 2018 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -39,18 +39,12 @@
 .Nd display manual pages
 .Sh SYNOPSIS
 .Nm man
-.Op Fl acfhklVw
+.Op Fl acfhklw
 .Op Fl C Ar file
-.Op Fl I Cm os Ns = Ns Ar name
-.Op Fl K Ar encoding
 .Op Fl M Ar path
 .Op Fl m Ar path
-.Op Fl O Ar option Ns = Ns Ar value
 .Op Fl S Ar subsection
-.Op Fl s Ar section
-.Op Fl T Ar output
-.Op Fl W Ar level
-.Op Ar section
+.Op Oo Fl s Oc Ar section
 .Ar name ...
 .Sh DESCRIPTION
 The
@@ -69,12 +63,8 @@ machine architecture
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl a
-Display all of the manual pages for a specified
-.Ar section
-and
-.Ar name
-combination.
-Normally, only the first manual page found is displayed.
+Display all matching manual pages.
+Normally, only the first page found is displayed.
 .It Fl C Ar file
 Use the specified
 .Ar file
@@ -88,6 +78,18 @@ Copy the manual page to the standard output instead of
 .Xr more 1
 to paginate it.
 This is done by default if the standard output is not a terminal device.
+.Pp
+When using
+.Fl c ,
+most terminal devices are unable to show the markup.
+To print the output of
+.Nm
+to the terminal with markup but without using a pager, pipe it to
+.Xr ul 1 .
+To remove the markup, pipe the output to
+.Xr col 1
+.Fl b
+instead.
 .It Fl f
 A synonym for
 .Xr whatis 1 .
@@ -95,39 +97,12 @@ It searches for
 .Ar name
 in manual page names and displays the header lines from all matching pages.
 The search is case insensitive and matches whole words only.
-This overrides any earlier
-.Fl k
-and
-.Fl l
-options.
-.It Fl I Cm os Ns = Ns Ar name
-Override the default operating system
-.Ar name
-for the
-.Xr mdoc 7
-.Ic \&Os
-and for the
-.Xr man 7
-.Ic \&TH
-macro.
 .It Fl h
 Display only the SYNOPSIS lines of the requested manual pages.
 Implies
 .Fl a
 and
 .Fl c .
-.It Fl K Ar encoding
-Specify the input encoding.
-The supported
-.Ar encoding
-arguments are
-.Cm us-ascii ,
-.Cm iso-8859-1 ,
-and
-.Cm utf-8 .
-By default, the encoding is automatically detected as described in the
-.Xr mandoc 1
-manual.
 .It Fl k
 A synonym for
 .Xr apropos 1 .
@@ -137,15 +112,9 @@ an expression can be provided using the syntax describ
 .Xr apropos 1
 manual.
 By default, it displays the header lines of all matching pages.
-This overrides any earlier
-.Fl f
-and
-.Fl l
-options.
 .It Fl l
 A synonym for
-.Xr mandoc 1
-.Fl a .
+.Xr mandoc 1 .
 The
 .Ar name
 arguments are interpreted as filenames.
@@ -153,15 +122,12 @@ No search is done and
 .Ar file ,
 .Ar path ,
 .Ar section ,
+.Ar subsection ,
 and
-.Ar subsection
-are ignored.
-This overrides any earlier
-.Fl f ,
-.Fl k ,
-and
 .Fl w
-options.
+are ignored.
+This option implies
+.Fl a .
 .It Fl M Ar path
 Override the list of standard directories which
 .Nm
@@ -173,12 +139,6 @@ must be a colon
 separated list of directories.
 This search path may also be set using the environment variable
 .Ev MANPATH .
-The subdirectories to be searched, and their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
 .It Fl m Ar path
 Augment the list of standard directories which
 .Nm
@@ -194,21 +154,8 @@ the directories specified using the
 option or the
 .Ev MANPATH
 environment variable.
-The subdirectories to be searched, and their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
-.It Fl O Ar option Ns = Ns Ar value
-Comma-separated output options.
-For each output format, the available options are described in the
-.Xr mandoc 1
-manual.
 .It Fl S Ar subsection
-Restricts the directories that
-.Nm
-will search to those of a specific
+Only show pages for the specified
 .Xr machine 1
 architecture.
 .Ar subsection
@@ -221,13 +168,9 @@ architecture whilst using another.
 This option overrides the
 .Ev MACHINE
 environment variable.
-.It Xo
-.Op Fl s
-.Ar section
-.Xc
-Restricts the directories that
-.Nm
-will search to a specific section.
+.It Oo Fl s Oc Ar section
+Only select manuals from the specified
+.Ar section .
 The currently available sections are:
 .Pp
 .Bl -tag -width "localXXX" -offset indent -compact
@@ -237,9 +180,7 @@ General commands
 .It 2
 System calls and error numbers.
 .It 3
-Libraries.
-.It 3f
-Fortran programmer's reference guide.
+Library functions.
 .It 3p
 .Xr perl 1
 programmer's reference guide.
@@ -250,79 +191,29 @@ File formats.
 .It 6
 Games.
 .It 7
-Miscellaneous.
+Miscellaneous information.
 .It 8
 System maintenance and operation commands.
 .It 9
 Kernel internals.
-.It X11
-An alias for X11R6.
-.It X11R6
-X Window System.
-.It local
-Pages located in
-.Pa /usr/local .
-.It n
-Tcl/Tk commands.
 .El
 .Pp
-The
-.Nm
-configuration file,
-.Xr man.conf 5 ,
-specifies the possible
-.Ar section
-values, and their search order.
-Additional sections may be specified.
-.It Fl T Ar output
-Select the output format.
-The default is
-.Cm locale .
-The other output modes
-.Cm ascii ,
-.Cm html ,
-.Cm lint ,
-.Cm man ,
-.Cm pdf ,
-.Cm ps ,
-.Cm tree ,
-and
-.Cm utf8
-are described in the
-.Xr mandoc 1
-manual.
-.It Fl V
-Print version and exit.
-.It Fl W 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 unsupp ;
-.Cm all
-is an alias for
-.Cm warning .
-By default,
-.Nm
-is silent.
-See the
-.Xr mandoc 1
-manual for details.
+If not specified and a match is found in more than one section,
+the first match is selected from the following list:
+1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 .It Fl w
-List the pathnames of the manual pages which
-.Nm
-would display for the specified
-.Ar section
-and
-.Ar name
-combination.
+List the pathnames of all matching manual pages instead of displaying
+any of them.
 .El
 .Pp
+The options
+.Fl IKOTW
+are also supported and are documented in
+.Xr mandoc 1 .
+The options
+.Fl fkl
+are mutually exclusive and override each other.
+.Pp
 Guidelines for writing
 man pages can be found in
 .Xr mdoc 7 .
@@ -332,13 +223,7 @@ for example
 .Pa cat1/foo.0
 and
 .Pa man1/foo.1 ,
-exist in the same directory, and at least one of them is selected,
-only the newer one is used.
-However, if both the
-.Fl a
-and the
-.Fl w
-options are specified, both file names are printed.
+exist in the same directory, only the unformatted version is used.
 .Sh ENVIRONMENT
 .Bl -tag -width MANPATHX
 .It Ev MACHINE
@@ -360,31 +245,66 @@ is case insensitive.
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER
-will be used instead of the standard pagination program,
+is used instead of the standard pagination program,
 .Xr more 1 .
+If
+.Xr less 1
+is used, the interactive
+.Ic :t
+command can be used to go to the definitions of various terms, for
+example command line options, command modifiers, internal commands,
+environment variables, function names, preprocessor macros,
+.Xr errno 2
+values, and some other emphasized words.
+Some terms may have defining text at more than one place.
+In that case, the
+.Xr less 1
+interactive commands
+.Ic t
+and
+.Ic T
+can be used to move to the next and to the previous place providing
+information about the term last searched for with
+.Ic :t .
+The
+.Fl O Cm tag Ns Op = Ns Ar term
+option documented in the
+.Xr mandoc 1
+manual opens a manual page at the definition of a specific
+.Ar term
+rather than at the beginning.
 .It Ev MANPATH
 The standard search path used by
 .Nm
-may be overridden by specifying a path in the
+may be changed by specifying a path in the
 .Ev MANPATH
-environment
-variable.
+environment variable.
 The format of the path is a colon
 .Pq Ql \&:
 separated list of directories.
-The subdirectories to be searched, as well as their search order,
-are specified by the
-.Dq _subdir
-line in the
-.Nm
-configuration file.
+Invalid paths are ignored.
+Overridden by
+.Fl M ,
+ignored if
+.Fl l
+is specified.
+.Pp
+If
+.Ev MANPATH
+begins with a colon, it is appended to the default list;
+if it ends with a colon, it is prepended to the default list;
+or if it contains two adjacent colons,
+the standard search path is inserted between the colons.
+If none of these conditions are met, it overrides the
+standard search path.
 .It Ev PAGER
 Specifies the pagination program to use when
 .Ev MANPAGER
 is not defined.
 If neither PAGER nor MANPAGER is defined,
-.Pa /usr/bin/more Fl s
-will be used.
+.Xr more 1
+.Fl s
+is used.
 .El
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact
@@ -393,21 +313,27 @@ default man configuration file
 .El
 .Sh EXIT STATUS
 .Ex -std man
+See
+.Xr mandoc 1
+for details.
+.Sh EXAMPLES
+Format a page for pasting extracts into an email message \(em
+avoid printing any UTF-8 characters, reduce the width to ease
+quoting in replies, and remove markup:
+.Pp
+.Dl $ man -T ascii -O width=65 pledge | col -b
+.Pp
+Read a typeset page in a PDF viewer:
+.Pp
+.Dl $ MANPAGER=mupdf man -T pdf lpd
 .Sh SEE ALSO
 .Xr apropos 1 ,
-.Xr intro 1 ,
-.Xr whatis 1 ,
+.Xr col 1 ,
+.Xr mandoc 1 ,
+.Xr ul 1 ,
 .Xr whereis 1 ,
-.Xr intro 2 ,
-.Xr intro 3 ,
-.Xr intro 4 ,
-.Xr intro 5 ,
 .Xr man.conf 5 ,
-.Xr intro 6 ,
-.Xr intro 7 ,
-.Xr mdoc 7 ,
-.Xr intro 8 ,
-.Xr intro 9
+.Xr mdoc 7
 .Sh STANDARDS
 The
 .Nm
@@ -416,7 +342,7 @@ utility is compliant with the
 specification.
 .Pp
 The flags
-.Op Fl aCcfhIKlMmOSsTVWw ,
+.Op Fl aCcfhIKlMmOSsTWw ,
 as well as the environment variables
 .Ev MACHINE ,
 .Ev MANPAGER ,
@@ -455,9 +381,23 @@ in
 .Fl C
 in
 .Nx 1.0 ;
-and
 .Fl s
 and
 .Fl S
 in
-.Ox 2.3 .
+.Ox 2.3 ;
+and
+.Fl I ,
+.Fl K ,
+.Fl l ,
+.Fl O ,
+and
+.Fl W
+in
+.Ox 5.7 .
+The
+.Fl T
+option first appeared in
+.At III
+and was also added in
+.Ox 5.7 .