diff options
Diffstat (limited to 'man.7')
| -rw-r--r-- | man.7 | 61 |
1 files changed, 59 insertions, 2 deletions
@@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.40 2009/10/24 05:45:04 kristaps Exp $ +.\" $Id: man.7,v 1.41 2009/10/26 10:36:46 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 24 2009 $ +.Dd $Mdocdate: October 26 2009 $ .Dt MAN 7 .Os . @@ -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 |