=================================================================== RCS file: /cvs/mandoc/Attic/manuals.7,v retrieving revision 1.11 retrieving revision 1.16 diff -u -p -r1.11 -r1.16 --- mandoc/Attic/manuals.7 2009/04/03 13:17:26 1.11 +++ mandoc/Attic/manuals.7 2009/07/16 22:16:44 1.16 @@ -1,23 +1,21 @@ -.\" $Id: manuals.7,v 1.11 2009/04/03 13:17:26 kristaps Exp $ +.\" $Id: manuals.7,v 1.16 2009/07/16 22:16:44 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the -.\" above copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: April 3 2009 $ -.Dt manuals 7 +.Dd $Mdocdate: July 16 2009 $ +.Dt MANUALS 7 .Os .\" SECTION .Sh NAME @@ -37,7 +35,7 @@ This document serves as a tutorial to writing documentation .Pq Dq manuals . .\" SECTION -.Sh COMPOSITION +.Sh ENVIRONMENT First, copy over the manual template from .Pa /usr/share/misc/mdoc.template into your source directory. @@ -105,36 +103,6 @@ for this document. Rename the template file: .Pp .Dl % mv mdoc.template myname.mysection .\" 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 man 7 -package of -.Xr roff 7 ; -newer languages such as DocBook or texinfo; or even ad-hoc conventions -such as README files. -.Em Avoid these formats . -.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 myname.mysection -and begin editing. -.\" SUBSECTION .Ss Development Tools While writing, make sure that your manual is correctly structured: .Pp @@ -157,7 +125,7 @@ or 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: April 3 2009 $ +.Dl \&.Dd $Mdocdate: July 16 2009 $ .\" SUBSECTION .Ss Viewing mdoc documents may be paged to your terminal with @@ -186,15 +154,17 @@ Makefiles in order to automatically check your input: Your manual must have a license. It should be listed at the start of your document, just as in source code. .\" SECTION -.Sh BEST PRACTICES -The +.Sh COMPOSITION +Manuals should +.Em always +be written in the .Xr mdoc 7 -and -.Xr mdoc.samples 7 -files are indispensable in guiding composition. In this section, we -introduce some -.Ux -manual best practices: +formatting language. +.\" PARAGRAPH +.Pp +Open the template you've copied into +.Pa myname.mysection +and begin editing. .\" SUBSECTION .Ss Language .Bl -enum