Common Blocks of Text

PreviousUpNext
Up: Special Formatting Next: Line Breaks Previous: Describing Arguments

In some cases, it is useful to repeat a body of text in many man pages. For example, there may be a common argument that has a lengthy description. A common block of text is defined with

 
/*N name 
   text 
N*/ 
The name may be any blank-delimited string.

To insert this block of text into a man page, use the .N format command

 
/*@ 
    ... 

.N name

... @*/

The definition must precede all uses. Once defined, the definition is remembered; if multiple files are processed and the first file contains a definition of a named block, all subsequently processed files may refer to that named block. This feature allows different replacement texts for different situations. For example, the replacement text for a man page should contain the entire text, whereas the replacement text for a manual (LaTeX) may reference a common section.

For example, the MPICH implementation of MPI uses this to define all of the error conditions. A file errnotes contains lines like

 
/*N Errors 
Errors: 

... text about MPI errors ...

N*/ /*N MPI_SUCCESS . MPI_SUCCESS - No error; MPI routine completed successfully. N*/ /*N MPI_ERR_BUFFER . MPI_ERR_BUFFER - Invalid buffer pointer. Usually a null buffer where one is not valid. N*/

Each MPI man page ends with references to the name blocks for the errors that the particular MPI routine may return. MPI_Send has the following commands at the end of its structured comment:
 
.N Errors 
.N MPI_SUCCESS 
.N MPI_ERR_COMM 
.N MPI_ERR_COUNT 
.N MPI_ERR_TYPE 
.N MPI_ERR_TAG 
.N MPI_ERR_RANK 


PreviousUpNext
Up: Special Formatting Next: Line Breaks Previous: Describing Arguments