gnu/usr.bin/man/README

   1 README file for man(1).
   2
   3 This is a replacement for Un*x man(1), apropos(1), whatis(1), and
   4 manpath(1).  It has all kinds of neat features that other versions of
   5 man don't, including support for multiple man page directory trees,
   6 preformatted man pages, and troff.  It is provided without any
   7 warranty whatever.  I hope you find it useful.
   8
   9 This program is not a GNU product but it is distributed under the
  10 terms of the GNU copyleft which is described in the file COPYING.
  11
  12 There is a solution written in perl which is probably superior in
  13 every way, but, like me, you may prefer this one anyway.
  14 :-)
  15
  16 If you compile with support for preformatted man pages, man(1) will
  17 try to update the preformatted page if the man page source is newer.
  18
  19 If you compile with support for troff, you can say things like
  20 `man -t foo | psdit > foo.ps' and have fabulous printed documentation
  21 as well.
  22
  23 I have resisted the temptation to handle all the bizarre ways various
  24 vendors have of organizing man pages.  This version of man assumes
  25 that directory trees have the structure:
  26
  27    .../man
  28           /manSect
  29               /foo.Sect*
  30                ...
  31           /catSect
  32               /foo.Sect*
  33                ...
  34
  35 where Sect is some number or string and should be listed in the set of
  36 sections to be searched.  It is not necessary to have both the cat*
  37 and man* subdirectories, but you must have at least one. :-)
  38
  39
  40 INSTALLATION
  41
  42 1. Run configure.  This will grope around your system a bit and then
  43    ask you a number of questions.  It will create a Makefile from the
  44    file Makefile.in, and a config.h file from config.h.in.  You may
  45    have to do some fine tuning to get things to work exactly right on
  46    your system.  If you do, I'd like to know what changes you had to
  47    make to get things working.
  48
  49 2. Edit the manpath.config file.  This determines the system-wide
  50    mappings for bin directories and man page directories.
  51
  52 3. Do a `make all', try it out, and then if you're happy with that, do
  53    a `make install'.  You don't need to be root to use this set of
  54    programs.
  55
  56 4. Install the whatis database(s) by running makewhatis.  If you want
  57    to keep things absolutely current, you'll need to run this whenever
  58    you add new man pages.  You might want to add an entry in your
  59    crontab.
  60
  61 BUGS
  62
  63 If you find one of these, please tell me about it.  If you have a fix,
  64 that's even better.  If not, I can't guarantee that I'll fix it, but I
  65 would like to know about them.
  66
  67 John Eaton
  68 jwe@che.utexas.edu
  69 Department of Chemical Engineering
  70 The University of Texas at Austin
  71 Austin, Texas  78712
  72
  73
  74 CHANGES
  75
  76 Partial list of changes since version 1.0:
  77
  78 Installation made easier (this was the intent anyway) with the
  79 introduction of a configure script.
  80
  81 Commands like `man 3f intro' handled properly when the name of the
  82 file we want is something like .../man3/intro.3f.
  83
  84 Man can now run set uid to a special user so formatted man pages don't
  85 have to be world writable.
  86
  87 Man now works with compressed (.Z) frozen (.F) and yabba (.Y) cat
  88 files.  Frozen files are compressed files using freeze/melt, some
  89 combination of LZW and tree coding.  Sources for it came out on
  90 comp.sources.misc or alt.sources or ... a few months ago.  Yabba files
  91 are compressed using yabba/unyabba, a data compression scheme posted
  92 to alt.sources by Dan Bernstein.
  93
  94 Man now uses a more reasonable default for the search order:
  95 1, n, l, 6, 8, 2, 3, 4, 5, 7, p, o
  96
  97 Man now allows for user-definable section search order via -S or
  98 MANSECT.
  99
 100 Glob.c can work even if you don't have alloca, and works properly on
 101 Suns with the Sun C compiler.
 102
 103 There is now a way to automatically to run preprocessors like the Sun
 104 man program.  The first line of the man page indicates which
 105 preprocessors should be run:
 106
 107       If the first line is a string of the form:
 108
 109           '\"  X
 110
 111       where  X is separated from the `"' by a single SPACE and
 112       consists of any combination of characters in  the  following
 113       list,  man  pipes  its input to troff(1) or nroff(1) through
 114       the corresponding preprocessors.
 115
 116           e    eqn(1), or neqn for nroff
 117           g    grap(1)
 118           p    pic(1)
 119           r    refer(1)
 120           t    tbl(1), and col(1V) for nroff
 121           v    vgrind(1)
 122
 123 Preprocessors may also be set on the command line with -p or from the
 124 environment with MANROFFSEQ.
 125
 126 The tbl preprocessor is run by default.
 127
 128 Manpath now stat()'s the directories in MANPATH to avoid including
 129 directories that don't exist.
 130
 131 The output of apropos and whatis are now piped through PAGER.
 132
 133 There is a new option to show where you would find a man page
 134 (-w option) and in what order (-w with -a).