"onf" <o...@disroot.org> writes:
I don't prefer it because I am some sort of BSD fanboy; I prefer
it
because it's easier to use and allows me to capture the meaning
of
the words I write, which then translates nicely into a visually
consistent, high quality output without much effort on my part.
i'd like to basically echo this. (Side note: i use both Gentoo and
OpenBSD, and appreciate each in various ways.)
i'm the porter/maintainer of mdoc(7) versions of documentation for
a number of packages in the skaware/s6 ecosystem. To give a rough
sense of the number of macros involved in these ports (and
obviously a not-insignificant underestimate, since the following
doesn't include the many instances of callable/'inline' macros):
$ ag '^\.[a-zA-Z]{2} ' *-man-pages | wc -l
19475
When i started this effort, i'd never created a man page
before. In looking into man(7), i found it quite challenging,
because it required me to remember conventions for associating
particular semantics with particular presentations - and i've done
enough Web stuff and document conversions to have Opinions™ about
separating content and presentation. (Which is one of the reasons
i'm not a fan of Markdown.) Whereas mdoc(7), despite having more
macros than man(7), has macros whose names are usually indicative
of their semantics; and i also don't have to worry about the sort
of issues discussed in the ox-man.el thread. This resulted in less
cognitive load for me overall. i've found mdoc(7) a pleasure to
work with.
(My first port was of the documentation for the s6 package, and
unfortunately, my learning-on-the-fly shows. Ingo has kindly given
me good feedback regarding this, but many of his
suggestions/recommendations are not yet implemented, due to lack
of Tuits - assistance with improvements would certainly be
welcome.)
Alexis.
