trying to improve mandoc Solaris support

[Ingo Schwarze via buildfarm]

Hi Joerg,

Joerg Schilling wrote on Thu, Mar 19, 2015 at 02:14:27PM +0100:
> Ingo Schwarze <schwarze at usta.de> wrote:
>> Joerg Schilling wrote:

[...]
>>> In general, the mandoc _format_ (introduced with BSD-4.4-lite)

>> I assume you are talking about the mdoc(7) format designed and
>> implemented by Cynthia Livingston - as opposed to the traditional
>> Version 7 AT&T UNIX man(7) format.

> I did not try to find out who was the author.

Oh, that is actually not easy to find out.  I didn't find the
information on the Internet either.  But i confirmed it by talking
to Kirk in person and by exchanging email with Cynthia herself.

> It was hard enough to find a useful version from dozens of variants
> that appear on the BSD snapshot from Kirk McKusick that comes with
> SCCS and a most recent edit timestamp from June 23 1995.

According to Cynthia, three noteworthy versions existed:

 * mdoc(7) version 1 was never checked into version control, never
   published, and the source code is probably lost.  It was what
   Cynthia used when starting the work.

 * mdoc(7) version 2 is still available here:
   http://svnweb.freebsd.org/csrg/share/tmac/tmac.doc.old
   That version was short-lived:  It was only contained
   in 4.3BSD-Reno and 4.3BSD-Net/2, but in Reno, only a small
   number of manuals was converted to mdoc(7), most were still
   shipped in the old man(7) format, and in Net/2, conversion
   to version 3 had already started.
   
 * mdoc(7) version 3 is available here:
   http://svnweb.freebsd.org/csrg/share/tmac/doc
   (and the doc-* files in the same directory)
   That's the version used in all variants of 4.4BSD,
   and the only one people usually have in mind when talking
   about "mdoc(7)" today.

>> I wasn't aware of that and have not checked your work in detail,
>> but i have a rough idea of the quality of Cynthia's original macro
>> implementation because it is still in use in Heirloom roff; Carsten
>> Kunze is working on improvements right now.

> If there are improvements, please keep me informed.

You should probably just follow

  https://github.com/n-t-roff/heirloom-doctools/

Carsten also announces releases on <groff at gnu.org>.

I'm not directly involved with Heirloom troff development,
so i'm not the ideal person to keep people informed about it.

> Are there *BSD man pages that go beyond the official 6 argument
> limit for troff macros?

Yes, we dropped that restriction in OpenBSD about four years ago,
and i doubt that FreeBSD and NetBSD still abide by it.

> From my interpretation, using such features is not a good idea if you 
> intend to create portable man pages.

Well, portable to what?  Historic systems?

That particular restriction makes writing manuals unnecessarily
hard for manual authors.  Given that we want *developers* to
write documentation - who usually aren't documentation specialists
and don't want to waste too much time on it - making it easy to
write documentation is important.  That seemed much more relevant
than portability to, say, 4.4BSD-Lite2 or System V.4, which nobody
is running today, anyway.

> For this reason I decided not to enhance the Solaris man macros
> to support more than 6 arguments, just to be sure to 
> detect problems early if I write or enhance man pages.

I'm not sure that's a wise choice.  Probably, the only effect is
that Solaris may be the only modern system out there that has
problems rendering modern manuals (admittedly, i didn't try, but
that's what i would expect).  Maybe, when i'm bored, i might
copy the OpenBSD manuals to the OpenCSW cluster and have a look...

[...]
> Is there something that is significantly better than man2html?

You would have to ask Kristaps.  I never used that particular
program.  The following is generated directly with mandoc:

  http://www.openbsd.org/cgi-bin/man.cgi  # many releases of OpenBSD
  http://mdocml.bsd.lv/cgi-bin/man.cgi    # UNIX-7, 4.4BSD, Net, Free, ...

[...]
> The performance of troff (the AT&T original code) is comparable to
> what you get from mandoc.  My tests resulted in aprox. 30% performance
> benefit with mandoc, but this seems to be neglible if you compare
> to gtroff.

Performance very much depends on the language (mdoc(7) vs. man(7),
and possibly tbl(7) and eqn(7)) and the size of the page in
question, so giving a single number does not tell me very much.
In general, performance differs more for mdoc(7) than for man(7)
and more for smaller pages than for larger ones.

[...]
> most of the man pages for my OSS packages use tbl features
> that do not work with mandoc.

Using unusual tbl(7) features in manuals doesn't look like a
particularly good idea to me, in particular if you care about
portability.

[...]
> My impression with the mdoc() macro set is that it mainly tries
> to provide new macros for use cases that work with classical
> man(5) macros if you know that there is \c to innterupt line
> processing with [nt]roff.

Not at all.  The point of mdoc(7) is semantic markup, while man(7)
is purely presentational markup.  So the two languages serve
completely different purposes.

[...]
> I did not yet check the quality of Heirloom troff.  I know however
> that there is not much maintenance for all the projects in Heirloom
> that I checked before.

Heirloom troff is now maintained seperately from the rest of the
Heirloom tools.

[...]
> I will however stay with the classical man(1) + troff on SchilliX.

Feel free to use whatever you like for your personal purposes.  :-)

> BTW: One reason is line formatting.  I prefer full justification
> before left aligned text.

That's indeed a matter of taste.  The vast majority of OpenBSD
developers prefer flush-left, and i don't remeber hearing complaints
about it from FreeBSD, NetBSD, DragonFly, illumos or any of the
Linux ports either.  Implementing .ad would not be that difficult,
but demand is tiny, so i'm treating it as a low-priority task.

Yours,
  Ingo