gnu/usr.bin/man/man/man.man

   1 .\" Man page for man
   2 .\"
   3 .\" Copyright (c) 1990, 1991, John W. Eaton.
   4 .\"
   5 .\" You may distribute under the terms of the GNU General Public
   6 .\" License as specified in the README file that comes with the man 1.0
   7 .\" distribution.
   8 .\"
   9 .\" John W. Eaton
  10 .\" jwe@che.utexas.edu
  11 .\" Department of Chemical Engineering
  12 .\" The University of Texas at Austin
  13 .\" Austin, Texas  78712
  14 .\"
  15 .\" $FreeBSD: src/gnu/usr.bin/man/man/man.man,v 1.10.2.8 2002/06/25 00:02:55 eric Exp $
  16 .\" $DragonFly: src/gnu/usr.bin/man/man/man.man,v 1.7 2008/08/21 21:02:33 thomas Exp $
  17 .\"
  18 .Dd August 21, 2008
  19 .Dt MAN 1
  20 .Os
  21 .Sh NAME
  22 .Nm man
  23 .Nd format and display the on-line manual pages
  24 .Sh SYNOPSIS
  25 .Nm
  26 .Op Fl adfhkotw
  27 .Op Fl m Ar machine
  28 .Op Fl p Ar string
  29 .Op Fl M Ar path
  30 .Op Fl P Ar pager
  31 .Op Fl S Ar list
  32 .Op Ar section
  33 .Ar name ...
  34 .Sh DESCRIPTION
  35 .Nm Man
  36 formats and displays the on-line manual pages.
  37 This version knows about the
  38 .Ev MANPATH
  39 and
  40 .Ev PAGER
  41 environment variables, so you can have
  42 your own set(s) of personal man pages and choose whatever program you
  43 like to display the formatted pages.
  44 If
  45 .Ar section
  46 is specified,
  47 .Nm
  48 only looks in that section of the manual.
  49 You may also specify the order to search the sections for entries and
  50 which preprocessors to run on the source files via command line options
  51 or environment variables.
  52 If enabled by the system administrator, formatted man pages will also
  53 be compressed with the
  54 .Nm %compress%
  55 command to save space.
  56 If
  57 .Ar name
  58 contains a
  59 .Sq / ,
  60 .Nm
  61 treats it as a file name.
  62 .Pp
  63 The options are as follows:
  64 .Bl -tag -width Fl
  65 .It Fl M Ar path
  66 Specify an alternate manpath.
  67 By default,
  68 .Nm
  69 uses
  70 .Xr manpath 1
  71 (which is built into the
  72 .Nm
  73 binary)
  74 to determine the path to search.
  75 This option overrides the
  76 .Ev MANPATH
  77 environment variable.
  78 .It Fl P Ar pager
  79 Specify which pager to use.
  80 By default,
  81 .Nm
  82 uses
  83 .Nm %pager% .
  84 This option overrides the
  85 .Ev PAGER
  86 environment variable.
  87 .It Fl S Ar list
  88 List is a colon separated list of manual sections to search.
  89 The default is
  90 .Dq 1:8:2:3:4:5:6:7:9 .
  91 This option overrides the
  92 .Ev MANSECT
  93 environment variable.
  94 .It Fl a
  95 By default,
  96 .Nm
  97 will exit after displaying the first manual page it
  98 finds.
  99 Using this option forces
 100 .Nm
 101 to display all the manual pages
 102 that match
 103 .Ar name ,
 104 not just the first.
 105 .It Fl d
 106 Don't actually display the man pages, but do print gobs of debugging
 107 information.
 108 .It Fl f
 109 Equivalent to
 110 .Nm whatis .
 111 .It Fl h
 112 Print a help message and exit.
 113 .It Fl k
 114 Equivalent to
 115 .Nm apropos .
 116 .It Fl m Ar machine
 117 As some manual pages are intended only for specific architectures,
 118 .Nm
 119 searches any subdirectories,
 120 with the same name as the current architecture,
 121 in every directory which it searches.
 122 Machine specific areas are checked before general areas.
 123 The current machine type may be overridden using this option
 124 or by setting the environment variable
 125 .Ev MACHINE
 126 to the name of a specific architecture.
 127 This option overrides the
 128 .Ev MACHINE
 129 environment variable.
 130 .It Fl o
 131 Look for original, non-localized manpages only.
 132 .Pp
 133 By default,
 134 .Nm
 135 searches for a localized manpage
 136 in a set of locale subdirectories of each
 137 .Xr manpath 1
 138 component.
 139 .Pp
 140 Locale name is taken from the first of three environment variables
 141 with a nonempty value:
 142 .Ev LC_ALL , LC_CTYPE ,
 143 or
 144 .Ev LANG ,
 145 in the specified order.
 146 .Pp
 147 If the value could not be determined, or is not a valid locale name,
 148 then only non-localized manpage will be looked up.
 149 .Pp
 150 Otherwise,
 151 .Nm
 152 will search in the following subdirectories, in the order of precedence:
 153 .Pp
 154 .Bl -item -offset indent -compact
 155 .Sm off
 156 .It
 157 .Pa <lang> _ <country> . <charset>
 158 .It
 159 .Pa <lang> . <charset>
 160 .It
 161 .Pa en . <charset>
 162 .Sm on
 163 .El
 164 .Pp
 165 For example, for
 166 .Dq de_DE.ISO8859-1
 167 locale,
 168 .Nm
 169 will search in the following subdirectories of the
 170 .Pa /usr/share/man
 171 manpath component:
 172 .Pp
 173 .Bl -item -offset indent -compact
 174 .It
 175 .Pa /usr/share/man/de_DE.ISO8859-1
 176 .It
 177 .Pa /usr/share/man/de.ISO8859-1
 178 .It
 179 .Pa /usr/share/man/en.ISO8859-1
 180 .El
 181 .Pp
 182 Finally,
 183 if the search of localized manpage fails,
 184 it will be looked up in the default
 185 .Pa /usr/share/man
 186 directory.
 187 .It Fl p Ar string
 188 Specify the sequence of preprocessors to run before nroff or troff.
 189 Not all installations will have a full set of preprocessors.
 190 Some of the preprocessors and the letters used to designate them are:
 191 eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r).
 192 This option overrides the
 193 .Ev MANROFFSEQ
 194 environment variable.
 195 .It Fl t
 196 Use
 197 .Nm %troff%
 198 to format the manual page, passing the output to stdout.
 199 The output from
 200 .Nm %troff%
 201 may need to be passed through some filter or another before being
 202 printed.
 203 .It Fl w
 204 Don't actually display the man pages, but do print the location(s) of
 205 the files that would be formatted or displayed.
 206 .El
 207 .Sh ENVIRONMENT
 208 .Bl -tag -width MANROFFSEQ
 209 .It Ev LC_ALL , LC_CTYPE , LANG
 210 These variables specify the preferred language for manual pages.
 211 (See the
 212 .Fl o
 213 option above.)
 214 .It Ev MACHINE
 215 If
 216 .Ev MACHINE
 217 is set, its value is used to override the current machine type
 218 when searching machine specific subdirectories.
 219 .It Ev MANPATH
 220 If
 221 .Ev MANPATH
 222 is set, its value is used as the path to search for manual pages.
 223 .It Ev MANROFFSEQ
 224 If
 225 .Ev MANROFFSEQ
 226 is set, its value is used to determine the set of preprocessors run
 227 before running
 228 .Xr nroff 1
 229 or
 230 .Xr troff 1 .
 231 By default, pages are passed through the table preprocessor before
 232 .Xr nroff .
 233 .It Ev MANSECT
 234 If
 235 .Ev MANSECT
 236 is set, its value is used to determine which manual sections to search.
 237 .It Ev PAGER
 238 If
 239 .Ev PAGER
 240 is set, its value is used as the name of the program to use to display
 241 the man page.
 242 By default,
 243 .Nm %pager%
 244 is used.
 245 .El
 246 .Sh EXAMPLES
 247 .Pp
 248 Normally, to look at the relevant manpage information for getopt,
 249 one would use:
 250 .Pp
 251 .Dl man getopt
 252 .Pp
 253 However, when referring to a specific section of the manual,
 254 such as
 255 .Xr getopt 3 ,
 256 one would use:
 257 .Pp
 258 .Dl man 3 getopt
 259 .Sh SEE ALSO
 260 .Xr apropos 1 ,
 261 .Xr groff 1 ,
 262 .Xr manpath 1 ,
 263 .Xr more 1 ,
 264 .Xr whatis 1 ,
 265 .Xr man 7 ,
 266 .Xr mdoc 7
 267 .Sh BUGS
 268 The
 269 .Fl t
 270 option only works if the
 271 .Xr troff 1 Ns -like
 272 program is installed.