Complete tutorial of the man command in Linux

If you've been tinkering with GNU/Linux for a while, you've probably used the command more than once. man to get you out of a tight spot with the syntax of some program, an unusual option, or a configuration file. Even so, many people only use it superficially and are unaware of everything behind it: sections, formats, shortcuts, and even the possibility of creating their own manuals.

In the following lines you will find a Complete tutorial on using man in LinuxThis will cover exactly what a manual is, how its pages are organized, how to consult them efficiently, where they are stored, how to create them manually using Groff macros, and how to generate them easily with tools like Pandoc. The goal is for you to end up not only reading manuals but also writing your own to document scripts and applications.

What is man and why is it so important in Linux

In UNIX-like systems, including GNU/Linux, the main documentation is organized into the so-called manual pages or man pages, accessible via the command the CommissionThese pages describe in detail commands, utilities, system calls, library functions, special files, and much more.

Each man input provides the Synopsis of command usage, an extensive description, the list of options, examples and often additional information such as related files, environment variables, known errors or references to other related man pages.

To access help for any installed tool, simply type something as simple as man command_name in the terminalThe result is displayed in a paginated manner (usually using the LESS viewer), allowing you to comfortably navigate through long documents without cluttering the screen.

In many distributions, pages are available in multiple languages ​​and are stored in different directories depending on the language. Not all content is translated into SpanishBut in Debian and derivatives you can install packages like manpages-es y manpages-es-extra to have a good part of the manual available in Spanish.

Within the GNU ecosystem there is also the well known The Linux Documentation Project (TLDP)which coordinates official documentation in English and has a Spanish version (es.tldp.org). You can also consult the Complete guide to server manualsAlthough not limited to man pages, it has been a key project in the dissemination of technical documentation in Linux.

Manual organization by sections

The UNIX and Linux manual is divided into numbered sections that group specific types of informationThis prevents mixing, for example, a user command with a kernel system call that has the same name.

The classic (and most widespread) sections of the manual are the following, each associated with a well-defined type of content within man:

• Section 1: user executable commands (programs launched from the shell).
• Section 2: system calls or syscalls provided by the kernel.
• Section 3: library functions (C, C++, Perl, etc.).
• Section 4: special device files, usually in / Dev.
• Section 5: file formats and conventions (for example / Etc / passwd).
• Section 6: games and screensavers.
• Section 7: miscellaneous (protocols, standards, various conventions, etc.).
• Section 8: system administration commands and daemons (intended for root).
• Section 9: internal kernel routines (not always present or standardized).

This division is reflected both in the logical structure of the manual and in the system directories: Each section has its own manN folder (man1, man2, man3, etc.), where the corresponding pages are stored, usually compressed with gzip.

It is common to find names repeated in different sections. For example, chmod exists as a user command and as a system callIn these cases, the section is what makes the difference between one page and another, and it is essential to know which one we want to access.

How to use man effectively

The basic use of the command is very simple: if we want to consult the help of any program, we just need to type something like this in the terminal: man command to open its manual pageFrom there, we enter a paginated viewer (usually less) that allows us to navigate through the content.

When the same name appears in multiple sections, man searches the manual from the lowest section to the highest and displays the first match it finds. For example, if you run man chmodYou will see the user command page (section 1) because that section takes precedence over section 2.

If you need to force a specific section, you can explicitly specify it before the name: when running man 1 chmod you get the command manual, while with man 2 chmod You access the description of the kernel's chmod system call.

The general format that the command follows is very easy to remember: man name…If you omit the section, man will search in ascending order; if you include it, you will go directly to the correct page without ambiguity.

Within the page, the output is presented paginated, typically using less as an internal viewfinderYou can navigate using the arrow keys, Page Up and Page Down, the space bar, or the typical Less shortcuts. To exit and return to the command line, simply press the Enter key. q.

Useful shortcuts when consulting manuals with less

As man leans on less, he inherits a whole battery of shortcuts that make reading easier of lengthy manuals. Some of them go unnoticed, but once you use them, it's hard to live without them.

If you're browsing a particularly long page and find a key point you want to return to later, you can mark the current position within the documentYou just have to press the key m followed by a letter (az or AZ) to create a marker.

When you want to return to that brand, simply press the single quote. ' followed by the same letter that you used when creating it. This way you can quickly jump between important positions without racking your brain trying to remember where everything was.

Note that Brands only live as long as you have that page open.As soon as you close `man` (and therefore `less`), they are lost. However, this trick also works for any other file you open directly with `less`, not just man pages.

Another very practical detail is the possibility of Run shell commands without closing the manual pageJust like in editors such as vi or vim, you can press ! Inside less, type the command you want to test and run it; when finished, return to where you were in the manual simply by pressing Enter.

