Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-) Softpanorama Search

Unix man command

The external man command searches for the file describing a particular command. If found, this file, called the manual entry is formatted and displayed on the screen. The manuals are often referred to as "man pages." There is one man page entry per command.

Man pages are produced nroff format The format is completely outdated and it is highly recommended to convert it html and use html browser instead. Still even for hardcore guys at least a couple of tools like man editor and tkman viewer might be useful (see below).

Note:

The file format is "roff", but nobody calls it that. The program that converts into postscript and the like for sophisticated display devices is troff. The program that converts for character-display devices is nroff. Since man pages are converted into a character-display format, the files are generally called "nroff files". 

Following is the general format of the man command.

  man  [ - ] [ -M path ] [ section ] title
  man  [ - ] [ -M path ] [ -f file ]
  man  [ - ] [ -M path ] [ -k keyword ]

man [ -cdw ] [ -Tterm ] [ section ] titles

Options

Arguments

The following list describes the arguments that may be passed to the man command.

The on-line copy of the Reference Manual is not always available to you. If you are on a small system or your system was running low on disk storage, the system administrator may have removed some of all of the manual entries to gain disk space. The entries use up approxiatmately 3 megabytes of storage.

The following is a description of each section and the layout of the manuals in their on-line and physical format.

Sections

There are twelve sections of the reference manuals. They are:

Some of the sections listed have subsections. The numbers of the sections follow the name of a command in parentheses. For example, cat(1) informs you that you can find the entry for the cat command in section 1 of the reference manual. The notation cu(1C) informs you that the cu command is used for communications. The following list describes the subsections.

Physical Layout

There are three reference manuals containing only the entries relavent to the named audience. They are:

User's Reference Manual (Sections 1 & 6)

Programmer's Reference Manual ( Sections 1, 2, 3, 4, & 5)

System Administrator's Reference Manual ( Sections 1, 7, & 8 or 1m)

On-line Layout

The on-line copy of the reference manual resides in these corresponding directories:

/usr/man/man1

/usr/man/man2

...

/usr/man/man8

For more information on how to read a man page refer to the Introduction of a Reference Manual. Each vendor may implement the manuals as they desire. Most BSD type vendors support the BSD man page layout while most System V vendors that support the man pages tend to follow the AT&T standard.

Old News ;-)

html2man

See also ntp-doc-4.2.4-26mdv2010.0.i586 RPM

#! @PATH_PERL@ -w
#
# html2man: Converts the NTP HTML documentation to man page format
#
# This file require the Perl HTML::TokeParser module:
# http://search.cpan.org/search?module=HTML::TokeParser
#
# Depending on where this is run from, you might need to modify $MANDIR below.
#
# Hacked together by Peter Boettcher <boettcher@ll.mit.edu>
# Last modified: <Mon Jan 28 17:24:38 2002 by pwb>
 

RuDI Ruby Utilities for DITA processing Wiki ManPageProcessing — Project Kenai

