May the source be with you, but remember the KISS principle ;-)
Home Switchboard Unix Administration Red Hat TCP/IP Networks Neoliberalism Toxic Managers
(slightly skeptical) Educational society promoting "Back to basics" movement against IT overcomplexity and  bastardization of classic Unix

man command

News Recommended Links Recommended  Papers Reference Man Tools Converters
Sections Options Examples Less    
Solaris AIX Horror Stories Unix History Humor Etc

The 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).


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
- The formatted output from man is piped into the more command. The -s option of more is used to remove duplicate blank lines. Thus the formatted text is displayed to your terminal one page at a time.
-M path Provides a path of directories searched for manual subdirectories. Normally man searches the subdirectories in the /usr/man directory. If -M is used, man searches each of the directories in path for subdirectories that contain man entries. For example,
   -M /usr/local:/share/man
causes man to search the /usr/local/man* and /share/man/man* directories for manual entries.
-k keyword See the apropos command.
-f file See the whatis command.

System V
-c Causes col to be invoked. Invoked as a default.
-d Search current directory for entry. man defaults to the /usr/catman or /usr/man directory structure. Full man page entry name must be given (e.g. use cat.1, not cat).
-w Display where the entry resides using the /usr/man path. The man entry is NOT formated and displayed. If -d is specified then the current directory is searched.
-Tterm Format the entry for displaying on the given terminal type term. The default for term is 450. The value of the TERM variable is used as the output device if the -T option is not used.


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

section The section of the manual you want man to search. There are typically seven sections of the man pages. man searches all seven sections if you do not specify a section. You may specify a section before each title.
local Format a local entry. Local entries are located in the /usr/man/manl directory (l as in local, not the number one). Each entry (file) in this directory must end with the .l suffix. You can add your own entries to this directory.
new Search for and format a new man page entry.
old Search for and format an old man page entry.
public Search for and format a public man page entry.
title The name of the command you want man to search for and format to your screen. Multiple titles may be given. All titles should be entered in lowercase letters (considering all commands are supposed to be lowercase).

System V
local Usually not supported.

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.


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

Section Description

1 Commands and Application Programs
2 System Calls (used in programming languages)
3 Subroutines (used in programming languages)
4 File Formats
5 Miscellaneous
6 Games
7 Special Files
8 System Maintenance Procedures
local Locally written man pages (third party software man pages.)
public Public domain software man pages.
new New software man pages.
old Old/obsolete software man pages.

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.

Subsection Description

1C Section 1, Communications
1G Section 1, Graphics
1M Section 1, Maintenance (System Adminstration)
3C Section 3, C programming language
3F Section 3, Fortran programming language
3M Section 3, Miscellaneous programming routines

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:


System V

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.

Top Visited
Past week
Past month


Old News ;-)

[Jul 26, 2019] Shows Cheat Sheets On The Command Line Or In Your Code Editor>

The choice of shell as a programming language is strange, but the idea is good...
Notable quotes:
"... The tool is developed by Igor Chubin, also known for its console-oriented weather forecast service , which can be used to retrieve the weather from the console using only cURL or Wget. ..."
Jul 26, 2019 |
/n /n/n

While it does have its own cheat sheet repository too, the project is actually concentrated around the creation of a unified mechanism /n to access well developed and maintained cheat sheet repositories.


The tool is developed by Igor Chubin, also known for its/n console-oriented weather forecast /n service , which can be used to retrieve the weather from the console using /n only cURL or Wget.


It's worth noting that is not new. In fact it had its initial commit around May, 2017, and is a very popular repository /n on GitHub. But I personally only came across it recently, and I found it very useful, so I figured there must be some Linux Uprising /n readers who are not aware of this cool gem.

/n/n features & more
/n /n tar example/n
/n major features:

/n /n The command line client features a special shell mode with a persistent queries context and readline support. It also has a query /n history, it integrates with the clipboard, supports tab completion for shells like Bash, Fish and Zsh, and it includes the stealth /n mode I mentioned in the features./n/n

