diff options
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | index.sgml | 7 | ||||
| -rw-r--r-- | manuals.7 | 236 |
3 files changed, 6 insertions, 245 deletions
@@ -96,7 +96,7 @@ HEADS = mdoc.h libmdoc.h man.h libman.h term.h \ libmandoc.h html.h chars.h out.h main.h roff.h \ mandoc.h -GSGMLS = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml manuals.7.sgml \ +GSGMLS = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml \ mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \ roff.3.sgml @@ -105,12 +105,12 @@ SGMLS = index.sgml HTMLS = ChangeLog.html index.html man.h.html mdoc.h.html \ mandoc.h.html roff.h.html mandoc.1.html mdoc.3.html \ man.3.html mdoc.7.html man.7.html mandoc_char.7.html \ - manuals.7.html roff.7.html roff.3.html + roff.7.html roff.3.html XSLS = ChangeLog.xsl TEXTS = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \ - mandoc_char.7.txt manuals.7.txt ChangeLog.txt \ + mandoc_char.7.txt ChangeLog.txt \ roff.7.txt roff.3.txt EXAMPLES = example.style.css @@ -123,7 +123,7 @@ MD5S = mdocml-$(VERSION).md5 TARGZS = mdocml-$(VERSION).tar.gz -MANS = mandoc.1 mdoc.3 mdoc.7 manuals.7 mandoc_char.7 man.7 \ +MANS = mandoc.1 mdoc.3 mdoc.7 mandoc_char.7 man.7 \ man.3 roff.7 roff.3 BINS = mandoc @@ -183,10 +183,6 @@ <TD>mandoc special characters</TD> </TR> <TR> - <TD><A HREF="manuals.7.html">manuals(7)</A> (<A HREF="manuals.7.txt">text</A>)</TD> - <TD>a guide to writing UNIX manuals</TD> - </TR> - <TR> <TD><A HREF="mdoc.3.html">mdoc(3)</A> (<A HREF="mdoc.3.txt">text</A>)</TD> <TD>mdoc macro compiler library</TD> </TR> @@ -266,7 +262,8 @@ <P> This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with - groff, as are implicit list entries for columns. + groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A + CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. </P> </DIV> <DIV CLASS="news"> diff --git a/manuals.7 b/manuals.7 deleted file mode 100644 index 039e5899..00000000 --- a/manuals.7 +++ /dev/null @@ -1,236 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> -.\" -.\" 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. -.\" -.\" 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$ -.Dt MANUALS 7 -.Os -.\" SECTION -.Sh NAME -.Nm Writing UNIX Documentation -.Nd a guide to writing UNIX manuals -.\" SECTION -.Sh DESCRIPTION -.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. -.Pp -This document serves as a tutorial to writing -.Ux -documentation -.Pq Dq manuals . -.\" SECTION -.Sh ENVIRONMENT -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 -.Em \&Do not -start afresh or by copying another manual unless you know exactly what -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 -manual names per section, so be specific: -.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. 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. Rename the template file: -.Pp -.Dl % mv mdoc.template myname.mysection -.\" SUBSECTION -.Ss Development Tools -While writing, make sure that your manual is correctly structured: -.Pp -.Dl % mandoc \-Tlint \-Wall \-fstrict name.1 -.Pp -The quick-fix feature of -.Xr vim 1 -is useful for checking over many manuals: -.Bd -literal -offset indent -% mandoc \-Wall \-fstrict \-Tlint \-fign-errors \e - ./path/to/manuals/* 2>&1 > /tmp/mandoc.errs -% vim -q /tmp/mandoc.errs -.Ed -.Pp -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 -.Xr cvs 1 -or -.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$ -.\" SUBSECTION -.Ss Viewing -mdoc documents may be paged to your terminal with -.Xr mandoc 1 . -If you plan on distributing your work to systems without this tool, -check it against -.Xr groff 1 : -.Bd -literal -offset indent -% mandoc \-Wall name.1 2>&1 | less -% groff -mandoc name.1 2>&1 | less -.Ed -.\" SUBSECTION -.Ss Automation -Consider adding your mdoc documents to -.Xr make 1 -Makefiles in order to automatically check your input: -.Bd -literal -offset indent -\&.SUFFIXES: .1 .in - -\&.in.1: - mandoc -Wall,error -Tlint $< - cp -f $< $@ -.Ed -.\" SUBSECTION -.Ss Licensing -Your manual must have a license. It should be listed at the start of -your document, just as in source code. -.\" SECTION -.Sh COMPOSITION -Manuals should -.Em always -be written in the -.Xr mdoc 7 -formatting language. -.\" PARAGRAPH -.Pp -Open the template you've copied into -.Pa myname.mysection -and begin editing. -.\" SUBSECTION -.Ss Language -.Bl -enum -.It -Use clear, concise language. Favour simplicity. -.It -Write your manual in non-idiomatic English. Don't worry about -Commonwealth or American spellings \(em just correct ones. -.It -Spell-check your manual, keeping in mind short-letter terms ( -.Xr iwi 4 -vs. -.Xr iwn 4 ) . -.It -If you absolutely must use special characters (diacritics, mathematical -symbols and so on), use the escapes dictated in -.Xr mdoc 7 . -.El -.\" SUBSECTION -.Ss Style -The structure of the mdoc language makes it very hard to have any -particular format style. Keep your lines under 72 characters in length. -If you must have long option lines, use -.Sq \&Oo/Oc . -The same goes for function prototypes. -.Em \&Do not -use -.Sq \&Xo/Xc . -Find another way to structure your line. -.\" SUBSECTION -.Ss References -Other components may be referenced with the -.Sq \&Xr -and -.Sq \&Sx -macros. Make sure that these exist. If you intend to distribute your -manual, make sure -.Sq \&Xr -references are valid across systems (within reason). If you cross-link with -.Sq \&Sx , -make sure that the section reference exists. -.\" SUBSECTION -.Ss Citations -Cite your work. If your system references standards documents or other -publications, please use the -.Sq \&Rs/Re -block macros. -.\" SUBSECTION -.Ss Formatting -.Em Don't style your manual . -Give it meaningful content. The front-end will worry about formatting -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 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. |