Delete substantial amounts of code

[mandoc.git] / man.1

diff --git a/man.1 b/man.1
index 9af77e967d1668b6350f5ace01870d7cdcbcf045..cf03693ee981856ebf92db59e5fdeb8787dfd213 100644 (file)
--- a/man.1
+++ b/man.1
@@ -1,4 +1,4 @@
-.\"    $Id: man.1,v 1.24 2017/03/21 18:06:12 schwarze Exp $
+.\"    $Id: man.1,v 1.33 2018/04/19 23:41:16 schwarze Exp $

 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.


@@ -31,7 +31,7 @@
 .\"
 .\"     @(#)man.1      8.2 (Berkeley) 1/2/94
 .\"
 .\"
 .\"     @(#)man.1      8.2 (Berkeley) 1/2/94
 .\"

-.Dd $Mdocdate: March 21 2017 $
+.Dd $Mdocdate: April 19 2018 $

 .Dt MAN 1
 .Os
 .Sh NAME
 .Dt MAN 1
 .Os
 .Sh NAME


@@ -41,16 +41,10 @@
 .Nm man
 .Op Fl acfhklw
 .Op Fl C Ar file
 .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 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 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
 .Ar name ...
 .Sh DESCRIPTION
 The


@@ -84,6 +78,18 @@ Copy the manual page to the standard output instead of using
 .Xr more 1
 to paginate it.
 This is done by default if the standard output is not a terminal device.
 .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 .
 .It Fl f
 A synonym for
 .Xr whatis 1 .


@@ -91,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.
 .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
 .Fl a
 and
 .Fl c .
 .It Fl h
 Display only the SYNOPSIS lines of the requested manual pages.
 Implies
 .Fl a
 and
 .Fl c .

-.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 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 .
 .It Fl k
 A synonym for
 .Xr apropos 1 .


@@ -133,15 +112,9 @@ an expression can be provided using the syntax described in the
 .Xr apropos 1
 manual.
 By default, it displays the header lines of all matching pages.
 .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
 .It Fl l
 A synonym for

-.Xr mandoc 1
-.Fl a .
+.Xr mandoc 1 .

 The
 .Ar name
 arguments are interpreted as filenames.
 The
 .Ar name
 arguments are interpreted as filenames.


@@ -149,15 +122,12 @@ No search is done and
 .Ar file ,
 .Ar path ,
 .Ar section ,
 .Ar file ,
 .Ar path ,
 .Ar section ,

-and
-.Ar subsection
-are ignored.
-This overrides any earlier
-.Fl f ,
-.Fl k ,
+.Ar subsection ,

 and
 .Fl w
 and
 .Fl w

-options.
+are ignored.
+This option implies
+.Fl a .

 .It Fl M Ar path
 Override the list of standard directories which
 .Nm
 .It Fl M Ar path
 Override the list of standard directories which
 .Nm


@@ -184,15 +154,8 @@ the directories specified using the
 option or the
 .Ev MANPATH
 environment variable.
 option or the
 .Ev MANPATH
 environment variable.

-.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
 .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
 .Xr machine 1
 architecture.
 .Ar subsection


@@ -238,53 +201,19 @@ Kernel internals.
 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.
 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 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 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.

 .It Fl w
 .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
 .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 .
 Guidelines for writing
 man pages can be found in
 .Xr mdoc 7 .


@@ -346,7 +275,7 @@ environment variable.
 The format of the path is a colon
 .Pq Ql \&:
 separated list of directories.
 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
 Overridden by
 .Fl M ,
 ignored if


@@ -369,11 +298,6 @@ If neither PAGER nor MANPAGER is defined,
 .Xr more 1
 .Fl s
 is used.
 .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
 .El
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact


@@ -382,21 +306,27 @@ default man configuration file
 .El
 .Sh EXIT STATUS
 .Ex -std man
 .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 ,
 .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 whereis 1 ,

-.Xr intro 2 ,
-.Xr intro 3 ,
-.Xr intro 4 ,
-.Xr intro 5 ,

 .Xr man.conf 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
 .Sh STANDARDS
 The
 .Nm