On 14 Jul 2014, at 21:05, Garrett D'Amore via illumos-developer <develo...@lists.illumos.org> wrote:
> (Sorry for the cross post, but this proposal potentially impacts a bunch of > folks, so I want to get it out here. Please read and respond only after > you've read, and only if you have specific concerns with this proposal. > Please send your +1's to /dev/null. :-) > > For a variety of reasons, I'm proposing that we import mandoc (see > http://mdocml.bsd.lv for details) into illumos, and move to using mdoc for > formatting man pages. > > The reasons for this are: > > a) mdoc supports simpler, cleaner, semantic (instead of physical) markup. > This can lead to much greater consistency between pages. (Our markup is > horribly inconsistent, and the auto-generated -- from SGML -- portion of it > is nigh unreadable.) > > b) mandoc is now mature and widely used (all the BSDs use it, and have for > many years. The markup language is ~20 years old.) > > c) it will facilitate collaboration between BSD groups and illumos -- we > already collaborate quite a bit, but this will just make it that much > easier. > > d) mandoc toolset is nice and small -- simpler than *roff and co. Very > lightweight > > e) mandoc supports native generation of PDF, PostScript, HTML, and text. > > f) There are folks actually continuing to sustain and improve this tool > chain. Solaris (err AT&T) derived troff and nroff by comparison are > practically dead, and almost undebuggable with horrible code written back > when linkers didn't support symbols with more than 6 characters in them. > > g) mandoc can format man(5) pages as well. So importing from foreign > sources should be straight-forward. > > h) mandoc supports formatting pages for specific locales and byte > encodings. (So pages can be written for zh_CN.UTF-8 or whatever, presuming > someone steps up to perform such a translation or authoring.) (Legacy > troff tools like tbl are not CSI capable.) > > Yuri Pankov did a lot of work on this already, and assuming he's agreeable > and still has the work handy, I'd like to use that a basis for the import. > > Ideally I'd like to convert all of the pages we have in illumos to mdoc > semantic markup. That will address the inconsistencies in the pages giving > us much more uniform markup and display. It also will make it easier > (lots!) to maintain them. As someone who recently went through a huge > swath of man page edits (libc locale stuff), I would have loved to have a > simpler semantic markup. Dealing with our physical markup is incredibly > tedious and error prone. > > It's an outstanding question as to whether we do these incrementally or all > at once. I'm willing to go either way. Obviously incremental improvement > is *easier*, but with less immediate benefit. > There are 108 new man pages in a libm package. I do prefer to import them as they are, so an incremental change here will be helpful. — Piotr Jasiukajtis ------------------------------------------- illumos-discuss Archives: https://www.listbox.com/member/archive/182180/=now RSS Feed: https://www.listbox.com/member/archive/rss/182180/21175430-2e6923be Modify Your Subscription: https://www.listbox.com/member/?member_id=21175430&id_secret=21175430-6a77cda4 Powered by Listbox: http://www.listbox.com
