Commands

Commands are the way in which a user operates her computer. Already I've noted the man command: if you've interacted with a UNIX system, you've probably run at least man intro or man man to learn about your system.

In this chapter, I'll discuss how to document these commands with mdoc.

This may be unfamiliar if you're accustomed to graphical interfaces — all of our examples will refer to command-line, text-based commands. If your target environment isn't a UNIX system, it's a good idea to read these examples anyway, as as they will expose the rudimentary structure of the mdoc language. As mentioned before, reading an introductory text on UNIX will help avoid confusion.

Let's begin by making a mental checklist for the criteria that make a good manual for a command. This checklist arises by inverting what a manual reader expects in opening a manual: what does the command do and how do I operate it?

• Do I describe the calling syntax of the command?
• Do I describe each flag and argument of the command?
• Do I describe the command's operation?
• Do I describe the command's exit status?
• Do I describe referenced files and environment variables?

Above all, the best litmus test is whether a colleague or friend can read your manual and be able to use your command without any assistance on your part. Don't be discouraged by how this can take several tries to get right!

I'll begin with a simple command, hi, which prints hello, world to the screen. I'll then add some command-line arguments to this command. By the time you finish this chapter, you should have a grasp of mdoc syntax and some of its more widely-used macros.

In this text, I'll refer to the invocation of commands as cmd flag farg arg. Here, cmd refers to the command invocation name, flag is a flag (or switch) to that command, farg is an argument to a flag (not all flags have arguments), and arg is an argument to the command.

The dash in front of flag indicates a flag, while the square brackets around flag farg indicate an optional part of the invocation. Since arg is not bracketed, it is a mandatory part of the invocation.

This convention is formalised by the POSIX.1-2008 standard (Base Definitions, sec. 12.1), so you can expect to see it often in the UNIX world.

Last edited by $Author: kristaps $ on $Date: 2011/11/04 22:24:07 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.