How-To Geek

How to create a man page on linux.

Tired of wrestling with hieroglyphics while trying to write your man page? pandoc makes the process so much easier!

Quick Links

The man pages, pandoc to the rescue, sections of a man page, sections of the manual, the format of a man page, an efficient workflow, creating your man page, if you want to . . ..

Want your new Linux program to look professional? Give it a man page. We'll show you the easiest, and fastest, way to do it.

There's a kernel of truth in the old Unix joke, "the only command you need to know is man ." The man pages contain a wealth of knowledge, and they should be the first place you turn when you want to learn about a command.

Providing a man page for a utility or command you’ve written elevates it from a useful piece of code to a fully-formed Linux package. People expect a man page to be provided for a program that's been written for Linux. If you’re natively supporting Linux, a man page is mandatory if you want your program to be taken seriously.

Historically the man pages have been written using a set of formatting macros. When you call upon man to open a page, it calls groff to read the file and generate formatted output , according to the macros in the file. The output is piped into

, and then  displayed for you .

Unless you create man pages frequently, writing one and manually inserting the macros is hard work. The act of creating a man page that parses correctly and looks right can overtake your aim to provide a concise, yet thorough, description of your command.

You should be concentrating on your content, not battling an obscure set of macros.

Related: How to Use Linux's man Command: Hidden Secrets and Basics

The pandoc program reads markdown files and generates new ones in about 40 different markup languages and document formats, including that of the man page. It totally transforms the man page writing process so you don't have to wrestle with hieroglyphics.

To get started, you can install pandoc on Ubuntu with this command:

sudo apt-get install pandoc

x-special/nautilus-clipboard copy file:///home/dave/Documents/Development/how-to-geek/create-man-page/images/trimmed/0.png file:///home/dave/Documents/Development/how-to-geek/create-man-page/images/trimmed/0b.png file:///home/dave/Documents/Development/how-to-geek/create-man-page/images/trimmed/0c.png in a terminal window

On Fedora, the command you need is the following:

sudo dnf install pandoc

On Manjaro, type:

sudo pacman -Syu pandoc

Related: How to Use pandoc to Convert Files on the Linux Command Line

man pages contain sections that follow a standard naming convention. The sections your man page needs are dictated by the sophistication of the command you're describing.

At a minimum, most man pages contain these sections:

  • Name : The name of the command and a pithy one-liner that describes its function.
  • Synopsis : A terse description of the invocations someone can use to launch the program. These show the types of accepted command-line parameters.
  • Description : A description of the command or function.
  • Options : A list of command-line options, and what they do.
  • Examples : Some examples of common usage.
  • Exit Values : The possible return codes and their meanings.
  • Bugs : A list of known bugs and quirks. Sometimes, this is supplemented with (or replaced by) a link to the issue tracker for the project.
  • Author : The person or people who wrote the command.
  • Copyright : Your copyright message. These also usually include the type of license under which the program is released.

If you look through some of the more complicated man pages, you’ll see there are many other sections, as well. For example, try man man . You don't have to include them all, though---just those you really need. man pages are no place for wordiness.

Some other sections you'll see reasonably frequently are:

  • See Also : Other commands related to the subject matter some would find useful or relevant.
  • Files : A list of files included in the package.
  • Caveats : Other points to know or watch out for.
  • History : A change history for the command.

The Linux manual is made up of all the man pages, which is then split into these numbered sections:

  • Executable programs: Or, shell commands.
  • System calls: Functions provided by the kernel.
  • Library calls: Functions within program libraries.
  • Special files.
  • File formats and conventions: For example, "/etc/passwd".
  • Miscellaneous: Macro packages and conventions, such as groff .
  • System administration commands: Usually reserved for root.
  • Kernel routines: Not usually installed by default.

Every man page must indicate to which section it belongs, and it must also be stored in the appropriate location for that section, as we'll see later on. The man pages for commands and utilities belong in section one.

The groff macro format is not easy to visually parse. In contrast, markdown is a breeze.

Below is a man page in  groff .

The same page is shown below in markdown.

Front Matter

The first three lines form something called front matter. These must all start with a percentage sign ( % ), with no leading spaces but one afterward, followed by:

  • The first line: Contains the name of the command, followed by the manual section in parentheses, with no spaces. The name becomes the left and right sections of the man page header. By convention, the command name is in uppercase, although you'll find plenty that aren't. Anything that follows the command name and manual section number becomes the left section of the footer. It's convenient to use this for the software version number.
  • The second line: The name(s) of the author(s). These are displayed in an automatically-generated authors section of the man page. You don't have to add an "Authors" section---just include at least one name here.
  • The third line: The date, which also becomes the center part of the footer.

