import and use mandoc
|Assignee:||Garrett D'Amore||% Done:|
|Category:||manpage - manual pages|
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.)
#1 Updated by Electric Monk over 4 years ago
- % Done changed from 90 to 100
- Status changed from New to Closed
commit 95c635efb7c3b86efc493e0447eaec7aecca3f0f Author: Garrett D'Amore <email@example.com> Date: 2014-07-21T16:20:34.000Z 5025 import and use mandoc Reviewed by: Hans Rosenfeld <firstname.lastname@example.org> Reviewed by: Igor Kozhukhov <email@example.com> Reviewed by: Robert Mustacchi <firstname.lastname@example.org> Reviewed by: Albert Lee <email@example.com> Approved by: Dan McDonald <firstname.lastname@example.org>
Also available in: Atom