In the SYNOPSIS, .Nm blocks can get broken if one of their children

[mandoc.git] / man.1

diff --git a/man.1 b/man.1
index 11bc4ad89f5ff90ce9851fd8fd21e47f5500ed12..67b53d70ed437116d448a5107b5347e309759394 100644 (file)
--- a/man.1
+++ b/man.1
@@ -1,4 +1,4 @@
-.\"    $Id: man.1,v 1.11 2015/01/15 04:26:40 schwarze Exp $
+.\"    $Id: man.1,v 1.21 2017/01/31 19:44:04 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: January 15 2015 $
+.Dd $Mdocdate: January 31 2017 $

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


@@ -39,7 +39,7 @@
 .Nd display manual pages
 .Sh SYNOPSIS
 .Nm man
 .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 C Ar file
 .Op Fl I Cm os Ns = Ns Ar name
 .Op Fl K Ar encoding


@@ -69,12 +69,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


@@ -100,6 +96,12 @@ This overrides any earlier
 and
 .Fl l
 options.
 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 I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name
 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name


@@ -110,12 +112,6 @@ and for the
 .Xr man 7
 .Ic \&TH
 macro.
 .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
 .It Fl K Ar encoding
 Specify the input encoding.
 The supported


@@ -173,12 +169,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


@@ -194,12 +184,6 @@ 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 O Ar option Ns = Ns Ar value
 Comma-separated output options.
 For each output format, the available options are described in the
 .It Fl O Ar option Ns = Ns Ar value
 Comma-separated output options.
 For each output format, the available options are described in the


@@ -221,13 +205,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


@@ -237,9 +217,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.


@@ -250,30 +228,12 @@ 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
 .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
 .It Fl T Ar output
 Select the output format.
 The default is


@@ -291,8 +251,6 @@ and
 are described in the
 .Xr mandoc 1
 manual.
 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
 .It Fl W Ar level
 Specify the minimum message
 .Ar level


@@ -300,9 +258,10 @@ to be reported on the standard error output and to affect the exit status.
 The
 .Ar level
 can be
 The
 .Ar level
 can be

-.Cm warning
+.Cm warning ,
+.Cm error ,

 or
 or

-.Cm error ;
+.Cm unsupp ;

 .Cm all
 is an alias for
 .Cm warning .
 .Cm all
 is an alias for
 .Cm warning .


@@ -361,6 +320,25 @@ Any non-empty value of the environment variable
 .Ev MANPAGER
 will be used instead of the standard pagination program,
 .Xr more 1 .
 .Ev MANPAGER
 will be 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 .

 .It Ev MANPATH
 The standard search path used by
 .Nm
 .It Ev MANPATH
 The standard search path used by
 .Nm


@@ -371,18 +349,13 @@ 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.

 .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
+.Xr more 1
+.Fl s

 will be used.
 .El
 .Sh FILES
 will be used.
 .El
 .Sh FILES


@@ -415,7 +388,7 @@ utility is compliant with the
 specification.
 .Pp
 The flags
 specification.
 .Pp
 The flags

-.Op Fl aCcfhIKlMmOSsTVWw ,
+.Op Fl aCcfhIKlMmOSsTWw ,

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


@@ -454,9 +427,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 .