summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-03-22 14:35:16 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-03-22 14:35:16 +0000
commitc045dee3b0c15ec8f2e1054b209abc29fb0f2414 (patch)
tree30108c00226fbfebb1e24a4dae3c16e2499ae387
parent1a0d0bee983784b66b0b5d5bae6ffcc4958b15a8 (diff)
downloadmandoc-c045dee3b0c15ec8f2e1054b209abc29fb0f2414.tar.gz
More updates.
-rw-r--r--manuals.731
1 files changed, 18 insertions, 13 deletions
diff --git a/manuals.7 b/manuals.7
index 41d3b10b..fac2f0ef 100644
--- a/manuals.7
+++ b/manuals.7
@@ -28,14 +28,15 @@ format or directory structure or device driver, it needs documentation.
.Sh CLASSIFICATION
Classify your system component. In
.Ux ,
-each component has a
-.Dq manual section ,
-which categorises the component's function. The section of a manual is
-usually listed in parenthesis next to the component name, such as
+each component has a manual section , which categorises the component's
+function. The section of a manual is usually listed in parenthesis next
+to the component name, such as
.Xr ps 1 ,
section 1. You can query a manual explicitly by its section:
-.Pp
-.Dl % man \-s 1 ps
+.Bd -literal -offset XXXX
+% man \-s 1 ps
+% apropos ps
+.Ed
.Pp
The following table lists classifications and the applicable manual
sections:
@@ -90,7 +91,12 @@ symbolic link handling
.El
.\" SECTION
.Sh COMPOSITION
-Prepare your composition environment.
+Prepare your composition environment by copying over the manual template
+from
+.Pa /usr/share/misc/mdoc.template .
+.Em \&Do not
+start afresh or by copying another manual unless you know exactly what
+you're doing!
.\" SUBSECTION
.Ss Naming
Your component will need a name by which to query its contents via
@@ -139,9 +145,9 @@ formal language reference
macro reference
.El
.Pp
-Don't merely copy existing manuals! Most systems distribute an mdoc
-template to help you get started in
-.Pa /usr/share/misc/mdoc.template .
+Open the template you've copied into
+.Pa name.section
+and begin editing.
.\" SUBSECTION
.Ss Development Tools
While writing, make sure that your manual is correctly structured:
@@ -161,7 +167,6 @@ to version-control your work. If you wish the last check-in to effect
your document's date, use the following RCS tag for the date macro:
.Pp
.Dl \&.Dd $Mdocdate$
-.Pp
.\" SUBSECTION
.Ss Viewing
mdoc documents may be paged to your terminal with traditional
@@ -208,7 +213,7 @@ The
.Xr mdoc 7
and
.Xr mdoc.samples 7
-files will be indispensable in guiding composition. In this section, we
+files are indispensable in guiding composition. In this section, we
introduce some
.Ux
manual best practices:
@@ -260,4 +265,4 @@ lists), assume that your output device is a fixed-width terminal window:
.Pp
You may assume that the width calculated by the string literal
.Qq Fl o Ar outfile
-will
+will be covered by the \-width argument.