How is the syntax described in the man pages?

One of the most important parts of any manual page is the SYNOPSIS sectionThis section displays the syntax of the command, function, or file. To ensure it is concise yet precise, a series of conventions are used that should be mastered.

When you see an item between This means it's optional.If the text appears as You can choose to select that option or not; however, if it is displayed as {x,y}The elements in braces are alternatives, but you must choose one of them.

If the synopsis includes something like this It indicates that you can use x, I'm nothingprecisely because the entire expression is enclosed in square brackets. In turn, if it appears x ...This means that x can be repeated as many times as you need on the command line.

The options are sometimes summarized with syntax like This suggests that none of them are mandatory, but if you use them, You can combine any of the letters in any order.Thus, -x, -y, -z, -xy, -zx, etc. would be valid, as long as the program accepts that combination.

This compact way of expressing syntax allows for condensation all the possibilities in one lineAlthough it may seem somewhat cryptic at first, once you internalize it, reading manuals becomes much more efficient.

Typical structure of a manual page

Behind every man page is a text file in a specific format based on Groff and in a set of macros that define sections, titles, styles, paragraphs, etc. Although at first glance the result is "just text", there is much more to it than that.

The basic anatomy of a manual page typically includes several sections well known as NAME, SYNOPSIS and DESCRIPTIONThese can be supplemented with others depending on what needs to be documented. There is no strict obligation, but there are a number of widely used conventions.

The most common sections you will find (or that you should use when creating your own pages) are, among others, the following, grouping the information in a predictable way for the user:

• NAME: command or file name and a brief description.
• SYNOPSIS: line or lines that summarize parameters and options.
• DESCRIPTION: detailed explanation of how it works.
• OPTIONS / OPTIONS: description of all command line options (mainly in sections 1 and 8).
• COMMANDS: list of subcommands or internal actions, if the tool has them.
• ENVIRONMENT: relevant environment variables and how the program uses them.
• FILES / ARCHIVES: files that the tool uses or modifies (configuration, logs, etc.).
• BUGS / ERRORS: known problems or limitations.
• EXAMPLE: real-world usage examples, very useful for everyday life.
• AUTHORS: authors of the program or the manual itself, often with email.
• SEE ALSO / VÉASE TBIÍA: references to other related man pages.

In addition to these, it is common to include others such as EXIT STATUS, CAVEATS, NOTES, RETURN VALUE or DIAGNOSTICS when you want to delve deeper into exit codes, warnings, additional notes, or specific error messages.

Although it might seem a bit tedious at first, respecting these sections when writing your manuals will make it users feel “at home”because they will know where to look for each type of information without having to explore blindly.

Groff formatting macros used in man pages

If you open the source file of a classic man page (for example, by unzipping gpg.1.gz), you'll see a rather raw text full of lines that begin with a period followed by acronymsThose acronyms are precisely the formatting macros that the manual system understands.

The macro that opens the page is called .TH and defines the main headerThe general structure that follows is something like this: .TH command-name section-number date Author title, all on a single line, with uppercase letters for the command name.

A real-world example might look something like this: .TH GPG 1 2015-03-08 «GnuPG 1.4.12» «GNU Privacy Guard», where the program name, section, manual revision date, version name, and a descriptive title are specified.

The different parts of the content are structured with the macro .SH, which introduces new sections into the documentIts basic form is very simple: .SH SECTION_NAME, and then the text that makes up that section, until a new one is declared.

To format specific text fragments, macros are used such as .B, .I and .RThese indicate bold, italic/underline, and "roman" font (normal text), respectively. Combinations like .BI or .IR also exist for mixing styles within the same line.

A very simple example would be something like this: .B this is a .I testwhich would be displayed roughly as “this is a” highlighted and “proof” in italics. The drawback is that These macros usually affect the rest of the entire line if they are not carefully controlled.

For finer control, it is common to use source switching sequences such as \fB, \fI and \fRwhich change the style briefly within a line. So you could write something like This is a test to obtain a more precise result.

Explicit line breaks are indicated with .br, while new paragraphs are created with .PPIn this way, the author of the manual decides how the text is visually structured when displayed, without relying solely on white space.

If necessary, leave Internal comments that users won't see When running man, you can use a comment macro (for example with lines starting with a period and a backslash), useful for giving hints to future maintainers of the manual without it being shown in the final version.

Location and organization of man pages in the system

To fully understand how the manual pages work, it's very helpful to know where the files are physically stored in the systemThis is especially useful when you want to inspect, copy, or create your own manuals.

