Getting Help Under Unix ----------------------- While they're not all well-advertised, there are actually a variety of means of getting help under Unix. The most important and reliable of these are `man' pages, so called because they correspond to online manuals for programs, file formats, functions, system calls, and so forth. `man' is also the name of the program used to read them. If you've never read one before, the best way to start is by typing 'man man' at the command line. Of course, while man pages are a vast improvement over the online documentation of most other OSes, they suffer from many failings: * some people don't like to read text on the screen * not very helpful unless you already know what to look for * not always accessible even when present * not always present, especially under Linux * often hard to read, as they try to be authoritative (and consequently are often too technical for new users) * frequently out of date That said, they're still better and more comprehensive than the alternatives. We'll try to address the first three failings in this document. Man pages are the standard documentation for every Unix. Before long you're bound to come across a reference of the form command (N), where N is a number from 1-9, possibly followed by a letter. For example, man (1), or ls (1). This means that the given command is documented under that name, in the section given within parentheses. Section Names ------------- The section may need to be specified if there are multiple man pages for the same name. For example, under SunOS there are man pages called `man' in both sections 1 and 7. If no section is specified man will give you the first manpage it finds, or you can use the **-f** option to see all the available man pages for a given name. As with man -k and apropos_, man -f is just a shorter way of saying 'whatis', so man -f SOMETHING and whatis SOMETHING are synonymous. You should be able to get a description of each section (they vary from Unix to Unix) by doing man SECTION# intro Printing Man Pages ------------------ You have a couple of options here, depending on whether you mind wasting a full page of paper for each page of text - we recommend printing man pages at least half-size, as you're unlikely to return to them a month later. The simplest and most portable thing to do (though alternatives exist) is man -t MANPAGE >MANPAGE.ps ( only works straightforwardly under Linux) This will produce a file called MANPAGE.ps in your current directory. You can then use psnup (1) under SunOS to print this file at 2 or 4 pages to a physical page. Unfortunately, while the -t parameter is itself portable to virtually all man implementations, the output is not. Under Linux, the above works fine. Under SunOS and Solaris, you have to do some preparation first: define the environment variable TCAT to be 'cat' and TROFF to be '/usr/local/bin/groff -man'. Furthermore, the GROFF_TYPESETTER variable must be set to 'ps'. If you have trouble getting psnup to work or don't feel like fooling around with it, you can always work with text instead. This isn't ~quite~ text, as it still has bolding and underlining and so forth, but a2ps (1) understands it, as does less (1). man MANPAGE|a2ps -m >MANPAGE.ps You don't have to produce the ps file if you don't like, of course - if you're confident that it'll work the first time, replace the '>MANPAGE.ps' with '|lpr -Pprinter-name'. Personally, I recommend previewing the output with ghostview (1) beforehand. _apropos _finding_man_pages Finding man pages ----------------- **apropos/man -k/man -kr** One invocation of man that you'll likely come to be very familiar with is the **-k** (keyword) option. This function is also available by running apropos (1), i.e., man -k and apropos are equivalent. It lets you search the database of man page summaries for a keyword. For example, suppose you were looking for utilities to manipulate postscript documents. Your first step could be man -k postscript This produces a list, with summaries, of man pages which are likely to be related to your topic. If you were looking for something less specific, say programs associated with databases, you would probably want to use less and/or grep to filter and view the output - it can get to be many screenfuls if your string is short or common enough. Note that these commands search a database which in most cases must be built by the system administrators, a task which is sometimes forgotten. If you can't find what you're looking for and you believe it's there, try doing `man -u man' under Linux followed by your search, or `man -F' under Solaris. SunOS has no such option. Before trying this, make sure your MANPATH variable is set correctly. **MANPATH** There can be several hierarchies of man pages, depending on the system. On most of our systems, for example, at least the following directories exist: /usr/man, /usr/local/man. In addition, there will usually be one for X programs (/usr/X11/man, /usr/local/X11/man, or /usr/openwin/man) and likely one for SOCS-specific man pages (/usr/socs/man). man searches the environment variable MANPATH (a colon-separated list of directories like the PATH variable) for man pages. Normally this will be set up correctly, but if you've hacked your script files or staff screwed up, your MANPATH may be wrong. This could be why a man page you're looking for isn't there. whereis_ may be able to help here. **manual searching of manuals** You can also try looking in the man pages themselves; see the section at the end of this document on searching_in_a_loop_. Alternatively, on non-Linux OSes you can just try the quick-and-dirty method of running grep (1) in the man directories you think might contain the command you're looking for. Note that man pages aren't stored in plain text format, so the output may not be readable. If you find the string you're looking for in a file located in MANDIR/man#, do man -M MANDIR # filename to view the corresponding manpage. There's no manpage for xxxx! ---------------------------- Ok, you've tried the suggestions given above to locate a man page, and still haven't had any luck. It's quite possible there is no man page corresponding to what you're looking for - either because the tool or functionality you're searching for isn't installed on the system, or because it has no man page installed. This may be an error, a lack (one has yet to be written) or deliberate: see the next point for alternate_help_sources_. Suppose you're especially determined because you **know** that the command exists - it does something, just not quite what you want. Rather than get irate at the undocumented command, first make sure that it is actually a program residing in the file system - if not, it likely doesn't deserves a man page or is documented in some more general man page. Here's an algorithm for tracking down a command's help file. If you're running ksh or bash (you'll know if you are), first do type -t CMD For any other shell, do which CMD This will tell you what kind of command you're dealing with. If it says CMD is a 'builtin', then do help CMD (bash only) or read your shell's manual page. ~(Note that tcsh - except under Linux - doesn't document all of its builtins since most are identical to csh's. I suggest looking in csh's man page first if you're somewhere other than Linux-land.)~ If you're told that CMD is an alias, then do alias CMD and repeat this procedure from the beginning with the first word that alias returns. If you're told that CMD is a function (not in csh), do typeset -f CMD to see its definition. From there you're on your own. If you're given a path, then you may be justified in being irate. Or maybe the documentation is in another format; keep reading. _alternate_help_sources Is man really what you want? ---------------------------- Not all documentation is located in the manpages. The shells and editors sometimes have online help, as do various other programs, especially graphical ones. Other major online help systems include: * info Info isn't really complex enough to deserve describing in detail. In brief, you can read info pages within emacs using `C-h i' (`info') or from the command line using the command `info'. Online help and a tutorial on the info system are available from within both interfaces. Don't discount info pages: although they're used mainly by GNU software, this includes such hugely usefulinfo pages as gdb, gcc, emacs, gawk, and make. Perl and bash also have info pages, though the information is available by other means as well in their cases. * /usr/doc Only available under Linux, and often not terribly interesting, as a well-behaved package will provide documentation that can be integrated with the major help systems. Still, there is a lot there, and should definately be considered if you can't find what you're looking for elsewhere. Of particular interest are the docs for xv, debian, vim, wget, pgp, pine, libg++, and hsc. Files contained here will generally be of three types: HTML, postscript. or plain text (ascii). We will make the assumption that you know how to deal with these formats; if not, you should learn. Use the information in this document to find help and read up on lynx (1), ghostview (1), and less (1). * /usr/local/pkgs, /usr/local/doc, /usr/share, /usr/local/share These are more common to the servers, though they may exists on the Linux machines as well. Software packages are commonly installed into > /usr/local/pkgs/PKGNAME-VER# and a link to that directory is created as > /usr/local/pkgs/PKGNAME. Sometimes there is documentation to be found there. Documentatin which is located in /usr/doc/PKGNAME on Linux will be in these directories on the servers, though they may get linked or copied into the other directories mentionned above (/usr/local/doc /usr/share /usr/local/share). * perldoc Much perl documentation is embedded with the source modules themselves. To access it, you can usually do > perldoc MODULENAME and a manpage will be generated for you. * source code and include files While it should probably be a last resort, the source is always the most current and sometimes the only documentation available for a particular package. This is usually not installed on the system unless it cannot be compiled: for example, perl scripts and elisp source are both interpreted, and so the program **is** the source. .. provide dirs for above examples? /usr/include and /usr/local/include may also have very useful files, whether or not the program you're trying to learn more about is written in a compiled or interpreted language.