Sections are indicated by lines that start with a number sign ( # ), which is the markup that indicates a header in markdown. The number sign ( #)  must be the first character on the line, followed by a space.

The name section holds a snappy one-liner that includes the name of the command, a space, a hyphen ( - ), a space, and then a very short description of what the command does.

The synopsis holds the different formats the command line can take. This command can accept a search pattern or a command-line option. The two asterisks ( ** ) on either side of the command name mean the name will be displayed in bold on the man page. A single asterisk ( * ) on either side of some text causes the man page to display it underlined.

By default, a line break is followed by a blank line. To force a hard break without a blank line, you can use a trailing backslash ( \ ).

Description

The description explains what the command or program does. It should cover the important details succinctly. Remember, you're not writing a user's guide.

Using two number signs ( ## ) at the start of a line creates a level two heading. You can use these to break your description into smaller chunks.

The options section contains a description of any command-line options that can be used with the command. By convention, these are displayed in bold, so include two asterisks ( ** ) before and after them. Include the text description of the options on the next line and start it with a colon ( : ), followed by a space.

If the description is short enough, man  will display it on the same line as the command-line option. If it's too long, it's displayed as an indented paragraph that begins on the line below the command-line option.

The examples section contains a selection of different command-line formats. Note that we start the description lines with a colon ( : ), just as we did the options section.

Exit Values

This section lists the return values your command sends back to the calling process. This might be the shell if you called it from the command line, or a script if you launched it from a shell script. We start description lines with a colon ( : ) in this section, too.

The bugs section lists known bugs, gotchas, or quirks people need to know about. For open-source projects, it's common to include a link here to the project's issue tracker to check on the status of any bugs or report new ones.

The copyright section contains your copyright statement, and, usually, a description of the type of license under which the software is released.

You can edit your man page in your favorite editor. Most that support syntax highlighting will be aware of markdown and color the text to highlight headings, as well as bold and underline it. That's great as far as it goes, but you're not looking at a rendered man page, which is the real proof in the pudding.

Open a terminal window in the directory that contains your markdown file. With it open in your editor, periodically save your file to your hard drive. Each time you do, you can execute the following command in the terminal window:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Once you've used this command, you can press the Up arrow to repeat it, and then press Enter.

This command also invokes  pandoc on the markdown file (here, it's called "ms.1.md"):

  • The -s (standalone) option generates a top-to-bottom complete man page, rather than just some text in man format.
  • The -t (output type) option with the "man" operator tells pandoc to generate its output in man format. We haven't told pandoc to send its output to a  file, so it'll be sent to stdout .

We're also piping that output into man  with the -l (local file) option. It tells man  not to search through the man database looking for the man page. Instead, it should open the named file. If the filename is - ,  man will take its input from stdin .

What this boils down to is you can save from your editor and press Q to close man  if it's running in the terminal window. Then, you can press the Up arrow, followed by Enter to see a rendered version of your man page, right inside man .

Related: What Are stdin, stdout, and stderr on Linux?

After you've completed your man page, you need to create a final version of it, and then install it on your system. The following command tells  pandoc  to generate a man page called "ms.1":

pandoc ms.1.md -s -t man -o ms.1

This follows the convention of naming the man page after the command it describes and appending the manual section number as though it were a file extension.

This creates an "ms.1" file, which is our new man page. Where do we put it? This command will tell us where  man searches for man pages:

The results give us the following info:

  • /usr/share/man: The location of the standard library of man pages. We don't add pages to this library.
  • /usr/local/share/man: This symbolic link points to "/usr/local/man."
  • /usr/local/man: This is where we need to place our new man page.

Note that the different manual sections are contained within their own directories: man1, man2, man3, and so on. If the directory for the section doesn't exist, we need to create it.

To do so, we type the following:

sudo mkdir /usr/local/man/man1

We then copy the "ms.1" file to the correct directory:

sudo cp ms.1 /usr/local/man/man1

man expects the man pages to be compressed, so we'll use  gzip to compress it :

sudo gzip /usr/local/man/man1/ms.1

To make man add the new file to its database, type the following:

That's it! We can now call our new man page the same as any other by typing:

Our new man page is found and displayed.

It looks just like any other man page, with bold, underlined, and indented text in the appropriate places.

Lines of description that fit next to the option they describe appear on the same line. Lines that are too long to fit appear below the option they describe.

We've also automatically generated an "Authors" section. The footer also includes the software version number, date, and command name, as defined in the front matter.

Once pandoc has created your  man page, you can also directly edit the file in the groff macro format before moving it to the man page directory, and gzip it.

It's FOSS

RTFM! How to Read (and Understand) the Fantastic Man Pages in Linux

Bill Dyer

The man pages , short for reference manual pages , are your keys to Linux. Everything you want to know is there – take it all in an run with it. The collection of documents will never win a Pulitzer prize, but the set is quite accurate and complete. The man pages are the primary source and that authority is well-known.

While they are the “go to” source, they aren’t the most pleasant to read. Once, in a long past philosophy class, I was told that reading Aristotle was the most boring read around. I disagreed: when it comes to dry reading, Aristotle comes in at a distant second to man pages.

At first glance, the pages may look incomplete but, believe it or not, the man pages aren’t designed to hide information from you – it’s just that there is so much information that the pages have to be structured and information is given in the most brief form possible. The explanations are rather spartan and they will take some getting used to, but once you get the hang of using them, you’ll see how useful they actually are.

Getting Started with the man Pages in Linux

The pages are viewed through a utility called, man , and the command to use it is rather easy. In the simplest form, to use man , you type man on the command line, followed by a space and the command that you want to look up, such as ls or cp , like so:

man opens the manual page of the ls command.

man page example

You can move up and down with the arrow keys and press q to quit viewing the man page. Usually, the man pages are opened with less so the keyboard shortcuts for less command work in man as well.

For example, you can search for a specific text using /search_term and so on.

There is an introduction to the man pages and it’s important that you read this one. It spells out, in great detail, how the man pages are laid out and organized.

To see this page, open a terminal and type:

man man

Section What?

Before you begin to look at man pages much deeper, it will be helpful to know that man pages have a set page layout and a filing scheme. This can be confusing to a newcomer since I can say: “Look at the NAME section of the man page for ls .” I can also say, “Look at the man page for passwd in section 5.”

I italicized the word, section to try to show a source of confusion. The word, section is being used in two different ways, but the difference isn’t always explained to newcomers.

I am not sure why this confusion sets in, but I have seen it happen a few times back when I trained new users and entry-level sysadmins. I think it might be tunnel vision. Focusing on one thing can make a person forget about another. It’s a lot like not being able to see the forest because the trees are in the way.

To those who know the difference already, you can skip this sub-section. This part is directed to the people new to man pages.

Here is the difference:

The man page

Individual man pages are made to show blocks of information. For example, every man page has a NAME section to show the name of the command along with a brief description. There will be another block of information, called SYNOPSIS to show how the command is used, and so on.

Linux man page example

Every man page will have these, and other headings. These sections, or headings, on individual man pages, helps keep things consistent and information compartmentalized.

The use of section , as in “Look at the man page for passwd in section 5” speaks of the manual as a whole. When we look at only one page, it can be easy to overlook that, but the man page for passwd is part of the same manual that has a man page for ls , rm , date , cal , and others.

The entire Linux manual is huge; it has thousands of pages. Some of those pages have specialized information. Some pages have information that programmers need, while others have information unique to networking, and others that system administrators would be interested in.

These pages are grouped according to their unique purpose. Think of splitting the entire manual into several chapters – each chapter having a specific topic. There are 9 or so chapters (very large ones at that). It just so happens that these chapters are called sections .

To sum this up:

  • Sections of a single page of the manual (what we call the man page) are blocks of information defined by the headings and
  • Sections of the manual-at-large (the collection of all of the pages) are chapters which happen to be called sections .

Now you know the difference and, hopefully, the rest of this article will be easier to follow.

man Page Sections

You will be looking at different man pages so let’s study the individual page layout first.

Manual pages are split into several headings and they may vary from vendor to vendor, but they will be similar. The general breakdown is as follows:

  • DESCRIPTION
  • DIAGNOSTICS
  • PORTABILITY
  • HISTORY WARNING (or Bugs)

NAME – Under this heading is the command name and a brief description of the command.

SYNOPSIS – Shows how the command is used. For instance, here is a synopsis of the cal command:

The synopsis begins with the name of the command, with a list of options following. The synopsis takes the general form of a command line; it shows what you can type and the order of the arguments. Arguments in square brackets ( [] ) are optional; you can leave these arguments out and the command will still work correctly. Items not in brackets must be used.

Take note that brackets are for readability only. They should not be typed when you enter a command.

DESCRIPTION – Describes the command or utility as to what it does and how you can use it. This section usually starts off with an explanation of the synopsis as well as telling what happens if you omit any of the optional arguments. This section may be subdivided for long or complex commands.

EXAMPLES – Some man pages provide examples of how the command or utility can be used. If this section is present, the page tries to give a few simple usage examples, as well as more complex examples to show how complex tasks can be completed.

DIAGNOSTICS – This section lists status or error messages returned by the command or utility. Self-explanatory error and status messages aren’t usually shown. Messages that may be hard to understand are usually listed.

FILES This section contains a list of supplementary files used by UNIX to run this specific command. Here, supplementary files are files not specified on the command line. For example, if you were looking at a man page for the passwd command, you may find /etc/passwd listed in this section since that is where UNIX stores password information.

LIMITS – This section describes any limitations of a utility. Operating system and hardware limitations are usually not listed as they are outside of the utility’s control.

PORTABILITY – Lists other systems where the utility is available, along with how other versions of the utility may differ.

SEE ALSO – lists related man pages that contain relevant information.

HISTORY – Gives a brief history of the command such as when it first appeared.

WARNING – If this section is present, it contains important advice for users.

NOTES – Not as severe as a warning, but important information.

Again, not all man pages use the exact headings listed above, but they’re close enough to follow.

The Manual’s Sections

The entire Linux manual collection of pages are traditionally divided into numbered sections:

  • Section 1 : Shell commands and applications
  • Section 2 : Basic kernel services – system calls and error codes
  • Section 3 : Library information for programmers
  • Section 4 : Network services – if TCP/IP or NFS is installed Device drivers and network protocols
  • Section 5 : Standard file formats – for example: shows what a tar archive looks like.
  • Section 6 : Games
  • Section 7 : Miscellaneous files and documents
  • Section 8 : System administration and maintenance commands
  • Section 9 : Obscure kernel specs and interfaces

The grouping of pages into these groups makes for more efficient searching. I sometimes do a little programming where I work, so I spend a little time look at section 3 man pages. I also do a little work in networking, so I’ve been known to wade through the networking section, and as a system administrator of several experimental machines, I spend a good deal of time in section 8.

Grouping pages into specific (chapters) sections make searching for information easier – both for the human needing it, and for the machine doing the searching.

You can tell which page belongs to which section by the number next to the name. For example, if you’re looking at a man page for ls and the very top of the page says this: LS(1) , you are viewing the ls page in section 1, which contains the pages about shell commands and applications.

Here is another example. If you’re looking at a man page for passwd and the top of the page shows: PASSWD(1) , you are reading the page from section 1 that describes how the passwd command changes passwords for user accounts. If you see PASSWD(5) , you are reading about the the password file and how it is made up.

man page passwd command

passwd happens to be be two different things: it is the name of a command and a name of a file. Again, section 1 describes the command, while section 5 covers file formats.

The number in the parenthesis is the big clue – that number tells you what section that the page you’re reading, came from.

Searching for a Specific Section

The basic command:

will search for the man page identified by name in every section, displaying them one at a time, in numerical order. To limit your search to a specific section, use an argument with the man command, like so:

This command will only search section 1, of the man pages, for name . Using our passwd example earlier, this means that we can keep the search targeted. If I want to read about the passwd command, I can type this in the terminal:

The man utility will only search through section 1 for passwd and display it. It will not look through any other section for passwd .

An alternative method for this command is to type: man passwd.1

Using man -k to Search all man Pages Containing a Certain Keyword

The man command, with the k option (often called a flag or switch ) can come in handy if you want a listing of man pages containing a certain keyword. For example, if you want to see a list of man pages that deal with, say, ftp , you can get this list by typing:

From the listing that will follow, you’ll be able to pick a specific man page to read:

man k example

On some systems, before man -k will work, the system administrator will need to run a utility called catman .

Using whatis and whereis Commands to Know the Manual’s Sections

There are two nifty utilities that can be helpful in your search for information: whatis and whereis.

There are times when we can quite get the information we need. Chances are great that the information we need is available – finding it can be a small problem.

For example, if I want to look at the man page about the passwd file, and I type this on the terminal:

I would see the page that tells me all about the passwd command, but nothing about the passwd file. I know that passwd is a command and there’s also a passwd file, but sometimes, I might forget that. It’s then that I realize that file structures are in a different section in the man pages, so I type:

and I get this reply:

Another lapse of forgetfulness. File structures are in section 4 of System V UNIX pages. Years ago, when I built files, I used man 4... a lot ; it’s still a habit with me. So where is it in the Linux manual?

It’s time to call whatis to straighten me out. To do this, I type this in my terminal:

and I see the following:

Ah! the page for the passwd file is in section 5. Now I am set straight and can access the information I want:

and I am brought to the man page that has the information I need.

whatis is handy utility that can tell you, in a brief one-liner, what a command does. Imagine that you want to know what cal does without having to view the man page. Just type this at the command prompt:

and you will see this in response:

Now that you know about the whatis command, I can let you in on a secret – there is a man command equivalent. To get this, we use the -f switch: man -f ...

Try it out. Type: whatis cal at a terminal prompt. Once that executes, type: man -f cal . The output of both commands will be identical.

whatis cal man f cal

The very name of the whereis command explains itself – it tells you where a program is within the filesystem. It will also tell you where the man page is stored too. Using cal as an example again, I type this at the prompt:

I will see this:

whereis cal

Look carefully at the reply. The answer is on one line, but it tells me two things:

/usr/bin/cal is where the cal program is and

/usr/share/man/man1/cal.1.gz is where the man page resides (I’m also clued into the fact that the man page is compressed, but not to worry – the man command knows how to decompress it on the fly)

whereis is PATH dependent; it can only tell you where files are if they are in your PATH environment.

You may be wondering if there is an equivalent man command for whereis . There isn’t one that will tell you where the executable file is, but there is a switch you can use that will tell you where the man page is. Using the date command in this example, if we type:

at a terminal prompt, we will see:

whereis date

We see that the date program is in the /usr/bin/ directory and the name and location of its man page is: /usr/share/man/man1/date.1.gz

The closest we can get man to act like whereis is to use the -w switch. We won’t get the location of the program, but we can at least get the location of the man page, like this:

and we will see this returned:

man w date 1

You know about whatis and whereis as well as a method to get the man command to do the same (or close) thing. I showed both ways for a couple of different reasons.

For years, I used whatis and whereis since they were in my training manuals. I didn’t learn about man -f ... and man -w ... until fairly recently. I’m sure I looked at the man page for man hundreds of times, but I never noticed the -f and -w switches. I was always looking at the man page for something else (i.e. man -k ... ). I concentrated only on what I needed to find and ignored the rest. Once I found the information I needed, I would leave the page and get the work done, not paying attention to some of the other gems the command had to offer.

This is okay since this is partly what the man pages are for: to help you get work done.

It wasn’t until I was recently showing someone how to use man pages, that I took the time to just read – “to see what else was possible” – and we took real notice of the information about what the man command’s -f and -w flags can do.

No matter how long you have been using Linux, or how experienced, there is always something new to learn.

The man pages will tell you what you may need to know to work through a certain task – but they also hold a lot more – enough to make you look like a magician – but only if you take the time to read.

If you spend some time and effort with the man pages, you will come out on top. Your proficiency of the man pages, will play a huge part in your mastery over Linux.

Bill has worked as a technician, programmer, and UNIX sysadmin. He is currently a continually caffeinated programmer who spends spare time building e-books for friends and restoring old text.

Complete Guide to Installing Linux on Chromebook

How to install and use conky in ubuntu linux, 11 ways to improve your privacy in online world, the ultimate guide to i3 customization in linux, getting started with markdown [beginner's guide], become a better linux user.

With the FOSS Weekly Newsletter, you learn useful Linux tips, discover applications, explore new distros and stay updated with the latest from Linux world

It's FOSS

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to It's FOSS.

Your link has expired.

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.

  • Embedded/IoT
  • Open Source
  • System Administration
  • Certification
  • What is Linux?

Linux.com

What you need to know to write man pages

Author: Peter Seebach

Why man pages?

Man pages, some assert, are obsolete. They’re old-fashioned, they don’t have a lot of neat modern features, and they’re written in nroff, an old and strange markup language.

All of this is true; nonetheless, man pages are the primary source of documentation for Unix-like systems, and have been for a long time. The man program is installed as standard on pretty much every Unix-like system ever shipped; competing formats may require users to install and learn new, unfamiliar tools. Man pages are well-suited to being printed without substantial effort; you don’t have to format them, you can just feed them to a printer. Furthermore, everyone knows how to use more to read files.

A user having trouble with a command is very likely to start with man command when looking for help. A man page that directs the user toward the format-of-the-week is unhelpful. Even if there’s a compelling reason to use another documentation format (such as better markup or support for hyperlinking) providing man pages is a good thing.

Nroff, troff, and macro packages

Man pages are written in a markup language, generally referred to as nroff; in fact, there are other processors for it (such as troff or groff), but it’s all the same language. Nroff is a markup language, but it’s a bit more primitive than HTML or SGML. On the other hand, it’s a macro language, so arbitrarily complex things can be done in it. There are sets of macros designed to support certain document types. The flag given to the traditional nroff program to specify a macro set is “-mNAME,” so many names are chosen to look natural with this; for instance, old-style man pages were written using the “tmac.an” set of macros, invoked with nroff -man .

There’s a newer set of macros called doc (tmac.doc) which come with groff, and a strange superset called mandoc (tmac.andoc) found on 4.4BSD systems which magically guesses whether you really want the old “man” macros or the new “doc” macros. We’ll cover the older macro set in passing, simply because it’s arcane and poorly documented, and it is therefore most likely that you will suddenly be tasked with writing in it. On systems using groff, there is usually a man page for these macros, installed under the name groff_man. The mdoc macros are probably a lot cleaner, but not everyone has them. Such is the price of progress.

In general, troff macros are introduced by starting a line with a period. For instance, an old man page might start out like this:

This takes a bit of interpretation. The TH macro introduces a manual page. TH probably stands for “title header.” It indicates the title of the man page (“C”), the section (“1”), and up to three extra flags; in this case, the “local” flag is used to indicate a local command, as opposed to a standard part of the system. (As a trivia point, on a sytem supporting the mandoc macro set, the TH macro may also load the “old” macros from the traditional man macro set.) The manual section is referenced elsewhere by referring to a command as name(section); for instance, ls(1), or printf(3).

In the doc macro set, you see introductions like this:

Macro names still start with a period at the beginning of a line. The Dd macro is the magic cookie the mandoc macros use to identify a file formatted using the doc macros. Note that the doc macros have specific sub-macros for the name and description of a command. In both macro sets, the name of the man page, and its section, are introduced very early on.

Pages within sections

The online manual is divided into sections. The exact scope of manual sections varies slightly from one system to another; a typical layout is this:

There are often additional subsections; for instance, programs installed in /usr/local might get man pages in section 1l. There may also be additional sections; NetBSD documents kernel internals in section 9, for instance.

Sections within a page

Confusingly, just as each manual page is in a “section” of the manual (e.g., section 1 for command-line utilities, or section 3 for library functions), each manual page consists of several named sections.

The SH macro (Sh in the doc macro set) introduces a section header. The exact set of section headers varies from one system to another. A reasonably complete set is NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS, EXAMPLES, ENVIRONMENT, FILES, CAVEATS, BUGS, RESTRICTIONS, NOTES, SEE ALSO, AUTHOR, and HISTORY.

The NAME section is the one used for the whatis database, and also for the man -k or apropos commands. It should have a one-line summary of what the thing described is — concise, but informative. Made-up words like “columnize” are probably bad style.

The SYNOPSIS section describes the usage of the command. In general, it should look very much like a traditional usage message. Here’s how it might look in source, with the old man macro set:

By convention, optional arguments are surrounded by square brackets. Options which take arguments are traditionally separated out and given meaningful names. The RB macro alternates between “roman” (plain) and bold styling. For instance, this line:

.RB [ -n spacing ]

prints a square bracket in plain font, the text “-n spacing” in bold, and then the closing bracket plain again. The backslash before the space is used to make the while “-n spacing” into a single argument; it would also work to write it this way:

.RB [ "-n spacing" ]

There is a related macro, BR, which also alternates between bold and roman, starting with bold.

The doc macro set improves substantially on this:

The Nm macro prints the name of the command; it doesn’t need to be repeated here, because an earlier macro saved it. The Op macro surrounds its arguments in square brackets, the Fl macro indicates flags, and the Ar macro indicates a named argument. This is a lot easier to write. The essential content remains the same.

The DESCRIPTION section gives a brief summary of what the man page describes; for instance, for a command or library function, it would be a summary of functionality. For a data structure or file format, it would be a summary of the structure of data and kind of data stored. Some man pages include descriptions of options in this section. Otherwise, they’re put in a separate section titled OPTIONS, which should start with a clear summary of what the manual page describes.

The formatting for options is itself a little weird. A typical OPTIONS section might look a bit like this:

The TP macro introduces an indented paragraph with a label, suitable for option lists. The B macro puts its arguments in bold print. With the doc macros, it’s formatted like this:

The list is introduced with a Bl macro, and ended with El. The It macro introduces an item, and the Fl macro introduces a flag, just as it did in the SYNOPSIS section.

Every option should be described. Avoid the mistake of not telling someone what the option really does; give some idea of when an option is useful and what its effects are. Merely saying that the “-f” option toggles the “foo” setting doesn’t help the reader.

Functions and command-line utilities should generally describe their return values or exit statuses; this is what the RETURN VALUE section is used for. This section is often omitted for command-line utilities that return 0 on success. Some man pages merge this into the DIAGNOSTICS section.

ERRORS and DIAGNOSTICS should describe any possible error indications a program or function can yield. By convention, programs have diagnostics, but functions have errors. Error messages should be explained in reasonable detail. For library functions or system calls, return codes should be described, and so should any changes that may be made to errno.

The ENVIRONMENT section should describe any way in which environment variables affect the behavior of a program. For instance, does it care about PATH, or TMPDIR? Many GNU utilities, for instance, follow the POSIX specification completely only when the environment variable POSIXLY_CORRECT has been set. This is where such behaviors should be documented.

Similarly, the FILES section should describe any files a program or function interacts with, especially any that are likely to be modified.

The SEE ALSO section should cross-reference other man pages that may be relevant to a user reading this man page. For instance, on NetBSD, the man page for ls(1) has SEE ALSO references for:

chflags(1), chmod(1), stat(2), getbsize(3), dir(5), symlink(7), sticky(8)

BUGS should include, not just crashing problems, but general limitations. For instance, the “c” utility described assumes an 80-column screen; while it tries to get the right value, it may fail, and this is a limitation, so it’s documented in BUGS. Related would be RESTRICTIONS, which are, to quote the pod2man man page, “bugs you don’t plan to fix.” Also related are CAVEATS, sometimes called WARNINGS, which are things to watch out for in how the program is designed, but which may not be what a user wants.

If present, a HISTORY section should describe where a command comes from; for instance, what Unix-like system, and what version, it first appeared in. The AUTHOR section should be used to identify the author or authors of the command.

The STANDARDS section should describe what standards, if any, something complies with. For instance, the manual page for printf(3) should say which version of the C standard the printf routine is compliant with. This section should also indicate whether any functionality provided is an extension to such standards; users may wish to avoid extensions when writing portable programs.

Most man pages benefit a lot from an EXAMPLES section. Whatever you’re documenting, show a couple of sample usages. For programs with many options, show how some common ones interact. [Editor’s note: This is a huge pet peeve of mine. Too few man pages provide any examples at all. Man writers, take this advice to heart!]

Finally, if you really have to say something but it doesn’t fit anywhere else, you can make a section called NOTES.

Weird macros

Some of the macros used are a bit confusing, or may have unusual limitations. For instance, on some systems, the RB and BR macros may take a maximum of 6 arguments. The same may apply to the BI, IB, IR, and RI macros (which alternate bold or roman text with italicized text). This can require special considerations when writing descriptions of C functions which take a number of arguments. One convention used in a lot of man pages is to have the function name and argument types in bold, and argument names in italics. This can result in needing to split a line up. For instance:

The “c” at the end of the first line tells the macro processor that the newline should not be treated as introducing whitespace between the last argument on the first line, and the first argument on the second line.

There are additional macros for some systems. For instance, on old SunOS systems, there’s an IX macro, used something like this:

.IX "mem2sz()" "" "makes sz from mem"

This was used in section 3 man pages to help populate an index; it doesn’t appear to have any effect in current man page systems. The pod2man utility generates these for section headings.

In addition to the font-selection macros, there are things you can do within a line. For instance, these two lines look the same:

The most likely ones to use are fB (bold), fI (italic), and fR (roman, or plain).

Alternatives to nroff

It’s pretty easy to imagine not wanting to write in nroff, especially not in the archaic man macro set. Some people swear off producing man pages at all. This is very annoying — don’t do it. Here are two alternatives to consider:

1. The doc macro set used with groff is widely available, and fairly friendly. 2. Perl’s POD documentation format converts reasonably well to manual pages.

Even if you’re stuck writing in the old man macro set, it’s still quite possible to produce good, readable, solid documentation. Don’t be afraid to copy some bits from existing manuals!

Many open source developers seem a little shy about documentation. Documentation can be a bit hard to write, and harder to write well. Putting out documentation sometimes seems like a way to ask people to waste your time with typo reports. It’s still worth it. Remember that bug reports for well-documented code will avoid the things you put in the CAVEATS section; furthermore, users will understand what you thought this widget did in the first place.

Don’t think of documentation as time taken away from developing a product; think of it as time spent figuring out what exactly you’re developing. Documentation is as much part of the final product as anything else; without documentation, a product is inaccessible to users.

RELATED ARTICLES MORE FROM AUTHOR

writing man pages

Bridging Design and Runtime Gaps: AsyncAPI in Event-Driven Architecture

Implementing opentelemetry natively in an event broker, innovation as a catalyst in telecommunications, linux 6.8 brings more sound hardware support for intel & amd, including the steam deck, opentofu is going ga.

Introduction

Manual pages are the canonical type of documentation for Unix systems. They are a bit arcane, but for a technology several decades old, they've held up quite well. The arcane bit is the markup language. This is a brief tutorial on writing good manual pages, at least for the typical cases. You'll be assumed to be familiar with reading manual pages already.

There are actually many ways to produce manual pages. The man (1) command needs a file using troff (1) formatting commands. troff is a typesetting system from the 1970s, written by the Unix developers. The troff file can be written manually, or generated from other formats, such as DocBook or Perl POD markup. On Linux, groff , the GNU implementation of troff , is used.

Conventions in manual pages

The important thing is that the formatted page follows manpage typesetting and other conventions, so that readers can efficiently extract the needed information from them. This bit is important: manpages are reference documentation, intended to quickly answer questions like "what is the purpose of this command" or "is there an option to show more information about files".

Here are some of the more important conventions:

  • the page should be short and to the point, without sacrificing clarity
  • use only the usual sections, in the usual order; see man-pages (7) for details
  • in particular, give a brief, readable summary of command line syntax in SYNOPSIS; if there are a lot of options, list them in the OPTIONS section
  • format the OPTIONS section so that options are in bold and their optional arguments are in italic, to improve fast skimming of the page
  • add examples for the common cases, not just special ones: you may think your program is obvious to use, but not everyone will find it so
  • don't forget ENVIRONMENT and FILES sections
  • the SEE ALSO section is also often useful to add

Example manual page

troff is a programming language for typesetting. It has a macro facility, and several macro packages have been written for writing manual pages. The most common of these is the -man one. Here's an example of a manpage, using that:

Save that in a file, called corrupt.1 , and then view it using the command man -l corrupt.1 . The output should be approximately like this (after a manual conversion to HTML to allow fonts):

CORRUPT(1) NAME     corrupt - modify files by randomly changing bits SYNOPSIS      corrupt [ -n BITS ] [ --bits BITS ] file ... DESCRIPTION      corrupt modifies files by toggling a randomly chosen bit. OPTIONS      -n , --bits = BITS         Set the number of bits to modify. Default is one bit. CORRUPT(1)

The title: .TH

Every manual page should start by specifying its title:

Here, CORRUPT is the name of the manual page, and 1 is the section in which the manual page belongs (section 1 for user commands, 2 for system calls, etc; see man-pages (7)` for the whole list).

You can additionally add three more pieces of information: the date of this revision of the manual page, where the program it documents came from, and the title of the whole book to which this page belongs to. I pretty much never use the optional ones: keeping the date up to date is a pain, and the others are not all that useful for my personal projects.

NAME section

The NAME section declares the name of command that is being documented. It also gives a very brief explanation of what it does. These two parts are separated by backslash-dash. That's a magic combination, the man command requires it.

This section is the source for data for man -k searches. That's a useful feature, and it is good to pay a bit of attention to making the brief explanation as useful as possible. However, do keep it brief; having it be broken on several lines looks bad. (It may be a sign of a badly designed program if the brief explanation is hard to write.)

The Debian and derivatives man implementation comes with lexgrog , which can verify that you get the NAME section right.

SYNOPSIS section

In this section, we give the user a summary of how the command line syntax of the program looks like. Font usage is important here, and carries information. All the parts that are in bold are things that the user is expected to write verbatim. Italic indicates values the user is expected to fill in. Normal font is used for syntax meta-characters: for the brackets that indicate optionality, and the ellipsis that indicates repetition.

Using fonts

Fonts can be set in two ways: either using the dot-commands, or the backslash-f escapes. The .B command (where the dot is at the beginning of a line) typesets the rest of the line in bold face. Similarly, .I typesets in italics (but terminals show that as underline), and .R in what troff calls the roman font, and the rest of us call the normal font. You can combine these, .BR typesets the first word on the line in bold, the second in normal font. The output will have no space between the words: .BR manpagename (7) would be the usual way to refer to another manual page. If a word has spaces in it, use double quotes: .B "far and away" for example.

Backslash-f escapes work anywhere on a line, and sometimes they're easier to use than the dot-commands. Their effect also does not end at the end of a line.

An unfortunate bit of arcane syntax is that dashes in options should be prefixed by backslashes. Thus, write \-\-bits , not just --bits . The Debian and Ubuntu implementation of man treats them the same, for terminal output, but this is not portable. Technically a naked - means a hyphen, whereas \- means a minus sign. Typographically these are distinct, and they are also distinct in Unicode. The typesetter is free to break a line at a hyphen, but not at a minus. For dashes in options, you should thus use minuses, but in normal text, for normal words, the hyphen.

DESCRIPTION section

The DESCRIPTION section describes what the program does, in more detail than the NAME section. There are no artificial size limits here, but it's still good style to avoid being long-winded. At the same time, it is perhaps best to not be quite as terse as the example.

Paragraphs and line structure

If you write more than one paragraph, start the other paragraphs with the .PP command. Do not just leave an empty line; this makes troff sometimes do the wrong thing. In fact, the manual page source should have no empty lines at all.

troff prefers you to start every sentence on a new line. This lets it typeset end-of-sentence whitespace better, when it produces output using proportional fonts. Also, this makes it easier to compare versions of a manpage with diff .

More about fonts

There are some more font conventions.

  • use bold for the command you are documenting
  • refer to other manual pages like this: man-pages (7) (easiest to achieve like this: .BR man-pages (7) )
  • filenames in italics

See man-pages (7) for more details.

OPTIONS section

Options are perhaps the most tedious part to document. It is also the part where proper formatting gives the most benefit to the reader.

First, there is the list structure. This is achieved with the .TP command, which is kind of magic. It takes the next line, and does not indent it, and then indents the rest of the paragraph. This gives the nice indented-paragraph style that makes it easy to quickly scan even a long list of options to find the right one.

That first, un-indented line describes the option, giving its name, and indicates if it gets an argument or not. If there are several names for an option (a long one, and a one-letter one, for example), they should be on the same line, separated by commas. The one-letter option name does not get the option argument, to keep things short.

Fonts are again used to clarify things:

  • the name of the option (including any dashes at the beginning) is in bold
  • any argument is in italic, but the equals sign (if any) is in normal font
  • the comma between options is in normal font

Comments in troff source

troff also supports comments: start a line with .\" and it is a comment. You can use them, for example, to add white space between descriptions of options in the OPTIONS section (remember, no empty lines).

Marking up examples

Most manual pages benefit from an EXAMPLES section, which shows basic use of the command. Sometimes advanced use is also useful to show, but basic use is almost always useful, because that's what people need most often.

Marking up examples of command line use is a bit tricky in manual pages. Here's an example of an example:

A few new troff commands:

  • .nf turns off paragraph filling mode: we don't want that for showing command lines.
  • .fi turns it back on.
  • .RS starts a relative margin indent: examples are more visually distinguishable if they're indented.
  • .RE ends the indent.
  • \\ puts a backslash in the output. Since troff uses backslash for fonts and other in-line commands, it needs to be doubled in the manual page source so that the output has one.

The backslash is used to show that the shell command line is broken into two physical lines, even if it is just one logical command. This is fairly commonly needed in manual pages: the page width is usually only 80 monospace characters wide, and with margins and indentations there's often only about 60 or 65 characters per line in the example. Command line examples therefore need to be wrapped, and it's better to be done explicitly in the manual page source than letting the man program do it.

Other ways of creating manual pages

This example used the -man macros for troff , since that is the most common way to write manual pages. However, they are admittedly arcane at this point in history. They're pretty easy to write, but not nearly as convenient as, say, Perl POD markup, or DocBook markup (see the refentry element). However, those other markup languages require conversion tools to produce a file that man can actually use, and the tools do not always properly follow the manpage formatting conventions.

For more information about writing manual pages, see:

  • man (7) , for the -man macros
  • mdoc (7) , for an alternative set of troff macros
  • man-pages (7) , for manpage structure and font conventions
  • Branden Robinson's Debconf5 talk

Other ways to create manual pages:

  • perlpod (1) , for Perl POD markup and conversion

Basics of Writing Unix Man Pages

On Unix-like systems, the documents that one views with the man command (known as “man pages”) are written in a markup language called “roff” (short for “run off”) that dates back to the pre-Unix days in the 1960’s. roff is technically a full-blown programming language with numerous features, but you only need to know a very small subset in order to produce most man pages. This article will describe that subset so that you can go on to write man pages for your own software.

Man pages, like most roff documents, use a roff macro package that defines a set of high-level commands. The macro package used by most man pages is, unsurprisingly, the man package, and that is what is covered here. Some man pages instead use the mdoc package, which originated in BSD. Modern versions of the man command use the mandoc package for processing man pages, which autodetects whether a file is written using man or mdoc and processes it accordingly.

roff Syntax

Document structure commands, font commands, additional escape sequences, select non-ascii characters, special ascii characters, man page conventions, manual sections, sections of a man page, other conventions, rendering a man page, a sample man page, further references.

A roff file is composed of a mixture of control lines — lines that start with a control character , usually a period or single-quote — and text lines — lines that do not.

Control lines are commands to roff (also known as requests ). They consist of a control character & a command name followed by some number of space-separated (not tab-separated!) arguments. To include spaces in an argument, either escape them with a backslash or enclose the entire argument in double-quotes; to use double-quotes inside an argument, write them as \(dq .

There may be any number of spaces & tabs (or none at all) between the control character and the command name, but the control character must be the first character in the line.

A line with just a period is ignored.

Text lines give the text that will be displayed. They can contain escape sequences , inline commands that start with backslashes.

Whitespace around escape sequences is significant and is not discarded. The syntax of an escape sequence allows roff to automatically determine where it ends; for example, escape sequences starting with \( are always followed by two more characters to complete the sequence, and so an escape sequence like \(em (em-dash) can be embedded in the middle of a word: foo\(embar becomes “foo—bar”.

To start a text line with a period, precede the period with either a backslash or the escape sequence \& .

To render a literal backslash in text, use the escape sequence \\ , \e , or \(rs .

A comment consists of a backslash and double quote ( \" ) and extends to the end of the line. A full-line comment can be formed by using the command .\" .

A single logical line can be broken across multiple physical lines by placing a backslash at the end of each physical line.

This must be the first non-comment command in a man page, and it must appear exactly once. It sets the page title (which is conventionally in all-caps) and section number for the man page (see “ Manual Sections ” below) to the given values, to be displayed in the form title(section) at the left & right sides of the header of the rendered manual page.

The remaining three arguments are optional. To omit an argument but still be able to specify an argument after it, write \& in place of the omitted argument.

If footer-middle is given, it will be rendered in the middle of the footer. This argument is usually set to the date the man page was written.

If footer-outside is given, it will be rendered on the left side of the footer. This is usually set to the version of the software being documented.

If header-middle is given, it will be rendered in the middle of the header. If it is omitted and section is a number from 1 to 9, certain versions of man will supply a default value.

Start an indented paragraph. The text argument, if given, will be used as the paragraph’s bullet/”tag”; this is usually the bullet escape sequence ( \(bu ), the em-dash escape sequence ( \(em ), or a number followed by a period. If no text argument is supplied, no bullet will be present, but the following paragraph will still be indented; this can be used to start a new indented paragraph after an initial indented paragraph created by .TP , .IP , or .HP .

If a numeric second argument is given, the paragraph will be indented by that many columns.

The following escape sequences can be used to change the font within a text line:

The following requests render an argument in a given font:

The following commands take multiple arguments and render them in alternating fonts. A word break/whitespace will be inserted before & after the arguments, but there will be no words breaks/whitespace inserted between the arguments. For example, the following:

will render as:

This is very styled text.

While modern groff lets you use these commands with any number of arguments, traditional implementations limit usage to six arguments; keep this in mind if you want to make your man page portable.

See grof_char(7) for the complete set of available character escape sequences.

When viewing a man page in the terminal, not all installations will display Unicode characters. On systems that display man pages in ASCII (which include macOS as of Big Sur), non-ASCII characters will be rendered as the visually closest ASCII character where possible.

Some output devices transform certain ASCII input characters to similar Unicode characters, so the following escape sequences can be used to ensure that the desired ASCII character appears in the rendered man page:

A backslash followed by a space produces a non-breaking space that remains at a fixed width when text is justified.

\~ produces a non-breaking space that nevertheless stretches like a normal inter-word space when justifying text.

\& produces a non-printable, zero-width character. It can be placed next to a token to deprive it of any special meaning; for example, it can be placed after a period at the end of an abbreviation to prevent it from being treated as the end of a sentence.

Each man page is traditionally placed into one of nine manual sections (not to be confused with the sections within a man page created by the .SH command; for that, see below). The pages for a given section are stored together, and the section number is also used as the file extension. The sections are:

Commands for use by general users

C system calls

C library functions, libraries, & headers

Devices, special files, and sockets

File formats

Miscellaneous

Commands for use by system administrators (including servers/daemons)

C kernel functions

The contents of a man page are divided into sections by the .SH command. Different sources give slightly different lists of the “standard” sections, but the most common, in roughly the order they should appear in a man page, are:

Gives the name of the man page and a short description of what it documents. This is usually considered the only mandatory section.

In order for a man page named “foobar” to be properly indexed by whatis and apropos , NAME must be the first section in the man page, and the .SH NAME line must be followed immediately by a line of the form foobar \- short description of foobar .

Shows the syntax for invoking a command or calling a C function.

The synopsis for a command usually follows the following conventions:

Text that should be entered as-is by the user (e.g., options and the name of the command) should be in bold , while placeholder text that should be replaced with some value by the user (e.g., command arguments) should be in italics/underlined .

Optional syntax elements (e.g., most options) should be enclosed in square brackets.

Alternative forms of a syntax element (e.g., the short and long form of an option) should be separated by whitespace and a vertical bar.

Syntax elements that can be repeated (e.g., arguments that can be given multiple times) are indicated by appending three periods ( ... ).

See A Sample Man Page below for an example of these rules in action.

Use \- instead of plain - for ASCII hyphens, e.g., in command-line options. Use plain - in hyphenated words.

Blank lines are discouraged, as they may not render correctly in all output formats. Use the .sp command instead to produce a blank line, or use .PP to start a new paragraph.

Each sentence should typically start on a new line.

Use only a single space between words in text; multiple spaces will not be collapsed into one when rendering.

To render a man page in the terminal the way that man would, run man -l path/to/man/page . (On macOS, you have to instead run mandoc -a path/to/man/page ). You may also want to pass the --warnings option ( -Wall for mandoc ) in order to catch any problematic syntax.

If your version of man does not support the -l option, you can instead run groff (GNU roff, the typical roff implementation on nearly all Unix machines nowadays) directly with groff -man -Tutf8 path/to/man/page | less -is .

Of course, groff can render to more than just terminals by changing the value passed to the -T option in the groff command. Values of interest include pdf , ps (for PostScript), and html ; these require the gropdf , grops , and grohtml commands, respectively, to be installed in order to work.

[ Download this file ]

groff(7) man page: < https://man7.org/linux/man-pages/man7/groff.7.html >

groff_char(7) man page: < https://man7.org/linux/man-pages/man7/groff_char.7.html >

groff_man(7) man page: < https://man7.org/linux/man-pages/man7/groff_man.7.html >

man-pages(7) man page: < https://man7.org/linux/man-pages/man7/man-pages.7.html >

  • Programming

Writing man Pages Using groff

Two of the original text processing systems found on Unix systems are troff and nroff, developed at Bell Labs for the original implementation of Unix (in fact, the development of Unix itself was spurred, in part, to support such a text-processing system). The first version of this text processor was called roff (for “runoff”); later came troff, which generated output for a particular typesetter in use at the time. nroff was a later version that became the standard text processor on Unix systems everywhere. groff is GNU's implementation of nroff and troff that is used on Linux systems. It includes several extended features and drivers for a number of printing devices.

groff is capable of producing documents, articles, and books, much in the same vein as other text-formatting systems, such as TeX. However, groff (as well as the original nroff) has one intrinsic feature that is absent from TeX and variants: the ability to produce plain-ASCII output. While other systems are great for producing documents to be printed, groff is able to produce plain ASCII to be viewed online (or printed directly as plain text on even the simplest of printers). If you're going to be producing documentation to be viewed online, as well as in printed form, groff may be the way to go (although there are alternatives, such as Texinfo, Lametex, and other tools).

groff also has the benefit of being much smaller than TeX; it requires fewer support files and executables than even a minimal TeX distribution.

One special application of groff is to format Unix man pages. If you're a Unix programmer, you'll eventually need to write and produce man pages of some kind. In this article, we'll introduce the use of groff through the writing of a short man page.

As with TeX, groff uses a particular text-formatting language to describe how to process the text. This language is slightly more cryptic than systems such as TeX, but also less verbose. In addition, groff provides several macro packages that are used on top of the basic formatter; these macro packages are tailored to a particular type of document. For example, the mgs macros are an ideal choice for writing articles and papers, while the man macros are used for man pages.

Writing man pages with groff is actually quite simple. For your man page to look like others, you need to follow several conventions in the source, which are presented below. In this example, we'll write a man page for a mythical command coffee that controls your networked coffee machine in various ways.

Using any text editor, enter the source from Listing 1 and save the result as coffee.man . Do not enter the line numbers at the beginning of each line; those are used only for reference later in the article.

Listing 1. Example man Page Source File

Don't let the amount of obscurity in this source file frighten you. It helps to know that the character sequences \fB , \fI , and \fR are used to change the font to boldface, italics, and roman type, respectively. \fP sets the font to the one previously selected.

Other groff requests appear on lines beginning with a dot ( . ). On line 1, we see that the .TH request is used to set the title of the man page to COFFEE , the man section to 1 , and the date of the last man page revision. (Recall that man section 1 is used for user commands, section 2 is for system calls, and so forth. The man man command details each section number.) On line 2, the .SH request is used to start a section, entitled NAME . Note that almost all Unix man pages use the section progression NAME , SYNOPSIS , DESCRIPTION , FILES , SEE ALSO , NOTES , AUTHOR , and BUGS , with extra, optional sections as needed. This is just a convention used when writing man pages and isn't enforced by the software at all.

Line 3 gives the name of the command and a short description, after a dash ( [mi] ). You should use this format for the NAME section so that your man page can be added to the whatis database used by the man -k and apropos commands.

On lines 4—6 we give the synopsis of the command syntax for coffee. Note that italic type \fI ... \fP is used to denote parameters on the command line, and that optional arguments are enclosed in square brackets.

Lines 7—12 give a brief description of the command. Boldface type is generally used to denote program and file names. On line 13, a subsection named Options is started with the .SS request. Following this on lines 14—25 is a list of options, presented using a tagged list. Each item in the tagged list is marked with the .TP request; the line after .TP is the tag, after which follows the item text itself. For example, the source on lines 14—16:

will appear as the following in the output:

You should document each command-line option for your program in this way.

Lines 26—29 make up the FILES section of the man page, which describes any files that the command might use to do its work. A tagged list using the .TP request is used for this as well.

On lines 30—31, the SEE ALSO section is given, which provides cross-references to other man pages of note. Notice that the string <\#34>SEE ALSO<\#34> following the .SH request on line 30 is in quotes; this is because .SH uses the first whitespace-delimited argument as the section title. Therefore any section titles that are more than one word need to be enclosed in quotes to make up a single argument. Finally, on lines 32—34, the BUGS section is presented.

In order to format this man page and view it on your screen, you can use the command:

The -Tascii option tells groff to produce plain-ASCII output; -man tells groff to use the man page macro set. If all goes well, the man page should be displayed as shown in Figure 1.

Figure 1. Formatted man Page

As mentioned before, groff is capable of producing other types of output. Using the -Tps option in place of -Tascii will produce PostScript output that you can save to a file, view with GhostView, or print on a PostScript printer. -Tdvi will produce device-independent .dvi output similar to that produced by TeX.

If you wish to make the man page available for others to view on your system, you need to install the groff source in a directory that is present in other users' MANPATH . The location for standard man pages is /usr/man. The source for section 1 man pages should therefore go in /usr/man/man1. Therefore, the command:

will install this man page in /usr/man for all to use (note the use of the .1 file name extension, instead of .man ). When man coffee is subsequently invoked, the man page will be automatically reformatted, and the viewable text saved in /usr/man/cat1/coffee.1.Z.

If you can't copy man page sources directly to /usr/man (say, because you're not the system administrator), you can create your own man page directory tree and add it to your MANPATH . The MANPATH environment variable is of the same format as PATH ; for example, to add the directory /home/mdw/man to MANPATH just use:

There are many other options and formatting commands available for groff and the man page macros. The best way to find out about these is to look at the files in /usr/lib/groff; the tmac directory contains the macro files themselves, which often contain some documentation on the commands they provide. To use a particular macro set with groff, just use the -m macro option. For example, to use the mgs macros, use:

The man pages for groff describe this option in more detail.

Unfortunately, the macro sets provided with groff are not well-documented. There are section 7 man pages for some of them; for example, man 7 groff_mm will tell you about the mm macro set. However, this documentation usually only covers the differences and new features in the groff implementation, which assumes you have access to the man pages for the original nroff/troff macro sets (known as DWB—the Documentor's Work Bench). The best source of information may be a book on using nroff/troff which covers these classic macro sets in detail. For more about writing man pages, you can always look at the man page sources (in /usr/man) and determine what they do by comparing the formatted output with the source.

This article is adapted from Running Linux, by Matt Welsh and Lar Kaufman, published by O'Reilly and Associates (ISBN 1-56592-100-3). Among other things, this book includes tutorials of various text-formatting systems used under Linux. Information in this issue of Linux Journal as well as Running Linux should provide a good head-start on using the many text tools available for the system.

Good luck, and happy documenting!

Matt Welsh ( [email protected] ) is a student and systems programmer at Cornell University, working with the Robotics and Vision Laboratory on projects dealing with real-time machine vision.

Firstwave Cloud

Create man page in Linux with examples (sample man page template)

man page template in linux. create man page. man page with examples. create man page for custom script to check man script. sample man page template. how to write man page in Linux. Man page example. Man page template. Man Page editor. man command in linux. tutorial on how to write man page and how to create man page with examples. groff man command.

How to create man page in Linux with examples (Sample man page template)

It is possible that in your organisation you have written a new tool for which you also need to create man page or write man page using any man page template. As man page are the single place where you can find all the details regarding the respective tool. man is the system's manual pager. Each page argument given to man is normally the name of a program, utility or function.

So in this article I will share the steps to create man page with example in Linux with a sample man page template.

Where to find?

As an end user we use man to access the man page of the respective tool but most of us are unaware of the location of the man page. Now the ideal and default location of man pages of all the system tools are available under

Most which I have used were available under

But if you plan to create man page, you should keep the file under

To get the complete list of locations you can check /etc/man_db.conf . Below is a small snippet, for complete list please check the original man_db.conf file.

How to create man page?

To create man page (assuming from scratch), you can start by creating a new file under /usr/local/man/man1 .

For the sake of this article I will create man page for a dummy tool (test_script). If I try to access the man page of test_script

As we have not created one for this tool, we get this error. To create man page let us create an empty file.

Now you should be able to access the man page for test_script . Since currently the text file is empty, we see blank output.

Supported Macros

Below are the list of supported Macros:

Man Page Template and Example

The groff (GNU Troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output such as man page

You can use any editor to create man page such as vim or nano. To demonstrate this article I will create man page under /usr/local/man/man1 .

Below I have created a man page template. Here I have tried to use various macros which can help you choose between various options to help you create man page of your own

Man command in Linux

Above using the template we wrote our man page example for test script. To access the man page which we created using our man page template you can use man scriptname from the terminal.

How to Install?

To install man page you can leave the file test_script.1 under /usr/local/man/man1/

You can also archive this file into gzip format

Next a new archive will be created with gzip extension

How to create user specific man page?

To create a user specific man page you can choose a separate folder which is accessible only to the respective user. For example I have a user deepak and I will place the man page file under the home directory of this user.

So I will create a new structure under /home/deepak

Next move the man page of test_script which we placed under /usr/local/man/man1 . We are moving the file as we want only deepak user to access this man page.

Switch user to deepak

Next we must define the path of the man page location for deepak user using MANPATH . Check if there are any existing path defined for MANPATH .

Since there are no paths defined we will add the new path for MANPATH

If the user was already using MANPATH var then you can append the new path using below command

So this will append the new man page path to MANPATH variable

Next verify your variable content

So this should do the trick and now we should be able to access the man page of test_script

But if you try to access the same using root

If you wish to allow root user to access man page for test_script then add /home/deepak/man/man1 path to root user's shell for MANPATH variable

Lastly I hope the steps from the article to create man page using man page template with examples on Linux was helpful. So, let me know your suggestions and feedback using the comment section.

Deepak Prasad

He is the founder of GoLinuxCloud and brings over a decade of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels in various domains, from development to DevOps, Networking, and Security, ensuring robust and efficient solutions for diverse projects. You can reach out to him on his LinkedIn profile or join on Facebook page.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to [email protected]

Thank You for your support!!

Leave a Comment Cancel reply

Save my name and email in this browser for the next time I comment.

Notify me via e-mail if anyone answers my comment.

write(2) — Linux manual page

Name         top, library         top, synopsis         top, description         top, return value         top, errors         top, standards         top, history         top, notes         top, bugs         top, see also         top.

Pages that refer to this page: ps(1) ,  pv(1) ,  strace(1) ,  telnet-probe(1) ,  close(2) ,  epoll_ctl(2) ,  eventfd(2) ,  fcntl(2) ,  fsync(2) ,  getpeername(2) ,  getrlimit(2) ,  io_uring_enter2(2) ,  io_uring_enter(2) ,  lseek(2) ,  memfd_create(2) ,  mmap(2) ,  open(2) ,  pipe(2) ,  pread(2) ,  read(2) ,  readv(2) ,  seccomp(2) ,  select(2) ,  select_tut(2) ,  send(2) ,  sendfile(2) ,  socket(2) ,  socketpair(2) ,  sync(2) ,  syscalls(2) ,  aio_error(3) ,  aio_return(3) ,  aio_write(3) ,  curs_print(3x) ,  dbopen(3) ,  fclose(3) ,  fflush(3) ,  fgetc(3) ,  fopen(3) ,  fread(3) ,  gets(3) ,  io_uring_prep_write(3) ,  io_uring_prep_writev2(3) ,  io_uring_prep_writev(3) ,  libexpect(3) ,  mkfifo(3) ,  mpool(3) ,  puts(3) ,  size_t(3type) ,  stdio(3) ,  xdr(3) ,  xfsctl(3) ,  dsp56k(4) ,  fuse(4) ,  lirc(4) ,  st(4) ,  proc(5) ,  systemd.exec(5) ,  aio(7) ,  cgroups(7) ,  cpuset(7) ,  epoll(7) ,  fanotify(7) ,  inode(7) ,  inotify(7) ,  landlock(7) ,  pipe(7) ,  sched(7) ,  signal(7) ,  signal-safety(7) ,  socket(7) ,  spufs(7) ,  tcp(7) ,  time_namespaces(7) ,  udp(7) ,  user_namespaces(7) ,  vsock(7) ,  x25(7) ,  fsfreeze(8) ,  netsniff-ng(8) ,  wipefs(8) ,  xfs_io(8)

Stack Exchange Network

Stack Exchange network consists of 183 Q&A communities including Stack Overflow , the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

How do I write man pages? [closed]

How do I write a man page?

Where can I find a reference of all formatting codes?

Are there any good tutorials on writing man pages?

What is the most convenient way to write a man page? Should I enter it directly in a text editor? Are there WYSIWYG editors? Or should I write it in a different format and then convert?

What rules should a good man page follow?

  • documentation

HopelessN00b's user avatar

  • This question appears to be too broad. It has only succeeded in attracting a bunch of link-only answers and a few unsupported opinions. –  200_success Oct 15, 2014 at 8:57
  • man man , man groff . –  Jenny D Oct 15, 2014 at 9:19

5 Answers 5

Here are a few web pages that will help get you started:

  • Creating and Formatting Man Pages
  • Creating Your Own MAN Page
  • Create Your own Man Page
  • How to Write a Man Page
  • What you need to know to write man pages

A couple of useful tools:

Dennis Williamson's user avatar

There are tools for writing man pages that bypass troff formatting. manpages are a small, well delimited language and easy to target.

Two popular tools are:

  • xmltoman , a small and well structured xml language that can generate manpages and html. It is used by Lennart Poettering's projects, syrep and pulseaudio for example .
  • asciidoc , used by git for example .

yodl and zoem seem to be other nice formats in this space.

All in all I'd recommend xmltoman because it's a very manpage specific dsl that will guide you closely.

Tobu's user avatar

  • "dsl" == "domain specific language"? –  Dennis Williamson Feb 4, 2010 at 16:23
  • yes (da. si. 15 chars.) –  Tobu Feb 4, 2010 at 16:46
  • 1 Another good option is ronn , which reads the more-widely-used Markdown text markup language. –  poolie Aug 10, 2013 at 6:07

I have written a rather extensive blog article about the topic, which you can find here:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

Igor's user avatar

  • 4 It'd be helpful if you could at least summarize the article here -- links alone are worthless once the linked page inevitably moves or disappears. –  Caleb Jun 26, 2013 at 16:09
  • I do not agree with Caleb. This is the web. The web is based on links, and stackexchange does not carry any special exception to this. Copying content is counterproductive. Whatever bad thing can happen to that page or document can also happen to this one. We cannot hoard scraped copies of all content just because the rest of the web might disappear. (Leave that job to sites like the wayback machine). –  Kaz Oct 9, 2013 at 21:23
  • Kaz, you may not agree, but Caleb's comment is definitely ServerFault best-practice. –  MadHatter Oct 15, 2014 at 8:03

I do not know of any IDEs or tutorials, but you can start by copying an existing man page and modify it to suit your needs.

For a reference of the groff language with MAN macros (which is what is used by a man page) consult the groff_man man page, or read it online here

Dan Andreatta's user avatar

Take a look at the ronn project . Its a markdown to man page generator. It can also generate the man pages in html, like this .

I like the idea of writing all my software documentation in one format. Markdown IMO is a good choice

Bruno Polaco's user avatar

Not the answer you're looking for? Browse other questions tagged documentation .

  • The Overflow Blog
  • It’s RAG time for LLMs that need a source of truth
  • In Rust we trust? White House Office urges memory safety
  • Featured on Meta
  • Changing how community leadership works on Stack Exchange: a proposal and...
  • Our partnership with Google and commitment to socially responsible AI

Hot Network Questions

  • Could Apollo have survived the lander toppling over?
  • within five to six days
  • How is Riddlemaster Sphinx's identifier greater than the number of cards in the set?
  • Is it bad practice for audio inputs and outputs to share a common ground?
  • Chromatic number of the infinite Erdős–Hajnal shift-graph
  • A class both derives from and its first member has type deriving from the same base class. Is the class standard-layout?
  • Can I follow this recipe?
  • Code for an application that replaces semicolons in a file with Greek question marks
  • Is the notion "If a polynomial has small coefficients (relative to the exponent), then it has small roots" true?
  • Regular Curve on Parallel Lines in Illustrator
  • Can mountains form in rings?
  • Converting to a scalar pure function without getting the warning messages
  • Are there any Scriptures that describe Maha-Sadashiva, The 25-headed form of Shiva?
  • Does doing 4 vs 3 substantive chapters in a US PhD come across as a "higher quality" dissertation?
  • DOS: How do I type an ANSI escape sequence?
  • When a bus goes around a corner, does the person sitting at the back travel further distance than the person sitting at the front?
  • Search and replace regular expressions
  • Is this KML file measured in degrees?
  • point-to-point or broadcast network : concrete case
  • Location of Soul
  • Substitute solution into ODE to verify it holds
  • How can I union two lists in the given way?
  • What are "Himalaya Wines", in the "Last Chronicle of Barset"?
  • What kind of drain pipe appears to be clay?

writing man pages

  • Writing man pages
  • Edit on GitHub

Writing man pages 

Command line tools should be shipped with man pages.

To make fullest use of all features, man pages should be written in their native markup language, mdoc.

However, this has a quite steep learning curve, so the following can be used to get started quickly.

One way to create man pages from Markdown is by using pandoc and the template from https://github.com/pragmaticlinuxblog/pandocmanpage.

To convert Markdown to man:

To convert man to txt:

Order of sections 

For more information, see man mdoc .

PROGNAME section

DESCRIPTION

IMPLEMENTATION NOTES

RETURN VALUES

ENVIRONMENT

EXIT STATUS

DIAGNOSTICS

SECURITY CONSIDERATIONS

bug

DESCRIPTION

Powered by the Ubuntu Manpage Repository , file bugs in Launchpad

Guido likes Linux because it is a very flexible and offers much more possibilities than any other operating system.

Traditional Linux command line utilities have always been documented in man-pages. A simple man commandname will tell you how to use the command.

The advantage of man-pages over other forms of documentation is that

  • They can be viewed within seconds in any Linux terminal
  • They can easily be converted to other formats: HTML, PDF, Postscript, Text,...
  • Man pages can not only be viewed in terminal windows but also other programs like konqueror (simply type: man:commandname)

All man-page formatter macros are documented in the man-page called groff_man(7) ( Click here to view a html version of the groff_man(7) page ). I will not explain the macros here instead suggest to read the groff_man page. The groff_man page is very detailed and contains all you need to know.

  • Man-page HOWTO
  • groff_man(7), man-page macros

Talkback form for this article

2003-09-14, generated by lfparser version 2.38

  • SysTutorials
  • Linux Manuals

man-pages (7) - Linux Manuals

Man-pages: conventions for writing linux man pages.

Command to display man-pages manual in Linux: $ man 7 man-pages

Pages related to man-pages

  • man (7) - macros to format man pages
  • mailaddr (7) - mail addressing description
  • maildirquota (7) - voluntary Maildir quotas
  • maildropex (7) - maildrop filtering language examples
  • maildropfilter (7) - maildrop's filtering language
  • maildropgdbm (7) - GDBM/DB support in maildrop

logo

DESCRIPTION

Throughout the UNIX manual pages, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.

GETTING STARTED

Title macros, predefined strings, diagnostics.

  • FORMATTING WITH GROFF, TROFF AND NROFF

TROFF IDIOSYNCRASIES

Macro usage.

In general, troff (1) macros accept up to nine arguments, any extra arguments are ignored. Most macros in -mdoc accept nine arguments and, in limited cases, arguments may be continued or extended on the next line (See Sx Extensions ) . A few macros handle quoted arguments (see Sx Passing Space Characters in an Argument below).

Most of the -mdoc general text domain and manual domain macros are special in that their argument lists are parsed for callable macro names. This means an argument on the argument list which matches a general text or manual domain macro name and is determined to be callable will be executed or called when it is processed. In this case, the argument, although the name of a macro, is not preceded by a `.' (dot). It is in this manner that many macros are nested; for example the option macro, `.[,] ' may call the flag and argument macros, `- ' and ` file ... ' to specify an optional flag with an argument:

To prevent a two character string from being interpreted as a macro name, precede the string with the escape sequence `\&' :

Here the strings `- ' and ` file ... ' are not interpreted as macros. Macros whose argument lists are parsed for callable arguments are referred to as parsed and macros which may be called from an argument list are referred to as callable throughout this document and in the companion quick reference manual mdoc (7). This is a technical faux pas as almost all of the macros in -mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, the term parsed has been used.

Passing Space Characters in an Argument

There are two possible ways to pass an argument which contains an embedded space. Implementation note Unfortunately, the most convenient way of passing spaces in between quotes by reassigning individual arguments before parsing was fairly expensive speed wise and space wise to implement in all the macros for AT&T troff. It is not expensive for groff but for the sake of portability, has been limited to the following macros which need it the most:

One way of passing a string containing blank spaces is to use the hard or unpaddable space character `\  ,' that is, a blank space preceded by the escape character `\' This method may be used with any macro but has the side effect of interfering with the adjustment of text over the length of a line. Troff sees the hard space as if it were any other printable character and cannot split the string into blank or newline separated pieces as one would expect. The method is useful for strings which are not expected to overlap a line boundary. For example:

If the `\' or quotes were omitted, `.Fn would ' see three arguments and the result would be:

Fn fetch char *str

For an example of what happens when the parameter list overlaps a newline boundary, see the Sx BUGS section.

Trailing Blank Space Characters

Escaping special characters, the anatomy of a man page, a manual page template.

.\" The following requests are required for all man pages. .Dd Month day, year .Os OPERATING_SYSTEM [version/release] .Dt DOCUMENT_TITLE [section number] [volume] .Sh NAME .Nm name .Nd one line description of name .Sh SYNOPSIS .Sh DESCRIPTION .\" The following requests should be uncommented and .\" used where appropriate. This next request is .\" for sections 2 and 3 function return values only. .\" .Sh RETURN VALUE .\" This next request is for sections 1, 6, 7 & 8 only .\" .Sh ENVIRONMENT .\" .Sh FILES .\" .Sh EXAMPLES .\" This next request is for sections 1, 6, 7 & 8 only .\" (command return values (to shell) and .\" fprintf/stderr type diagnostics) .\" .Sh DIAGNOSTICS .\" The next request is for sections 2 and 3 error .\" and signal handling only. .\" .Sh ERRORS .\" .Sh SEE ALSO .\" .Sh CONFORMING TO .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh BUGS

The first items in the template are the macros ( ., ., . ) the document date, the operating system the man page or subject source is developed or modified for, and the man page title ( in uppercase ) along with the section of the manual the page belongs in. These macros identify the page, and are discussed below in Sx TITLE MACROS .

The remaining items in the template are section headers ( .

The default volume labeling is URM for sections 1, 6, and 7; SMM for section 8; PRM for sections 2, 3, 4, and 5.

.FreeBSD 2.2

or for a locally produced set

.CS Department

The Berkeley default, `.without ' an argument, has been defined as BSD in the site-specific file /usr/share/tmac/mdoc/doc-common It really should default to LOCAL Note, if the `.macro ' is not present, the bottom left corner of the page will be ugly.

January 25, 1989

INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS

What's in a name....

In the first case, troff (1) macros are themselves a type of command; the general syntax for a troff command is:

.Va argument1 argument2 ... argument9

The `. is ' a macro command or request, and anything following it is an argument to be processed. In the second case, the description of a UNIX command using the content macros is a bit more involved; a typical Sx SYNOPSIS command line might be displayed as:

filter [- flag ] infile outfile

Here, filter is the command name and the bracketed string - flag is a flag argument designated as optional by the option brackets. In -mdoc terms, infile and outfile are called arguments The macros which formatted the above example:

.Nm filter .Op Fl flag .Ar infile outfile

In the third case, discussion of commands and command syntax includes both examples above, but may add more detail. The arguments infile and outfile from the example above might be referred to as operands or file arguments Some command-line argument lists are quite long:

Here one might talk about the command make and qualify the argument makefile as an argument to the flag, - f or discuss the optional file operand target In the verbal context, such detail can prevent confusion, however the -mdoc package does not have a macro for an argument to a flag. Instead the ` file ... ' argument macro is used for an operand or file argument like target as well as an argument to a flag like variable The make command line was produced from:

.Nm make .Op Fl eiknqrstv .Op Fl D Ar variable .Op Fl d Ar flags .Op Fl f Ar makefile .Op Fl I Ar directory .Op Fl j Ar max_jobs .Op Ar variable=value .Bk -words .Op Ar target ... .Ek

The `.and ' `.macros ' are explained in Sx Keeps .

General Syntax

. sptr, ptr),

The result is:

sptr, ptr),

The punctuation is not recognized and all is output in the literal font. If the punctuation is separated by a leading white space:

. sptr , ptr ) ,

The punctuation is now recognized and is output in the default font distinguishing it from the strings in literal font.

To remove the special meaning from a punctuation character escape it with `\&' Troff is limited as a macro language, and has difficulty when presented with a string containing a member of the mathematical, logical or quotation set:

{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

The problem is that troff may assume it is supposed to actually perform the operation or evaluation suggested by the characters. To prevent the accidental evaluation of these characters, escape them with `\&' Typical syntax is shown in the first content macro displayed below, `. '

MANUAL DOMAIN

Address macro.

Usage: . address ... [ .,:;()[]?! ]

It is an error to call `. without ' arguments. `. is ' callable by other macros and is parsed.

Author Name

Usage: .An author_name [ .,:;()[]?! ]

The `.An macro ' is parsed and is callable. It is an error to call `.An without ' any arguments.

Argument Macro

Usage: . argument ... [ .,:;()[]?! ]

If `. file ... ' is called without arguments, ` file ... ' is assumed. The `. file ... ' macro is parsed and is callable.

Configuration Declaration (section four only)

Command modifier, defined variables.

Usage: . defined_variable ... [ .,:;()[]?! ]

It is an error to call `. without ' arguments. `. is ' parsed and is callable.

Errno's (Section two only)

Usage: .Er ERRNOTYPE ... [ .,:;()[]?! ]

It is an error to call `.Er without ' arguments. The `.Er macro ' is parsed and is callable.

Environment Variables

It is an error to call `. without ' arguments. The `. macro ' is parsed and is callable.

Function Argument

Usage: .Fa function_argument ... [ .,:;()[]?! ]

It is an error to call `.Fa without ' arguments. `.Fa is ' parsed and is callable.

Function Declaration

Usage: .Fd include_file (or defined variable)

In the Sx SYNOPSIS section a `.Fd request ' causes a line break if a function has already been presented and a break has not occurred. This leaves a nice vertical space in between the previous function call and the declaration for the next function.

Usage: .- argument ... [ .,:;()[]?! ]

The `.- ' macro without any arguments results in a dash representing stdin / stdout . Note that giving `.- ' a single dash, will result in two dashes. The `.- ' macro is parsed and is callable.

Functions (library routines)

It is an error to call `.Fn without ' any arguments. The `.Fn macro ' is parsed and is callable, note that any call to another macro signals the end of the `.Fn call ' (it will close-parenthesis at that point).

For functions that have more than eight parameters (and this is rare), the macros `.Fo (function ' open) and `.Fc (function ' close) may be used with `.Fa (function ' argument) to get around the limitation. For example:

.Fo "int res_mkquery" .Fa "int op" .Fa "char *dname" .Fa "int class" .Fa "int type" .Fa "char *data" .Fa "int datalen" .Fa "struct rrec *newrr" .Fa "char *buf" .Fa "int buflen" .Fc
Fo int res_mkquery Fa int op Fa char *dname Fa int class Fa int type Fa char *data Fa int datalen Fa struct rrec *newrr Fa char *buf Fa int buflen Fc

The `.Fo and ' `.Fc macros ' are parsed and are callable. In the Sx SYNOPSIS section, the function will always begin at the beginning of line. If there is more than one function presented in the Sx SYNOPSIS section and a function type has not been given, a line break will occur, leaving a nice vertical space between the current function name and the one prior. At the moment, `.Fn does ' not check its word boundaries against troff line lengths and may split across a newline ungracefully. This will be fixed in the near future.

Function Type

Usage: .Ft type ... [ .,:;()[]?! ]

The `.Ft request ' is not callable by other macros.

Interactive Commands

The `. man mdoc.samples ' macro is parsed and is callable.

Usage: . [options ... [ .,:;()[]?! ]]

The `.] ' and `.[macros: '

.Oo .Op Fl k Ar kilobytes .Op Fl i Ar interval .Op Fl c Ar count .Oc

Produce: [[- k kilobytes ] [- i interval ] [- c count ] ]

The macros `.[,] ' `.] ' and `.[are ' parsed and are callable.

Usage: .pathname [ .,:;()[]?! ]

The `.macro ' is parsed and is callable.

Usage: . variable ... [ .,:;()[]?! ]

It is an error to call `. without ' any arguments. The `. macro ' is parsed and is callable.

Manual Page Cross References

Usage: .man_page[1,...,8][ .,:;()[]?! ]

The `.macro ' is parsed and is callable. It is an error to call `.without ' any arguments.

GENERAL TEXT DOMAIN

At&t macro.

Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... [ .,:;()[]?! ]

The `.AT&T System ' macro is not parsed and not callable It accepts at most two arguments.

Usage: .BSD [Version/release] ... [ .,:;()[]?! ]

The `.BSD macro ' is parsed and is callable.

FreeBSD Macro

Usage: .Fx Version.release ... [ .,:;()[]?! ]

The `.Fx macro ' is not parsed and not callable It accepts at most two arguments.

Usage: .UNIX

The `.UNIX ' macro is parsed and is callable.

Enclosure and Quoting Macros

Quote          Close    Open     Function          Result .Aq      .Ac       .Ao       Angle Bracket Enclosure<string> .Bq       .Bc       .Bo       Bracket Enclosure         [string] .Dq       .Dc       .Do       Double Quote      ``string''          .Ec       .Eo       Enclose String (in XX)    XXstringXX .Pq       .Pc       .Po       Parenthesis Enclosure     (string) .Ql                         Quoted Literal    `st' or string .Qq       .Qc       .Qo       Straight Double Quote     "string" .Sq       .Sc       .So       Single Quote      `string'

Except for the irregular macros noted below, all of the quoting macros are parsed and callable. All handle punctuation properly, as long as it is presented one character at a time and separated by spaces. The quoting macros examine opening and closing punctuation to determine whether it comes before or after the enclosing string This makes some nesting possible.

The `. (no ' space) macro performs the analogous suffix function.

Examples of quoting:

For a good example of nested enclosure macros, see the `.[option] ' macro. It was created from the same underlying enclosure macros as those presented in the list above. The `. ' and `. ' extended argument list macros were also built from the same underlying routines and are a good example of -mdoc macro usage at its worst.

No-[or Normal Text Macro]

Space macro.

Note: the `. macro ' always invokes the `. macro ' after eliminating the space unless another macro name follows it. The macro `. is ' parsed and is callable.

Section Cross References

References and citations.

The macros beginning with `%' are not callable, and are parsed only for the trade name macro which returns to its caller. (And not very predictably at the moment either.) The purpose is to allow trade names to be pretty printed in troffNs/NsXrditroff output.

Return Values

Usage: .Rv [-std function]

`.Rv -std ' atexit will generate the following text:

Rv -std atexit

The - std option is valid only for manual page sections 2 and 3.

Trade Names (or Acronyms and Type Names)

Usage: . symbol ... [ .,:;()[]?! ]

The `. macro ' is parsed and is callable by other macros.

Extended Arguments

Here is an example of `. ' using the space mode macro to turn spacing off:

.Sm off .It Xo Sy I Ar operation .No \en Ar count No \en .Xc .Sm on
I operation \n count \n
.Sm off .It Cm S No / Ar old_pattern Xo .No / Ar new_pattern .No / Op Cm g .Xc .Sm on
S / old_pattern / new_pattern / [ g ]
.It Xo .Ic .ifndef .Oo \&! Oc Ns Ar variable .Op Ar operator variable ... .Xc
.ifndef [! variable ] [ operator variable ... ]

PAGE STRUCTURE DOMAIN

Section headers.

cat [- benstuv ] [- ] file ...

The following macros were used:

. [- benstuv ]

Note The macros `.[,] ' `.- ' and `. file ... ' recognize the pipe bar character `|' so a command line such as:

". [- a | -b ]

will not go orbital. Troff normally interprets a | as a special operator. See Sx PREDEFINED STRINGS for a usable | character in other situations.

' begin-list, `.

' end-list macros are used (see Sx Lists and Columns below).

The following `.

ENVIRONMENT

ls (1), ps (1), group (5), passwd (5).

At this time refer (1) style references are not accommodated. .Sh CONFORMING TO If the command, library function or file adheres to a specific implementation such as St -p1003.2 or St -ansiC this should be noted here. If the command does not adhere to any standard, its history should be noted in the Sx HISTORY section. .Sh HISTORY Any command which does not adhere to any specific standards should be outlined historically in this section. .Sh AUTHORS Credits, if need be, should be placed here. .Sh DIAGNOSTICS Diagnostics from a command should be placed in this section. .Sh ERRORS Specific error handling, especially from library functions (man page sections 2 and 3) should go here. The `.Er macro ' is used to specify an errno. .Sh BUGS Blatant problems with the topic go here...

User specified `.

Paragraphs and Line Spacing.

' paragraph command may be used to specify a line space where necessary. The macro is not necessary after a `.

' macro. (The `.

' macro asserts a vertical distance unless the -compact flag is given).

Examples and Displays

- ldghfstru
- ldghfstru . (D-ell) Display one line of indented literal text. The `. example
% ls -ldg /usr/local/bin
% ls -ldg /usr/local/bin . Begin-display. The `. ' display must be ended with the `. ' macro. Displays may be nested within displays and lists. `. ' has the following syntax: ".

The display-type must be one of the following four types and may have an offset specifier for indentation: `. '

".Bf font-mode

The font-mode must be one of the following three types: `.Bf '

Tagged Lists and Columns

In addition, several list attributes may be specified such as the width of a tag, the list offset, and compactness (blank lines between items allowed or disallowed). Most of this document has been formatted with a tag style list (- tag ) For a change of pace, the list-type used to present the list-types is an over-hanging list (- ohang ) This type of list is quite popular with TeX users, but might look a bit funny after having read many pages of tagged lists. The following list types are accepted by `.Bl' :

.Bl -enum -compact .It Item one goes here. .It And item two here. .It Lastly item three goes here. .El

The results:

  • Item one goes here.
  • And item two here.
  • Lastly item three goes here.

A simple bullet list construction:

.Bl -bullet -compact .It Bullet one goes here. .It Bullet two here. .El
  • Bullet one goes here.
  • Bullet two here.

Here is the source text which produced the above example:

.Bl -inset -offset indent .It Em Tag The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manuals. .It Em Diag Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored. .It Em Hang Hanged labels are a matter of taste. .It Em Ohang Overhanging labels are nice when space is constrained. .It Em Inset Inset labels are useful for controlling blocks of paragraphs and are valuable for converting .Nm -mdoc manuals to other formats. .El

Here is a hanged list with two items:

And the unformatted text which created it:

.Bl -hang -offset indent .It Em Hanged labels appear similar to tagged lists when the label is smaller than the label width. .It Em Longer hanged list labels blend in to the paragraph unlike tagged paragraph labels. .El

The tagged list which follows uses an optional width specifier to control the width of the tag.

The raw text:

.Bl -tag -width "PAGEIN" -compact -offset indent .It SL sleep time of the process (seconds blocked) .It PAGEIN number of disk .Tn I/O Ns 's resulting from references by the process to pages not loaded in core. .It UID numerical user ID of process owner .It PPID numerical ID of parent of process process priority (nonpositive when in noninterruptible wait) .El

Acceptable width specifiers:

If a width is not specified for the tag list type, the first time `. ' is invoked, an attempt is made to determine an appropriate width. If the first argument to `.It' is a callable macro, the default width for that macro will be used as if the macro name had been supplied as the width. However, if another item in the list is given with a different callable macro name, a new and nested list is assumed.

If a nonescaped register name is given in the argument list of a request, unpredictable behavior will occur. In general, any time huge portions of text do not appear where expected in the output, or small strings such as list tags disappear, chances are there is a misunderstanding about an argument type in the argument list. Your mother never intended for you to remember this evil stuff - so here is a way to find out whether or not your arguments are valid: The `.Db (debug) ' macro displays the interpretation of the argument list for most macros. Macros such as the `.

' (paragraph) macro do not contain debugging information. All of the callable macros do, and it is strongly advised whenever in doubt, turn on the `.Db macro. '

Usage: .Db [on | off]

An example of a portion of text with the debug macro placed above and below an artificially created problem (a flag argument `aC' which should be `\&aC' in order to work):

.Db on .Op Fl aC Ar file ) .Db off

The resulting output:

DEBUGGING ON DEBUG(argv) MACRO: `.Op' Line #: 2 Argc: 1 Argv: `Fl' Length: 2 Space: `' Class: Executable Argc: 2 Argv: `aC' Length: 2 Space: `' Class: Executable Argc: 3 Argv: `Ar' Length: 2 Space: `' Class: Executable Argc: 4 Argv: `file' Length: 4 Space: ` ' Class: String Argc: 5 Argv: `)' Length: 1 Space: ` ' Class: Closing Punctuation or suffix MACRO REQUEST: .Op Fl aC Ar file ) DEBUGGING OFF

The first line of information tells the name of the calling macro, here `.[,] ' and the line number it appears on. If one or more files are involved (especially if text from another file is included), the line number may be bogus. If there is only one file, it should be accurate. The second line gives the argument count, the argument (`- ' ) and its length. If the length of an argument is two characters, the argument is tested to see if it is executable (unfortunately, any register which contains a nonzero value appears executable). The third line gives the space allotted for a class, and the class type. The problem here is the argument aC should not be executable. The four types of classes are string, executable, closing punctuation and opening punctuation. The last line shows the entire argument list as it was read. In this next example, the offending `aC' is escaped:

.Db on .Em An escaped \&aC .Db off
DEBUGGING ON DEBUG(fargv) MACRO: `.Em' Line #: 2 Argc: 1 Argv: `An' Length: 2 Space: ` ' Class: String Argc: 2 Argv: `escaped' Length: 7 Space: ` ' Class: String Argc: 3 Argv: `aC' Length: 2 Space: ` ' Class: String MACRO REQUEST: .Em An escaped &aC DEBUGGING OFF

The argument `\&aC' shows up with the same length of 2 as the `\&' sequence produces a zero width, but a register named `\&aC' was not found and the type classified as string.

Other diagnostics consist of usage statements and are self explanatory.

GROFF, TROFF AND NROFF

The package inhibits page breaks, and the headers and footers which normally occur at those breaks with nroff, to make the manual more efficient for viewing on-line. At the moment, groff with - T ascii does eject the imaginary remainder of the page at end of file. The inhibiting of the page breaks makes nroffNs'd files unsuitable for hardcopy. There is a register named `cR' which can be set to zero in the site dependent style file /usr/src/share/tmac/doc-nroff to restore the old style behavior.

Predefined strings are not declared in documentation.

Section 3f has not been added to the header routines.

`. man mdoc.samples ' font should be changed in Sx NAME section.

`.Fn needs ' to have a check to prevent splitting up if the line length is too short. Occasionally it separates the last parenthesis, and sometimes looks ridiculous if a line is in fill mode.

The method used to prevent header and footer page breaks (other than the initial header and footer) when using nroff occasionally places an unsightly partially filled line (blank) at the would be bottom of the page.

The list and display macros to not do any keeps and certainly should be able to.

TRANSLATIONS

Last searched.

  • netdev_lower_state_changed (9)
  • DateTime::Locale::en_TT (3)
  • Net::Trac::Ticket (3)
  • MPI_Ialltoallw (3)
  • strndupa (3)
  • umad_status (3)
  • Module::Install::API (3)

Read the Latest on Page Six

  • Sports Betting
  • Sports Entertainment

Recommended

Boxing star ryan garcia posts ‘death’ message that has ex-wife worried: ‘not ok’.

  • View Author Archive
  • Email the Author
  • Get author RSS feed

Contact The Author

Thanks for contacting us. We've received your submission.

Ryan Garcia had fans, fellow fighters and his ex-wife concerned after he shared a string of odd posts on social media on Sunday.

Andrea Celina, his ex-wife and the mother of their son, Henry Leo Garcia, reportedly explained that she believes Garcia “is not ok” after the 25-year-old boxer posted a video with the message: “RYAN GARCIA RIP BITCH.” It also had a caption that read, “THE DEATH OF RYAN GARCIA.”

“If all my followers who are believers can you please pray for Ryan,” Celina wrote in a since-expired message on her Instagram story, according to The Daily Mail. “We are not together and i’ve been in contact with him and he may seen fine but he is not.

View this post on Instagram A post shared by Ryan Garcia (@kingryan)

Andrea Celina.

“I know in my heart he is being heavily oppressed. This is not a troll, I’m genuinely concerned and so is all his family members. We are not part of any of this and want him to get better but this IS REAL. Pray for him.”

In a comment to a fan that asked if Garcia is ok, his father, Henry Garcia, reportedly wrote: “Yes Ryan is ok , he’s just trolling the wrong way. No there’s more to it . Trust.”

Garcia, the former WBC interim lightweight champion, has yet to address his ex-wife’s message.

Ryan Garcia, left, hits Javier Fortuna, right, during a lightweight boxing bout July 16, 2022, in Los Angeles.

Garcia announced their divorce last month in a now-deleted post on Instagram, which came on the same day he shared the news of their son’s birth.

The boxer filed for divorce due to “irreconcilable differences,” according to court documents obtained by TMZ . They were together since 2019.

Garcia’s post, which featured random letters and other cryptic remarks, included a video that appeared to show someone shuffling through a home.

View this post on Instagram A post shared by Andrea Célina (@dreacelina)

Fans expressed their concern in the comments, as well as MMA fighter Dillon Danis and Diego Sanchez, who currently competes on the Super Lightweight division of Eagle Fighting Championship.

“I’ll pay for you to get help man feel bad for you,” Danis wrote.

“Praying for you Ryan… your young and under spiritual attack you have opened doorways for the enemy to attack you,” Sanchez added. “You don’t have to reach rock bottom like I did to repent and be delivered…”

The video was still posted on Garcia’s social media as of Monday morning.

Garcia is currently dating Mikaela Testa, an Australian influencer with over 400,000 followers on Instagram, according to reports.

Ryan Garcia and  Emmanuel Tagoe exchange punches during their Lightweight bout at the Alamodome on April 9, 2022 in San Antonio, Texas.

In one of his posts over the weekend, Garcia shared a video that showed him kissing his ex, Hehleena Million.

“We broke up a long time ago @hehleena but I’m coming back I LOVE YOU!” Garcia wrote, to which Million responded in the comments with: “I always loved you Ry.”

Garcia is set to fight Devin Haney at Barclays Center on April 20.

In a separate post on Instagram, which promoted the bout, Garcia said he’s “hiring Kanye West to perform” and tagged Kylie Jenner saying, “I love you.”

The Post reached out to Garcia’s promoter Golden Boy Promotions and did not receive an immediate reply.

Share this article:

Andrea Celina.

Advertisement

writing man pages

IMAGES

  1. Man Writing in Notebook · Free Stock Video

    writing man pages

  2. Man writing in notepad stock image. Image of adult, office

    writing man pages

  3. Man Writing on Notebook · Free Stock Photo

    writing man pages

  4. Free photo: writing man

    writing man pages

  5. Man Writing In Notebook

    writing man pages

  6. Man Writing in a Book · Free Stock Photo

    writing man pages

VIDEO

  1. Is this Beginner Writing Advice USEFUL or DAMAGING?

  2. Master the Art of Engaging Readers Visually

COMMENTS

  1. Man Pages

    There are various ways to create man pages, the old-school way being to write them in "roff" format. There are several resources available, such as "Practical Unix Manuals: mdoc" and the Groff manual. Man pages can also be generated from other sources, such as Markdown, with tools like pandoc, and ronn from the Ruby world. 38.

  2. man-pages(7): conventions for writing man pages

    This page describes the conventions that should be employed when writing man pages for the Linux man-pages project, which documents the user-space API provided by the Linux kernel and the GNU C library. The project thus provides most of the pages in Section 2, as well as many of the pages that appear in Sections 3, 4, 5, and 7 of the man pages on a Linux system.

  3. How to Create a man Page on Linux

    The following command tells pandoc to generate a man page called "ms.1": pandoc ms.1.md -s -t man -o ms.1. This follows the convention of naming the man page after the command it describes and appending the manual section number as though it were a file extension. This creates an "ms.1" file, which is our new man page.

  4. man-pages(7)

    This page describes the conventions that should be employed when writing man pages for the Linux man-pages project, which documents the user-space API provided by the Linux kernel and the GNU C library. The project thus provides most of the pages in Section 2, many of the pages that appear in Sections 3, 4, and 7, and a few of the pages that ...

  5. Understanding the man pages in Linux

    Navigation. Navigation in a man page is handled entirely by the pager that is being used. By default, man uses the pager command. And in most modern Linux systems pager is a symbolic link to less. To close the manual at any time, simply press q on your keyboard. This quits the pager and returns to the shell.

  6. Understanding Man Pages in Linux [Beginner's Guide]

    Getting Started with the man Pages in Linux. The pages are viewed through a utility called, man, and the command to use it is rather easy. In the simplest form, to use man, you type man on the command line, followed by a space and the command that you want to look up, such as ls or cp, like so: man ls. man opens the manual page of the ls command.

  7. What you need to know to write man pages

    A man page that directs the user toward the format-of-the-week is unhelpful. Even if there's a compelling reason to use another documentation format (such as better markup or support for hyperlinking) providing man pages is a good thing. Nroff, troff, and macro packages. Man pages are written in a markup language, generally referred to

  8. man(7)

    The first command in a man page (after comment lines, that is, lines that start with .\") should be. .TH title section date source manual. For details of the arguments that should be supplied to the TH. command, see man-pages(7) . Note that BSD mdoc-formatted pages begin with the Dd command, not. the TH command.

  9. How To

    Man Page Location. The system stores its man pages at /usr/share/man/ directory as described in about section. For example, the directory /usr/share/man/man1 stores man pages for user shell commands. You can view it by typing the following command: cd / usr / share / man / man1. ls -l zcat ls.1.gz.

  10. Writing manual pages

    This is a brief tutorial on writing good manual pages, at least for the typical cases. You'll be assumed to be familiar with reading manual pages already. There are actually many ways to produce manual pages. The man(1) command needs a file using troff(1) formatting commands. troff is a typesetting system from the 1970s, written by the Unix ...

  11. Knowledge Bits

    Basics of Writing Unix Man Pages. On Unix-like systems, the documents that one views with the man command (known as "man pages") are written in a markup language called "roff" (short for "run off") that dates back to the pre-Unix days in the 1960's. roff is technically a full-blown programming language with numerous features, but ...

  12. Writing man Pages Using groff

    For more about writing man pages, you can always look at the man page sources (in /usr/man) and determine what they do by comparing the formatted output with the source. This article is adapted from Running Linux, by Matt Welsh and Lar Kaufman, published by O'Reilly and Associates (ISBN 1-56592-100-3). Among other things, this book includes ...

  13. Create man page in Linux with examples (sample man page template

    Man command in Linux. Above using the template we wrote our man page example for test script. To access the man page which we created using our man page template you can use man scriptname from the terminal. # man test_script test_script(1)() test_script(1)() test_script - user interface to perform some task SYNOPSIS test_script {OBJECT} [OPTIONS] DESCRIPTION test_script Write detailed ...

  14. man-pages

    This page describes the conventions that should be employed when writing man pages for the. Linux man-pages project, which documents the user-space API provided by the Linux kernel. and the GNU C library. The project thus provides most of the pages in Section 2, as well. as many of the pages that appear in Sections 3, 4, 5, and 7 of the man ...

  15. manpage

    A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly. For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown ...

  16. write(2)

    file description (see open(2)) perform a write () (or writev(2) ) at the same time, then the I/O operations were not atomic with. respect to updating the file offset, with the result that the. blocks of data output by the two processes might (incorrectly) overlap. This problem was fixed in Linux 3.14.

  17. documentation

    5 Answers. There are tools for writing man pages that bypass troff formatting. manpages are a small, well delimited language and easy to target. xmltoman, a small and well structured xml language that can generate manpages and html. It is used by Lennart Poettering's projects, syrep and pulseaudio for example.

  18. Writing man pages

    Writing man pages Command line tools should be shipped with man pages. Note. To make fullest use of all features, man pages should be written in their native markup language, mdoc. However, this has a quite steep learning curve, so the following can be used to get started quickly.

  19. man-pages

    This page describes the conventions that should be employed when writing man pages for the. Linux man-pages project, which documents the user-space API provided by the Linux kernel. and the GNU C library. The project thus provides most of the pages in Section 2, as well. as many of the pages that appear in Sections 3, 4, 5, and 7 of the man ...

  20. lf309, UNIXBasics: Writing man-pages

    To write a man page is very simple. It is a simple make-up language where keywords for the markup language start with a dot at the beginning of the line. These keywords are also called macros. The most important macros are: .TH -> This starts the title/header of the man page .SH -> Section heading .PP -> New paragraph ." ...

  21. man-pages: conventions for writing Linux man pages

    DESCRIPTION. This page describes the conventions that should be employed when writing man pages for the Linux man-pages project, which documents the user-space API provided by the Linux kernel and the GNU C library. The project thus provides most of the pages in Section 2, many of the pages that appear in Sections 3, 4, and 7, and a few of the ...

  22. man mdoc.samples (1): tutorial sampler for writing

    A tutorial sampler for writing BSD manual pages with the -mdoc macro package, a content -based and domain -based formatting package for troff (1). Its predecessor, the -man7 package, addressed page layout leaving the manipulation of fonts and other typesetting details to the individual author. In -mdoc page layout macros make up the page ...

  23. Ryan Garcia posts 'death' message that has ex-wife worried

    Ryan Garcia had fans, fellow fighters and his ex-wife concerned after he shared a string of odd posts on social media on Sunday. Andrea Celina, his ex-wife and the mother of their son, Henry Leo ...

  24. man(7): macros to format man pages

    Using the -mandoc option is, however, recommended, since this will automatically detect which macro package is in use. For conventions that should be employed when writing man pages for the Linux man-pages package, see man-pages (7). The first command in a man page (after comment lines, that is, lines that start with .\") should be.