Mandoc

Last updated
mandoc
Initial releaseNovember 2008
Stable release
1.14.6 / September 23, 2021;22 months ago (2021-09-23) [1]
Repository
Written in C
Type Typesetting
License ISC license
Website mandoc.bsd.lv

mandoc (historically called mdocml) is a utility used for formatting man pages in BSD Operating Systems (e.g. NetBSD), specifically those written in the mdoc and man macro languages. Unlike the groff and older troff and nroff tools that are predominantly used for this purpose by tools such as man, mandoc focuses specifically on manuals and is not suitable for general-purpose type-setting.

Contents

mandoc is mainly used to format the mdoc manuals used in the BSD Operating Systems, but it also implements most of the man macros used in Linux distributions, as well as a subset of roff commands occasionally intermixed with the man macros. [2] [1] : 1.14.5  It does not support other macro sets such as mm and ms, or any typesetting features like hyphenation, fonts and alignment. [2] : compatibility  Simple styling such as bold and italics are supported, but italicized text is replaced by underlined text on the terminal. [3] [4]

mandoc has built-in support for the troff soelim (inclusion) preprocessor and partial built-in support for tbl and eqn. It has strong support for UTF-8 output. It can also use the semantic information in mdoc manuals to implement semantic search, which before version 1.4.1, relied on sqlite. [1] : 1.4.1 

History

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. [5] It was then showcased at AsiaBSDCon-2009. [6] [7] [8] In summer of 2010, mandoc was the subject of a NetBSD-mentored Google Summer of Code project [9] for producing PostScript and PDF output alongside the existing text, HTML, and XHTML outputs. This work was completed in August 2010. [10] mandoc became the default formatter of manuals for OpenBSD 4.8, released in November 2010. [11] [12] It later became the default formatter in NetBSD, FreeBSD, illumos, Void Linux, Alpine Linux and macOS, and is also included in DragonFlyBSD, MINIX 3, Debian, Ubuntu, Gentoo, and Fedora. [13] Its advantages were stated as high speed, [14] license, and clean reimplementation.

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 mdoc UNIX manual. [15] 

# Page manual to the terminal.$mandoc-lfoo.1 # HTML output with a style-sheet.$mandoc-Thtml-Ostyle=style.css>foo.1.html

Multibyte (localised) manuals may also be rendered without preprocessing. In this example, foo.jp.1 is a Japanese manual encoded in UTF-8. mandoc will automatically detect the encoding. [15] 

# Page wide-character manual to the terminal.$mandoc-lfoo.jp.1

The included apropos implementation can use semantic information in search: [16] 

# Search for all functions starting with 'str' having return type size_t:$apropos-s3Ft=size_t-aNm~^str

Other features

Related Research Articles

troff, short for "typesetter roff", is the major component of a document processing system developed by Bell Labs for the Unix operating system. troff and the related nroff were both developed from the original roff.

DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of documentation.

man page Unix software documentation

A man page is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs, formal standards and conventions, and even abstract concepts. A user may invoke a man page by issuing the man command.

nroff is a text-formatting program on Unix and Unix-like operating systems. It produces output suitable for simple fixed-width printers and terminal windows. It is an integral part of the Unix help system, being used to format man pages for display.

Joseph Frank Ossanna, Jr. was an electrical engineer and computer programmer who worked as a member of the technical staff at the Bell Telephone Laboratories in Murray Hill, New Jersey. He became actively engaged in the software design of Multics, a general-purpose operating system used at Bell.

roff is a typesetting markup language. As the first Unix text-formatting computer program, it is a predecessor of the nroff and troff document processing systems.

In software development, Make is a build automation tool that builds executable programs and libraries from source code by reading files called makefiles which specify how to derive the target program. Though integrated development environments and language-specific compiler features can also be used to manage a build process, Make remains widely used, especially in Unix and Unix-like operating systems.

The C standard library or libc is the standard library for the C programming language, as specified in the ISO C standard. Starting from the original ANSI C standard, it was developed at the same time as the C library POSIX specification, which is a superset of it. Since ANSI C was adopted by the International Organization for Standardization, the C standard library is also called the ISO C library.

