Bug #5025

import and use mandoc

Added by Garrett D'Amore about 3 years ago. Updated about 3 years ago.

Status:ClosedStart date:2014-07-18
Priority:NormalDue date:
Assignee:Garrett D'Amore% Done:

100%

Category:manpage - manual pages
Target version:-
Difficulty:Medium Tags:

Description

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 less Closed 2010-09-29
Related to illumos gate - Bug #614: catman should execute nawk Closed 2011-01-08
Related to illumos gate - Bug #1157: man could support gzipped pages Closed 2011-06-27
Related to illumos gate - Feature #1195: man -k and -s should cooperate Closed 2011-07-10

History

#1 Updated by Electric Monk about 3 years ago

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

git commit 95c635efb7c3b86efc493e0447eaec7aecca3f0f

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

    5025 import and use mandoc
    Reviewed by: Hans Rosenfeld <hans.rosenfeld@nexenta.com>
    Reviewed by: Igor Kozhukhov <ikozhukhov@gmail.com>
    Reviewed by: Robert Mustacchi <rm@joyent.com>
    Reviewed by: Albert Lee <trisk@nexenta.com>
    Approved by: Dan McDonald <danmcd@omniti.com>

Also available in: Atom