===================================================================
RCS file: /cvs/mandoc/man.1,v
retrieving revision 1.26
retrieving revision 1.35
diff -u -p -r1.26 -r1.35
--- mandoc/man.1	2017/03/25 12:46:36	1.26
+++ mandoc/man.1	2019/03/09 15:55:01	1.35
@@ -1,9 +1,9 @@
-.\"	$Id: man.1,v 1.26 2017/03/25 12:46:36 schwarze Exp $
+.\"	$Id: man.1,v 1.35 2019/03/09 15:55:01 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-2017 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: March 25 2017 $
+.Dd $Mdocdate: March 9 2019 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -41,16 +41,10 @@
 .Nm man
 .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
@@ -84,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 .
@@ -91,11 +97,6 @@ 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 h
 Display only the SYNOPSIS lines of the requested manual pages.
 Implies
@@ -111,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.
@@ -127,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
@@ -218,17 +210,32 @@ 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 .
 .Pp
+The
+.Xr mandoc.db 5
+database is used for looking up manual page entries.
+In cases where the database is absent, outdated, or corrupt,
+.Nm
+falls back to looking for files called
+.Ar name . Ns Ar section .
 If both a formatted and an unformatted version of the same manual page,
 for example
 .Pa cat1/foo.0
 and
 .Pa man1/foo.1 ,
 exist in the same directory, only the unformatted version is used.
+The database is kept up to date with
+.Xr makewhatis 8 ,
+which is run by the
+.Xr weekly 8
+maintenance script.
 .Sh ENVIRONMENT
 .Bl -tag -width MANPATHX
 .It Ev MACHINE
@@ -271,6 +278,13 @@ and
 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
@@ -280,7 +294,7 @@ environment variable.
 The format of the path is a colon
 .Pq Ql \&:
 separated list of directories.
-Invalid paths, or paths without manual databases, are ignored.
+Invalid paths are ignored.
 Overridden by
 .Fl M ,
 ignored if
@@ -303,11 +317,6 @@ If neither PAGER nor MANPAGER is defined,
 .Xr more 1
 .Fl s
 is used.
-Only used if
-.Fl a
-or
-.Fl l
-is specified.
 .El
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact
@@ -319,20 +328,24 @@ default man configuration file
 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 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