Mathematics Department computing facilities
|Computer and Printing Support|
|Nelson H. F. Beebefirstname.lastname@example.org||801-581-5254|
Table of contents
The bulk of our online software documentation is stored in the emacs info system, accessible inside emacs with the keystrokes C-h i (Control-h followed by the letter i), and on the Unix command line with the info and xinfo programs.
If you are unfamiliar with info, once inside, just type h for help and a tutorial. Barely a half-dozen one-letter commands suffice for most uses of info, and you can get a command summary at any time by typing a question mark (?). To quit, just type q.
In particular, documentation for almost all GNU software packages, locally-written packages, and mathematical libraries like EISPACK, LINPACK, and LAPACK, is provided in info form. Simple navigational and search commands and extensive use of hyperlinks make document access even easier than in Web browsers. From emacs, re-entry to the info system brings you back to the last node visited, making it easy to switch back and forth between documentation and the program that you are writing, and you don't need a window system to use info.
Traditional documentation in the Unix system takes the form of manual pages, which vendors normally also provided as a series of about ten fat printed volumes. Low-numbered volumes are used most frequently: volume 1 is user commands, volume 2 is system calls, volume 3 is C library functions, and so on. The higher volumes are numbered inconsistently across different Unix platforms.
The manual pages are intended to be brief summaries of software capabilities, not tutorials or detailed reference manuals. Nevertheless, some are large: the Unix shells (each of them a complex programming language) have manual pages of 30 or more pages.
The man command provides access to the manual pages. It takes an optional section number (-s n or n, depending on the Unix flavor), and the name of a command, file, system call, or library routine for which you need documentation. The section number is only rarely needed: it disambiguates names that appear in more than one section of the manual.
Here is an example:
% man f90 User Commands F95(1) NAME f95, f90 - Fortran 95 compiler SYNOPSIS May be invoked by either f95 or f90 commands; they are equivalent. f95 [ -a ] [ -aligncommon[=a] ] [ -ansi ] [ -arg=local ] [ -autopar ] [ -Bx ] [ -C ] [ -c ] [ -cg89 ] [ -cg92 ] [ -copyargs ] [ -Dnm[=def] ] [ -dalign ] ... DESCRIPTION ... OPTIONS ... ENVIRONMENT ... FILES ... SEE ALSO ... asa(1), cc(1), dbx(1), fpp(1), fpr(1), fsplit(1), gprof(1), ild(1), ld(1), perror(3f), prof(1), tcov(1) ...
As illustrated, the manual page is organized into sections:
- NAME (one-line summary),
- SYNOPSIS (command and its [optional] arguments),
- DESCRIPTION (explanatory prose),
- OPTIONS (documentation of command-line options),
- ENVIRONMENT (Unix environment variables that affect command behavior),
- FILES (documentation of files that the command uses),
- BUGS (caveats, misfeatures, and notes about potential problems), and
- SEE ALSO (cross references to related commands).
The first four, and last, of those sections should always be present. The remaining sections, and others not listed here, may be present or absent, according to their author's intent.
The parenthesized section number is conventional in cross-references in manual-page documentation, as shown above in the fragment of the SEE ALSO section.
Here are examples of manual pages for a name that is both a user command
% man -s 1 chown User Commands chown(1) NAME chown - change file ownership SYNOPSIS chown [ -fhR ] owner [ : group ] file ... ...
and a system call:
% man -s 2 chown System Calls chown(2) NAME chown, lchown, fchown - change owner and group of a file SYNOPSIS #include <unistd.h> #include <sys/types.h> int chown(const char *path, uid_t owner, gid_t group); ...
The man command is fine when you know exactly what documentation you need, but with 10,000+ manual pages available, more context is helpful. Manual pages are normally written in the -man style in the nroff and troff markup systems (although Sun Solaris often uses SGML markup instead), and to provide more information for subject searches, they contain a title header markup command that provides a one-line summary of their documentation. A database of those summaries is kept up-to-date nightly and can be accessed with the man -k (keyword) command, or equivalently, the apropos command:
% apropos fortran ... same as next example ... % man -k fortran ... asa (1) - convert FORTRAN carriage-control output to printable form f77 (1) - FORTRAN 77 compiler f95, f90 (1) - Fortran 95 compiler fdumpmod (1) - utility for displaying Fortran 95 module information fpp (1) - the Fortran language preprocessor for FORTRAN 77 and Fortran 95. ...
The output gives the manual page name, section (in parentheses), and a one-line summary.
Sometimes, even the one-line summaries are insufficient to find what you want: after all, they represent less than 0.3% of the more than three million lines of documentation in our collected vendor-provided and locally-added manual pages. We therefore provide full-text searching of the entire manual-page collection with the glimpseman command (named after the underlying search engine, glimpse):
% glimpseman fortran | less ... /opt/SUNWspro/prod/man/man1/fsplit.1: (This option has meaning for fortran-90 text only). ... /usr/local/man/man1/phase.1: A fortran routine that computes f(t,x,p). This is created as ... /usr/local/man/man1/ftnchek.1: ftp://netlib.org/fortran . ...
The output of this command can be voluminous, so we piped it into the less pager utility. The output shows filenames and contained lines whose text matches the command-line argument. The subdirectory man1 corresponds to section 1 of the manual, so you could later issue a man -s 1 ftnchek command to view the user-command manual pages for ftnchek(1).
Some manual pages can be converted to HTML with the man2html or rman utilities, and as a result, several thousand HTML files exist in the directory tree /usr/local/man/html for access via the File -> Open menu path in Web browsers.
- Frequently-asked questions (FAQ)
- Accounts FAQ
- Software catalog and FAQ
- Hardware FAQ
- C language and C compilers
Please read the FAQ before selecting a mail client. Most of them have unique mailbox formats that are unusable by other mail clients, making it difficult to switch clients without losing access to your old mail.
Text-based mail clients include:
- mail (the original Unix mail client)
- Mail (the `improved' BSD Unix mail client)
- mm (recommended)
- pine (recommended)
- rmail (inside GNU Emacs) (recommended)
GUI-based mail clients include:
- evolution (GNU/Linux only)
- kmail (GNU/Linux only)
- mailtool (Sun Solaris 8 and 9 only: dropped from Solaris 10)
- thunderbird (recommended: it is the companion to the firefox GUI-based browser)
- w3schools HTML Tutorial , HTML Goodies or HTML Code Tutorial (HyperText Markup Language). See also the URL (Uniform Resource Locator) primer.
- J. Williard Marriott Library (catalog and document databases)
- Login FAQ
- Maple symbolic-algebra system (including high-precision arithmetic and 2-D and 3-D graphing of functions)
- Mathematica symbolic-algebra system (including high-precision arithmetic and 2-D and 3-D graphing of functions)
- Matlab online matrix laboratory
- MuPAD symbolic-algebra system (including high-precision arithmetic and 2-D and 3-D graphing of functions)
- Printing FAQ
- TeX and METAFONT FAQ (typesetting and font design)
- ed (the original Unix editor)
- edit (variant of ex)
- ex (the kernel under vi)
- emacs (the world's most powerful text editor) (recommended)
- jove and its tutorial system teachjove
- sed (stream editor)
- textedit (Sun Solaris only)
- vi (the original BSD Unix screen editor)
- Unix tutorial
- Unix command summary
GUI-based browsers available include:
- firefox (recommended)
- konqueror (GNU/Linux only)
- safari (Mac OS X only)
- xmosaic (the original Web browser)
Text-based browsers available include:
With suitable command-line arguments, most text-based browsers can convert HTML to plain text, with or without hypertext links as footnotes. That is often convenient for batch processing, or for just getting a large document into a format to which you can apply more powerful search techniques, such as regular-expression pattern matching, optionally with surrounding context, with agrep, egrep, glimpse, grep, seft, and xseft.
A useful adjunct to browsers is the wget utility, which can recursively fetch entire remote Web document trees for local storage. The ncftp and ncftpget commands have similar capabilities for fetching remote FTP archives.
- wired and wireless networks FAQs