Bug #5025


import and use mandoc

Added by Garrett D'Amore over 9 years ago. Updated over 9 years ago.

manpage - manual pages
Start date:
Due date:
% Done:


Estimated time:
Gerrit CR:
External Bug:


This is an RFE to import mandoc (mdocml) for formatting man pages, and to update the man program to use it for formatting rather than troff. This brings a number of key benefits:

1. Ability to cope with mdoc(5) and man(5) pages.
2. Facilitates collaboration with BSD projects that prefer mdoc(5)
3. Semantic markup that is easier to read, write, and maintain than physical markup
4. Support for numerous output formats (ASCII, UTF-8, PostScript, HTML/XHTML, PDF, even man(5)).
5. Programmatic validation of man format (-T lint)
6. A lighter-weight, and more maintainable (and maintained actively) code base than troff
7. Support for locale based pages encoded in UTF-8 or other encodings (CSI, which troff isn't)
8. Ultimately allowing us to move troff out of tree at some later date

As part of this effort there are a few changes -- the whatis database is slightly different and renamed to whatis (from windex), we lose any semblance of support for SGML, and we don't support generation of actual preformatted (cat) pages (there is no point in that anymore anyway).

We're also proposing to replace the attributes(5) table in new pages with individual sections labeled CODE SET INDEPENDENCE, ARCHITECTURE, MT-LEVEL, and INTERFACE STABILITY. The content of those sections will largely remain the same as in the attributes table, except that there shall be no need to reference other sections (e.g. no "See notes"), instead the details can be inlined.

Initially some new pages will be in mandoc format (e.g. mandoc(1), and mdoc(5)!), and we will gradually convert existing pages to mdoc(5), which shall be come the new preferred format for reference man pages.

We will also activate pbchk and make check to verify formatting with mandoc -Tlint.

Note that much of the work involved here was initially performed by Yuri Pankov at Nexenta. I'm just focusing on finishing it up (some final touches and adaptations for recent updates in the gate, etc.)

Related issues

Related to illumos gate - Feature #281: Make man(1) suck slightly lessClosed2010-09-29

Related to illumos gate - Bug #614: catman should execute nawkClosed2011-01-08

Related to illumos gate - Bug #1157: man could support gzipped pagesClosed2011-06-27

Related to illumos gate - Feature #1195: man -k and -s should cooperateClosed2011-07-10

Actions #1

Updated by Electric Monk over 9 years ago

  • Status changed from New to Closed
  • % Done changed from 90 to 100

git commit 95c635efb7c3b86efc493e0447eaec7aecca3f0f

commit  95c635efb7c3b86efc493e0447eaec7aecca3f0f
Author: Garrett D'Amore <>
Date:   2014-07-21T16:20:34.000Z

    5025 import and use mandoc
    Reviewed by: Hans Rosenfeld <>
    Reviewed by: Igor Kozhukhov <>
    Reviewed by: Robert Mustacchi <>
    Reviewed by: Albert Lee <>
    Approved by: Dan McDonald <>


Also available in: Atom PDF