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 0c88dbb9ef30ab13e696d7e702abdb2deb450935..67b53d70ed437116d448a5107b5347e309759394 100644 (file)
--- a/man.1
+++ b/man.1
@@ -1,9 +1,9 @@
-.\"    $Id: man.1,v 1.6 2014/10/25 01:03:52 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) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
 .\"
 .\" 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 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2014, 2015 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


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

-.Dd $Mdocdate: October 25 2014 $
+.Dd $Mdocdate: January 31 2017 $

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


@@ -39,12 +39,17 @@
 .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 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 section
 .Op Fl S Ar subsection
 .Op Fl s Ar section

+.Op Fl T Ar output
+.Op Fl W Ar level

 .Op Ar section
 .Ar name ...
 .Sh DESCRIPTION
 .Op Ar section
 .Ar name ...
 .Sh DESCRIPTION


@@ -64,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


@@ -98,7 +99,31 @@ options.
 .It Fl h
 Display only the SYNOPSIS lines of the requested manual pages.
 Implies
 .It Fl h
 Display only the SYNOPSIS lines of the requested manual pages.
 Implies

-.Fl a .
+.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 .


@@ -144,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


@@ -165,12 +184,11 @@ 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
+.Xr mandoc 1
+manual.

 .It Fl S Ar subsection
 Restricts the directories that
 .Nm
 .It Fl S Ar subsection
 Restricts the directories that
 .Nm


@@ -187,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


@@ -203,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.


@@ -216,32 +228,49 @@ 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
+.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
 The

+.Ar level
+can be
+.Cm warning ,
+.Cm error ,
+or
+.Cm unsupp ;
+.Cm all
+is an alias for
+.Cm warning .
+By default,

 .Nm
 .Nm

-configuration file,
-.Xr man.conf 5 ,
-specifies the possible
-.Ar section
-values, and their search order.
-Additional sections may be specified.
-.It Fl V
-Print version and exit.
+is silent.
+See the
+.Xr mandoc 1
+manual for details.

 .It Fl w
 List the pathnames of the manual pages which
 .Nm
 .It Fl w
 List the pathnames of the manual pages which
 .Nm


@@ -252,14 +281,6 @@ and
 combination.
 .El
 .Pp
 combination.
 .El
 .Pp

-The
-.Nm
-utility also supports the options
-.Fl IKOTW
-described in the
-.Xr mandoc 1
-manual.
-.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 .


@@ -299,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


@@ -309,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


@@ -353,7 +388,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 ,


@@ -392,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 .