From ada70fb8e9b388b782565c73a5b8ccc20a22d190 Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Sun, 22 Mar 2009 08:52:27 +0000 Subject: More documentation clarification. --- Makefile | 4 ++-- manuals.7 | 39 +++++++++++++++++++++++++++++++++++++++ mdoc.3 | 7 +++++-- mdoc.7 | 53 ++++++++++++++++++++++++++++++++++++++++++++--------- 4 files changed, 90 insertions(+), 13 deletions(-) create mode 100644 manuals.7 diff --git a/Makefile b/Makefile index 1ef0764a..b7d83b37 100644 --- a/Makefile +++ b/Makefile @@ -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..049c9380 --- /dev/null +++ b/manuals.7 @@ -0,0 +1,39 @@ +.Dd $Mdocdate: March 22 2009 $ +.Dt "Writing Unix Documentation" paper +.Os +.Sh NAME +.Nm Writing Unix Documentation +.Nd a guide to writing Unix manuals +.Sh DESCRIPTION +

+ Writing Unix Documentation +

+ +

+ 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. +

+ + + + +
+ Copyright © 2009 Kristaps Džonsons, $Date: 2009/03/22 08:52:27 $ +
+ + + + + + diff --git a/mdoc.3 b/mdoc.3 index f7e32d04..959cca97 100644 --- a/mdoc.3 +++ b/mdoc.3 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.3,v 1.21 2009/03/21 21:09:00 kristaps Exp $ +.\" $Id: mdoc.3,v 1.22 2009/03/22 08:52:27 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 21 2009 $ +.Dd $Mdocdate: March 22 2009 $ .Dt mdoc 3 .Os .\" SECTION @@ -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 diff --git a/mdoc.7 b/mdoc.7 index a659efc7..6f0749f2 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.12 2009/03/21 13:47:02 kristaps Exp $ +.\" $Id: mdoc.7,v 1.13 2009/03/22 08:52:27 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 21 2009 $ +.Dd $Mdocdate: March 22 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -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 -- cgit v1.2.3