Re: mandoc shortcomings

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Wed, 16 Dec 2015 18:31:17 -0500
    From:        "James K. Lowden" <jklowden%schemamania.org@localhost>
    Message-ID:  <20151216183117.03528236b7f979d13ff7711c%schemamania.org@localhost>

  | One nice feature is that you know you're "done" for any given stage
  | (base, pkgsrc) when /usr/share/man[1-9]  is empty.  

No, you never want that (except when the objective is to save space
perhaps) - those should be left so they can be troff'd (for printing,
or for xman or similar - anything that can print properly formatted
pages rather than the nroff approximations.)

I also believe that the mdoc man page is the one that you want to find
the doc for the format supported by mandoc (man 7 mdoc).

However, I agree that pure mdoc alone is not really sufficient, man
pages are allowed to (and sometimes need to) contain text formatted by
eqn, or tbl, or perhaps even pic (though I've never seen one of those
I admit.)   The page installed in /usr/share/man/manX should have been
preprocessed already, so the man command doesn't need to learn how to
run the preprocessors, but it does need to know how to deal with the
basic *roff formatting commands that those things emit (which can
include diversions, spacing up & down, arbitrary font changes, size
changes, ...)

I also find it kind of amusing that mandoc (well, -mdoc really) can
deal with refer input (kind of) as its sole *roff preprocessor, but
seems to lack the refer ability to access an external database of
references, everything has to be inlined which is kind of weird - refer
format makes sense when it is part of a database, but not nearly as
much when you have to type it every time.

Lastly, mdoc lacks basic formatting selections like "italic please".
It does have .Em (emphasis) which the doc says is "usually italic",
but "usually" isn't good enough - there are common (latin derived mostly)
phrases that are fairly common in man pages (like "e.g.", and "i.e.")
which typographical conventions say should be set in italics.   They
certainly aren't intended to be emphasised in the Em sense however.

I'd suggest that mandoc is fine, or would be, if it would scan the input,
producing nothing, to see if there is any *roff in there that it cannot
handle.  For the vast majority of man pages, there won't be, and it can
just exec a proper formatter to do the work (more slowly).

I also would consider it close to heresy to remove all versions of troff
from NetBSD base - text formatting was the rational for the existence of
unix, if there's any single application that ought to be retained, troff
is it.   It certainly does not need to be groff however...   I do notice
though that mdoc uses (and documents) groffisms (\*[xx] stuff, and there's
at least one macro defined with a 3 letter name) which would make
replacing groff with a more standard troff (heirloom troff or some other)
more of a challenge.   Getting rid of all signs of groffisms from
everywhere would be an excellent idea.

kre