:man| Alphabetical   Categories   About us 
 
MDOC.SAMPLES (7) | | Unix Manual Pages | :man

NAME

mdoc.samples - tutorial sampler for writing BSD manuals with -mdoc

CONTENTS

Synopsis
Description
Getting Started
Troff Idiosyncrasies
Macro Usage
Passing Space Characters in an Argument
Trailing Blank Space Characters
Escaping Special Characters
The Anatomy Of A Man Page
A manual page template
Title Macros
Introduction Of Manual And General Text Domains
What’s in a name...
General Syntax
Manual Domain
Address Macro
Author Name
Argument Macro
Configuration Declaration (section four only)
Command Modifier
Defined Variables
Errno’s (Section two only)
Environment Variables
Function Argument
Function Declaration
Flags
Functions (library routines)
Function Type
Interactive Commands
Name Macro
Options
Pathnames
Variables
Manual Page Cross References
General Text Domain
AT&T Macro
BSD Macro
FreeBSD Macro
UNIX Macro
Enclosure and Quoting Macros
No-Op or Normal Text Macro
No Space Macro
Section Cross References
References and Citations
Return Values
Trade Names (or Acronyms and Type Names)
Extended Arguments
Page Structure Domain
Section Headers
Paragraphs and Line Spacing.
Keeps
Examples and Displays
Font Modes
Tagged Lists and Columns
Predefined Strings
Diagnostics
Groff, Troff And Nroff
Files
See Also
Bugs

SYNOPSIS

man mdoc.samples

DESCRIPTION

A tutorial sampler for writing BSD manual pages with the -mdoc macro package, a content -based and domain -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 BSD 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 Unix 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:
  1. "TROFF IDIOSYNCRASIES"
    "Macro Usage".
    "Passing Space Characters in an Argument".
    "Trailing Blank Space Characters (a warning)".
    "Escaping Special Characters".
  2. "THE ANATOMY OF A MAN PAGE"
    "A manual page template".
  3. "TITLE MACROS".
  4. "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS".
    "What’s in a name...".
    "General Syntax".
  5. "MANUAL DOMAIN"
    "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".
    "Interactive Commands".
    "Names".
    "Options".
    "Pathnames".
    "Variables".
    "Cross References".
  6. "GENERAL TEXT DOMAIN"
    "AT&T Macro".
    "BSD Macro".
    "FreeBSD Macro".
    "UNIX Macro".
    "Enclosure/Quoting Macros"
    "Angle Bracket Quote/Enclosure".
    "Bracket Quotes/Enclosure".
    "Double Quote macro/Enclosure".
    "Parenthesis Quote/Enclosure".
    "Single Quotes/Enclosure".
    "Prefix Macro".
    "No-Op or Normal Text Macro".
    "No Space Macro".
    "Section Cross References".
    "References and Citations".
    "Return Values (sections two and three only)"
    "Trade Names (Acronyms and Type Names)".
    "Extended Arguments".
  7. "PAGE STRUCTURE DOMAIN"
    "Section Headers".
    "Paragraphs and Line Spacing".
    "Keeps".
    "Displays".
    "Font Modes (Emphasis, Literal, and Symbolic)".
    "Lists and Columns".
  8. "PREDEFINED STRINGS"
  9. "DIAGNOSTICS"
  10. "FORMATTING WITH GROFF, TROFF AND NROFF"
  11. "BUGS"

TROFF IDIOSYNCRASIES

The -mdoc package attempts to simplify the process of writing a man page. Theoretically, one should not have to learn the dirty details of troff(1) to use -mdoc; however, there are a few limitations which are unavoidable and best gotten out of the way. And, too, be forewarned, this package is not fast.

Macro Usage

As in troff(1), a macro is called by placing a ‘.’ (dot character) at the beginning of a line followed by the two character name for the macro. Arguments may follow the macro separated by spaces. It is the dot character at the beginning of the line which causes troff(1) to interpret the next two characters as a macro name. To place a ‘.’ (dot character) at the beginning of a line in some context other than a macro invocation, precede the ‘.’ (dot) with the ‘\&’ escape sequence. The ‘\&’ translates literally to a zero width space, and is never displayed in the output.

In general, troff(1) macros accept up to nine arguments, any extra arguments are ignored. Most macros in -mdoc accept nine arguments and, in limited cases, arguments may be continued or extended on the next line (See Extensions). A few macros handle quoted arguments (see Passing Space Characters in an Argument below).

