=================================================================== RCS file: /cvs/mandoc/man.1,v retrieving revision 1.27 retrieving revision 1.40 diff -u -p -r1.27 -r1.40 --- mandoc/man.1 2017/03/27 14:40:39 1.27 +++ mandoc/man.1 2020/07/20 16:57:30 1.40 @@ -1,9 +1,9 @@ -.\" $Id: man.1,v 1.27 2017/03/27 14:40:39 schwarze Exp $ +.\" $Id: man.1,v 1.40 2020/07/20 16:57:30 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 -.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze +.\" Copyright (c) 2010, 2011, 2014-2020 Ingo Schwarze .\" .\" 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 27 2017 $ +.Dd $Mdocdate: July 20 2020 $ .Dt MAN 1 .Os .Sh NAME @@ -41,23 +41,17 @@ .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 .Nm utility displays the -manual pages entitled +manual page entitled .Ar name . Pages may be selected according to a specific category @@ -70,7 +64,6 @@ The options are as follows: .Bl -tag -width Ds .It Fl a Display all matching manual pages. -Normally, only the first page found is displayed. .It Fl C Ar file Use the specified .Ar file @@ -81,9 +74,21 @@ See for a description of the contents of this file. .It Fl c Copy the manual page to the standard output instead of using -.Xr more 1 +.Xr less 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 . @@ -108,8 +113,7 @@ manual. By default, it displays the header lines of all matching pages. .It Fl l A synonym for -.Xr mandoc 1 -.Fl a . +.Xr mandoc 1 . The .Ar name arguments are interpreted as filenames. @@ -121,32 +125,34 @@ No search is done and and .Fl w are ignored. +This option implies +.Fl a . .It Fl M Ar path -Override the list of standard directories which -.Nm -searches for manual pages. +Override the list of directories to search for manual pages. The supplied .Ar path must be a colon .Pq Ql \&: separated list of directories. -This search path may also be set using the environment variable -.Ev MANPATH . +This option also overrides the environment variable +.Ev MANPATH +and any directories specified in the +.Xr man.conf 5 +file. .It Fl m Ar path -Augment the list of standard directories which -.Nm -searches for manual pages. +Augment the list of directories to search for manual pages. The supplied .Ar path must be a colon .Pq Ql \&: separated list of directories. -These directories will be searched before the standard directories or -the directories specified using the +These directories will be searched before those specified using the .Fl M -option or the +option, the .Ev MANPATH -environment variable. +environment variable, the +.Xr man.conf 5 +file, or the default directories. .It Fl S Ar subsection Only show pages for the specified .Xr machine 1 @@ -161,6 +167,7 @@ architecture whilst using another. This option overrides the .Ev MACHINE environment variable. +.Tg s .It Oo Fl s Oc Ar section Only select manuals from the specified .Ar section . @@ -190,13 +197,12 @@ System maintenance and operation commands. .It 9 Kernel internals. .El -.Pp -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 List the pathnames of all matching manual pages instead of displaying any of them. +If no +.Ar name +is given, list the directories that would be searched. .El .Pp The options @@ -207,16 +213,46 @@ The options .Fl fkl are mutually exclusive and override each other. .Pp -Guidelines for writing -man pages can be found in -.Xr mdoc 7 . +The search starts with the +.Fl m +argument if provided, then continues with the +.Fl M +argument, the +.Ev MANPATH +variable, the +.Ic manpath +entries in the +.Xr man.conf 5 +file, or with +.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man +by default. +Within each of these, directories are searched in the order provided. +Within each directory, the search proceeds according to the following +list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p. +The first match found is shown. .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. +.Pp +Guidelines for writing +man pages can be found in +.Xr mdoc 7 . .Sh ENVIRONMENT .Bl -tag -width MANPATHX .It Ev MACHINE @@ -239,7 +275,7 @@ is case insensitive. Any non-empty value of the environment variable .Ev MANPAGER is used instead of the standard pagination program, -.Xr more 1 . +.Xr less 1 . If .Xr less 1 is used, the interactive @@ -259,16 +295,23 @@ 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 -may be changed by specifying a path in the +Override the standard search path which is either specified in +.Xr man.conf 5 +or the default path. +The format of .Ev MANPATH -environment variable. -The format of the path is a colon +is a colon .Pq Ql \&: separated list of directories. -Invalid paths, or paths without manual databases, are ignored. +Invalid directories are ignored. Overridden by .Fl M , ignored if @@ -277,50 +320,48 @@ 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; +begins with a colon, it is appended to the standard path; +if it ends with a colon, it is prepended to the standard path; 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. +the standard path is inserted between the colons. .It Ev PAGER Specifies the pagination program to use when .Ev MANPAGER is not defined. If neither PAGER nor MANPAGER is defined, -.Xr more 1 -.Fl s +.Xr less 1 is used. -Only used if -.Fl a -or -.Fl l -is specified. .El .Sh FILES .Bl -tag -width /etc/man.conf -compact .It Pa /etc/man.conf -default man configuration file +default +.Nm +configuration file .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 , -.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 @@ -340,7 +381,7 @@ are extensions to that specification. A .Nm command first appeared in -.At v3 . +.At v2 . .Pp The .Fl w