(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-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