Most of the -mdoc general text domain and manual domain macros are special in that their argument lists are parsed for callable macro names. This means an argument on the argument list which matches a general text or manual domain macro name and is determined to be callable will be executed or called when it is processed. In this case the argument, although the name of a macro, is not preceded by a ‘.’ (dot). It is in this manner that many macros are nested; for example the option macro, ‘.Op’, may call the flag and argument macros, ‘Fl’ and ‘Ar’, to specify an optional flag with an argument:

[-s bytes] is produced by .Op Fl s Ar bytes

To prevent a two character string from being interpreted as a macro name, precede the string with the escape sequence ‘\&’:

[Fl s Ar bytes] is produced by .Op \&Fl s \&Ar bytes

Here the strings ‘Fl’ and ‘Ar’ are not interpreted as macros. Macros whose argument lists are parsed for callable arguments are referred to as parsed and macros which may be called from an argument list are referred to as callable throughout this document and in the companion quick reference manual mdoc(7). This is a technical faux pas as almost all of the macros in -mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, the term parsed has been used.

Passing Space Characters in an Argument

Sometimes it is desirable to give as one argument a string containing one or more blank space characters. This may be necessary to defeat the nine argument limit or to specify arguments to macros which expect particular arrangement of items in the argument list. For example, the function macro ‘.Fn’ expects the first argument to be the name of a function and any remaining arguments to be function parameters. As "ANSI C" stipulates the declaration of function parameters in the parenthesized parameter list, each parameter is guaranteed to be at minimum a two word string. For example, int foo.

There are two possible ways to pass an argument which contains an embedded space. Implementation note: Unfortunately, the most convenient way of passing spaces in between quotes by reassigning individual arguments before parsing was fairly expensive speed wise and space wise to implement in all the macros for AT&T troff. It is not expensive for groff but for the sake of portability, has been limited to the following macros which need it the most:

Cd Configuration declaration (section 4 SYNOPSIS)
Bl Begin list (for the width specifier).
Em Emphasized text.
Fn Functions (sections two and four).
It List items.
Li Literal text.
Sy Symbolic text.
%B Book titles.
%J Journal names.
%O Optional notes for a reference.
%R Report title (in a reference).
%T Title of article in a book or journal.

One way of passing a string containing blank spaces is to use the hard or unpaddable space character ‘\ ’, that is, a blank space preceded by the escape character ‘\’. This method may be used with any macro but has the side effect of interfering with the adjustment of text over the length of a line. Troff sees the hard space as if it were any other printable character and cannot split the string into blank or newline separated pieces as one would expect. The method is useful for strings which are not expected to overlap a line boundary. For example:

fetch char *str
is created by ‘.Fn fetch char\ *str
fetch "char *str" can also be created by ‘.Fn fetch ""char *str""

If the ‘\’ or quotes were omitted, ‘.Fn’ would see three arguments and the result would be:

fetch char *str

For an example of what happens when the parameter list overlaps a newline boundary, see the BUGS section.

Trailing Blank Space Characters

Troff can be confused by blank space characters at the end of a line. It is a wise preventive measure to globally remove all blank spaces from <blank-space><end-of-line> character sequences. Should the need arise to force a blank character at the end of a line, it may be forced with an unpaddable space and the ‘\&’ escape character. For example, ‘string\ \&’.

Escaping Special Characters

Special characters like the newline character ‘\n’, are handled by replacing the ‘\’ with ‘\e’ (e.g. ‘\en’) to preserve the backslash.

THE ANATOMY OF A MAN PAGE

The body of a man page is easily constructed from a basic template found in the file /usr/share/misc/mdoc.template. Several example man pages can also be found in /usr/share/examples/mdoc.

A manual page template


.\" The following requests are required for all man pages.
.Dd Month day, year
.Os OPERATING_SYSTEM [version/release]
.Dt DOCUMENT_TITLE [section number] [volume]
.Sh NAME
.Nm name
.Nd one line description of name
.Sh SYNOPSIS
.Sh DESCRIPTION
.\" The following requests should be uncommented and
.\" used where appropriate. This next request is
.\" for sections 2 and 3 function return values only.
.\" .Sh RETURN VALUES
.\" This next request is for sections 1, 6, 7 & 8 only
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" This next request is for sections 1, 6, 7 & 8 only
.\"(command return values (to shell) and
.\" fprintf/stderr type diagnostics)
.\" .Sh DIAGNOSTICS
.\" The next request is for sections 2 and 3 error
.\" and signal handling only.
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Sh CONFORMING TO
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh BUGS


Share this page

     Follow us

Facebook Twitter Google+ LinkedIn


 
Created by Blin Media, 2008-2013