===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.1
retrieving revision 1.7
diff -u -p -r1.1 -r1.7
--- mandoc/Attic/manuals.7 2009/03/22 08:52:27 1.1
+++ mandoc/Attic/manuals.7 2009/03/22 21:19:34 1.7
@@ -1,39 +1,241 @@
.Dd $Mdocdate: March 22 2009 $
-.Dt "Writing Unix Documentation" paper
+.Dt manuals 7
.Os
+.\" SECTION
.Sh NAME
-.Nm Writing Unix Documentation
-.Nd a guide to writing Unix manuals
+.Nm Writing UNIX Documentation
+.Nd a guide to writing UNIX manuals
+.\" SECTION
.Sh DESCRIPTION
-
- Writing Unix Documentation
-
+.Em A utility without good documentation is of no utility at all .
+.\" PARAGRAPH
+.Pp
+A system component's documentation describes the utility of that
+component, whether it's a device driver, an executable or, most
+importantly, a game. Although there are plenty of documents available
+on how to read
+.Ux
+documents, or where to find them, few focus on composition.
+.\" PARAGRAPH
+.Pp
+This document serves as a tutorial to writing
+.Ux
+documentation
+.Pq Dq manuals .
+If you add something to your operating system, whether it's a new file
+format or directory structure or device driver, it needs documentation.
+.\" SECTION
+.Sh COMPOSITION
+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 Section Numbering
+Find an appropriate section for your manual. There may exist multiple
+manual names per section, so be specific. A table of all available
+manual sections follows:
+.Pp
+.\" LIST
+.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
+.It Em Section
+.Em Description
+.It 1
+operator utilities
+.It 2
+system calls
+.It 3, 3p, 3f
+programming libraries (C, Perl, Fortran)
+.It 5
+file and wire protocol formats
+.It 6
+games
+.It 7
+tutorials, documents and papers
+.It 8
+administrator utilities
+.It 9
+in-kernel routines
+.El
+.Pp
+If your manual falls into multiple categories, choose the most
+widely-used or, better, re-consider the topic of your manual to be more
+specific. You can list all manuals per section by invoking
+.Xr apropos 1 ,
+then provide the
+.Fl s
+flag to
+.Xr man 1
+to see the specific section manual (section 1, in this example):
+.\" DISPLAY
+.Bd -literal -offset indent
+% apropos myname
+myname (1) - utility description
+myname (3) - library description
+% man \-s 1 myname
+.Ed
+.\" SUBSECTION
+.Ss Naming
+Name your component. Be terse, erring on the side of clarity. You may
+want to look for other manuals by that same name before committing:
+.Pp
+.Dl % apropos myname
+.Pp
+Manual files are named
+.Pa myname.mysection ,
+such as
+.Pa manuals.7
+for this document.
+.\" SUBSECTION
+.Ss Input Language
+Manuals should
+.Em always
+be written in the
+.Xr mdoc 7
+formatting language.
+.Pp
+There exist other documentation-specific languages, such as the
+historical
+.Xr me 7 ,
+.Xr ms 7
+and
+.Xr man 7
+packages of
+.Xr roff 7 ;
+newer languages such as DocBook, texinfo or schema-driven XML; or even
+ad-hoc conventions such as README files.
+.Em Avoid these formats .
+Historical formats fail to capture a manual's semantic content, instead
+only modelling its style. Newer methods requires special,
+system-specific tools and may change or become obsolete over the
+life-time of your component.
+.Pp
+There are two canonical references for writing mdoc. Read them.
+.Pp
+.\" LIST
+.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
+.It Xr mdoc 7
+formal language reference
+.It Xr mdoc.samples 7
+macro reference
+.El
+.Pp
+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:
+.Pp
+.Dl % mandoc \-Tlint \-Wall name.1
+.Pp
+You may spell-check your work as follows:
+.Pp
+.Dl % deroff name.1 | spell
+.Dl % ispell \-n name.1
+.Pp
+Use
+.Xr cvs 1
+or, if not available,
+.Xr rcs 1
+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: March 22 2009 $
+.\" SUBSECTION
+.Ss Viewing
+mdoc documents may be paged to your terminal with traditional
+tools such as
+.Xr nroff 1 ,
+.Xr groff 1 ,
+or with newer, more powerful tools such as
+.Xr mandoc 1 :
+.\" DISPLAY
+.Bd -literal -offset indent
+% nroff \-mandoc name.1 | less
+% groff \-Tascii \-mandoc name.1 | less
+% mandoc name.1 | less
+.Ed
+.Pp
+Other output formats are also supported:
+.\" DISPLAY
+.Bd -literal -offset indent
+% groff \-Tps \-mandoc name.1 | less
+% mandoc \-Thtml name.1 | less
+.Ed
+.\" SUBSECTION
+.Ss Automation
+Consider adding your mdoc documents to
+.Xr make 1
+Makefiles in order to automatically check your input and generate
+output:
+.Bd -literal -offset indent
+\&.SUFFIXES: .html .txt .1 .in
-
- A utility without documentation is of no utility at all.
-
-
-
- A system component's documentation describes the utility of that component, whether it's a device
- driver, an executable or, most importantly, a game. Although there are plenty of documents available on
- how to read Unix documents, or where to find them, few focus on how to write them.
-
-
-
- This document serves as a reference guide to writing Unix documentation. If you add something to your
- operating system, whether it's a new file format or directory structure or device driver, it needs
- documentation.
-
-
-
-
- |
-
- |
-
-
-
-
-