trying to improve mandoc Solaris support

[Kristaps Dzonsons via buildfarm]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

> I did recently run a test with the mandoc program on Solaris and 
> tried to check the results. In general, the tbl support is
> extremely bad. Many tables are unreadable or disappear from the
> output.
> 
> In general, the mandoc _format_ (introduced with BSD-4.4-lite) is
> not a problem on Solaris if you use the enhanced man program I
> created some years ago and that is published together with
> Schillix-ON, see:
> 
> https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/man/
>
>
> 
What I did was to take the mandoc troff macros from BSD-4.4-lite
> (those that still work with original troff) and added a few minor 
> fixes (e.g. a Y2000 fix).
> 
> What I don't understand is why the mandoc program was written at
> all. Compared to most software that has been recently developped,
> it looks nice, but if I remember correctly, the sourcecode for
> "mandoc" is 2-3x more that the sourcecode for "man", "troff",
> "tbl", "soelim", "col" ... all together and the current state seems
> to be that only 80-90% of the Solaris man pages work with the
> mandoc program.
> 
> The former problem that groff is under GPL is no longer a problem 
> since the original AT&T troff has been made OpenSource under a
> free license together with OpenSolaris in June 2005.
> 
> Can you enlighten me please?

Hi Jorg,

I think I can answer this--I originally wrote mandoc(1).

First, mandoc(1) is NOT a troff implementation.  It's a compiler for
mdoc(7) and man(7).  If you run mandoc(1) on an mdoc(7) document, it
understands the mdoc(7) itself.  Thus, an mdoc(7) manpage has its full
semantic tree available to mandoc(1) for formatting and analysis.
This is incredibly helpful, because mandoc(1) knows that `Fn foo'
describes a function, not just text in bold.

Moreover, since mdoc(7) and man(7) are both hierarchical (i.e., `Ss'
in `Sh', `Em' in `Bd', etc.), mandoc(1) can even convert mdoc(7) and
man(7) into hierarchical mark-up languages like HTML.

On OpenBSD, FreeBSD, and NetBSD, this is great: most manuals are
written in mdoc(7), so mandoc(1) has a lot of power in understanding
the entire manpage corpus as a semantic body.

To cope with the larger body of manuals not written in mdoc(7) or
man(7) (or written poorly), mandoc(1) has over the years been extended
to cope with more and more roff(7) macros, which have no semantic
value at all. This is difficult for mandoc(1): roff(7) is not
hierarchical, and moreover, as mandoc(1) considers mdoc(7) and man(7)
their own languages and roff(7) can change the behaviour of these
macros, conflicts can and do arise.

I don't know about Solaris' manpages, so I'm not sure how
representative documents look.  If mandoc(1) and your troff(1) have
dissimilar output, the reason is often because of roff(7) macros in the
manpages used for line formatting.

As for tbl(7), if you have issues, then please send us the offending
manpages and we'll look at them!  mandoc(1) tries to handle tbl(7) and
eqn(7), but it doesn't always get them right.

As for source size, mandoc(1) does pretty well considering that it
parses tbl(7), eqn(7), man(7), mdoc(7), and some roff(7); converts these
into PDF, PS, HTML; has a database indexer makewhatis(8); full semantic
querying on the command line or over CGI in apropos(1) and man.cgi(8);
and even a man(1) implementation.  GNU troff's C/C++ files are over
100K LOC, while mandoc's amount to 36K.

Best,

Kristaps
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCgAGBQJVCrTQAAoJEMT2SUY9XBEST+YP/jpfmR44pFB1p2BoCAP/Mlbe
oTwBnd9xmDTdDWOTUdS5azK/jZGgn8tXe8RNVZdN+tCdcC9PC849+v6vKyBmH6nO
kWm0nIyhxoNo4W1gBS33N/q2FKHSWG7sbwbd6c1iebAjZVDGBApfoNzbn8qXFIxN
ounpjuuB7wzQ/Hq0x2nrqkkHHgjPHnF8Rrp8zilM1TMYJLW+6awHQb7GBVRl4Wz2
fBeu2BSbD+9FgFCzHpwcfqiVhHQiU6afhBWqij4Q/olG/OUXcpbelw/wNtWwDYWY
C2VK4bYPaWkyukHeBWhkaVF+XMYjx7ELTLBrRUa1skyVEkiXkBtVDLg0YdmV0daM
TykFILjowRev4SGkfMq3Nb1Xh5TzrjmcbC4eyz6yEc3pI2Nrosl6YJ8V7MrHTEJ5
Pir+Kr7ZurnvqbOEXn2bjxqktOS8jvA1VCpaAH12C9XMfAkLJFSAZJGljneIBxN2
zy0AgSaVw7mSv7eGOdyWiabP3T8gg6wtaUyPBCkSCFeTpdPUjr5mTx+Rv5HJzlyE
VqTbXOqw272N2Pz1cWgXOEJQICO6oiZBIMG/B0fsLOv3zDMRnPYY0lEeqV/qdNye
SbQOjNOrQ130bJZVkN/bAOXW8kKaSLwJjs7rxRPyGGFDdKS+bQnbul2FUudpGjZh
AgDpqSvS3v5PDbThxYFe
=YpYT
-----END PGP SIGNATURE-----