[BACK]Return to man.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.1 between version 1.2 and 1.36

version 1.2, 2014/08/21 01:35:43 version 1.36, 2020/01/07 11:16:33
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"     $OpenBSD$  
 .\"  .\"
 .\" Copyright (c) 1989, 1990, 1993  .\" Copyright (c) 1989, 1990, 1993
 .\"     The Regents of the University of California.  All rights reserved.  .\"     The Regents of the University of California.  All rights reserved.
 .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>  .\" 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-2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" Redistribution and use in source and binary forms, with or without  .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions  .\" modification, are permitted provided that the following conditions
Line 40 
Line 39 
 .Nd display manual pages  .Nd display manual pages
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm man  .Nm man
 .Op Fl acfhkw  .Op Fl acfhklw
 .Op Fl C Ar file  .Op Fl C Ar file
 .Op Fl M Ar path  .Op Fl M Ar path
 .Op Fl m Ar path  .Op Fl m Ar path
 .Op Fl S Ar subsection  .Op Fl S Ar subsection
 .Op Fl s Ar section  .Op Oo Fl s Oc Ar section
 .Op Ar section  
 .Ar name ...  .Ar name ...
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility  utility
 displays the  displays the
 manual pages entitled  manual page entitled
 .Ar name .  .Ar name .
 Pages may be selected according to  Pages may be selected according to
 a specific category  a specific category
Line 65  machine architecture
Line 63  machine architecture
 The options are as follows:  The options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl a  .It Fl a
 Display all of the manual pages for a specified  Display all matching manual pages.
 .Ar section  
 and  
 .Ar name  
 combination.  
 Normally, only the first manual page found is displayed.  
 .It Fl C Ar file  .It Fl C Ar file
 Use the specified  Use the specified
 .Ar file  .Ar file
Line 84  Copy the manual page to the standard output instead of
Line 77  Copy the manual page to the standard output instead of
 .Xr more 1  .Xr more 1
 to paginate it.  to paginate it.
 This is done by default if the standard output is not a terminal device.  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  .It Fl f
 A synonym for  A synonym for
 .Xr whatis 1 .  .Xr whatis 1 .
Line 92  It searches for
Line 97  It searches for
 in manual page names and displays the header lines from all matching pages.  in manual page names and displays the header lines from all matching pages.
 The search is case insensitive and matches whole words only.  The search is case insensitive and matches whole words only.
 .It Fl h  .It Fl h
 Display only the  Display only the SYNOPSIS lines of the requested manual pages.
 .Dq SYNOPSIS  Implies
 lines of the requested manual pages.  .Fl a
   and
   .Fl c .
 .It Fl k  .It Fl k
 A synonym for  A synonym for
 .Xr apropos 1 .  .Xr apropos 1 .
Line 104  an expression can be provided using the syntax describ
Line 111  an expression can be provided using the syntax describ
 .Xr apropos 1  .Xr apropos 1
 manual.  manual.
 By default, it displays the header lines of all matching pages.  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  .It Fl M Ar path
 Override the list of standard directories which  Override the list of directories to search for manual pages.
 .Nm  
 searches for manual pages.  
 The supplied  The supplied
 .Ar path  .Ar path
 must be a colon  must be a colon
 .Pq Ql \&:  .Pq Ql \&:
 separated list of directories.  separated list of directories.
 This search path may also be set using the environment variable  This option also overrides the environment variable
 .Ev MANPATH .  .Ev MANPATH
 The subdirectories to be searched, and their search order,  and any directories specified in the
 are specified by the  .Xr man.conf 5
 .Dq _subdir  file.
 line in the  
 .Nm  
 configuration file.  
 .It Fl m Ar path  .It Fl m Ar path
 Augment the list of standard directories which  Augment the list of directories to search for manual pages.
 .Nm  
 searches for manual pages.  
 The supplied  The supplied
 .Ar path  .Ar path
 must be a colon  must be a colon
 .Pq Ql \&:  .Pq Ql \&:
 separated list of directories.  separated list of directories.
 These directories will be searched before the standard directories or  These directories will be searched before those specified using the
 the directories specified using the  
 .Fl M  .Fl M
 option or the  option, the
 .Ev MANPATH  .Ev MANPATH
 environment variable.  environment variable, the
 The subdirectories to be searched, and their search order,  .Xr man.conf 5
 are specified by the  file, or the default directories.
 .Dq _subdir  
 line in the  
 .Nm  
 configuration file.  
 .It Fl S Ar subsection  .It Fl S Ar subsection
 Restricts the directories that  Only show pages for the specified
 .Nm  
 will search to those of a specific  
 .Xr machine 1  .Xr machine 1
 architecture.  architecture.
 .Ar subsection  .Ar subsection
Line 158  architecture whilst using another.
Line 167  architecture whilst using another.
 This option overrides the  This option overrides the
 .Ev MACHINE  .Ev MACHINE
 environment variable.  environment variable.
 .It Xo  .It Oo Fl s Oc Ar section
 .Op Fl s  Only select manuals from the specified
 .Ar section  .Ar section .
 .Xc  
 Restricts the directories that  
 .Nm  
 will search to a specific section.  
 The currently available sections are:  The currently available sections are:
 .Pp  .Pp
 .Bl -tag -width "localXXX" -offset indent -compact  .Bl -tag -width "localXXX" -offset indent -compact
