mandoc shortcomings

["James K. Lowden" <jklowden%schemamania.org@localhost>]

I recently upgraded to NetBSD 7.0 and my early experience with the new 
mandoc-based man utility is less than wonderful.  I'm concerned
there's a quality-control issue, because the problem could have
been detected in advance of the release: "mandoc -Wall" reports many
errors for the file.  

I should qualify that by saying I didn't use sysinst to prepare the
system.  It's possible some of my problems are of my own making.
postinstall(8) reports no problems for catpages and manconf.  

The page in question is /usr/share/man/man7/groff.7.  mandoc does not
render the Short Reference section correctly:  

$ mandoc $(man -w  7 groff) | col -b \
	| sed  -Ene '/Short/,/Assign/p' 
 Request Short Reference
       Empty line, ignored.
                 Useful for structuring documents.
       Complete line is a comment.
       Print     string on standard error, exit program.
       Begin line adjustment for output lines in current adjust mode.
       Start line adjustment in mode
                 c (c=l,r,b,n).
       Assign format

It should look like this: 

$ nroff -mandoc  $(man -w  7 groff) | col -b \
	| sed  -Ene '/Short/,/Assign/p'
 Request Short Reference
       .         Empty line, ignored.  Useful for structuring documents.
       .\" anything
                 Complete line is a comment.
       .ab string
                 Print string on standard error, exit program.
       .ad       Begin line adjustment for  output  lines  in  current
adjust mode.
       .ad c     Start line adjustment in mode c (c=l,r,b,n).
       .af register c
                 Assign format c to register (c=l,i,I,a,A).

A glance at groff.7 shows the file defines a REQ macro that is used to
represent requests.  mandoc appears not to interpret it correctly.  

Points of concern: 

1.  The documentation for man(1) does not mention mandoc.  In fact,
man.conf(5) doesn't either, although it mentions nroff in passing.
Only by looking at /etc/man.conf was I reminded of a line in the
release notes, "Man pages are now handled with mandoc(1)...", and of
discussions on this list about taking that step.  Because man pages
have been formatted with some version of nroff since the Unix epoch
(roughly), the user could be forgiven for assuming it's still true.  

2.  mandoc is evidently not ready to parse all manpages, not even just
those in base.  Until it can parse arbitrary troff requests, some kind
of fallback to nroff is needed.  Until then, removing groff would mean
a loss of functionality.  

3.  For the present, we need some way to have man(1) invoke nroff for
pages mandoc cannot render correctly.  That could be done dynamically
by testing (with e.g. test "$(mandoc -T lint filename 2>&1)") or by
means of a whitelist/blacklist.  For modern hardware that is not
resource constrained, the fallback method would be plenty fast enough.
Unfortunately, mandoc does not return a error status for documents
containing contructs that it can't interpret.  

4.  http://wiki.netbsd.org/projects/project/troff/ says, "importing a
newer groff is problematic for assorted other reasons".  What are
they?  If the critical Perl bits were converted to C, would that be
enough to bring the current groff into base?  

--jkl