Re: mandoc shortcomings

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

On Wed, 16 Dec 2015 11:43:13 +0100
Joerg Sonnenberger <joerg%britannica.bec.de@localhost> wrote:

> Almost all cases of man pages failing to give a
> decent output with mandoc fell into one of two categories:
> (1) Stupid macro abuse that just accidentely worked with groff.
> (2) Creating a feature test for groff use.

I'm not so sure about "fell".  Experience so far suggests the testing
was done somewhat optimistically.  No one on this thread has mentioned a
plan to deal with pages that fall outside mandoc's domain.  

> groff's own man pages often fall into category (2). They don't need to
> use nearly as much low level features as they do, the equivalent
> mandoc documentation clearly shows that. 

In the case of groff.7, it's not a feature test.  Maybe mdoc macros
would do the job.  I know there's no appetite to rewrite it in mdoc. 

The groff pages are basically -man, and rely heavily on troff
requests to do what -man macros will not. I append a list below; there
are 48 instances of .de, for example, to define macros (for
*formatting*, not for demonstration, else they wouldn't be at the left
edge).  

A quick spot-check shows .de seems to work sometimes.  I don't know
which requests mandoc recognizes because, ahem, it's not documented:
"man 7 mandoc" is not found.  (When did it become acceptable in NetBSD
to install a utility in base that lacks documentation describing its
input langauge?)    

I'm happy to say I haven't found any other egregious problems.  Before
I do any more testing, though, could someone perhaps enlighten me as to
the methodology used for acceptance testing?  That might help me avoid
covering the same ground.  

--jkl

$ awk '/^\.[a-z][^ ]/ {print $1}' *.man *.am | sort | uniq -c | sort -rn
  84 .request
  58 .esc
  48 .de
  23 .ft
  23 .command
  19 .na
  19 .ad
  17 .squoted_char
  17 .scaleindicator
  13 .cp
  12 .xsub
  12 .x-command
  12 .ds
   9 .register
   9 .indexed_offset
   9 .br
   8 .do
   8 .co
   7 .ne
   7 .ie
   7 .el
   7 .au
   5 .esc[]
   5 .dquoted_char
   4 .rm
   4 .option
   4 .nr
   4 .nf
   4 .if
   4 .fi
   3 .scalednumber
   3 .escarg
   2 .offset
   2 .ig