-.\" $Id: man.7,v 1.4 2009/03/26 16:23:22 kristaps Exp $
+.\" $Id: man.7,v 1.5 2009/03/26 23:01:26 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
.\"
\&.SH Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
-.\" PARAGRAPH
-.Pp
-Macros are character sequences whose structural rules are described
-later in this document.
.\" SECTION
.Sh INPUT ENCODING
.Nm
space character
.Sq \ .
All manuals must have
+.Ux
.Sq \en
line termination.
.Pp
-Blank lines are acceptable; where found, the output will also assert a
+Blank lines are acceptable; where found, the output will assert a
vertical space.
.Pp
The
.Sq \&.RI .
When these macros are invoked without arguments, the subsequent line is
considered a continuation of the macro. Thus:
-.Bd -literal -offset indent
-\&.RI foo
-.Ed
-.Pp
-and
-.Bd -literal -offset indent
-\&.RI
-foo
-.Ed
-.Pp
-are equivalent. If two consecutive lines exhibit the latter behaviour,
-an error is raised. Thus, the following is acceptable:
.Bd -literal -offset indent
\&.RI
-\&.I Hello, world.
foo
.Ed
.Pp
-The following, however, is not:
+is equivalent to
+.Sq \&.RI foo .
+If two consecutive lines exhibit the latter behaviour,
+an error is raised. Thus, the following is not acceptable:
.Bd -literal -offset indent
\&.RI
\&.I
.Pp
The
.Sq \&.TP
-macro has similar behaviour, but does not need an empty argument line in
-order to trigger scope.
+macro is similar, but does not need an empty argument line to trigger
+the behaviour.
.\" PARAGRAPH
.Sh MACROS
This section contains a complete list of all
.Nm
-macros, arranged alphabetically, with the number of arguments.
+macros and corresponding number of arguments.
.Pp
.Bl -column "MacroX" "Arguments" -compact -offset indent
.It Em Macro Ta Em Arguments
-.\" $Id: manuals.7,v 1.9 2009/03/24 10:59:50 kristaps Exp $
+.\" $Id: manuals.7,v 1.10 2009/03/26 23:01:26 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
.\"
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: March 24 2009 $
+.Dd $Mdocdate: March 26 2009 $
.Dt manuals 7
.Os
.\" SECTION
.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. Although there are plenty of documents available
-on how to read
-.Ux
-documents, or where to find them, few focus on composition.
-.\" PARAGRAPH
+importantly, a game.
.Pp
This document serves as a tutorial to writing
.Ux
documentation
.Pq Dq manuals .
-If you add something to your operating system, whether it's a new file
-format or directory structure or device driver, it needs documentation.
.\" SECTION
.Sh COMPOSITION
Prepare your composition environment by copying over the manual template
.\" SUBSECTION
.Ss Section Numbering
Find an appropriate section for your manual. There may exist multiple
-manual names per section, so be specific. A table of all available
-manual sections follows:
+manual names per section, so be specific:
.Pp
.\" LIST
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
.Ed
.\" SUBSECTION
.Ss Naming
-Name your component. Be terse, erring on the side of clarity. You may
-want to look for other manuals by that same name before committing:
+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
.Xr man 7
package of
.Xr roff 7 ;
-newer languages such as DocBook, texinfo or schema-driven XML; or even
-ad-hoc conventions such as README files.
+newer languages such as DocBook or texinfo; or even ad-hoc conventions
+such as README files.
.Em Avoid these formats .
-Historical formats fail to capture a manual's semantic content, instead
-only modelling its style. Newer methods requires special,
-system-specific tools and may change or become obsolete over the
-life-time of your component.
.Pp
There are two canonical references for writing mdoc. Read them.
.Pp
.Pp
Use
.Xr cvs 1
-or, if not available,
+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: March 24 2009 $
-.Pp
-If using version control, the first line in your manual should be a
-comment with the
-.Li $Id: manuals.7,v 1.9 2009/03/24 10:59:50 kristaps Exp $
-rcs tag.
+.Dl \&.Dd $Mdocdate: March 26 2009 $
.\" SUBSECTION
.Ss Viewing
-mdoc documents may be paged to your terminal with traditional
-tools such as
-.Xr nroff 1 ,
-.Xr groff 1 ,
-or with newer, more powerful tools such as
-.Xr mandoc 1 :
-.\" DISPLAY
-.Bd -literal -offset indent
-% nroff \-mandoc name.1 | less
-% groff \-Tascii \-mandoc name.1 | less
-% mandoc name.1 | less
-.Ed
-.Pp
-Other output formats are also supported:
-.\" DISPLAY
+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
-% groff \-Tps \-mandoc name.1 | less
-% mandoc \-Thtml name.1 | less
+% 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 and generate
-output:
+Makefiles in order to automatically check your input:
.Bd -literal -offset indent
-\&.SUFFIXES: .html .txt .1 .in
+\&.SUFFIXES: .1 .in
\&.in.1:
mandoc -Wall,error -Tlint $<
cp -f $< $@
-\&.1.html:
- mandoc -Thtml $< >$@
-\&.1.txt:
- mandoc -Tascii $< | col -b >$@
.Ed
.\" SUBSECTION
.Ss Licensing
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 ;
-instead, either fine another way to write long lines, or, at the
-absolute worst, use CPP-style newline escapes.
+.Sq \&Xo/Xc .
+Find another way to structure your line.
.\" SUBSECTION
.Ss References
Other components may be referenced with the
block macros.
.\" SUBSECTION
.Ss Formatting
-.Em Don't style your manual.
+.Em Don't style your manual .
Give it meaningful content. The front-end will worry about formatting
and style.
.\" SECTION
-.\" $Id: mdoc.7,v 1.16 2009/03/26 16:23:22 kristaps Exp $
+.\" $Id: mdoc.7,v 1.17 2009/03/26 23:01:26 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
.\"
\&.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 INPUT ENCODING
.Nm
.Pq ampersand, deprecated
.El
.\" SECTION
-.Sh ONTOLOGY
+.Sh STRUCTURE
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 other circumstances, scope is simply closed out.
.\" SECTION
.Sh SYNTAX
-Macros are generally two and at times three characters in length. The
-syntax of macro invocation depends on its classification.
+Macros are two or three characters in length. The syntax of macro
+invocation depends on its classification.
.Qq \-arg
refers to the macro arguments (which may contain zero or more values).
In these illustrations,
.Nm
macros, arranged ontologically. A
.Qq callable
-macro is may be invoked subsequent to the initial macro-line macro. A
+macro is invoked subsequent to the initial macro-line macro. A
.Qq parsable
macro may be followed by further (ostensibly callable) macros.
.\" SUB-SECTION
git.ckatri.com / mandoc.git / commitdiff