=================================================================== RCS file: /cvs/mandoc/Attic/manuals.7,v retrieving revision 1.10 retrieving revision 1.16 diff -u -p -r1.10 -r1.16 --- mandoc/Attic/manuals.7 2009/03/26 23:01:26 1.10 +++ mandoc/Attic/manuals.7 2009/07/16 22:16:44 1.16 @@ -1,23 +1,21 @@ -.\" $Id: manuals.7,v 1.10 2009/03/26 23:01: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: March 26 2009 $ -.Dt manuals 7 +.Dd $Mdocdate: July 16 2009 $ +.Dt MANUALS 7 .Os .\" SECTION .Sh NAME @@ -37,15 +35,16 @@ This document serves as a tutorial to writing documentation .Pq Dq manuals . .\" SECTION -.Sh COMPOSITION -Prepare your composition environment by copying over the manual template -from -.Pa /usr/share/misc/mdoc.template . +.Sh ENVIRONMENT +First, copy over the manual template from +.Pa /usr/share/misc/mdoc.template +into your source directory. .Pp -If this file doesn't exist, bug your administrator. +.Dl % cp /usr/share/misc/mdoc.template \. +.Pp .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,37 +99,9 @@ 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. +for this document. Rename the template file: .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 name.section -and begin editing. +.Dl % mv mdoc.template myname.mysection .\" SUBSECTION .Ss Development Tools While writing, make sure that your manual is correctly structured: @@ -140,6 +111,11 @@ While writing, make sure that your manual is correctly 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 @@ -149,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: March 26 2009 $ +.Dl \&.Dd $Mdocdate: July 16 2009 $ .\" SUBSECTION .Ss Viewing mdoc documents may be paged to your terminal with @@ -178,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 @@ -242,6 +220,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.