Case Study

I now introduce a case study of a real-world function manual, in particular the manual for the strtonum function, which is an extension to the C Standard Library found in OpenBSD. The original file may be viewed on-line at src/lib/libc/stdlib/strtonum.3, file version 1.14.

In this case study, I've chosen a manual with some bad behaviour — not broken, but bad. This is intentional to show how real-world manuals deviate from recommended forms. I'll explicitly note each instance of bad behaviour as we explore the manual's contents.

This is the standard comment header to manual files in OpenBSD. Indeed, most distributed manuals begin with a copyright notice, then a license. The $​OpenBSD$ line is automatically updated by the revision control system, cvs, whenever an update to the file is committed. The line following is the copyright message, and following that is the text form of the ISC license.

These three standard macros establish the last modified date, manual title (same as the single documented function but capitalised), manual category 3 (functions), and the default operating system. The $​Mdocdate$ line, like the $​OpenBSD$ line, is automatically updated by cvs whenever the document is committed to the source repository.

Declares a single documented function, strtonum, and its purpose. The quotations within the Nd macro are superfluous: like Qq macro studied earlier, Nd accepts an arbitrary number of arguments to format. Quotation, in grouping these as one argument, serves little but to pass in whitespace (there is no special whitespace to pass in).

This declares the function prototype and calling syntax. First, let's examine the new Fd macro. The use of this macro for a header inclusion is obsolete: new manuals should always use In. This makes it easier for parsers to understand a header file — and possibly link to it — instead of being a generic preprocessor statement. The re-written form would begin as follows:

Moving along, we see that each function argument includes its name (e.g., nptr and minval). While not common in header file prototypes, this allows later references of function invocation in the manual to refer back to the prototype for type and context information. In the previous section, we discussed the relevance of quotation with Fa: the same is done here.

While we could have used Fn, it would have created an overly long input line. Using Fn instead of Fo is purely a matter of convenience and has no effect on parsing or formatting.

In the SYNOPSIS, the Fa included the full type information. Here, however, we use Fa with just its name, nptr. We could have done the same in the SYNOPSIS, but the C language includes all type information in its prototypes.

The Li macro here isn't good practise: since the long long refers to a type, it should be of type Vt. This behaviour — using a presentation macro instead of a semantic one — is a holder from legacy manual forms that are purely presentational. If you find yourself applying a style, think twice whether it's a good idea!

The remainder of the DESCRIPTION section has completely captured the calling syntax and behaviour of the function. The usage of Ql macro is simply to set aside non-alphanumeric letters from the regular stream of text.

Since this function returns a rather tricky error message, it's necessary to describe the effects of both the return value and the passed-in arguments.

Many manual readers jump directly to the EXAMPLES section to gain an understanding of your function. Thus, not only must the example compile and run, it must also demonstrate as many parts of the function as possible. In the case of strtonum, an error condition and a non-error condition are documented. However, the header file inclusion(s) are missing, which may mislead readers. In particular, the non-standard errx function requires the err.h header file.

The ERRORS section will be rigorously covered in the section on System Calls. In brief, since the errno global error variable is set, each possible value must be documented in a list using the Er macro. These are always enclosed within Bq.

Furthermore, the error string in errstr must also be documented.

This section collects all references to other manuals made elsewhere in this manual, then adds more for completion. Note that the entries are alphabetically sorted.

Since this function is included in OpenBSD's C Standard Library, the fact that the function is not standard must absolutely be documented. In this, the Ox macro indicates the OpenBSD operating system (each BSD UNIX operating system has its own macro).

Last edited by $Author: kristaps $ on $Date: 2011/11/05 16:50:11 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.