summaryrefslogtreecommitdiffstats
path: root/manuals.7
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-04-03 13:17:26 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-04-03 13:17:26 +0000
commit0f67958754bbd15e7e78b16906347cd2081370f0 (patch)
treefe439c99846ff231cb10c09007c15393163b0e64 /manuals.7
parente3914afc1290b59c10836bf8fd0fd4d34c1b5b0d (diff)
downloadmandoc-0f67958754bbd15e7e78b16906347cd2081370f0.tar.gz
Updated manuals.7.
Fixed .Dl display.
Diffstat (limited to 'manuals.7')
-rw-r--r--manuals.730
1 files changed, 20 insertions, 10 deletions
diff --git a/manuals.7 b/manuals.7
index e351648b..8e772750 100644
--- a/manuals.7
+++ b/manuals.7
@@ -38,14 +38,15 @@ documentation
.Pq Dq manuals .
.\" SECTION
.Sh COMPOSITION
-Prepare your composition environment by copying over the manual template
-from
-.Pa /usr/share/misc/mdoc.template .
+First, copy over the manual template from
+.Pa /usr/share/misc/mdoc.template
+into your source directory.
+.Pp
+.Dl % cp /usr/share/misc/mdoc.template \.
.Pp
-If this file doesn't exist, bug your administrator.
.Em \&Do not
start afresh or by copying another manual unless you know exactly what
-you're doing!
+you're doing! If the template doesn't exist, bug your administrator.
.\" SUBSECTION
.Ss Section Numbering
Find an appropriate section for your manual. There may exist multiple
@@ -100,7 +101,9 @@ Manual files are named
.Pa myname.mysection ,
such as
.Pa manuals.7
-for this document.
+for this document. Rename the template file:
+.Pp
+.Dl % mv mdoc.template myname.mysection
.\" SUBSECTION
.Ss Input Language
Manuals should
@@ -129,7 +132,7 @@ macro reference
.El
.Pp
Open the template you've copied into
-.Pa name.section
+.Pa myname.mysection
and begin editing.
.\" SUBSECTION
.Ss Development Tools
@@ -140,6 +143,11 @@ While writing, make sure that your manual is correctly structured:
You may spell-check your work as follows:
.Pp
.Dl % deroff name.1 | spell
+.Pp
+If
+.Xr ispell 1
+is installed, it has a special mode for manuals:
+.Pp
.Dl % ispell \-n name.1
.Pp
Use
@@ -242,6 +250,8 @@ and style.
.\" SECTION
.Sh MAINTENANCE
As your component changes and bugs are fixed, your manual may become out
-of date. You may be tempted to use automation tools like Doxygen to
-smooth the development of your manuals. Don't. Source documentation is
-different from a component manual.
+of date. You may be tempted to use tools like Doxygen to automate the
+development of your manuals. Don't.
+.Pp
+.Em Manuals are part of a system component :
+if you modify your code or specifications, modify the documentation.