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
