Actually a lot of work has been done on mandoc in the past two years.. It might be worth starting with Yuri's work, and updating it to import a newer drop from the upstream.
On Mon, Jul 14, 2014 at 12:21 PM, Garrett D'Amore <garr...@damore.org> wrote: > Thanks Gordon. I agree that starting with Yuri's work probably makes the > most sense. I'll have a look. I'm also interested to know if Yuri is > still at Nexenta, and is he interested in continuing to work on this > project? (I sent him a message to his Nexenta address under separate > cover.) > > - Garrett > > > On Mon, Jul 14, 2014 at 12:19 PM, Gordon Ross <gordon.r...@nexenta.com> > wrote: > >> I think this would be helpful. I don't have much preference on when it >> happens, but I suspect incrementally will be more practical given our >> limited contributor time. >> >> How about we start by getting the mandoc tools integrated? >> Yurip has that already in our fork of illumos: >> https://github.com/Nexenta/illumos-nexenta/tree/master/usr/src/cmd/mandoc >> (and other changes) >> >> Gordon >> >> >> >> >> >> On Mon, Jul 14, 2014 at 3:05 PM, 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. >>> >>> The other item of note is our ATTRIBUTES section and table. I'd really >>> like to nuke these tables (they are some of the worst for consistency in >>> markup and even content). I'd propose that in order to avoid losing the >>> data there, we create the following new sections: ARCHITECTURE, CSI, >>> INTERFACE STABILITY, MT-LEVEL, and STANDARD. (Actually I might rename >>> these as: ARCHITECTURE, CODE SET INDEPENDENCE, INTERFACE STABILITY, >>> MULTITHREADED SAFETY, and STANDARDS. (Possibly STANDARDS could be omitted >>> entirely since almost every reference to it in existing pages simply points >>> users to standards(5) instead of providing any useful content directly in >>> the page.) >>> >>> As to man(1) and compatibility; it is my intention that we retain the >>> same user interface for man(1), apropos(1), and whatis(1) -- or at least >>> one that is upwardly compatible. This may be achieved by several >>> approaches -- either ensuring the mandoc version of man(1) supports all of >>> our usages (enhancing it as needed), or perhaps more simply just gutting >>> our man(1) and making it call mandoc(1) for formatting. (This last is >>> probably a much simpler and safer way to go.) End users shouldn't notice, >>> really, except for trivial differences in formatted output. I'm open to >>> the idea that we don't need to retain any compatibility of makewhatis(1m), >>> or the database(s) themselves (the windex files). >>> >>> I am specifically suggesting that any support SGML markup be tossed. >>> (Actually, that has mostly already happened -- we don't support sgml2roff >>> anymore, although man(1) seems to have some of the legacy support still in >>> it.) >>> >>> I'm also not proposing to support pre formatted man pages. Does anyone >>> use those? >>> >>> Likewise, man.cf seems to be undocumented, and is not even present on >>> my system. I wonder, do people use/depend on it? >>> >>> - Garrett >>> *illumos-developer* | Archives >>> <https://www.listbox.com/member/archive/182179/=now> >>> <https://www.listbox.com/member/archive/rss/182179/21175074-7782178a> | >>> Modify >>> <https://www.listbox.com/member/?&;> >>> Your Subscription <http://www.listbox.com> >>> >> >> > ------------------------------------------- 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
