diff options
| -rw-r--r-- | Makefile | 4 | ||||
| -rw-r--r-- | manuals.7 | 39 | ||||
| -rw-r--r-- | mdoc.3 | 3 | ||||
| -rw-r--r-- | mdoc.7 | 49 |
4 files changed, 86 insertions, 9 deletions
@@ -36,13 +36,13 @@ OBJS = $(LIBOBJS) $(MAINOBJS) SRCS = $(LIBSRCS) $(MAINSRCS) DATAS = arch.in att.in lib.in msec.in st.in vol.in ascii.in HEADS = mdoc.h private.h term.h -SGMLS = index.sgml +SGMLS = index.sgml HTMLS = index.html STATICS = style.css external.png TARGZS = mdocml-$(VERSION).tar.gz \ mdocml-oport-$(VERSION).tar.gz \ mdocml-nport-$(VERSION).tar.gz -MANS = mandoc.1 mdoc.3 mdoc.7 +MANS = mandoc.1 mdoc.3 mdoc.7 manuals.7 BINS = mandoc CLEAN = $(BINS) $(LNS) $(LLNS) $(LIBS) $(OBJS) $(HTMLS) $(TARGZS) INSTALL = $(SRCS) $(HEADS) Makefile DESCR $(MANS) $(SGMLS) \ diff --git a/manuals.7 b/manuals.7 new file mode 100644 index 00000000..1f98a905 --- /dev/null +++ b/manuals.7 @@ -0,0 +1,39 @@ +.Dd $Mdocdate$ +.Dt "Writing Unix Documentation" paper +.Os +.Sh NAME +.Nm Writing Unix Documentation +.Nd a guide to writing Unix manuals +.Sh DESCRIPTION + <h1> + Writing Unix Documentation + </h1> + + <p> + <span class="attn">A utility without documentation is of no utility at all.</span> + </p> + + <p> + 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 <i>read</i> Unix documents, or where to find them, few focus on how to <i>write</i> them. + </p> + + <p> + 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. + </p> + </td> + </tr> + <tr> + <td> + <div class="foot"> + Copyright © 2009 Kristaps Džonsons, $Date$ + </div> + </td> + </tr> + </tbody> + </table> + </body> +</html> @@ -345,4 +345,7 @@ if not included. List-width suffix .Qq m isn't handled. +.\" LIST-ITEM +.It +Contents of the SYNOPSIS section aren't checked. .El @@ -30,18 +30,33 @@ The language is used to format .Bx .Ux -manuals. An +manuals. In this reference document, we describe the syntax, ontology +and structure of the +.Nm +language. +.\" PARAGRAPH +.Pp +An .Nm document follows simple rules: lines beginning with the control -character +character .Sq \. are parsed for macros. Other lines are interpreted within the scope of -prior macros. This document describes the encoding, ontology and syntax -of these macros. +prior macros: +.Bd -literal -offset XXX +\&.Sh Macro lines change control state. +Other lines are interpreted within the current state. +.Ed +.\" PARAGRAPH +.Pp +Macros are two- or three-character sequences whose scope rules, rules +that dictate handling of subsequent-line or same-line arguments, are +governed by one of five classifications described in this document. .\" SECTION -.Sh CHARACTER ENCODING +.Sh INPUT ENCODING .Nm -documents may contain only printable characters, the space character +documents may contain only graphable 7-bit ASCII characters, the space +character .Sq \ , and, in certain circumstances, the tab character .Sq \et . @@ -529,7 +544,11 @@ Special symbols: .El .\" SECTION .Sh ONTOLOGY -Macros are classified in an ontology described by scope rules. +Macros are classified in an ontology described by their scope rules. +Some macros are allowed to deviate from their classifications to +preserve backward-compatibility with old macro combinations still found +in the manual corpus. These are specifically noted on a per-macro +basis. .\" SUB-SECTION .Ss Scope .Bl -inset @@ -729,6 +748,22 @@ close at the invocation's end-of-line. .It \&.Dl Ta \&No Ta Yes .It \&.Ql Ta Yes Ta Yes .El +.\" PARAGRAPH +.Pp +The +.Sq \&Op +may be broken by \&Oc as in the following example: +.Bd -literal -offset XXXX +\&.Oo +\&.Op Fl a Oc +.Ed +.Pp +In the above example, the scope of +.Sq \&Op +is technically broken by +.Sq \&Oc , +however, due to the overwhelming existence of this sequence, it's +allowed. .\" SUB-SECTION .Ss Block partial-explicit Each of these contains at least a body and, in limited circumstances, a |