diff options
Diffstat (limited to 'man.7')
| -rw-r--r-- | man.7 | 57 |
1 files changed, 57 insertions, 0 deletions
@@ -237,6 +237,63 @@ The \efBfoo\efR utility processes files... \&.\e\*q .SH BUGS \&.\e\*q .SH SECURITY CONSIDERATIONS .Ed +.Pp +The sections in a +.Nm +document are conventionally ordered as they appear above. Sections +should be composed as follows: +.Bl -tag -width Ds -offset Ds +.It NAME +The name(s) and a short description of the documented material. The +syntax for this is generally as follows: +.Pp +.D1 \efBname\efR \e(en description +.It LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2 or 3 manual. For functions in +the C library, this may be as follows: +.Pp +.D1 Standard C Library (libc, -lc) +.It SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Pp +.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... +.Pp +For the second, function calls (sections 2, 3, 9): +.Pp +.D1 \. Ns Sx \&B No char *name(char *\efIarg\efR); +.Pp +And for the third, configurations (section 4): +.Pp +.D1 \. Ns Sx \&B No name* at cardbus ? function ? +.Pp +Manuals not in these sections generally don't need a SYNOPSIS. +.It DESCRIPTION +This expands upon the brief, one-line description in NAME. It usually +contains a break-down of the options (if documenting a command). +.It IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. This is useful when +implementing standard functions that may have side effects or notable +algorithmic implications. +.It EXIT STATUS +.It RETURN VALUES +.It ENVIRONMENT +.It FILES +.It EXAMPLES +.It DIAGNOSTICS +.It ERRORS +.It SEE ALSO +.It STANDARDS +.It HISTORY +.It AUTHORS +.It CAVEATS +.It BUGS +.It SECURITY CONSIDERATIONS +.El . . .Sh MACRO SYNTAX |