The core of the system is html2man.rb--a Ruby utility script that converts HTML pages to nroff/troff* man pages. The utility has been in use for several years, operating on files that were at times 80 pages long. (There were 5 distinct formats in those files, Some had TOCs and some didn't, and there was a variety of header styles, for example. So the tool is nothing if not robust.)

Wrapped around that utility is a Rake script that does the builds, along with some convenience scripts:

• html2man which sets environment variables and invokes html2man.rb
• man which (once configured) uses the local man page processor to display the results, and
• zap which removes an output file so that running the script causes it to be regenerated

Note:
 

The file format is "roff", but nobody calls it that. The program that converts into postscript and the like for sophisticated display devices is troff. The program that converts for character-display devices is nroff. Since man pages are converted into a character-display format, the files are generally called "nroff files".

unroff release 1.0 information

Unroff reads and parses UNIX troff documents and translates the embedded markup into a different format (see Figure 1). Neither the actual output format nor any knowledge about particular troff macro sets (-man, -ms, etc.) are hard-wired into unroff. Instead, the translation process is controlled by a set of user-supplied procedures written in the Scheme programming language.

Translation rules for new output formats and troff macro packages can be added easily by providing a corresponding set of Scheme procedures (a ``back-end''). Version 1.0 of unroff includes back-ends for translating documents using the ``man'' and ``ms'' macros into the Hypertext Markup Language (HTML) version 2.0. Additional requests facilitate use of arbitrary hypertext links in troff documents.

manServer - Man Page To HTML Converter

manServer is a troff (or nroff) to HTML interpreter written in Perl. It is designed specifically to convert manual pages written using the man(7) troff macros into HTML for display and navigation with a web browser. To this end it includes direct support for man macros (also limited support for tbl, eqn and the doc macros) as well as the most common troff directives.

It differs from programs like man2html which merely take rather ugly nroff output and put a thin HTML wrapper around it.

The following macros and directives are supported by manServer, with varying degrees of correspondence to their troff counterparts. Where there are significant differences these are usually due to the fact that troff tends to be layout-oriented while HTML is more content-oriented and does not provide the same kind of detailed layout control.

Man oh man

The contents of a man page

Although options may vary wildly from command to command, the contents of a man page are highly regular. Indeed, man pages are invaluable because of the conventions. After reading just a handful, you can quickly jump to the right portion of the document to find the information you seek.

A minimal man page includes five segments: a name, a synopsis, a description, some examples, and references to other pertinent material. You can see the first three segments shown in Figure 1.

• The name field lists the name of the command or function or file format and a precise, one-line description of what the software does.
• The synopsis provides a terse shorthand to describe how to use the software. If the topic of the man page is a command, this field shows the mandatory and optional switches, the format of the arguments, and the argument order. If the topic at hand is a system call or a library function, this field shows the formal arguments of the function and what, if any, header files are required to use the function.

  For example, here is the synopsis for the du command on BSD UNIX.

  du [-H | -L | -P] [-a | -s | -d depth] [-c] [-h | -k | -m | -g] [-x] [-I mask] [file ...]

  
   

  The notation used in a command synopsis is one of the helpful conventions found in the man system (and extends to the usage hints provided by late -model utilities). Here, the notation reads, "Type du; optionally, follow with one of -H, -L, or -P; again, optionally, follow by one of -a, -s, or -d, but if you use the latter, specify a depth; provide -c or not; optionally, follow with one of -h, -k, -m, or -g; and specify -x or not; specify -I and a mask or omit; and finally, provide the name of one or more files to operate on. The ellipsis (...) indicates more than one.

  Options grouped together, such as the first batch of -H, -L, and -P, work like radio buttons in a graphical user interface (GUI): You choose one of several formats mutually exclusively. The independent options, such as -c and -x, work like check boxes: on or off. Reading this notation and translating it into action becomes second nature very quickly.

  And here is the synopsis for the open() system call on BSD UNIX:

  #include <fcntl.h> int open(const char *path, int oflag, ...);

  
   

  This synopsis indicates that the fcntl.h header file is required, open() returns an integer, and you must specify the path to the file to open and a batch of flags that determine the mode (read-only, read/write, open and truncate, and so on).

• The description segment is a protracted discussion about features, usage, and all the options available on the command -line. If you want to know what du -H does, you would read the text in the description.
• The examples section shows common uses of the utility and often special cases along with an explanation.
• The last section, titled See Also, points to further reading, such as other, related commands, important system files, industry-standard specifications, and more.

In addition to the aforementioned sections, you may find a host of other ad hoc sections within a man page. One important variant is titled "Environment." It lists environment variables you can set to affect the operation of the utility. For example, the man page for man names some 10 environment variables you can alter to customize man. One is MANPATH, which lists directories to search for man pages.

---

Back to top

Stupid man tricks

So, how do you use man effectively? Here are some helpful tips:

• Customize with MANPATH. If you recall, the shell variable PATH lists directories to search for executables. For example, if you set PATH to /usr/bin:/bin:/usr/local/bin, the shell would search those three directories in the order listed to find command-line programs. Similarly, you can set MANPATH to a colon-separated list of directories to find man pages. For instance, if you set MANPATH to /usr/share/man:/usr/local/mysql/man (each is the root of a repository), man would search both directories for a matching man page.
• Search the man page repositories for content. The man utility can search man pages for strings. To search, type man -k pattern to find all pages that contain pattern. One caveat: This operation can be very slow. One alternative is to use apropos. It's an adjunct to man but searches only the one-line name fields of each page. It does not search as far and wide as man -k, but it's very fast.
• Use your favorite pager. The man utility recognizes a number of environment variables to customize output. Set the environment variable PAGER to use your favorite paging application, such as less. Some systems provide Hypertext Markup Language (HTML) versions of man pages; on those systems, set your favorite browser with the BROWSER environment variable.
• Hunt for content. Use the search capabilities of your PAGER to quickly find the content you want. For example, if you're browsing the man page for man and your pager is less and you want to learn more about MANPATH, type /MANPATH (the forward slash is the command to search), and then press Return. The less pager highlights all occurrences of the string; you can use n and ? to find the next occurrence and previous occurrence of the string, respectively.
• Tune out the noise. Use the MANSECT environment variable to list the sections you want to search for man pages (that is, 1, 2, 3, up to 8). Any section that does not appear in MANSECT is ignored. For example, if you want to ignore section 1 and concentrate on section 5, set MANSECT to 5.
• Read a man page file. If you're writing a new man page or have downloaded some files from the Internet, you can read a single man page using man's Immediate mode. To read a specific file, run man filename, where filename is a fully qualified path to the file. For example, if you are writing stocks.1—a new command in section 1 to show stock quotes—you can preview it with the command man ./stocks.1. (If you omit the leading path, man looks for a man page called stocks.1 in your MANPATH.)
• Help your fellow with man. If you install a batch of man pages on your system, you can change the global MANPATH to include the new directory and provide those man pages to every user who shares your system. The text file /etc/manpaths lists repositories one per line. You can also establish entire subsystems by creating new lists in the directory /etc/manpaths.d. Type man man.conf for more information.

By the way, if you want to list the system-wide man page repositories defined for your system, simply type manpath:

$ manpath /usr/local/man:/usr/local/share/man:/usr/share/man:/usr/man

 

However, some versions of man go further and search directories beyond those shown by manpath. On BSD UNIX, for instance, man also searches each directory listed in PATH as well as the parent directory of each path listed in PATH. Thus, if you have /usr/mysql/bin in your PATH, man would search that specific path and look for /usr/mysql/man.

 

[Sep 25, 2007] HelpUpdate suse - SUSE Wiki

The makewhatis utility collects the names and short descriptions from all the unformatted man pages in the directories and puts them into a file used by the whatis and apropos commands.

SuSE does not include this utility in their distribution because they utilize another package that takes care of the ‘man’ (manual) pages. The system administrator may install other packages eventually that does rely on the ‘makewhatis’ application. This will have to be downloaded and installed using the ‘rpm’ command.

1. Make a folder called --> /utils

2. Download this file --> makewhat-2006.1.25-29.i586.rpm to the folder called /utils

3. Go to TERMINAL - Change directory to --> /utils - Install the application using the ‘rpm’ command and ‘-ivh’ options

4. Access a TERMINAL session and type in --> makewhatis [ENTER] What happens?

freshmeat.net Project details for ManEdit

The ManEdit UNIX Manual Page Editor is an editor specifically tailored for UNIX manual pages. It has a preview viewer, uses the manual page XML format for easy editing, and comes with a tutorial and reference guide. It uses the GTK+ widget set and features syntax highlighting, a complete drag and drop system for easy viewing and editing, a crash recovery system, and sample manual page templates.

GNU-Info Bad, Man(1) Good

Posted 16 Dec 2003 by ncm (Master)

I remember the first time I encountered GNU Info. A man page said nothing useful, and referred me to GNU Info.

The first problem was that the key bindings were stupid and counterintuitive. (Still are. Every time I run it I have to figure them out all over again.) A bigger problem was that the files were badly organized, so that the information I needed was dispersed to lots of different places. Worst, having scoured the whole subtree, what I needed to know usually was not there.

I could see what had happened. All this handy organizational apparatus had to be used, so everything is broken into little sub-pages. Since it's essentially hierarchical, every detail gets separated from other related details and stuck under a nice sub-sub-heading. The really useful information doesn't really fit under any nice hierarchical category. Since there's no good place to put it, it doesn't get written down at all.

Contrast this with the experience of man pages. On my system, man automatically pipes to less, so I can scroll around freely to see the whole thing. There are headers, but no intrusive hierarchy. For anything useful the author thinks of, there was someplace good to put it, generally next to something related. In better-written pages, there's a flow, with later paragraphs building on earlier foundations. At the end, there's a "see also" that tells me what other man pages might be interesting. Usually there are examples.

The only useful info pages I've seen were converted from man pages.

Back in "the day", something as big as the make manual was considered too big to put in a man page, but that seems not to be a problem any more; certainly the bash man page is huge yet useful and entirely usable.

Can man(1) be improved upon without damaging what's good about it? Does it really lack anything important?

---

interesting(5), posted 16 Dec 2003 by yeupou (Journeyer)

moa@ulysse:~$ export PAGER=nl && man bash | tail -1 Remise en forme de bash(1), attendez SVP... 3803 GNU 20 Janvier 1999 BASH(1)

Woaw, I did not knew that the bash's man was as long... This man page is well-crafted, a very good reference. However, I think that addition to this man page would be probably too much.

I've never been fond of info, but I cannot imagine, for instance, the Emacs manual in a man page. Info as probably been written for very very big software, like gmake you mentioned.

Konqueror / Long manuals, posted 16 Dec 2003 by tjansen (Journeyer)

1. If you are using KDE, try the URL info:commandname 2. Man pages are completely unusable for very long documentation, like gcc or automake

Likewise in gnome (and emacs), posted 16 Dec 2003 by itamar (Master)

The gnome help browser lets you browse info in htmlish interface. And emacs has an info browser.

not too bad when printed too, posted 16 Dec 2003 by gilbou (Journeyer)

your bash experiment, yeupou, makes me think of the ksh man page i checked once. i had installed openbsd and the csh was a bit hard on me so i installed ksh and checked its man page. i started reading but it looked very long to me so i started scrolling down and the more i did scroll, the more pages came to screen and it was frightening at first :)
i have the habit to take notes when i read some man pages but i saw that ksh man page was so big i'd rather print it. in fact, printed man pages look pretty good.
i have a plan9 cd + manual (sent by the plan9 team to me, i was to write an article about it but i left the journal i was working for before i even started that article) and their manual is just man pages printed, and the whole thing is just great and very nice to read.
makes me think of the documentation for unix. i think i read that from "25 years of unix" (buy it if you don't own it, it's only good stuff) that they had first wrote the man pages and documentation before starting to write code. laying doc made sure everything was logical and complete, then it was just programming each tool up to its specs and what it should do. like the design of an api before you start chewing code around, what i consider a very good move to do first when it comes to writing code other people will (hopefully) reuse :D