Line 174  General commands
Line 179  General commands
 .It 2  .It 2
 System calls and error numbers.  System calls and error numbers.
 .It 3  .It 3
 Libraries.  Library functions.
 .It 3f  
 Fortran programmer's reference guide.  
 .It 3p  .It 3p
 .Xr perl 1  .Xr perl 1
 programmer's reference guide.  programmer's reference guide.
Line 187  File formats.
Line 190  File formats.
 .It 6  .It 6
 Games.  Games.
 .It 7  .It 7
 Miscellaneous.  Miscellaneous information.
 .It 8  .It 8
 System maintenance and operation commands.  System maintenance and operation commands.
 .It 9  .It 9
 Kernel internals.  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 w  .It Fl w
 List the pathnames of the manual pages which  List the pathnames of all matching manual pages instead of displaying
 .Nm  any of them.
 would display for the specified  
 .Ar section  
 and  
 .Ar name  
 combination.  
 .El  .El
 .Pp  .Pp
 Guidelines for writing  The options
 man pages can be found in  .Fl IKOTW
 .Xr mdoc 7 .  are also supported and are documented in
   .Xr mandoc 1 .
   The options
   .Fl fkl
   are mutually exclusive and override each other.
 .Pp  .Pp
   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,  If both a formatted and an unformatted version of the same manual page,
 for example  for example
 .Pa cat1/foo.0  .Pa cat1/foo.0
 and  and
 .Pa man1/foo.1 ,  .Pa man1/foo.1 ,
 exist in the same directory, and at least one of them is selected,  exist in the same directory, only the unformatted version is used.
 only the newer one is used.  The database is kept up to date with
 However, if both the  .Xr makewhatis 8 ,
 .Fl a  which is run by the
 and the  .Xr weekly 8
 .Fl w  maintenance script.
 options are specified, both file names are printed.  .Pp
   Guidelines for writing
   man pages can be found in
   .Xr mdoc 7 .
 .Sh ENVIRONMENT  .Sh ENVIRONMENT
 .Bl -tag -width MANPATHX  .Bl -tag -width MANPATHX
 .It Ev MACHINE  .It Ev MACHINE
Line 258  is case insensitive.
Line 270  is case insensitive.
 .It Ev MANPAGER  .It Ev MANPAGER
 Any non-empty value of the environment variable  Any non-empty value of the environment variable
 .Ev MANPAGER  .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  .It Ev MANPATH
 The standard search path used by  Override the standard search path which is either specified in
 .Nm  .Xr man.conf 5
 may be overridden by specifying a path in the  or the default path.
   The format of
 .Ev MANPATH  .Ev MANPATH
 environment  is a colon
 variable.  
 The format of the path is a colon  
 .Pq Ql \&:  .Pq Ql \&:
 separated list of directories.  separated list of directories.
 The subdirectories to be searched, as well as their search order,  Invalid directories are ignored.
 are specified by the  Overridden by
 .Dq _subdir  .Fl M ,
 line in the  ignored if
 .Nm  .Fl l
 configuration file.  is specified.
   .Pp
   If
   .Ev MANPATH
   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 path is inserted between the colons.
 .It Ev PAGER  .It Ev PAGER
 Specifies the pagination program to use when  Specifies the pagination program to use when
 .Ev MANPAGER  .Ev MANPAGER
 is not defined.  is not defined.
 If neither PAGER nor MANPAGER is defined,  If neither PAGER nor MANPAGER is defined,
 .Pa /usr/bin/more Fl s  .Xr more 1
 will be used.  .Fl s
   is used.
 .El  .El
 .Sh FILES  .Sh FILES
 .Bl -tag -width /etc/man.conf -compact  .Bl -tag -width /etc/man.conf -compact
 .It Pa /etc/man.conf  .It Pa /etc/man.conf
 default man configuration file  default
   .Nm
   configuration file
 .El  .El
 .Sh EXIT STATUS  .Sh EXIT STATUS
 .Ex -std man  .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  .Sh SEE ALSO
 .Xr apropos 1 ,  .Xr apropos 1 ,
 .Xr intro 1 ,  .Xr col 1 ,
 .Xr whatis 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 mdoc 7
 .Xr intro 7 ,  
 .Xr mdoc 7 ,  
 .Xr intro 8 ,  
 .Xr intro 9  
 .Sh STANDARDS  .Sh STANDARDS
 The  The
 .Nm  .Nm
Line 314  utility is compliant with the
Line 367  utility is compliant with the
 specification.  specification.
 .Pp  .Pp
 The flags  The flags
 .Op Fl aCcfhMmSsw ,  .Op Fl aCcfhIKlMmOSsTWw ,
 as well as the environment variables  as well as the environment variables
 .Ev MACHINE ,  .Ev MACHINE ,
 .Ev MANPAGER ,  .Ev MANPAGER ,
Line 353  in
Line 406  in
 .Fl C  .Fl C
 in  in
 .Nx 1.0 ;  .Nx 1.0 ;
 and  
 .Fl s  .Fl s
 and  and
 .Fl S  .Fl S
 in  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 .
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.36
CVSweb