MDOC.SAMPLES (7)

SYNOPSIS

man mdoc.samples

DESCRIPTION

A tutorial sampler for writing manual pages with the -mdoc macro package, a content Ns -based and domain Ns -based formatting package for troff 1 . Its predecessor, the -man 7 package, addressed page layout leaving the manipulation of fonts and other typesetting details to the individual author. In -mdoc , page layout macros make up the "page structure domain" which consists of macros for titles, section headers, displays and lists. Essentially items which affect the physical position of text on a formatted page. In addition to the page structure domain, there are two more domains, the manual domain and the general text domain. The general text domain is defined as macros which perform tasks such as quoting or emphasizing pieces of text. The manual domain is defined as macros that are a subset of the day to day informal language used to describe commands, routines and related files. Macros in the manual domain handle command names, command line arguments and options, function names, function parameters, pathnames, variables, cross references to other manual pages, and so on. These domain items have value for both the author and the future user of the manual page. It is hoped the consistency gained across the manual set will provide easier translation to future documentation tools.

Throughout the manual pages, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.

GETTING STARTED

Since a tutorial document is normally read when a person desires to use the material immediately, the assumption has been made that the user of this document may be impatient. The material presented in the remained of this document is outlined as follows: -enum -offset indent

"TROFF IDIOSYNCRASIES" -tag -width flag -compact -offset indent

"Macro Usage" .

"Passing Space Characters in an Argument" .

"Trailing Blank Space Characters (a warning)" .

"Escaping Special Characters" .

"THE ANATOMY OF A MAN PAGE" -tag -width flag -compact -offset indent

"A manual page template" .

"TITLE MACROS" .

"INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . -tag -width flag -compact -offset indent

"What's in a name..." .

"General Syntax" .

"MANUAL DOMAIN" -tag -width flag -compact -offset indent

"Addresses" .

"Author name" .

"Arguments" .

"Configuration Declarations (section four only)" .

"Command Modifier" .

"Defined Variables" .

"Errno's (Section two only)" .

"Environment Variables" .

"Function Argument" .

"Function Declaration" .

"Flags" .

"Functions (library routines)" .

"Function Types" .