From 04bc882719f61ddc85125c713ae0b2bee7fc6694 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 23 May 2007 06:16:43 +0000 Subject: [PATCH] Minor changes. --- man7/man-pages.7 | 49 ++++++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/man7/man-pages.7 b/man7/man-pages.7 index dc10af1bd..326b8978b 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -21,6 +21,9 @@ .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 2007-05-30 created by mtk, using text from old man.7 plus +.\" rewrites and additional text. .\" .TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual" .SH NAME @@ -88,7 +91,7 @@ package described in This choice is mainly for consistency: the vast majority of existing Linux manual pages are marked up using these macros. .SS Conventions for source file layout -Please limit source code line length to no more than 75 characters +Please limit source code line length to no more than about 75 characters wherever possible. This helps avoid line-wrapping in some mail clients when patches are submitted inline. @@ -117,8 +120,8 @@ The section number in which the man page should be placed (e.g., .TP .I date The date of the last revision\(emremember to change this every time a -change is made to the man page, since this is the most general way of doing -version control. +change is made to the man page, +since this is the most general way of doing version control. Dates should be written in the form YYYY-MM-DD. .TP .I source @@ -157,7 +160,7 @@ The list below shows conventional or suggested sections. Most manual pages should include at least the .B highlighted sections. -Srrange a new manual page so that sections +Arrange a new manual page so that sections are placed in the order shown in the list. .in +0.5i .nf @@ -184,7 +187,7 @@ NOTES BUGS EXAMPLE .\" AUTHOR sections are discouraged -AUTHOR [Discouraged] +.\" AUTHOR [Discouraged] \fBSEE ALSO\fP .fi @@ -212,8 +215,8 @@ for important details of the line(s) that should follow the briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); -boldface is used for as-is text and italics are used to indicate replaceable -arguments. +boldface is used for as-is text and italics are used to +indicate replaceable arguments. Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or @@ -309,17 +312,22 @@ system call or library function appeared, or changed significantly in its operation. .TP .B CONFORMING TO -describes any standards or conventions that relate to the function or command described by the manula page. -For a page in Section 2 or 3, this section should note the POSIX.1 -version(s) that the call conforms to. -If the call is not governed by any standards but exists on other -systems, note them. +describes any standards or conventions that relate to the function +or command described by the manual page. +For a page in Section 2 or 3, +this section should note the POSIX.1 +version(s) that the call conforms to, +and also whether the call is specified in C99. +(Don't worry too much about other standards like SUS, SUSv2, and XPG, +or the SVr4 and 4.xBSD implementation standards, +unless the call was specified in those standards, +but isn't in the current version of POSIX.1.) +(See +.BR standards (7).) + +If the call is not governed by any standards but commonly +exists on other systems, note them. If the call is Linux specific, note this. -When talking about standards and systems -here is probably no need to talk about anything more than -C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4, and perhaps Solaris -(see -.BR standards (7)). .TP .B NOTES provides miscellaneous notes. @@ -333,13 +341,14 @@ and other questionable activities. .B EXAMPLE provides one or more examples describing how this function, file or command is used. -For details on writing example programs, see \fIExample Programs\fP below. +For details on writing example programs, +see \fIExample Programs\fP below. .TP .B AUTHOR lists authors of the documentation or program so you can mail in bug reports. -.BR "Use of an AUTHOR section is discouraged for pages in -the \fIman-pages\fP package". +\fBUse of an AUTHOR section is discouraged\fP for pages in +the \fIman-pages\fP package. (One exception is Section 4 pages that list the authors of device drivers, to whom software bugs should be sent.) Generally, it is better not to clutter every page with a list