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
/*@ ...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: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:
... 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*/
.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