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
