summaryrefslogtreecommitdiffstatshomepage
path: root/man.7
diff options
context:
space:
mode:
Diffstat (limited to 'man.7')
-rw-r--r--man.761
1 files changed, 59 insertions, 2 deletions
diff --git a/man.7 b/man.7
index ffdbdf39..5c2ac3a2 100644
--- a/man.7
+++ b/man.7
@@ -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