deb is the format, as well as filename extension of the software package format for the Debian Linux distribution and its derivatives.

cksum Unix command

cksum is a command in Unix and Unix-like operating systems that generates a checksum value for a file or stream of data. The cksum command reads each file given in its arguments, or standard input if no arguments are provided, and outputs the file's 32-bit cyclic redundancy check (CRC) checksum and byte count. The CRC output by cksum is different from the CRC-32 used in zip, PNG and zlib.

Signals are standardized messages sent to a running program to trigger specific behavior, such as quitting or error handling. They are a limited form of inter-process communication (IPC), typically used in Unix, Unix-like, and other POSIX-compliant operating systems.

Part of the troff suite of Unix document layout tools, tbl is a preprocessor that formats tables in preparation for processing with troff/nroff.

The following tables compare general and technical information for a number of documentation generators. Please see the individual products' articles for further information. Unless otherwise specified in footnotes, comparisons are based on the stable versions without any add-ons, extensions or external programs. Note that many of the generators listed are no longer maintained.

In computing, a shebang is the character sequence consisting of the characters number sign and exclamation mark at the beginning of a script. It is also called sharp-exclamation, sha-bang, hashbang, pound-bang, or hash-pling.

groff (software) Unix typesetting software used for man pages

groff is a typesetting system that creates formatted output when given plain text mixed with formatting commands. It is the GNU replacement for the troff and nroff text formatters.

In computing, Pic is a domain-specific programming language by Brian Kernighan for specifying line diagrams. The language contains predefined basic linear objects: line, move, arrow, and spline, the planar objects box, circle, ellipse, arc, and definable composite elements. Objects are placed with respect to other objects or absolute coordinates. A liberal interpretation of the input invokes default parameters when objects are incompletely specified. An interpreter translates this description into concrete drawing commands in a variety of possible output formats. Pic is a procedural programming language, with variable assignment, macros, conditionals, and looping. The language is an example of a little language originally intended for the comfort of non-programmers in the Unix environment.

utmp, wtmp, btmp and variants such as utmpx, wtmpx and btmpx are files on Unix-like systems that keep track of all logins and logouts to the system.

In computing, apropos is a command to search the man page files in Unix and Unix-like operating systems. Apropos takes its name from the French "à propos" which means about. It is particularly useful when searching for commands without knowing their exact names.

In computing, tty is a command in Unix and Unix-like operating systems to print the file name of the terminal connected to standard input.

References

  1. 1 2 3 "Release notes". September 23, 2021.
  2. 1 2 roff(7)  –  OpenBSD Miscellaneous Information Manual
  3. ↑ "Italics and colour in manual pages on a nosh user-space virtual terminal". jdebp.eu.
  4. ↑ mandoc(1)  –  FreeBSD General Commands Manual. "Font styles are applied by using back-spaced encoding..."
  5. ↑ "Source history". Mdocml.bsd.lv. Retrieved 2010-12-18.
  6. ↑ "AsiaBSDCon 2009: Deprecating groff for BSD manual display". 2009.asiabsdcon.org. 2009-03-15. Retrieved 2010-12-18.
  7. ↑ "Deprecating groff for BSD manual display" (PDF). Retrieved 2010-12-18.
  8. ↑ "Video of AsiaBSDCon presentation". Youtube.com. Retrieved 2010-12-18.
  9. ↑ "Google Summer of Code: mandoc_ps". Netbsd-soc.sourceforge.net. Retrieved 2010-12-18.
  10. ↑ "NetBSD Blog". Blog.netbsd.org. 2010-08-11. Retrieved 2010-12-18.
  11. ↑ "OpenBSD 4.8". Openbsd.org. 2010-11-01. Retrieved 2010-12-18.
  12. ↑ "groff deleted from tree".
  13. ↑ "Availability of the mandoc toolset". Mdocml.bsd.lv.
  14. ↑ Unangst, Ted. "mandoc speed benchmarks".
  15. 1 2 3 mandoc(1)  –  OpenBSD General Commands Manual
  16. ↑ apropos(1)  –  OpenBSD General Commands Manual
  17. ↑ man.cgi(8)  –  OpenBSD System Manager's Manual
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.