The web, curl and (command line) interfaces all make use of /n but if you prefer, you can self-host it .


It should be noted that each editor plugin supports a different feature set (configurable server, multiple answers, toggle comments, /n and so on). You can view a feature comparison of each editor plugin on the/n Editors integration section of the project's /n GitHub page.


Want to contribute a cheat sheet? See the guide on/n editing or adding a new cheat sheet.


Interested in bookmarking commands instead? You may want to give/n Marker, a command bookmark /n manager for the console , a try.

/n/n curl / command line client usage examples
/n Examples of using using the curl interface (this requires having curl installed as you'd expect) from the command /n line:


Show the tar command cheat sheet:

/n Example with output:/n/n
/n$ curl To extract an uncompressed archive:/ntar -xvf /path/to/foo.tar/n/n# To create an uncompressed archive:/ntar -cvf /path/to/foo.tar /path/to/foo//n/n# To extract a .gz archive:/ntar -xzvf /path/to/foo.tgz/n/n# To create a .gz archive:/ntar -czvf /path/to/foo.tgz /path/to/foo//n/n# To list the content of an .gz archive:/ntar -ztvf /path/to/foo.tgz/n/n# To extract a .bz2 archive:/ntar -xjvf /path/to/foo.tgz/n/n# To create a .bz2 archive:/ntar -cjvf /path/to/foo.tgz /path/to/foo//n/n# To extract a .tar in specified Directory:/ntar -xvf /path/to/foo.tar -C /path/to/destination//n/n# To list the content of an .bz2 archive:/ntar -jtvf /path/to/foo.tgz/n/n# To create a .gz archive and exclude all jpg,gif,... from the tgz/ntar czvf /path/to/foo.tgz --exclude=\*.{jpg,gif,png,wmv,flv,tar.gz,zip} /path/to/foo//n/n# To use parallel (multi-threaded) implementation of compression algorithms:/ntar -z ... -> tar -Ipigz .../ntar -j ... -> tar -Ipbzip2 .../ntar -J ... -> tar -Ipixz .../n
/n also works instead of
/n Want to search for a keyword in all cheat sheets? Use:/n/n
/n List the Python programming language cheat sheet for random list :/n/n
/n Example with output:/n/n
/n$ curl  python - How to randomly select an item from a list?/n#  /n#  Use random.choice/n#  ( random/n/nfoo = ['a', 'b', 'c', 'd', 'e']/nprint(random.choice(foo))/n/n#  For cryptographically secure random choices (e.g. for generating a/n#  passphrase from a wordlist), use random.SystemRandom/n#  (  class:/n/nimport random/n/nfoo = ['battery', 'correct', 'horse', 'staple']/nsecure_random = random.SystemRandom()/nprint(secure_random.choice(foo))/n/n#  [Pēteris Caune] [so/q/306400] [cc by-sa 3.0]/n
/n Replace python with some other programming language supported by, and random+list with the cheat /n sheet you want to show./n/n

Want to eliminate the comments from your answer? Add ?Q at the end of the query (below is an example using the same /n /python/random+list):

/n$ curl random/n/nfoo = ['a', 'b', 'c', 'd', 'e']/nprint(random.choice(foo))/n/nimport random/n/nfoo = ['battery', 'correct', 'horse', 'staple']/nsecure_random = random.SystemRandom()/nprint(secure_random.choice(foo))/n
/n For more flexibility and tab completion you can use, the command line client; you'll find instructions for how to /n install it further down this article. Examples of using the command line client:/n/n

Show the tar command cheat sheet:

/ tar/n
/n List the Python programming language cheat sheet for random list :/n/n
/ python random list/n
/n There is no need to use quotes with multiple keywords./n/n

You can start the client in a special shell mode using:

/ --shell/n
/n And then you can start typing your queries. Example:/n/n
/n$ --shell/> bash loop/n
/n If all your queries are about the same programming language, you can start the client in the special shell mode, directly in that /n context. As an example, start it with the Bash context using:/n/n
/ --shell bash/n
/n Example with output:/n/n
/n$ --shell bash/> loop/n.........../> switch case/n
/n Want to copy the previously listed answer to the clipboard? Type c , then press Enter to copy the whole /n answer, or type C and press Enter to copy it without comments./n/n

Type help in the interactive shell mode to see all available commands. Also look under the/n Usage section from the GitHub project page for more /n options and advanced usage.


How to install command line client
/n You can use in a web browser, from the command line with the help of curl and without having to install anything else, as /n explained above, as a code editor plugin, or using its command line client which has some extra features, which I already mentioned. /n The steps below are for installing this command line client.


If you'd rather install a code editor plugin for, see the/n Editors integration page.


1. Install dependencies.


To install the command line client, the curl command line tool will be used, so this needs to be installed /n on your system. Another dependency is rlwrap , which is required by the special shell mode. Install these dependencies /n as follows.

/n /n/n
/nsudo apt install curl rlwrap/n
/n /n/n
/nsudo dnf install curl rlwrap/n
/n /n/n
/nsudo pacman -S curl rlwrap/n
/n /n/n
/nsudo zypper install curl rlwrap/n
/n The packages seem to be named the same on most (if not all) Linux distributions, so if your Linux distribution is not on this list, /n just install the curl and rlwrap packages using your distro's package manager./n/n

2. Download and install the command line interface.


You can install this either for your user only (so only you can run it), or for all users:

/n /n/n
/ncurl > ~/.bin/ +x ~/.bin/
/n /n/n
/ncurl | sudo tee /usr/local/bin/ chmod +x /usr/local/bin/
/n If the first command appears to have frozen displaying only the cURL output, press the Enter key and you'll be prompted /n to enter your password in order to save the file to /usr/local/bin ./n/n

You may also download and install the command completion for Bash or Zsh:

/n /n/n
/nmkdir ~/.bash.d/n/ncurl > ~/.bash.d/ ". ~/.bash.d/" >> ~/.bashrc/n
/n /n/n
/nmkdir ~/.zsh.d/n/ncurl > ~/.zsh.d/_cht/n/necho 'fpath=(~/.zsh.d/ $fpath)' >> ~/.zshrc/n
/n Opening a new shell / terminal and it will load the completion./n /n/n

[Oct 12, 2018] How To Create And Maintain Your Own Man Pages by sk

Oct 09, 2018 |
/n /n /n/n

We already have discussed about a few/n good alternatives to Man /n pages . Those alternatives are mainly used for learning concise Linux command examples without having to go through the comprehensive /n man pages. If you're looking for a quick and dirty way to easily and quickly learn a Linux command, those alternatives are worth /n trying. Now, you might be thinking – how can I create my own man-like help pages for a Linux command? This is where "Um" comes in /n handy. Um is a command line utility, used to easily create and maintain your own Man pages that contains only what you've learned /n about a command so far.

/n /n/n

By creating your own alternative to man pages, you can avoid lots of unnecessary, comprehensive details in a man page and include /n only what is necessary to keep in mind. If you ever wanted to created your own set of man-like pages, Um will definitely help. In /n this brief tutorial, we will see how to install "Um" command line utility and how to create our own man pages.

/n/n Installing Um/n/n

Um is available for Linux and Mac OS. At present, it can only be installed using Linuxbrew package manager in Linux systems. Refer /n the following link if you haven't installed Linuxbrew yet.

/n /n/n

Once Linuxbrew installed, run the following command to install Um utility.

/n$ brew install sinclairtarget/wst/um/n

If you will see an output something like below, congratulations! Um has been installed and ready to use.

/n[...]/n==> Installing sinclairtarget/wst/um/n==> Downloading> Downloading from # # /n==> Downloading 100.0%/n==> gem install /home/sk/.cache/Homebrew/downloads/d0a5d978120a791d9c5965fc103866815189a4e3939/n==> Caveats/nBash completion has been installed to:/n/home/linuxbrew/.linuxbrew/etc/bash_completion.d/n==> Summary/n /home/linuxbrew/.linuxbrew/Cellar/um/4.0.0: 714 files, 1.3MB, built in 35 seconds/n==> Caveats/n==> openssl/nA CA file has been bootstrapped using certificates from the SystemRoots/nkeychain. To add additional certificates (e.g. the certificates added in/nthe System keychain), place .pem files in/n/home/linuxbrew/.linuxbrew/etc/openssl/certs/n/nand run/n/home/linuxbrew/.linuxbrew/opt/openssl/bin/c_rehash/n==> ruby/nEmacs Lisp files have been installed to:/n/home/linuxbrew/.linuxbrew/share/emacs/site-lisp/ruby/n==> um/nBash completion has been installed to:/n/home/linuxbrew/.linuxbrew/etc/bash_completion.d/n

Before going to use to make your man pages, you need to enable bash completion for Um.


To do so, open your ~/.bash_profile file:

/n$ nano ~/.bash_profile/n

And, add the following lines in it:

/nif [ -f $(brew --prefix)/etc/bash_completion.d/ ]; then/n  . $(brew --prefix)/etc/bash_completion.d/

Save and close the file. Run the following commands to update the changes.

/n$ source ~/.bash_profile/n

All done. let us go ahead and create our first man page.

Create And Maintain Your Own Man Pages

Let us say, you want to create your own man page for "dpkg" command. To do so, run:

/n$ um edit dpkg

The above command will open a markdown template in your default editor:


Create a new man page


My default editor is Vi, so the above commands open it in the Vi editor. Now, start adding everything you want to remember about /n "dpkg" command in this template.


Here is a sample:


Add contents in dpkg man page


As you see in the above output, I have added Synopsis, description and two options for dpkg command. You can add as many as sections /n you want in the man pages. Make sure you have given proper and easily-understandable titles for each section. Once done, save and /n quit the file (If you use Vi editor, Press ESC key and type :wq ).


Finally, view your newly created man page using command:

/n$ um dpkg

View dpkg man page


As you can see, the the dpkg man page looks exactly like the official man pages. If you want to edit and/or add more details in /n a man page, again run the same command and add the details.

/n$ um edit dpkg

To view the list of newly created man pages using Um, run:

/n$ um list

All man pages will be saved under a directory named .um in your home directory


Just in case, if you don't want a particular page, simply delete it as shown below.

/n$ um rm dpkg

To view the help section and all available general options, run:

/n$ um --help/nusage: um <page name>/n       um <sub-command> [ARGS...]/n/nThe first form is equivalent to `um read <page name>`./n/nSubcommands:/n  um (l)ist                 List the available pages for the current topic./n  um (r)ead <page name>     Read the given page under the current topic./n  um (e)dit <page name>     Create or edit the given page under the current topic./n  um rm <page name>         Remove the given page./n  um (t)opic [topic]        Get or set the current topic./n  um topics                 List all topics./n  um (c)onfig [config key]  Display configuration environment./n  um (h)elp [sub-command]   Display this help message, or the help message for a sub-command.

Configure Um


To view the current configuration, run:

/n$ um config/nOptions prefixed by '*' are set in /home/sk/.um/umconfig./neditor = vi/npager = less/npages_directory = /home/sk/.um/pages/ndefault_topic = shell/npages_ext = .md

In this file, you can edit and change the values for pager , editor , default_topic , pages_directory , and pages_ext options /n as you wish. Say for example, if you want to save the newly created Um pages in your/n Dropbox folder, simply change /n the value of pages_directory directive and point it to the Dropbox folder in ~/.um/umconfig file.

/npages_directory = /Users/myusername/Dropbox/um

And, that's all for now. Hope this was useful. More good stuffs to come. Stay tuned!





/n /n/n

[Jul 16, 2017] How to use a man page Faster than a Google search

Jul 16, 2017 |
/n /n It's easy to get/n into the habit of googling anything you want to know about a command or operation in Linux, but/n I'd argue there's something even better: a living and breathing, complete reference, the man/n pages , which is short for manual pages./n/n/n

The history of man pages predates Linux, all the way back to the early days of Unix./n/nAccording to Wikipedia/n ,/n Dennis Ritchie and Ken Thompson wrote the first man pages in 1971, well before the days of/n personal computers, around the time when many calculators in use were the size of toaster/n ovens. Man pages also have a reputation of being terse and, in a way, have a language of their/n own. Just like Unix and Linux, the man pages have not been static, and they continue to be/n developed and maintained just like the kernel./n


Man pages are divided into sections referenced by numbers:/n

  1. General user commands/n
  2. /n
  3. System calls/n
  4. /n
  5. Library functions/n
  6. /n
  7. Special files and drivers/n
  8. /n
  9. File formats/n
  10. /n
  11. Games and screensavers/n
  12. /n
  13. Miscellanea/n
  14. /n
  15. System administration commands and daemons/n
  16. /n

Even so, users generally don't need to know the section where a particular command lies to/n find what they need./n


The files are formatted in a way that may look odd to many users today. Originally, they/n were written in in an old form of markup called troff because they were designed to be printed/n through a PostScript printer, so they included formatting for headers and other layout aspects./n In Linux,/ngroff/n is/n used instead./n


In my Fedora, the man pages are located in /usr/share/man with subdirectories (like man1 for/n Section 1 commands) as well as additional subdirectories for translations of the man pages./n


If you look up the man page for the command man , you'll see the file man.1.gz , which is/n the man pages compressed with the gzip utility. To access a man page, type a command such/n as:/n


for example, to show the man page for man . This uncompresses the man page, interprets the/n formatting commands, and displays the results with/nless/n , so navigation is the same as when you/n use less ./n


All man pages should have the following subsections: Name , Synopsis , Description ,/n Examples , and See Also . Many have additional sections, like Options , Exit Status ,/n Environment , Bugs , Files , Author , Reporting Bugs , History , and Copyright ./n

/nBreaking/n down a man page/n/n

To explain how to interpret a typical man page, let's use the/nman page for ls/n as an example. Under Name , we/n see/n

/n/nls/n - list directory contents/n/n

which tells us what ls means in the simplest terms./n


Under Synopsis , we begin to see the terseness:/n

/n/nls/n[/nOPTION/n]/n... /n[/nFILE/n]/n/n

Any element that occurs inside brackets is optional. The above command means you can/n legitimately type ls and nothing else. The ellipsis after each element indicates that you can/n include as many options as you want (as long as they're compatible with each other) and as many/n files as you want. You can specify a directory name, and you can also use * as a wildcard. For/n example:/n

/n/nls/n Documents/n/*/n.txt/n/n

Under Description , we see a more verbose description of what the command does, followed by/n a list of the available options for the command. The first option for ls is/n

-a, --all/n
/n do not ignore entries starting with ./n/n/n

If we want to use this option, we can either type the short form syntax, -a , or the long/n form --all . Not all options have two forms (e.g., --author ), and even when they do, they/n aren't always so obviously related (e.g., - F, --classify ). When you want to use multiple/n options, you can either type the short forms with spaces in between or type them with a single/n hyphen and no spaces (as long as they do not require further sub-options). Therefore,/n




are equivalent./n


The command tar is somewhat unique, presumably due to its long history, in that it doesn't/n require a hyphen at all for the short form. Therefore,/n

/n/ntar/n-cvf/n filearchive.tar thisdirectory/n//n/n


/n/ntar/n cvf filearchive.tar thisdirectory/n//n/n

are both legitimate./n


On the ls man page, after Description are Author , Reporting Bugs , Copyright , and See Also/n ./n


The See Also section will often suggest related man pages, so it is generally worth a/n glance. After all, there is much more to man pages than just commands./n


Certain commands that are specific to Bash and not system commands, like alias , cd , and a/n number of others, are listed together in a single BASH_BUILTINS man page. While the/n documentation for these is even more terse and compact, overall it contains similar/n information./n


I find that man pages offer a lot of good, usable information, especially when I need a/n command I haven't used recently, and I need to brush up on the options and requirements. This/n is one place where the man pages' much-maligned terseness is actually very beneficial./n/nTopics/n/nLinux/n/nAbout/n the author/n/n/n/n Greg Pittman - Greg is a retired neurologist in/n Louisville, Kentucky, with a long-standing interest in computers and programming, beginning/n with Fortran IV in the 1960s. When Linux and open source software came along, it kindled a/n commitment to learning more, and eventually contributing. He is a member of the Scribus/n Team./n


Tricks UrFix's Blog Page 2

7 Cool Ways To Use The Man Pages In Linux


Man pages (short for manual pages) are the extensive documentation that comes preinstalled with almost all substantial Unix and Unix-like operating systems. The Unix command used to display them is man. Each page is a self-contained document.


To read a manual page for a Unix command, one can use

 man <command_name>
1) Create a pdf version of a manpage

man -t manpage | ps2pdf – filename.pdf

Quick and dirty version. I made a version that checks if a manpage exists (but it's not a oneliner). You must have ps2pdf and of course Ghostscript installed in your box.

Enhancements appreciated :-)

2) Colorful man

apt-get install most && update-alternatives –set pager /usr/bin/most

That command installs "most" and make this command as the default man reader. The "most" works like "less" (the current man reader), but it render colors for manpages and may do more things. Read "man most".

You can see a preview here:

3) Print out a man page

man -t man | lp

man -t manpagename gives a postscript version of said man page. You then pipe it to ls, and assuming you have cups set up, it prints in your default printer.

4) Search manpages for a keyword

man -k <keyword>

Search manpages for a keyword. Very useful when you don't know where to find the information.

5) Show File System Hierarchy

man hier

Curious about differences between /bin, /usr/bin, and /usr/local/bin? What should be in the /sbin dir? Try this command to find out.

Tested against Red Hat & OS X

6) Convert "man page" to text file


man ls | col -b > ~/Desktop/man_ls.txt

You can convert any UNIX man page to .txt

7) Launch a command from a manpage


Launch a command from within a manpage, vim style. This is rather trivial, but can be very useful to try out the functions described in a manpage without actually quitting it (or switching to another console/screen/…).

[Jan 23, 2012] Save man-page as pdf

man -t awk | ps2pdf - awk.pdf


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:
# Depending on where this is run from, you might need to modify $MANDIR below.
# Hacked together by Peter Boettcher <[email protected]>
# 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:

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.

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:

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

$ manpath

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?

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:, 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; 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


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) 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

Google matched content

Softpanorama Recommended

Top articles


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 Man Tools 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.



This is Solaris man page for man




Formatting Manual Pages








[ Bottom of Page | Previous Page | Next Page | Index ]

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:

C Specifies commands (including system management commands).
F Specifies file-type manual pages.
L Specifies library functions.
n Specifies new.
l Specifies local.
o Specifies old.
p Specifies public.

The n, l, o, and p section specifiers are not valid for reading the hypertext information bases, which contain the operating system documentation.

The section numbers are:

1 Indicates user commands and daemons.
2 Indicates system calls and kernel services.
3 Indicates subroutines.
4 Indicates special files, device drivers, and hardware.
5 Indicates configuration files.
6 Indicates games.
7 Indicates miscellaneous commands.
8 Indicates administrative commands and daemons.

The operating system documentation in the hypertext information databases is grouped into three sections only: command manual pages (in section 1, equivalent to section C), subroutine manual pages (in section 3, equivalent to section L), and file manual pages (in section 4, equivalent to section F). When searching for hypertext information, specifying section 1, 6, 7, or 8 will default to the command manual pages, section 2 or 3 will default to the subroutine manual pages, and section 4 or 5 will default to the file manual pages.

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.


    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
    • %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

    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:

cmds Commands Reference
libs Subroutines, System Calls
files Files Reference

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:

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 $.

-a Display all matching entries.
-c Displays the manual information using the cat command.
-f Displays entries in the keyword database related only to the command name given as the final parameter. You can enter more than one command name, each separated by a space. Use this flag to search for command articles only. To use the -f flag, a root user must have previously entered catman -w to create the /usr/share/man/whatis file.
-F Display only the first matching entry.
-k Displays each line in the keyword database that contains a string of characters matching the title given as the final parameter. You can enter more than one title, each separated by a space. To use the -k flag, a root user must have previously entered catman -w to create the /usr/share/man/whatis file.
-m Only search in the paths specified in MANPATH or -M.
-Mpath Changes the standard location where the man command searches for manual information. The path is a colon-separated list of paths, where the following special symbols can be used:
  • %D –
  • The default AIX paths for man pages.
  • %L – A locale-specific directory location corresponding to the LC_MESSAGES category of the current locale.
  • %l - A locale-specific directory location corresponding to the first 2 characters of the LC_MESSAGES category of the current.
-r Searches remotely for the manual information. If for any reason the remote search fails, then man performs a local search for the requested man page. Any of the following conditions can cause the remote search to fail:
  • The remote machine is not reachable.
  • There is a problem reading the URL.
  • Java™ is not installed or it is not found in the user's search path, specified in the PATH environment variable.

The DOCUMENT_SERVER_MACHINE_NAME environment variable should be set to the name of the documentation search server machine the user wants to use. If the AIX Base Documentation is not supported for the host's locale, the man command searches for the documentation for an alternate locale. If the search is successful, the documentation page is displayed after conversion to the local host's locale. If the alternate locale is not installed on the local host, the man command fails to display the documentation page.

-t Formats the manual information using the troff command. This flag is ignored if the manual page is found in a hypertext information base.
Exit Status

This command returns the following exit values:

0 Successful completion.
>0 An error occurred.
  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
/usr/bin/man Contains the man command.
/usr/share/man Standard manual directory structure.
/usr/share/man/cat?/* Directory containing preformatted pages.
/usr/share/man/whatis Contains the keyword database.
/usr/share/man/man?/* Directory containing nroff format manual pages.
Related Information

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

[ Top of Page | Previous Page | Next Page | Index ]



Groupthink : Two Party System as Polyarchy : Corruption of Regulators : Bureaucracies : Understanding Micromanagers and Control Freaks : Toxic Managers :   Harvard Mafia : Diplomatic Communication : Surviving a Bad Performance Review : Insufficient Retirement Funds as Immanent Problem of Neoliberal Regime : PseudoScience : Who Rules America : Neoliberalism  : The Iron Law of Oligarchy : Libertarian Philosophy


War and Peace : Skeptical Finance : John Kenneth Galbraith :Talleyrand : Oscar Wilde : Otto Von Bismarck : Keynes : George Carlin : Skeptics : Propaganda  : SE quotes : Language Design and Programming Quotes : Random IT-related quotesSomerset Maugham : Marcus Aurelius : Kurt Vonnegut : Eric Hoffer : Winston Churchill : Napoleon Bonaparte : Ambrose BierceBernard Shaw : Mark Twain Quotes


Vol 25, No.12 (December, 2013) Rational Fools vs. Efficient Crooks The efficient markets hypothesis : Political Skeptic Bulletin, 2013 : Unemployment Bulletin, 2010 :  Vol 23, No.10 (October, 2011) An observation about corporate security departments : Slightly Skeptical Euromaydan Chronicles, June 2014 : Greenspan legacy bulletin, 2008 : Vol 25, No.10 (October, 2013) Cryptolocker Trojan (Win32/Crilock.A) : Vol 25, No.08 (August, 2013) Cloud providers as intelligence collection hubs : Financial Humor Bulletin, 2010 : Inequality Bulletin, 2009 : Financial Humor Bulletin, 2008 : Copyleft Problems Bulletin, 2004 : Financial Humor Bulletin, 2011 : Energy Bulletin, 2010 : Malware Protection Bulletin, 2010 : Vol 26, No.1 (January, 2013) Object-Oriented Cult : Political Skeptic Bulletin, 2011 : Vol 23, No.11 (November, 2011) Softpanorama classification of sysadmin horror stories : Vol 25, No.05 (May, 2013) Corporate bullshit as a communication method  : Vol 25, No.06 (June, 2013) A Note on the Relationship of Brooks Law and Conway Law


Fifty glorious years (1950-2000): the triumph of the US computer engineering : Donald Knuth : TAoCP and its Influence of Computer Science : Richard Stallman : Linus Torvalds  : Larry Wall  : John K. Ousterhout : CTSS : Multix OS Unix History : Unix shell history : VI editor : History of pipes concept : Solaris : MS DOSProgramming Languages History : PL/1 : Simula 67 : C : History of GCC developmentScripting Languages : Perl history   : OS History : Mail : DNS : SSH : CPU Instruction Sets : SPARC systems 1987-2006 : Norton Commander : Norton Utilities : Norton Ghost : Frontpage history : Malware Defense History : GNU Screen : OSS early history

Classic books:

The Peter Principle : Parkinson Law : 1984 : The Mythical Man-MonthHow to Solve It by George Polya : The Art of Computer Programming : The Elements of Programming Style : The Unix Hater’s Handbook : The Jargon file : The True Believer : Programming Pearls : The Good Soldier Svejk : The Power Elite

Most popular humor pages:

Manifest of the Softpanorama IT Slacker Society : Ten Commandments of the IT Slackers Society : Computer Humor Collection : BSD Logo Story : The Cuckoo's Egg : IT Slang : C++ Humor : ARE YOU A BBS ADDICT? : The Perl Purity Test : Object oriented programmers of all nations : Financial Humor : Financial Humor Bulletin, 2008 : Financial Humor Bulletin, 2010 : The Most Comprehensive Collection of Editor-related Humor : Programming Language Humor : Goldman Sachs related humor : Greenspan humor : C Humor : Scripting Humor : Real Programmers Humor : Web Humor : GPL-related Humor : OFM Humor : Politically Incorrect Humor : IDS Humor : "Linux Sucks" Humor : Russian Musical Humor : Best Russian Programmer Humor : Microsoft plans to buy Catholic Church : Richard Stallman Related Humor : Admin Humor : Perl-related Humor : Linus Torvalds Related humor : PseudoScience Related Humor : Networking Humor : Shell Humor : Financial Humor Bulletin, 2011 : Financial Humor Bulletin, 2012 : Financial Humor Bulletin, 2013 : Java Humor : Software Engineering Humor : Sun Solaris Related Humor : Education Humor : IBM Humor : Assembler-related Humor : VIM Humor : Computer Viruses Humor : Bright tomorrow is rescheduled to a day after tomorrow : Classic Computer Humor

The Last but not Least Technology is dominated by two types of people: those who understand what they do not manage and those who manage what they do not understand ~Archibald Putt. Ph.D

Copyright © 1996-2021 by Softpanorama Society. was initially created as a service to the (now defunct) UN Sustainable Development Networking Programme (SDNP) without any remuneration. This document is an industrial compilation designed and created exclusively for educational use and is distributed under the Softpanorama Content License. Original materials copyright belong to respective owners. Quotes are made for educational purposes only in compliance with the fair use doctrine.

FAIR USE NOTICE This site contains copyrighted material the use of which has not always been specifically authorized by the copyright owner. We are making such material available to advance understanding of computer science, IT technology, economic, scientific, and social issues. We believe this constitutes a 'fair use' of any such copyrighted material as provided by section 107 of the US Copyright Law according to which such material can be distributed without profit exclusively for research and educational purposes.

This is a Spartan WHYFF (We Help You For Free) site written by people for whom English is not a native language. Grammar and spelling errors should be expected. The site contain some broken links as it develops like a living tree...

You can use PayPal to to buy a cup of coffee for authors of this site


The statements, views and opinions presented on this web page are those of the author (or referenced source) and are not endorsed by, nor do they necessarily reflect, the opinions of the Softpanorama society. We do not warrant the correctness of the information provided or its fitness for any purpose. The site uses AdSense so you need to be aware of Google privacy policy. You you do not want to be tracked by Google please disable Javascript for this site. This site is perfectly usable without Javascript.

Last modified: February 19, 2020