In the validators, translate obsolete macro aliases (Lp, Ot, LP, P)

[mandoc.git] / man.1

diff --git a/man.1 b/man.1
index b4c67b527a439a712baf98fcddd6a49137d88a1b..5eae0e2ee5fe4df9384afadee506fd1588490d89 100644 (file)
--- a/man.1
+++ b/man.1
@@ -1,7 +1,9 @@
-.\"    $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc 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) 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-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
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions


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

-.Dd $Mdocdate: August 21 2014 $
+.Dd $Mdocdate: November 22 2018 $

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


@@ -37,24 +39,18 @@
 .Nd display manual pages
 .Sh SYNOPSIS
 .Nm man
 .Nd display manual pages
 .Sh SYNOPSIS
 .Nm man

-.Op Fl achw
+.Op Fl acfhklw

 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
 .Op Fl S Ar subsection
 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
 .Op Fl S Ar subsection

-.Op Fl s Ar section
-.Op Ar section
+.Op Oo Fl s Oc Ar section

 .Ar name ...
 .Ar name ...

-.Nm man
-.Fl f Ar command ...
-.Nm man
-.Fl k Ar keyword ...

 .Sh DESCRIPTION
 The
 .Nm
 utility
 displays the
 .Sh DESCRIPTION
 The
 .Nm
 utility
 displays the

-.Bx

 manual pages entitled
 .Ar name .
 Pages may be selected according to
 manual pages entitled
 .Ar name .
 Pages may be selected according to


@@ -67,12 +63,8 @@ machine architecture
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl a
 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
 .It Fl C Ar file
 Use the specified
 .Ar file


@@ -86,56 +78,56 @@ 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.

-.It Fl f Ar command
+.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 .
 A synonym for
 .Xr whatis 1 .

-It looks up a given command and
-gives the header line from the manual page.
-.Ar command
-is case insensitive.
+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.

 .It Fl h
 .It Fl h

-Display only the
-.Dq SYNOPSIS
-lines of the requested manual pages.
-.It Fl k Ar keyword
+Display only the SYNOPSIS lines of the requested manual pages.
+Implies
+.Fl a
+and
+.Fl c .
+.It Fl k

 A synonym for
 .Xr apropos 1 .
 A synonym for
 .Xr apropos 1 .

-It shows which manual pages contain instances of any of the given
-keywords in their title line.
-.Ar keyword
-is case insensitive.
-.Pp
-For instance,
-to list all man pages which contain
-.Dq mount
-in the
-.Dq NAME
-line of the man page:
-.Pp
-.Dl $ man -k mount
-.Pp
-Which would produce a list much like this:
-.Bd -literal
-amd (8) \(en automatically mount file systems
-amq (8) \(en automounter query tool
-domountroothooks (9) \(en run all mountroot hooks
-exports (5) \(en define remote mount points for NFS mount requests
-getfsstat (2) \(en get list of all mounted file systems
-getmntinfo (3) \(en get information about mounted file systems
-mount (8) \(en mount file systems
-mount, unmount (2) \(en mount or dismount a filesystem
-mount_cd9660 (8) \(en mount an ISO-9660 filesystem
-mount_ext2fs (8) \(en mount an ext2fs file system
-mount_ffs (8) \(en mount a Berkeley Fast File System
-mount_msdos (8) \(en mount an MS-DOS file system
-mount_nfs (8) \(en mount NFS file systems
-mount_ntfs (8) \(en mount an NTFS file system
-mount_procfs (8) \(en mount the process file system
-mount_udf (8) \(en mount a UDF filesystem
-mount_vnd, vnconfig (8) \(en configure vnode disks
-mountd (8) \(en service remote NFS mount requests
-\&...
-.Ed
+Instead of
+.Ar name ,
+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.
+.It Fl l
+A synonym for
+.Xr mandoc 1 .
+The
+.Ar name
+arguments are interpreted as filenames.
+No search is done and
+.Ar file ,
+.Ar path ,
+.Ar section ,
+.Ar subsection ,
+and
+.Fl w
+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


@@ -147,12 +139,6 @@ must be a colon
 separated list of directories.
 This search path may also be set using the environment variable
 .Ev MANPATH .
 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
 .It Fl m Ar path
 Augment the list of standard directories which
 .Nm


@@ -168,16 +154,8 @@ the directories specified using the
 option or the
 .Ev MANPATH
 environment variable.
 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 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


@@ -190,13 +168,9 @@ architecture whilst using another.
 This option overrides the
 .Ev MACHINE
 environment variable.
 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
 The currently available sections are:
 .Pp
 .Bl -tag -width "localXXX" -offset indent -compact


@@ -206,9 +180,7 @@ General commands
 .It 2
 System calls and error numbers.
 .It 3
 .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.
 .It 3p
 .Xr perl 1
 programmer's reference guide.


@@ -219,42 +191,30 @@ File formats.
 .It 6
 Games.
 .It 7
 .It 6
 Games.
 .It 7

-Miscellaneous.
+Miscellaneous information.

 .It 8
 System maintenance and operation commands.
 .It 9
 Kernel internals.
 .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
 .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.
+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
 .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

-Guidelines for
-.Ox
+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
 man pages can be found in
 .Xr mdoc 7 .
 .Pp


@@ -263,13 +223,7 @@ for example
 .Pa cat1/foo.0
 and
 .Pa man1/foo.1 ,
 .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
 .Sh ENVIRONMENT
 .Bl -tag -width MANPATHX
 .It Ev MACHINE


@@ -291,31 +245,66 @@ is case insensitive.
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER
 .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 .
 .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
 .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
 .Ev MANPATH

-environment
-variable.
+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.

-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,
 .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
 .El
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact


@@ -324,21 +313,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


@@ -347,7 +342,7 @@ utility is compliant with the
 specification.
 .Pp
 The flags
 specification.
 .Pp
 The flags

-.Op Fl aCcfhMmSsw ,
+.Op Fl aCcfhIKlMmOSsTWw ,

 as well as the environment variables
 .Ev MACHINE ,
 .Ev MANPAGER ,
 as well as the environment variables
 .Ev MACHINE ,
 .Ev MANPAGER ,


@@ -386,9 +381,23 @@ in
 .Fl C
 in
 .Nx 1.0 ;
 .Fl C
 in
 .Nx 1.0 ;

-and

 .Fl s
 and
 .Fl S
 in
 .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 .