1. Overview
In Unix environments, documentation plays a crucial role in helping users, developers, and system administrators understand and use various commands and utilities effectively.
Among the most widely used documentation systems are man and info. In particular, each offers valuable information but presents it in different ways.
In this tutorial, we’ll explore the key differences between man and info as documentation systems. Moreover, we’ll look at code snippets to understand their usage. Furthermore, we’ll discuss when to use one over the other based on specific use cases.
2. man Documentation
In this section, we’ll explore the man command in-depth, as it’s a fundamental component of Unix-like operating systems. Its primary purpose is to provide detailed and comprehensive documentation for various commands and utilities available in the system.
The word man stands for manual, – a classic name for a traditional documentation system. In fact, man has been present since the early days of Unix.
2.1. Theoretical Understanding
The man command operates by accessing formatted documentation files known as man pages. These man pages contain detailed information about each command, structured into various sections to present a clear and organized view of the topic:
- concepts
- system and library calls
- functions
- tools
- commands
- utilities
When we run the man command followed by the name of a command or utility, it searches for the corresponding man page in the system’s manpath. Moreover, manpath usually includes directories like /usr/share/man and /usr/local/share/man. In essence, manpath is an environment variable that specifies the directories where man pages are stored.
Once the man command locates the appropriate man page, it uses a pager application, usually less, to display the content. Accordingly, the pager enables us to navigate through the manual:
- scroll through the man page
- view information section by section
- navigate conveniently
Finally, some man pages even include examples of command usage.
2.2. Exploring Practical Examples
Since we’ve previously understood the theory behind the man command, let’s check out a practical illustration:
$ man ls
LS(1) User Commands LS(1)
NAME
ls - list directory contents
SYNOPSIS
ls [OPTION]... [FILE]...
DESCRIPTION
List information about the FILEs (the current directory by default).
OPTIONS
-l use a long listing format
-a, --all
do not ignore entries starting with .
...
The above snippet is an example of viewing the man page of the ls command. As we can see from the output, it includes sections like NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, and more.
2.3. Navigation
The man pages are organized into numbered sections, each dedicated to a specific category of commands. There are eight common sections in the man pages:
- Section 1: User Commands
- Section 2: System Calls
- Section 3: Library Functions
- Section 4: Devices and Drivers
- Section 5: File Formats and Conventions
- Section 6: Games and Amusements
- Section 7: Miscellaneous
- Section 8: System Administration Commands
Because of this wide coverage, there are thousands of man pages. Previously, we checked an example with the manual of ls, which relies on the User Commands section.
Now, let’s try to access a specific section. To do so, we use the -s option followed by the section number. For example, let’s view the man page for the printf function from the C library as part of Section 3:
$ man -S 3 printf
PRINTF(3) Linux Programmer's Manual PRINTF(3)
NAME
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf,
vdprintf, vsprintf, vsnprintf - formatted output conversion
SYNOPSIS
#include <stdio.h>
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int dprintf(int fd, const char *format, ...);
...
We used the -s option followed by the number 3 to indicate that we’re navigating to Section 3.
2.4. Switch Modifiers
The man command offers several options and switches to make changes to the way we view pages. Let’s explore two of these options:
- -f, –whatis: display a one-line summary of the command’s purpose
- -k, –apropos: search for topics containing a specific keyword
Next, let’s explore the whatis and apropos options to search for information about the grep command:
$ man -f grep
grep (1) - print lines matching a pattern
The whatis option indicated by -f displays a one-line summary of the grep command’s purpose.
Afterward, let’s utilize the -k option:
$ man -k search
agrep (1) - search a file for a string or regular expression, with approximate matching capabilities
Searching by keyword also works and returns a command that contains the search string.
3. The info Command
info is another documentation system found in Unix and Linux environments. In fact, it replaced man as the default format for documentation inside the GNU project.
3.1. Theoretical Understanding
The info pages are organized into nodes, forming a hierarchical, interconnected structure. Furthermore, a node in info documentation serves as a building block for presenting information in a structured way. In other words, nodes are self-contained units of information, representing a specific topic or subtopic, enabling us to navigate through related information seamlessly.
Unlike man pages, info offers a menu system, accessible by pressing h or ? while viewing a page, listing major topics or nodes. Accordingly, this feature enables us to jump directly to the desired section without traversing the entire documentation.
Moreover, info pages often include hyperlinks and cross-references to related nodes, fostering deeper exploration.
3.2. Installation
Unlike man, info still isn’t widespread by default. Accordingly, let’s first check first whether it’s installed:
$ info --version
texinfo 6.5
The above output implies that info is installed.
In case it isn’t, we can install info using our package manager:
$ sudo apt-get update
$ sudo apt-get install texinfo
Here, we use sudo along with apt to update the package lists on the system. Afterward, we install the textinfo package, which provides info.
3.3. Practical Illustration
info uses a simple syntax similar to that of man. Let’s see an example to check the info documentation of the ls command:
$ info ls
File: coreutils.info, Node: ls invocation, Next: dir color, Up: Directory listing, (dir)
LS Invocation
=============
The 'ls' program lists information about files (of any type, including
directories). Options and file arguments can be intermixed arbitrarily, as
usual.
`ls' supports several style options, including some that are not mentioned
in the reference manuals. This node documents all the options recognized
by 'ls' version 3.0.
OPTIONS
-l
--format=long
...
-a
--all
...
As we can see above, the output of info differs from that of man. Typically, info uses a structure similar to that of a book. In particular, info documentation refers to a comprehensive and interconnected collection of nodes that form a detailed guide or manual on a specific topic.
On the other hand, man is more specific to a certain command or a system function.
3.4. Using Different Switches
Similar to man, there are multiple options that info supports:
- -a, –al: use all matching manuals and display them
- -k, –apropos: search for commands containing a specific keyword
Let’s start with the -a option:
$ info -a xml
Node: File names matching 'xml'
Info File Index
***************
File names that match 'xml':
* Menu:
*__1: (/usr/share/info/xml.info.gz).
*__2: (*manpages*)xml.
...
As we can see, the -a option returns nodes that match xml.
Now, let’s check the -k option:
$ info -k search
* Menu:
Searching in Info Documentation: Tips for effectively searching within Info documentation.
Grep Command: Using the 'grep' command for searching within text files.
Search Operators: Understanding Boolean search operators for Info documents.
Here, we can notice the difference between man and info using the same -k option which should have the same function. As illustrated before, the main difference is in the visualization and representation of the output.
4. Conclusion
In this article, we learned the differences between man and info in Linux. We saw that man provides a concise representation of a command or topic’s purpose, syntax, and available options. Thus, manual pages are efficient for quick reference.
On the other hand, info offers a more extensive, interconnected structure, ideal for in-depth exploration and understanding of related concepts.
In short, man is suitable for quick references and straightforward organization, while info is beneficial for navigating through interconnected topics and exploring a hierarchical structure.