A very typical route where these pages reside is / usr / share / manalthough you can also find other locations such as /usr/man, /usr/local/man or /usr/local/share/mandepending on the distribution or whether it is locally installed software.

Each section of the manual corresponds to a subdirectory called manN (man1, man2, man3, etc.)For example, a typical user program might have its manual in /usr/share/man/man1/programa.1.gz, while an administration page could reside in man8.

If you want to locate the files associated with a specific program (including its man page), you can use whereis program_name so that the system indicates relevant pathsThe output will usually include the exact path to the .N.gz file from the manual page.

When you need to "dissect" a manual to learn how it's made without risking breaking anything, you can Copy the file from /usr/share/man to a secure directory like /usr/src, and then decompress it with gzip to analyze its contents with your favorite editor.

Keep in mind that the section numbering is not decorative: upon inspection /usr/share/man you will see directories man1 to man8 (and sometimes man9)Each one groups manuals of a specific type. In this way, a coherent and easy-to-maintain structure is achieved.

How to create your own man pages “by hand”

Once you understand the structure and basic macros, you can dive in create your own manual for scripts or programs (for example, a Bash manualThe process is not as complicated as it may seem, although it does require some care to ensure it is clean and usable.

A classic approach involves choosing an existing man page as a reference (for example, the one for gpg or iptables), copying it to another directory, decompressing it, and use it as a template to learn the actual syntaxFrom there, you remove content and leave only the structure you need.

When naming the file, the convention is followed of section nameIf your script is called test and it's a normal user program, the usual thing to do is to call it test.1 because it goes to section 1Then, inside, you will define the title with .TH, the sections with .SH, and the formatted content with the macros you already know.

Once you have that ready, the next step is compress the file with gzipThis will generate test.1.gz, ready to be installed in the appropriate location. The compressed format is the one used by the default manual system.

To make it available to other users, simply copy the compressed file to the appropriate section directoryFor example, /usr/share/man/man1/ if it's a normal command, or man8 if it's an administrative command.

With the file placed in the correct location, you can open your manual simply by typing man test from any system terminalFrom then on, it will behave like any other man page installed in the standard way.

Creating manuals with pandoc and Markdown

Editing directly in Groff format is fine for learning, but it can be a bit rough around the edges. If you prefer something more user-friendly, you can Use Markdown and convert it to man format with tools like pandoc.which greatly speeds up the documentation process.

The first step is to install pandoc using your distribution's package manager (apt, dnf, pacman, etc.). Once installed, you can create your man page in a file with the .N.md extension, for example. hello.1.md for a command called hello.

In that Markdown file you can write your documentation with sections that reflect NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES and any other you might need. Any simple text editor like vim, nano, gedit, or similar will work for this task.

When you've finished writing the content in Markdown, it's time to tell pandoc to convert it to manual format that understands manTo do this, a command like this is used: pandoc -s -t man -o hola.1 hola.1.md, where the output name has the section as its extension.

The option -s (standalone) tells pandoc to generate a full man pagewith all the necessary structure, and not just a fragment of text without a heading. For its part, the option The `-t man` clause specifies that the output type must be precisely the format of the manual. which the system then understands.

Once the hola.1 file has been generated, you can compress it if you wish, and copy it to /usr/local/man/man1 or another appropriate path and verify that it works by typing `man hola`. This way you'll have a clean and maintainable manual, with the added convenience of having written it in Markdown.

Installing, locating, and removing your man pages

When you develop your own script or program, it makes sense not only to install the binary, but also place your man page in the correct path so that any user can easily call her from the terminal.

If you have created, for example, an executable called hello, a typical location for the binary would be /usr/bin/helloso you can call it simply by typing hello without having to go to its source folder or modify the PATH.

The relevant manual page should go to /usr/share/man/man1/hola.1.gz or a similar directory According to the section and policy of your distribution. If it's an administration tool, you might prefer to place it in man8.

In environments where you distribute your software to third parties, it is very convenient. include installation and uninstallation scripts that copy or delete both the binary and the man page. This way, if the user decides to delete your tool, no orphaned documentation will remain scattered throughout the system.

To uninstall manually, you would simply need to Remove the binary from its path (e.g., /usr/bin/hello) and the man page from its corresponding man directoryAfter that, any attempt to run man hola will return an error that the entry does not exist.

Using these locations consistently makes it Your software integrates "natively" into the system, following the same patterns used by the tools included in the distribution.

Ultimately, mastering the man command and the format of man pages allows you not only to consult Linux documentation very efficiently, but also Turn your own scripts and applications into well-documented and easy-to-use toolsWhen you incorporate manuals with clear sections, examples, and references, you greatly improve the experience of whoever will use your work, whether it's someone else or yourself in a few months when you no longer remember the details.