Even if ZoL uses legacy man, there is an easy way to convert from mdoc to man (mandoc even has support for doing it). The reverse is very much not the case.
On Mon, Jul 14, 2014 at 3:49 PM, Matthew Ahrens <mahr...@delphix.com> wrote: > If illumos switches to mandoc, It would be great to unify the ZFS manpages > (zfs.1m, zpool.1m, zpool-features.5, zdb.1m, zstreamdump.1m) on illumos and > FreeBSD (at least the majority of the content could be the same). > > The ZFS on Linux project uses the roff-style manpages like illumos > currently does. I wonder if they could/would switch to mandoc too. > > --matt > > > On Mon, Jul 14, 2014 at 12:05 PM, Garrett D'Amore via illumos-discuss < > discuss@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-discuss* | Archives >> <https://www.listbox.com/member/archive/182180/=now> >> <https://www.listbox.com/member/archive/rss/182180/21175667-2019e749> | >> 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
