{{Short description|Manpage formatter}} {{lowercase title}} {{Infobox software | name = mandoc | screenshot = | caption = | author = | developer = | released = November 2008 | latest release version = 1.14.6 | latest release date = {{Start date and age|2021|09|23}}<ref name=NEWS>{{cite web | url = http://mandoc.bsd.lv/NEWS | title = Release notes | date = September 23, 2021}}</ref> | programming language = C | genre = Typesetting | license = ISC license }} '''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 {{Code|man}}, mandoc focuses specifically on manuals and is not suitable for general-purpose type-setting.
{{Code|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.<ref name=roff7>{{man|7|roff|OpenBSD}}</ref><ref name=NEWS/>{{rp|at=1.14.5}} It does not support other macro sets such as ''mm'' and ''ms'', or any typesetting features like hyphenation, fonts and alignment.<ref name=roff7/>{{rp|at=compatibility}} Simple styling such as bold and italics are supported, but italicized text is replaced by underlined text on the terminal.<ref>{{cite web |title=Italics and colour in manual pages on a nosh user-space virtual terminal |url=https://jdebp.uk/Softwares/nosh/italics-in-manuals.html |website=jdebp.eu}}</ref><ref>{{man|1|mandoc|FreeBSD}}. "Font styles are applied by using back-spaced encoding..."</ref>
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.<ref name=NEWS/>{{rp|at=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.<ref name="cvsweb">{{cite web|url=http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml|title=Source history|date=|publisher=Mdocml.bsd.lv|accessdate=2010-12-18}}</ref> It was then showcased at AsiaBSDCon-2009.<ref name="absdcon">{{cite web|url=http://2009.asiabsdcon.org/live/abc2009-P6B.html|title=AsiaBSDCon 2009: Deprecating groff for BSD manual display|date=2009-03-15|publisher=2009.asiabsdcon.org|accessdate=2010-12-18}}</ref><ref name="absdconpdf">{{cite web|url=http://2009.asiabsdcon.org/papers/abc2009-P6B-paper.pdf|title=Deprecating groff for BSD manual display|date=|format=PDF|accessdate=2010-12-18}}</ref><ref name="absdconvid">{{cite web|url=https://www.youtube.com/watch?v=z25FFo01Zpw|title=Video of AsiaBSDCon presentation|date=|publisher=Youtube.com|author= |accessdate=2010-12-18}}</ref> In summer of 2010, mandoc was the subject of a NetBSD-mentored Google Summer of Code project<ref name="mandoc_ps">{{cite web|url=https://netbsd-soc.sourceforge.net/projects/mandoc_ps/|title=Google Summer of Code: mandoc_ps|date=|publisher=Netbsd-soc.sourceforge.net|accessdate=2010-12-18}}</ref> for producing PostScript and PDF output alongside the existing text, HTML, and XHTML outputs. This work was completed in August 2010.<ref>{{cite web|url=http://blog.netbsd.org/tnf/entry/google_summer_of_code_postscript|title=NetBSD Blog|date=2010-08-11|publisher=Blog.netbsd.org|accessdate=2010-12-18}}</ref> mandoc became the default formatter of manuals for OpenBSD 4.8, released in November 2010.<ref name="openbsd">{{cite web|url=http://www.openbsd.org/48.html|title=OpenBSD 4.8|date=2010-11-01|publisher=Openbsd.org|accessdate=2010-12-18}}</ref><ref>{{cite web|url=http://www.undeadly.org/cgi?action=article&sid=20110314142734|title=groff deleted from tree}}</ref> 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.<ref>{{cite web|url=http://mdocml.bsd.lv/ports.html|title=Availability of the mandoc toolset|publisher=Mdocml.bsd.lv}}</ref> Its advantages were stated as high speed,<ref name="speed">{{cite web|last=Unangst|first=Ted|url=http://marc.info/?l=openbsd-misc&m=127070066732223|title=mandoc speed benchmarks}}</ref> license, and clean reimplementation.
==Sample usage== The following demonstrates running <code>mandoc</code> on its own. Usually, it would be called via the man utility. In this example, <code>foo.1</code> is the name of an ''mdoc'' UNIX manual.<ref name=mandoc>{{man|1|mandoc|OpenBSD}}</ref> <syntaxhighlight lang="console"> $ # Page manual to the terminal. $ mandoc -l foo.1 $ # HTML output with a style-sheet. $ mandoc -Thtml -Ostyle=style.css >foo.1.html </syntaxhighlight> Multibyte (localised) manuals may also be rendered without preprocessing. In this example, <code>foo.jp.1</code> is a Japanese manual encoded in UTF-8. mandoc will automatically detect the encoding.<ref name=mandoc/> <syntaxhighlight lang="console"> $ # Page wide-character manual to the terminal. $ mandoc -l foo.jp.1 </syntaxhighlight> The included apropos implementation can use semantic information in search:<ref name=apropos>{{man|1|apropos|OpenBSD}}</ref> <syntaxhighlight lang="console"> $ # Search for all functions starting with 'str' having return type size_t: $ apropos -s 3 Ft=size_t -a Nm~^str </syntaxhighlight>
== Other features == * <code>mandoc</code> supports HTML 5, PostScript, and PDF output via the {{code|-T}} parameter.<ref name=mandoc/> * <code>man.cgi</code> is a CGI program designed to display manual pages on the web. OpenBSD uses it to format all its manual pages.<ref name=man.cgi>{{man|8|man.cgi|OpenBSD}}</ref>
==References== {{reflist|30em}}
==External links== * [https://mandoc.bsd.lv/ The mandoc UNIX manpage compiler toolset] * [https://man.openbsd.org/ OpenBSD online manpages], generated by mandoc's man.cgi program * [http://www.undeadly.org/cgi?action=article&sid=20100604082319&mode=expanded Undeadly article on mandoc] * [https://netbsd-soc.sourceforge.net/projects/mandoc_ps/ Google Summer of Code mandoc_ps project site] - work on PostScript support * [http://freecode.com/projects/mandoc Freecode page for mandoc] - used until 1.12.2
{{OpenBSD}}
Category:BSD software Category:OpenBSD software using the ISC license