Mandoc
Encyclopedia
mandoc is an ISC licensed utility for formatting man pages, specifically those written in the mdoc
macro language. Unlike the groff
and older troff
and nroff
tools predominantly used for this purpose, mandoc focusses specifically on manuals and is not suitable for general-purpose type-setting.
Development began in November 2008 specifically to produce CSS
-enabled HTML
forms of manuals in response to the limitations of groff
. mandoc gained initial text-mode output in February 2009. It was then showcased at AsiaBSDCon-2009. In summer of 2010, mandoc was the subject of a NetBSD
-mentored Google Summer of Code
project for producing PostScript
and PDF output alongside the existing text, HTML, and XHTML
outputs. This work was completed in August 2010. mandoc became the default formatter of manuals for OpenBSD
4.8, released in November 2010. It is also part of NetBSD
and DragonFlyBSD, and a third-party port for FreeBSD
. Its advantages were stated as high speed, license, and clean reimplementation.
While mandoc works well with the mdoc
manuals used in the BSD Operating Systems
, it poorly handles older troff macros such as man, me, and the roff language itself. This makes it a poor fit for GNU/Linux distributions, which primarily use man troff macros and low-level roff for their manual pages.
mandoc has built-in support for the troff soelim preprocessor and partial built-in support for tbl
and eqn
. It has strong support for wide-character output.
UNIX manual.
# Pipe output to a pager.
$ mandoc foo.1 | less
# HTML output with a style-sheet.
$ mandoc -Thtml -Ostyle=style.css >foo.1.html
Multibyte (localised) manuals may also be rendered with the included preconv recoding utility. In this example, foo.jp.1 is a Japanese manual encoded in UTF-8
. It assumes that the user's terminal has support for locale
s.
# Pipe wide-character output to a pager.
$ preconv -e utf-8 foo.jp.1 | mandoc -Tlocale | less
# XHTML output with manual links.
$ preconv -e utf-8 foo.jp.1 | mandoc -Txhtml -Oman=%N.%S.xhtml >foo.1.xhtml
MDOC
MDOC can refer to:* Maine Department of Corrections* Michigan Department of Corrections* Mississippi Department of Corrections* Missouri Department of Corrections...
macro language. Unlike the groff
Groff (software)
Groff is the GNU replacement for the troff and nroff text formatters. It is an original implementation written primarily in C++ by James Clark and is modeled after ditroff, including many extensions. The first version, 0.3.1, was released June 1990. The first stable version, 1.04, was announced in...
and older troff
Troff
troff is a document processing system developed by AT&T for the Unix operating system.-History:troff can trace its origins back to a text formatting program called RUNOFF, written by Jerome H. Saltzer for MIT's CTSS operating system in the mid-1960s...
and nroff
Nroff
nroff is a Unix text-formatting program; it produces output suitable for simple fixed-width printers and terminal windows...
tools predominantly used for this purpose, mandoc focusses specifically on manuals and is not suitable for general-purpose type-setting.
Development began in November 2008 specifically to produce CSS
CSS
-Computing:*Cascading Style Sheets, a language used to describe the style of document presentations in web development*Central Structure Store in the PHIGS 3D API*Closed source software, software that is not distributed with source code...
-enabled HTML
HTML
HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....
forms of manuals in response to the limitations of groff
Groff
Groff is an anglicized form of the surname Graf or Graff and of predominantly Swiss and sometimes German origin.Groff may also refer to:People:*Groff family, one of the early 17th century founding families of North America...
. mandoc gained initial text-mode output in February 2009. It was then showcased at AsiaBSDCon-2009. In summer of 2010, mandoc was the subject of a NetBSD
NetBSD
NetBSD is a freely available open source version of the Berkeley Software Distribution Unix operating system. It was the second open source BSD descendant to be formally released, after 386BSD, and continues to be actively developed. The NetBSD project is primarily focused on high quality design,...
-mentored Google Summer of Code
Google Summer of Code
The Google Summer of Code is an annual program, first held from May to August 2005, in which Google awards stipends to hundreds of students who successfully complete a requested free or open-source software coding project during the summer...
project for producing PostScript
PostScript
PostScript is a dynamically typed concatenative programming language created by John Warnock and Charles Geschke in 1982. It is best known for its use as a page description language in the electronic and desktop publishing areas. Adobe PostScript 3 is also the worldwide printing and imaging...
and PDF output alongside the existing text, HTML, and XHTML
XHTML
XHTML is a family of XML markup languages that mirror or extend versions of the widely-used Hypertext Markup Language , the language in which web pages are written....
outputs. This work was completed in August 2010. mandoc became the default formatter of manuals for OpenBSD
OpenBSD
OpenBSD is a Unix-like computer operating system descended from Berkeley Software Distribution , a Unix derivative developed at the University of California, Berkeley. It was forked from NetBSD by project leader Theo de Raadt in late 1995...
4.8, released in November 2010. It is also part of NetBSD
NetBSD
NetBSD is a freely available open source version of the Berkeley Software Distribution Unix operating system. It was the second open source BSD descendant to be formally released, after 386BSD, and continues to be actively developed. The NetBSD project is primarily focused on high quality design,...
and DragonFlyBSD, and a third-party port for FreeBSD
FreeBSD
FreeBSD is a free Unix-like operating system descended from AT&T UNIX via BSD UNIX. Although for legal reasons FreeBSD cannot be called “UNIX”, as the direct descendant of BSD UNIX , FreeBSD’s internals and system APIs are UNIX-compliant...
. Its advantages were stated as high speed, license, and clean reimplementation.
While mandoc works well with the mdoc
MDOC
MDOC can refer to:* Maine Department of Corrections* Michigan Department of Corrections* Mississippi Department of Corrections* Missouri Department of Corrections...
manuals used in the BSD Operating Systems
Berkeley Software Distribution
Berkeley Software Distribution is a Unix operating system derivative developed and distributed by the Computer Systems Research Group of the University of California, Berkeley, from 1977 to 1995...
, it poorly handles older troff macros such as man, me, and the roff language itself. This makes it a poor fit for GNU/Linux distributions, which primarily use man troff macros and low-level roff for their manual pages.
mandoc has built-in support for the troff soelim preprocessor and partial built-in support for tbl
Tbl
Part of the troff suite of Unix document layout tools, tbl is a preprocessor that formats tables.Like the main troff program, tbl uses command lines interspersed with data to be printed...
and eqn
Eqn
Part of the troff suite of Unix document layout tools, eqn is a preprocessor that formats equations for printing. A similar program, neqn, accepted the same input as eqn, but produced output tuned to look better in nroff...
. It has strong support for wide-character output.
Sample Usage
The following demonstrates running mandoc on its own. Usually, it would be called via the man utility. In this example, foo.1 is the name of an mdocMDOC
MDOC can refer to:* Maine Department of Corrections* Michigan Department of Corrections* Mississippi Department of Corrections* Missouri Department of Corrections...
UNIX manual.
# Pipe output to a pager.
$ mandoc foo.1 | less
# HTML output with a style-sheet.
$ mandoc -Thtml -Ostyle=style.css >foo.1.html
Multibyte (localised) manuals may also be rendered with the included preconv recoding utility. In this example, foo.jp.1 is a Japanese manual encoded in UTF-8
UTF-8
UTF-8 is a multibyte character encoding for Unicode. Like UTF-16 and UTF-32, UTF-8 can represent every character in the Unicode character set. Unlike them, it is backward-compatible with ASCII and avoids the complications of endianness and byte order marks...
. It assumes that the user's terminal has support for locale
Locale
In computing, locale is a set of parameters that defines the user's language, country and any special variant preferences that the user wants to see in their user interface...
s.
# Pipe wide-character output to a pager.
$ preconv -e utf-8 foo.jp.1 | mandoc -Tlocale | less
# XHTML output with manual links.
$ preconv -e utf-8 foo.jp.1 | mandoc -Txhtml -Oman=%N.%S.xhtml >foo.1.xhtml