I see. Lets assume that this project won't impact a large import like that, no matter whether we do an incremental change or otherwise.
On Mon, Jul 14, 2014 at 1:14 PM, Piotr Jasiukajtis < [email protected]> wrote: > > On 14 Jul 2014, at 21:05, Garrett D'Amore via illumos-developer < > [email protected]> 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