info adds nothing important, and has weird keystrokes!, posted 16 Dec 2003 by tk (Journeyer)

I think man is good, it doesn't lack anything really important.

(Some fundamentalist bloke said, "man is underfeatured". Right, how many bells and whistles do we need to just read a technical document? Should we throw in Microsoft's Clippit too?)

(And, "Still baffles me how people learn vi as if it's the cool thing to do, [...] and yet are scared off by simpler tools such as lynx or info." Because, many of vi's keystrokes can be directly used in more and man. Not info.)

Can man be improved? Some kind of internal/external hyperlinking facility will be nice, but this requires some twiddling in both groff and more. And last I checked, groff's HTML output support is still experimental.)

my info rant, posted 17 Dec 2003 by trs80 (Apprentice)

I already ranted about info but I'll link to it here for completeness. Thanks ncm for expressing your opinion (which is pretty similar to mine) on man(1) in a less ranty and more coherent way than I did, and putting it into an article (which I should have done).

searching in info documents, posted 17 Dec 2003 by jamesh (Master)

trs80: the standalone info reader does support searching within an info document. It uses the same keybinding as Emacs does. Just type ctrl+s and start typing. If the word isn't found on the current page, it continues to the next. Press ctrl+s again to search to the next match.

they're kinda different, but I like info, posted 17 Dec 2003 by graydon (Master)

personally, I really like info. I like that emacs has a nice reader for it, I like writing docs in texi (comparing with docbook and troff, texi is aesthetically much more pleasant to write) and I like the browser paradigm for documentation: setting bookmarks and having a "go back" key really helps.

I think there's a philosophical difference, anyways. texi is designed to "embed reference docs in the context of a book", or book-like document. it's a medium which is more GNU, less unix: the document is supposed to invite readers in, even novices, to learn about your program. texi docs should contain tutorial and getting started sections, as well as reference.

man pages are terse, usually just refreshers in "how to invoke so-and-so properly, and some common mistakes". you still need to know you want to run so-and-so to do a task, and roughly how it works. if you look at a lot of the older man pages, they really are just 1 printed page.

makeinfo --no-header, posted 17 Dec 2003 by abraham (Master)

You can get the "one page, readable with less" format from texi files as well. I use it to produce files like README and INSTALL from texi source.

In general, I believe the info format is well over its prime. Low-end desktop computer are more than fast enough to convert texinfo on the fly, and can do a much better job when the markup hasn't been stripped. Of course, this would require that a) someone provided an texi based infrastructure, and b) someone wrote the texinfo based browsers.

I do like the texinfo format very much, as is simple and readable, especially compared to all the SGML based formats out there.

The standalone info browser used to be rather broken, because most of the people who cared about info files were using the superior build-in Emacs info browser. I hear that it has improved a lot recently, though.

texi2pod & pod2man, posted 17 Dec 2003 by robilad (Master)

For SPASS, we use texi2pod and pod2man to create man pages out of texinfo sources. Using texinfo, it's also quite trivial to generate hyperlinked docs from the same source for online help, and PDF docs for printing. There is also a texi2man project somewhere, but it's hopelessly outdated and unmaintained.

 

For Kaffe OpenVM, though, we[1] are moving over to using DocBook for everything. From that, it should also be easy to generate man pages, hypertext docs, or whatever else people come up with as the documentation standard of the future.

 

The main problem I have with man is not man pages, it's the arcane language needed to write man pages. I'll take texinfo anyday over roff.

[1] This is a different we.

info is good for what it's good for, posted 17 Dec 2003 by Omnifarious (Journeyer)

Info is good for very big manuals, or tutorials, or for meta-organization (like having some big tract about sockets that points at the actual documentation for the various related calls). It isn't for small software or documenting individual system calls.

What really should happen is that the info system should additionally be able to produce man pages as well as html, TeX, and .info files as it currently does.

Or, perhaps docbook can be extended so that it can make man pages as well. Man pages are extremely useful as a well indexed quick reference. Other documentation systems should work with man.

perldoc plays well with man.

docbook to man, posted 17 Dec 2003 by jamesh (Master)

DocBook has had elements for marking up man pages for a long time (I don't know if they were there in the beginning). Just use <refentry> as your toplevel element. The xmlto tool included in many distros can perform the conversion from DocBook/XML to man format like so:

xmlto man filename.xml

Man pages are easier to use, posted 18 Dec 2003 by error27 (Journeyer)

I do dislike info. I like xemacs but I don't like info. Perhaps JWZ should create a forked version of info. :P

Man pages are easy to use because you can just press "Page Up" or "Page Down" depending on which way you want to go. Also you can search them with the '/' character. That's not intuitive, but I guess a bunch of programs use it.

When you type `man ls` it says right at the top in bold letters what `ls` is and what it does. When you type `info ls` it says right at the top "File: coreutils.info, Node: ls invocation, Next: dir invocation, Up: Directory listing." The info page is confusing and cramped. It doesn't use bold characters to seperate the heading from the rest of the text.

Even large complex topics can be handled with man pages. For example, the Perl man pages are brilliant. I refer to them all the time.

Python has great online books and resources, but I do a lot of programming on the train to work and cannot connect to the net. Even when the html is available, I sometimes prefer man pages.

One thing where I think man pages could be improved was if there was some way to make changes and additions to the documentation. Maybe you could press "CTRL-E" to edit, after you were finished it would be saved somewhere in your $HOME directory.

Also it would be nice if there was someway to automatically upload your changes to the net. The man page would have an embeded address in it and when you typed CTRL-U, then you would type in a few notes about your changes and upload it to the address. The person on the recieving end would have some kind of screening process and then the changes could go live.

In Debian when you look for something that should have a man page but doesn't it points you to "man undocumented". Wouldn't it be awesome if people could throw up some documentation right away without any fuss? Even if they just filled out the name and one line description fields it would help. I use "man -k" all the time when I need programs. In one situation, I logged into a system and couldn't find an editor until I used `man -k` to locate `ae`.

Another man page improvement would be to add more examples of the obvious stuff. The Debian "tar" manual is terrific because it explains everything I want right away. The "tar" manual on other OSs is crap because it doesn't have the examples...

Man Wiki, posted 18 Dec 2003 by ncm (Master)

I think what error27 is talking about is a man->wiki gateway. I think such a thing could be fabulous, and ought to be remarkably easy to cobble together. There are already lots of man->www gateways that would be easy to adapt. The trick would be getting the edits merged upstream, and merging local edits with new versions released.

Having thought about the whole issue further, I think that (like the products of the Sirius Cybernetics Corporation) the fundamental problems of info are masked by its superficial problems. Its UI stinks, but that's fixable. The fundamental problem may be that while man pages have a recommended set of headings appearing in fixed order, writers of info pages are on their own. It appears that they are, as a rule, spectacularly bad at choosing section headings, and at breaking material along boundaries meaningful to readers.

Besides familiarity, there is much to be said for a standard set of headers that has nothing to do with the program or function being documented. It allows the material in the paragraphs to flow naturally. There's nothing inherent in make or sed that would lead the author of an info page to add a "see also", or even an "examples" section. The only reason they would appear is if they were in the template. Expecting the author to come up with the headings leads them to design bad documents.

No fooling around with a UI can fix this fundamental problem. Even with an info->wiki gateway, the texts would not naturally evolve away from their bad initial organization. The hierarchy would persist.

examples!, posted 18 Dec 2003 by connolly (Master)

Good man pages have the examples that you're looking for 80% of the time in the first screenful. Monkey-see-monkey-do works. Copy-and-paste, slurp-and-burp, whatever you want to call it. The synopsis section often works this way for arguments to functions.

Please, folks that document etc files and such, gimme examples!

Why do so many man pages list the options in alphabetical order? How many readers open the ls man page thinking quick! I need to know what the -l flag does! More likely, they know they want a long or detailed listing.

Taking an arbitrary topic, I just looked at the man page and the info manual for pr. They both exhuastively enumerate the arguments. (OK, so the synopsis is not too bad, and the one sentence description "Paginate or columnate FILE(s) for printing." is worth its screenspace, and the info page starts with a paragraph or so that's perhaps useful. But then on to the march of arguments they both go.)

Hooray for the author of the pump man page; the one configuration option I wanted to know about (how to keep it from clobbering /etc/resolv.conf and hosing my local DNS cache) is documented with an example!

Successive elaboration, not exhaustive enumeration, please! Start with the most straightforward thing that works. Then add a wrinkle, etc. A tutorial, it's sometimes called.

If, after you've explained what I need 80% of the time, go ahead, document the remaining 20% in exhaustive enumeration style. (if I really want to know how to use all the arcane features, I'll probably have to resort to the O'Reilly book anyway).

Yes, sometimes I have too much time on my hand and I appreciate a good "theory of operation" tome. But not often.

The Linux How-To series was a godsend for a while. Step 1: get the source from foo.edu; step 2: unpack... make install... put your email addres there. start it up. you win! But I see more and more documents called "How To" that don't tell me how to do it at all, but insist that I learn all about how it's architected for maximum extensibility and flexibility. Argh!

info bad, man worse, posted 18 Dec 2003 by grumbel (Journeyer)

Both info and man are pretty much flawed, they simply show there age. Sure man is still good enough for providing basically a 'foobar --help' with some addition documentation, but thats it. I find longer manpages quite hard to handle and unpleasant to use due to there lack of any TOC, hyperlinks and other things that make life easier. Let alone that most even lack a simply example section, but thats really more a content issue than a issue with man itself. After all manpages are not much more than plain text-files with some bold/underline markup.

Info on the other side while it provides basic hyperlinks and TOCs and is much more pleasant for longer documentation (Emacs, Gnus, etc.) is not so usefull for the short references that man is good at. Most info pages simply overstructure the commands just a bit to much, so one has to click through a bunch of links before reaching the desired info. The major flaw of info however is the dependency on .info files, .texi provides so much more structure and makes wonderfull printed documents, but all that gets stripped away once they get converted to .info. For example there is no way to get an equally nice printout from an info page compared that one could get from the original .texi page. So if one wants a nice printout one often ends up downloading source (distros seldomly ship the .texi files with the binary packages) and trying to generate a .ps from the .texi sources, which often is far from throuble free (A4 vs letter, double-page vs single-page), so even that way the results are less good than they could be in theory. The .info limitation of course also results in the impossibility of including graphics and such, after all a documentation system should be flexible enough for all apps, not just for command-line tools. So after all getting rid of .info and working directly with the .texi files could already lead to far better results.

One last word to .html documetation as it is seen here and there (Gnome, KDE). While it provides nice looking rendering, it becomes pretty much useless from a users point of view due to the complete lack of structure across multilpe pages, which basically result in the lack of a full-text search across the whole documentation or single section as provided by info.

So what would a good documetation system need? Fulltext search, good command line and GUI clients to access the docu, a way to structure and markup the documentation (after all when I want to look for a commandline option, it would be good to have a way to directly jump to it), a good way to print the docu and after all a few standards or guide lines for documentation writers. Both man and info provide a few of these features, but lack some of the other not less important ones.

Texinfo good, info(1) bad, posted 18 Dec 2003 by aaronl (Master)

A little digging revealed to me that Info was first writen in 1987. I was betting that it was designed before HTML was in widespread use, and I seem to be correct. I prefer to read texinfo manuals in their HTML or printed forms over using the clumsy info tool. There's no advantage to the info reader - HTML has hyperlinks, which info only implements in an awkward way. I'd prefer lynx to info any day.

Texinfo is pretty good when you evaluate it as a documentation markup format, which is what it is. It's designed to be used for full length reference books, not "pages". It's easily converitble to everything from text to DVI, and nothing forces you to use the info program rather than a browser or PDF viewer. Most texinfo documents (all the GNU ones at least) are avilable in HTML and PDF/PS.

The existence of a useful reference manual in texinfo format is no excuse for a shabby manpage. Info documents should exist to supplement terse man(1) pages. A lot of GNU tools neglect their manpages, and I think more projects should follow the lead of GCC which has a complete 9000 line manual page indexing command line options in addition to reference documentation detailing usage and development.

info, texinfo and html, posted 19 Dec 2003 by abraham (Master)

info is older than texinfo, I believe it was used for some of the ancient DEC operating systems.

html 1.0 was strongly inspired by texinfo, one could view it as an sgml based version of texinfo, without the programming documentations specific tags.

I actually find info superior for documentations than plain html, because info has "full document search" and "one key reading" (like man pages), plus internal hyperlinks like html. However, a specialized html browser or an ordinary browser plus a bit of scripting on both server and client should be able to offer the same.

Try tkinfo(1), posted 19 Dec 2003 by ftobin (Journeyer)

I recommend looking at tkinfo; it is a much easier to use than info(1). Info pages, as with HTML pages, are best driven with a mix of keyboard and mouse, which are not both accessible in terminals.

For a good example of proper use of info pages in contrast to manpages is the documentation for CVS. The manpages for CVS are simply reference. The info pages are tutorial.

Is info really that bad?, posted 20 Dec 2003 by richdawe (Journeyer)

Is info really that bad? I don't find that hard to use. I use it both on the command-line and from Emacs. Its user interface isn't great, but cursors to navigate, s to search whole manual, / to search individual page, u to go up section, etc. These all make sense to me. It's slightly easier to use in Emacs.

Anyhow, I typically use a combination of man, info, Emacs info mode, perldoc, Emacs perldoc mode and HTML pages, depending on whether I just want to refer quickly to the docs or not. For quick reference, command-line man, info and perldoc are great. For longer reading I much prefer the HTML docs.

I think man and info are complementary. man pages are like "cheat sheets" in my opinion. So the GNU project's anti-man page stance strikes me as illogical and just idealogical. Fortunately most GNU packages include man pages anyhow, by using help2man, which generates a nicely formatted summary of the command-line options.

Finally, as usually happens when this topic comes up, you don't have to use info. There are lots of alternative interfaces to info documentation.

technical or politics ?, posted 20 Dec 2003 by gilbou (Journeyer)

richdawe: that's a source for the problem, the fact that the anti-man page stance of gnu is not a technical decision but rather an ideological/political one. it's like some recent moves from the gnu gcc project where they do/try to do stuff for political reasons rather than technical ones (and you don't need examples for that, do you ?). doing things from a technical point of view makes me feel good. but too much gnu-fsf land prioritizes ideology/politics and restrict their moves to stuff that gets into agreement with their stance. well, one of the many reasons i keep to bsd rather than linux. just want to restrict myself to technical stuff, not having politricks or alike getting into the equation.

Can't agree, posted 22 Dec 2003 by haruspex (Journeyer)

gilbou: source for the problem, the fact that the anti-man page stance of gnu is not a technical decision but rather an ideological/political one

I don't think there is any justification for this - but OTOH there are many technical reasons why info is a better conceived system for online documentation (today it's hard to imagine a serious manual without hypertext). Developments of the last 15 years (e.g. HTML) may mean that info isn't going to become the leading viewer but as far as I am concerned, man is obsolete. How that translates into any kind of "ideological/political" position baffles me.

Many people seem to take any opportunity to label GNU capricious. They're the software geniuses you love to hate! Perhaps it's the tall poppy syndrome. Personally I admire GNU both for awesome technical achievements and hard work, as well as their "ideological/political" stance. I imagine they have long given up hope for credit where it's due.

Re: Can't agree, posted 22 Dec 2003 by tk (Journeyer)

There are also many flaws with info compared to man -- many have mentioned them above. But since the FSF never mentions these flaws, as far as haruspex is concerned, they don't exist.

Is this a technical justification or what?

Neatly missing one point, and demonstrating my other, posted 22 Dec 2003 by haruspex (Journeyer)

tk, this still leaves my assertion from the earliest post on the topic - that man begs for a hypertext replacement - on the table.

 

Would you care to explain why you like to snipe at the FSF? I mean, the whole story. If not, put that prejudice aside to discuss the issue at hand.

Hypertext is good..., posted 22 Dec 2003 by tk (Journeyer)

...but it's not urgent. I already said that.

I use man with less, in case that's new to you. When I want to go to the section SHELL BUILTIN COMMANDS in bash(1), I type /^, copy and paste to get

/^SHELL BUILTIN COMMANDS

and then press [Enter]. To look up information on the set command, I just enter

/^ *set \[

So there you are: the technical part.

I'm not trying to chase info off the face of the earth. I think everyone should be free to read documentation in whatever way he likes. On the contrary, it's people like your good self who'd like to force/twist/persuade everyone to switch to info, and in the process conjure up imaginary man-iacs who are bent on killing info. The FSF's the one sniping people, not the other way round.

For API reference documentation..., posted 22 Dec 2003 by slamb (Apprentice)

...man and info have already been replaced. Almost any good, newer library will have documentation in javadoc, doxygen, headerdoc or similar. These systems are completely superior.

Their most important feature is how easy it is to create documentation and keep it up-to-date. It's right with the actual source, so you've already got the file open whenever you're making changes. You can make it whine when things are unimplemented. Because they can look at the program context, the source is much less redundant. It's also very readable. This is a killer feature. For lots and lots of projects, I think it's the difference between not having any documentation at all and having fairly good documentation. Sure, ideally they'd also have tutorials and a user manual, but just API docs isn't horrible, especially with the quality these tools generate (below).

Another important feature is that they generate good-looking, easy-to-browse documentation. You can view it through your web browser of choice, so there are many viewers available, and you're already familiar with their use. You can view the documentation on the project's website without having it installed. It's hypertext with lots of hyperlinks, so it's extremely easy to go to related sections.

Doxygen generates great diagrams. Inheritance diagrams, collaboration diagrams, dependency diagrams, and call tree diagrams. These are really helpful for understanding the system very quickly.

Furthermore, if you're completely set on having man pages, it can generate them. doxygen has a man output mode which is fairly good.

I just wish that all the legacy code I still use had doxygen-generated API references. For one thing, it'd be nice to see everything in a consistent format. For another, my documentation could easily include the underlying code's with hyperlinks and call tree diagrams. For example, my code uses the system C library, boost, OpenSSL, and libpq. None of these have doxygen documentation available. It also uses ICU and libstdc++; they do.

Back on Point, posted 23 Dec 2003 by ncm (Master)

I would like to focus the discussion a little bit.

Flame wars pro- or anti-FSF, vi, emacs, troff, texinfo, or what have you, are off topic. Yes, the attitude of some in the FSF toward man is unfortunate. People who live in emacs do like it. Yes, troff is archaic markup, and texinfo is nicer in its way, and doxygen is leading the way to a glorious future. This is all secondary.

The point I meant to hint at in the original article was that, normally, newer solutions to old problems are manifestly better than the old ones. The implementer has full benefit of hindsight, a modern execution environment, better tools, new ideas, and motivation. When the new supplants the old, we generally don't notice for long. Everybody switches to the newer, better thing, and moves on. When the new fails to supplant the old, that's worth studying.

Now, some people do like info better, but many don't. That's something odd. With all the advantages, how did info fail to win over so many? It's not as if man got new features that enabled it to compete. (True, less makes it nicer to read man pages than did more, but that's pretty thin icing.) Info's UI is sucks, but there are lots of alternatives, none of which (except emacs, in some quarters) has really caught on.

My claim is that there's something, or things, fundamentally good about the man format, and the contents of actual man pages, that has failed to be translated forward into its proposed replacements. Disparaging man as a "cheatsheet" just prevents you from discovering those merits and adopting or bettering them. (I see the same effect when Lispers disparage C, and a similar effect wherever nationalism is practiced.) "Bigotry prevents insight" is not an earthshaking observation, but it bears repeating now and again.

I have speculated earlier on what it is about the man pages that made them work better for me. It occurs to me, though, that my experience may differ from most readers'. My early exposure to man pages was of the Bell Labs pages, often as filtered through Berkeley. While riddled with factual errors, and incomplete, they set a standard of literacy and thoughtfulness not matched in the info files I have encountered. Very few of the man pages on typical Linux installations are traceable to Bell Labs, or even to Berkeley.

Still, I don't think lamenting the current condition of programmer (or FSF) literacy gets to the heart of the matter. The Bell Labs programmers were also users, like us. Like us, they were also writing for nonprogrammers -- in their case, the Bell legal department word processing department secretaries, at first. When they found a man page unclear, they could read the source, and then check in (with sccs!) improvements on the spot. Improving a random man or info page you encounter these days takes a lot more work. We don't generally have CVS write access for every page we use. A web-based wiki that automatically generates sorta-patches sent to maintainers ought to help encourage participation.

I've already alluded to the difference in organization of info pages, compared to man pages. In info pages, cleavage into sections is left entirely to the author, and in practice, section headings tend to match program features. While this makes the page feel more natural to write, it bewilders those new to a program because it presumes more knowledge than the reader has, yet. Man's more-rigid header organization ensures that top-level topics are familiar to the reader, both because they are the same in different man pages, and because they refer to the users' experience, rather than to internal details of program operation.

Man's more rigid organization also, paradoxically, allows details about a program to be placed more freely. This freedom allows the author to put together in one place details that, if sorted out by category, might be widely scattered. It allows details to be presented in a narrative order more natural to a new user, perhaps building from simple to more elaborate examples, each bringing in a new feature.

Besides encouraging better organization, the man format provokes information that might not otherwise be expressed. Its generic top-level headers create a "commons" for details that relate to more than one part of a program, that might find no place in a hierarchy based directly on program features. At a more basic level, the man format demands thought on what to place under sections "SEE ALSO", "HISTORY", "BUGS", and "FILES", that it might not naturally occur to a program author to document.

None of these merits has anything to do with hypertext capability, or with choice of markup format. There's no inherent reason that info files could not be composed and presented as well as man pages are today. It would take a lot of rewriting, true, and the info program itself would probably best be scrapped. The key, though, is not in the code, but in the structure imposed on authors. Given good text to work from, presentation is a matter of taste.

As for most long-standing problems in Free Software, to improve matters we need clear standards, and apparatus to make participation easy. Both are readily achieved.

Re: Back on Point, posted 23 Dec 2003 by slamb (Apprentice)

So you're saying that you like man pages better because:

1. back in the day, it was easy for anyone to edit them, so unclear things were quickly clarified
2. they follow a really good style guide

#2 should be easy to duplicate. Write style guides for various types of documentation and publicize them. For API reference documentation, Sun already created this guide for writing Javadoc comments. It actually is pretty helpful, but it doesn't address a "History", "Bugs", or "Files" section. You could write a new guide that includes whatever you found helpful about man pages. And add specific notes for languages other than Java and doc tools other than Javadoc.

Additional man vs. info rant, posted 6 Jan 2004 by kmself (Journeyer)

I prefer man. I find the policy of FSF and the GNU Project of deprecatign man pages inexcuseable. Info was a neat idea, but has been surpassed by HTML and DocBook in its niche, and never should have attempted replacing man.

More at Info vs. Manpage.

Recommended Links

---

In case of broken links please try to use Google search. If you find the page please notify us about new location

Manual page (Unix) - Wikipedia, the free encyclopedia

AIX man page

In this post, Don Day provides two good references for man page formats, including the Cover pages and the DocBook refentry markup.

Man to html converters

• man2html  by Earl Hood
  troff2html Perl script by Daniel Quinlan
• Rik Harris's man to HTML converter
• Jim Garlick's mail2html.c
• OpenOSX What's new in GRASS 6.2.1
  • g.html2man: fixes for improved man page output
• RosettaMan is a filter for UNIX manual pages.
• rman.pl is a CGI-form interface to RosettaMan. RosettaMan
• man-cgi is shell-sed-awk script which converts on the fly the output of the "man" command to HTML.

Man Tools

freshmeat.net Project details for ManEdit

The ManEdit UNIX Manual Page Editor is an editor specifically tailored for UNIX manual pages. It has a preview viewer, uses the manual page XML format for easy editing, and comes with a tutorial and reference guide. It uses the GTK+ widget set and features syntax highlighting, a complete drag and drop system for easy viewing and editing, a crash recovery system, and sample manual page templates.

TkMan Home Site

TkMan is a graphical, hypertext manual page and Texinfo browser for UNIX. TkMan boasts hypertext links, unmatched online text formatting and display quality, (optional) outline view of man pages [screen dump], high quality display and superior navigational interface to Texinfo documents [screen dump], a novel information visualization mechanism called Notemarks, full text search among man pages and Texinfo, incremental and regular expression search within pages, regular expression search within Texinfo that shows all matches (not just the next), robustly attached yellow highlight annotations, a shortcut/hot list, lists of all pages in user configurable volumes, a comprehensive Preferences panel, and man page versioning support, among many other features.

"I encourage you to use TkMan for reading man pages. ... TkMan provides an extremely pleasant GUI for browsing man pages. I cannot describe all the nice features of TkMan in this small space. Instead I will merely say that I now actually look forward to reading man pages as long as I can do it with TkMan."
-- Don Libes, Exploring Expect, page 21

Read the Linux Gazette review.

Check out the Multivalent Browser with its manual page display module, and its TkMan comparison.

Reference

Solaris

man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name…
man [-M path] -k keyword…
man [-M path] -f file…
 

The man command displays information from the reference manuals. It displays complete manual pages that you select by name, or one-line summaries selected either by keyword (-k), or by the name of an associated file (-f). If no manual page is located, man prints an error message.

• Reference Manual pages are marked up with either nroff (see nroff(1)) or SGML (Standard Generalized Markup Language) tags (see sgml(5)). The man command recognizes the type of markup and processes the file accordingly. The various source files are kept in separate directories depending on the type of markup.

Location of Manual Pages

The online Reference Manual page directories are conventionally located in /usr/share/man. The nroff sources are located in the /usr/share/man/man* directories. The SGML sources are located in the /usr/share/man/sman* directories. Each directory corresponds to a section of the manual. Since these directories are optionally installed, they may not reside on your host. You may have to mount /usr/share/man from a host on which they do reside.

If there are preformatted, up-to-date versions in the corresponding cat* or fmt* directories, man simply displays or prints those versions. If the preformatted version of interest is out of date or missing, man reformats it prior to display and will store the preformatted version if cat* or fmt* is writable. The windex database is not updated. See catman(1M). If directories for the preformatted versions are not provided, man reformats a page whenever it is requested. man uses a temporary file to store the formatted text during display.

If the standard output is not a terminal, or if the `-' flag is given, man pipes its output through cat(1). Otherwise, man pipes its output through more(1) to handle paging and underlining on the screen.

OPTIONS

The following options are supported:

-a

Shows all manual pages matching name within the MANPATH search path. Manual pages are displayed in the order found.

-d

Debugs. Displays what a section-specifier evaluates to, method used for searching, and paths searched by man.

-f file ...

man attempts to locate manual pages related to any of the given files. It strips the leading path name components from each file, and then prints one-line summaries containing the resulting basename or names. This option also uses the windex database.

-F

Forces man to search all directories specified by MANPATH or the man.cf file, rather than using the windex lookup database. This option is useful if the database is not up to date and it has been made the default behavior of the man command. The option therefore does not have to be invoked and is documented here for reference only.

-k keyword ...

Prints out one-line summaries from the windex database (table of contents) that contain any of the given keywords. The windex database is created using catman(1M).

-l

Lists all manual pages found matching name within the search path.

-M path

Specifies an alternate search path for manual pages. path is a colon-separated list of directories that contain manual page directory subtrees. For example, if path is /usr/share/man:/usr/local/man, man searches for name in the standard location, and then /usr/local/man. When used with the -k or -f options, the -M option must appear first. Each directory in the path is assumed to contain subdirectories of the form man* or sman* , one for each section. This option overrides the MANPATH environment variable.

-r

Reformats the manual page, but does not display it. This replaces the man - -t name combination.

-s section ...

Specifies sections of the manual for man to search. The directories searched for name are limited to those specified by section. section can be a numerical digit, perhaps followed by one or more letters to match the desired section of the manual, for example, “3libucb”. Also, section can be a word, for example, local, new, old, public. section can also be a letter. To specify multiple sections, separate each section with a comma. This option overrides the MANPATH environment variable and the man.cf file. See Search Path below for an explanation of how man conducts its search.

-t

man arranges for the specified manual pages to be troffed to a suitable raster output device (see troff(1)). If both the - and -t flags are given, man updates the troffed versions of each named name (if necessary), but does not display them.

-T macro-package

Formats manual pages using macro-package rather than the standard -man macros defined in /usr/share/lib/tmac/an. See Search Path under USAGE for a complete explanation of the default search path order.

OPERANDS

The following operand is supported:

name

A keyword or the name of a standard utility.

USAGE

The usage of man is described below:

Manual Page Sections

Entries in the reference manuals are organized into sections. A section name consists of a major section name, typically a single digit, optionally followed by a subsection name, typically one or more letters. An unadorned major section name, for example, “9”, does not act as an abbreviation for the subsections of that name, such as “9e”, “9f”, or “9s”. That is, each subsection must be searched separately by man -s. Each section contains descriptions apropos to a particular reference category, with subsections refining these distinctions. See the intro manual pages for an explanation of the classification used in this release.

Search Path

Before searching for a given name, man constructs a list of candidate directories and sections. man searches for name in the directories specified by the MANPATH environment variable. If this variable is not set, /usr/share/man is searched by default.

Within the manual page directories, man confines its search to the sections specified in the following order:

• sections specified on the command line with the -s option
• sections embedded in the MANPATH environment variable
• sections specified in the man.cf file for each directory specified in the MANPATH environment variable

If none of the above exist, man searches each directory in the manual page path, and displays the first matching manual page found.

The man.cf file has the following format:

MANSECTS=section[,section]...

Lines beginning with `#' and blank lines are considered comments, and are ignored. Each directory specified in MANPATH can contain a manual page configuration file, specifying the default search order for that directory.

Formatting Manual Pages

Manual pages are marked up in nroff(1) or sgml(5). Nroff manual pages are processed by nroff(1) or troff(1) with the -man macro package. Please refer to man(5) for information on macro usage. SGML—tagged manual pages are processed by an SGML parser and passed to the formatter.

Preprocessing Nroff Manual Pages

When formatting an nroff manual page, man examines the first line to determine whether it requires special processing. If the first line is a string of the form:

'\" X

where X is separated from the `"' by a single SPACE and consists of any combination of characters in the following list, man pipes its input to troff(1) or nroff(1) through the corresponding preprocessors.

e

eqn(1), or neqn for nroff

r

refer(1)

t

tbl(1)

v

vgrind(1)

If eqn or neqn is invoked, it will automatically read the file /usr/pub/eqnchar (see eqnchar(5)). If nroff(1) is invoked, col(1) is automatically used.

Referring to Other nroff Manual Pages

If the first line of the nroff manual page is a reference to another manual page entry fitting the pattern:

.so man*/sourcefile

man processes the indicated file in place of the current one. The reference must be expressed as a path name relative to the root of the manual page directory subtree.

When the second or any subsequent line starts with .so, man ignores it; troff(1) or nroff(1) processes the request in the usual manner.

Processing SGML Manual Pages

Manual pages are identified as being marked up in SGML by the presence of the string <!DOCTYPE. If the file also contains the string SHADOW_PAGE, the file refers to another manual page for the content. The reference is made with a file entity reference to the manual page that contains the text. This is similar to the .so mechanism used in the nroff formatted man pages.

ENVIRONMENT VARIABLES

See environ(5) for descriptions of the following environment variables that affect the execution of man: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

MANPATH

A colon-separated list of directories; each directory can be followed by a comma-separated list of sections. If set, its value overrides /usr/share/man as the default directory search path, and the man.cf file as the default section search path. The -M and -s flags, in turn, override these values.)

PAGER

A program to use for interactively delivering man's output to the screen. If not set, `more -s' is used. See more(1).

TCAT

The name of the program to use to display troffed manual pages.

TROFF

The name of the formatter to use when the -t flag is given. If not set, troff(1) is used.

EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

FILES

/usr/share/man

Root of the standard manual page directory subtree

/usr/share/man/man?/*

Unformatted nroff manual entries

/usr/share/man/sman?/*

Unformatted SGML manual entries

/usr/share/man/cat?/*

nroffed manual entries

/usr/share/man/fmt?/*

troffed manual entries

/usr/share/man/windex

Table of contents and keyword database

/usr/share/lib/tmac/an

Standard –man macro package

/usr/share/lib/sgml/locale/C/dtd/*

SGML document type definition files

/usr/share/lib/sgml/locale/C/solbook/*

SGML style sheet and entity definitions directories

/usr/share/lib/pub/eqnchar

Standard definitions for eqn and neqn

man.cf

Default search order by section

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdoc
CSI	Enabled (see NOTES)
Interface Stability	Standard

SEE ALSO

apropos(1), cat(1), col(1), eqn(1), more(1), nroff(1), refer(1), tbl(1), troff(1), vgrind(1), whatis(1), catman(1M), attributes(5), environ(5), eqnchar(5), man(5), sgml(5), standards(5)

NOTES

The -f and -k options use the windex database, which is created by catman(1M).

The man command is CSI-capable. However, some utilities invoked by the man command, namely, troff, eqn, neqn, refer, tbl, and vgrind, are not verified to be CSI-capable. Because of this, the man command with the -t option may not handle non-EUC data. Also, using the man command to display man pages that require special processing through eqn, neqn, refer, tbl, or vgrind may not be CSI-capable.

BUGS

The manual is supposed to be reproducible either on a phototypesetter or on an ASCII terminal. However, on a terminal some information (indicated by font changes, for instance) is lost.

Some dumb terminals cannot process the vertical motions produced by the e (see eqn(1)) preprocessing flag. To prevent garbled output on these terminals, when you use e, also use t, to invoke col(1) implicitly. This workaround has the disadvantage of eliminating superscripts and subscripts, even on those terminals that can display them. Control-q will clear a terminal that gets confused by eqn(1) output.

AIX man Command

man [ [ [ -c ] [ -t ] [ section ] ] | [ -k | -f ] ] [ -F ] [ -m ] [ -Mpath ] [ -r ] [ -a ] title ...

The man command provides reference information on topics, such as commands, subroutines, and files. The man command provides one-line descriptions of commands specified by name. The man command also provides information on all commands whose descriptions contain a set of user-specified keywords.

The man command formats a specified set of manual pages. If you specify a section for the section parameter, the man command searches in that section of the manual pages for the title specified by the title parameter. The value of the section parameter can be either an Arabic number from 1 through 8 or a letter.

The section letters are:

The section numbers are:

If the section parameter is omitted, the man command searches all sections of the manual.

The search path the man command uses is a list of directories separated by a : (colon) in which manual subdirectories can be found. The MANPATH environment variable value is used for the default path.

The man command displays the manual pages as follows:

1. The man command searches the nroff directories (man?) under the /usr/share/man directory.
2. The man command searches the formatted version directories (cat?) under the /usr/share/man directory. If the formatted version is available, and if it has a more recent modify time than the nroff command source, the man command displays the formatted version. Otherwise, the manual page is formatted with the nroff command and displayed. If the user has permission, the formatted manual page is deposited in the proper place, so that later invocations of the man command do not format the page again.
   Note:
   There is no nroff source for the supplied manual pages. However, you can put nroff source for manual pages into the man directories and the man command can locate and process the nroff source.
3. If the man command does not find a manual page in the /usr/share/man/man or /usr/share/man/cat directory, the man command searches the paths specified through -M option or MANPATH environment variable for nroff directories (man?) and formatted version directories (cat?).
4. If the man command does not find a manual page in the /usr/share/man/man or /usr/share/man/cat or the user-specified man/cat directory, the man command reads from the hypertext information bases. The hypertext information bases reside in the /usr/share/man/info directory structure and contain the operating system documentation. When reading from the hypertext databases, the man command does not put any manual pages in the /usr/share/man/cat directory structure. The man command converts the HTML file into a formatted text file to fit on the display, and displays the manual page using the command described by the PAGER environment variable.
5. If the man command does not find a manual page in the hypertext information bases residing in the /usr/share/man/info directory structure, it looks for user-specified hypertext information base (through -M or MANPATH). The user-defined hypertext information base, should follow the following directory structure:

   BasePath[/%{ L | l }]/DocLibraryname/Section/command_or_routine_or_filename.htm

   Where:
   • %L represents the ISO language notation specified using the LC_MESSAGES, %l represents the first 2 characters of the ISO language notation specified using the LC_MESSAGES. For example, for LC_MESSAGES=en_US the documents can be placed in Path/en_US or Path/en.
   • DocLibraryname represents the name of the documentation library.
   • Section represents the section name, which must be one of the following:
     • cmds — Represents Commands Section
     • libs — Represents Library Section
     • files — Represents Files Section
   Note:
   If -m option is specified, then the search for manual pages will be done only in the order of paths specified through -M or the MANPATH environment variable.

When accessing the HTML databases, man looks for the operating system library before it proceeds to other LPP libraries. Within these libraries, it processes information in the following order:

If the standard output is a tty, the man command pipes its output using the more command with the -s and -v flags. The -s flag eliminates multiple blank lines and stops after each page on the screen. The -v flag suppresses the display of nonprinting characters to the screen. To continue scrolling, press the space bar. To scroll an additional 11 lines when the output stops, press the Ctrl-D key sequence.

The PAGER environment variable can be set to whatever pager is desired. The default value is the more command. To change the default pager, enter:

PAGER=Somepager
export PAGER

For example, if there are customized manual pages which are formatted with reverse or fractional line feeds, the PAGER environment variable may be set to /usr/bin/pg so that the line feeds are not printed as control characters. This procedure is not necessary for the manual pages.

When the man command uses a hypertext database, it can retrieve several articles. For example, man open displays several articles. The use of SIGINT (Ctrl-C) exits the man command completely. On the other hand, man open close also displays several articles but the use of SIGINT (Ctrl-C) causes man to display the close command information instead of exiting. Using SIGINT (Ctrl-C) again exits the man command completely.

When specifying one of the Network Computing System library routines that contains a $ (dollar sign) in its name, enter a \ (backslash) preceding the $.

Flags

Exit Status

This command returns the following exit values:

Examples

1. To display information about the grep command, enter the following command:

    

   man grep

2. To display information about the rpc_$register library routine, enter the following command:

    

   man rpc_\$register

3. To display all entries in the /usr/share/man/whatis keyword database that contain the "mkdir" string , enter the following command:

    

   man -k mkdir

   The output is equivalent to the apropos command. You receive output from the -k flag only when the /usr/share/man/whatis keyword database already exists.

4. To display all entries from the keyword database related to the nroff and troff commands, enter the following command:

    

   man -f nroff troff

   The output is equivalent to the whatis command. You receive output from the -f flag only when the /usr/share/man/whatis keyword database already exists.

5. To display all ftp command related articles in the /usr/share/man or /usr/share/man/local path, enter the following command:

    

   man -M/usr/share/man:/usr/share/man/local ftp

6. To display all matching entries, enter the following command:

   man –a title

7. To display only the first matching entry, enter the following command:

   man –F title

8. To search only in the paths specified in MANPATH or –M, enter the following command:

   man -m –M PATH title

9. To search in the user-defined PATH, enter the following command:

   man –M PATH title

Files

Related Information

The apropos command, catman command, more command, whatis command, whereis command.