summaryrefslogtreecommitdiffstats
path: root/man.7
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2010-07-19 23:21:39 +0000
committerIngo Schwarze <schwarze@openbsd.org>2010-07-19 23:21:39 +0000
commite3b9d34e7bf3e1e75514451170cb01d7a2f60195 (patch)
treeef7a4f2e3ffc6848e90299138212fa29f4544f6c /man.7
parent5e8acb6bcefb0282a4c83bd0370ae5b92db51549 (diff)
downloadmandoc-e3b9d34e7bf3e1e75514451170cb01d7a2f60195.tar.gz
sync to OpenBSD:
* briefly mention the HISTORY of the man(7) language * update the copyright notice * improve the wording in a few places * fix a couple of typos including two suggestions from J.C. Roberts feedback and ok jmc@, ok sobrado@ and kristaps@
Diffstat (limited to 'man.7')
-rw-r--r--man.748
1 files changed, 30 insertions, 18 deletions
diff --git a/man.7 b/man.7
index 4236c537..3dc62e26 100644
--- a/man.7
+++ b/man.7
@@ -1,6 +1,6 @@
.\" $Id$
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
@@ -37,7 +37,7 @@ Use the
.Xr mdoc 7
language, instead.
.Pp
-An
+A
.Nm
document follows simple rules: lines beginning with the control
character
@@ -52,7 +52,7 @@ Other lines are interpreted within the current state.
.Sh INPUT ENCODING
.Nm
documents may contain only graphable 7-bit ASCII characters, the
-space character, and the tabs character.
+space character, and the tab character.
All manuals must have
.Ux
line termination.
@@ -92,7 +92,7 @@ and
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
-escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+escape followed by an indicator: B (bold), I (italic), R (Roman), or P
(revert to previous mode):
.Pp
.D1 \efBbold\efR \efIitalic\efP
@@ -300,7 +300,7 @@ Documents any usages of environment variables, e.g.,
.Xr environ 7 .
.It Em FILES
Documents files used.
-It's helpful to document both the file and a short description of how
+It's helpful to document both the file name and a short description of how
the file is used (created, modified, etc.).
.It Em EXIT STATUS
Command exit status for section 1, 6, and 8 manuals.
@@ -346,18 +346,19 @@ The history of any manual without a
section should be described in this section.
.It Em AUTHORS
Credits to authors, if applicable, should appear in this section.
-Authors should generally be noted by both name and an e-mail address.
+Authors should generally be noted by both name and email address.
.It Em CAVEATS
-Explanations of common misuses and misunderstandings should be explained
+Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
-Extant bugs should be described in this section.
+Known bugs, limitations and work-arounds should be described
+in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.El
.Sh MACRO SYNTAX
Macros are one to three three characters in length and begin with a
-control character ,
+control character,
.Sq \&. ,
at the beginning of the line.
The
@@ -393,11 +394,11 @@ is equivalent to
.Sq \&.I foo .
If next-line macros are invoked consecutively, only the last is used.
If a next-line macro is followed by a non-next-line macro, an error is
-raised (unless in the case of
+raised, except for
.Sx \&br ,
.Sx \&sp ,
-or
-.Sx \&na ) .
+and
+.Sx \&na .
.Pp
The syntax is as follows:
.Bd -literal -offset indent
@@ -660,7 +661,7 @@ and
Begin an undecorated paragraph.
The scope of a paragraph is closed by a subsequent paragraph,
sub-section, section, or end of file.
-The saved paragraph left-margin width is re-set to the default.
+The saved paragraph left-margin width is reset to the default.
.Pp
See also
.Sx \&HP ,
@@ -757,7 +758,7 @@ bold face.
Begin a section.
The scope of a section is only closed by another section or the end of
file.
-The paragraph left-margin width is re-set to the default.
+The paragraph left-margin width is reset to the default.
.Ss \&SM
Text is rendered in small size (one point smaller than the default
font).
@@ -765,7 +766,7 @@ font).
Begin a sub-section.
The scope of a sub-section is closed by a subsequent sub-section,
section, or end of file.
-The paragraph left-margin width is re-set to the default.
+The paragraph left-margin width is reset to the default.
.Ss \&TH
Sets the title of the manual page with the following syntax:
.Bd -filled -offset indent
@@ -774,9 +775,9 @@ Sets the title of the manual page with the following syntax:
.Op Cm date Op Cm source Op Cm volume
.Ed
.Pp
-At least the upper-case document title
+At least the upper-case document
.Cm title
-and numeric manual section
+and the manual
.Cm section
arguments must be provided.
The
@@ -932,9 +933,20 @@ control character.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc_char 7
-.Sh AUTHORS
+.Sh HISTORY
The
.Nm
+language first appeared as a macro package for the roff typesetting
+system in
+.At v7 .
+It was later rewritten by James Clark as a macro package for groff.
+The stand-alone implementation that is part of the
+.Xr mandoc 1
+utility written by Kristaps Dzonsons appeared in
+.Ox 4.6.
+.Sh AUTHORS
+This
+.Nm
reference was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
.Sh CAVEATS