Re: [jperkin@netbsd.org: CVS commit: pkgsrc/textproc/mdocml]

[Ingo Schwarze <schwarze@usta.de>]

Hi Thomas,

thanks for sharing this.

Thomas Klausner wrote on Thu, Sep 12, 2013 at 01:03:01PM +0200:

> ----- Forwarded message from Jonathan Perkin <jperkin@netbsd.org> -----
> 
> Date: Thu, 12 Sep 2013 10:33:29 +0000
> From: Jonathan Perkin <jperkin@netbsd.org>
> To: pkgsrc-changes@NetBSD.org
> Subject: CVS commit: pkgsrc/textproc/mdocml
[...]
> Log Message:
> Rename preconv and roff.7 to have a 'mandoc-' prefix.  This removes the
> conflicts with textproc/groff and allows both packages to co-exist,
> paving the way for mdocml to be used in the tools infrastructure as an
> nroff replacement.

I see why this makes sense for NetBSD.

In OpenBSD, we don't have these conflicts.
OpenBSD doesn't provide preconv(1) at all, neither the program
nor the manual.
While the roff.7 from mandoc lives in /usr/share/man/,
the roff.7 from groff lives in /usr/local/man/,
so there is no conflict either.

I agree that calling our manual "roff(7)" was presumptuous, and that
mandoc-roff(7) is better.  If Kristaps explicitly agrees i might
consider renaming the file in the bsd.lv repo as well.  Probably,
i would first ask for opinions in OpenBSD as well because keeping
things in sync would be nicer.

So far, i didn't look at preconv(1) at all and hardly know what
it is doing.  Maybe at some point i will look at it, but before
that, i feel quite reluctant to touch it at all.


I used the ooportunity to check out a copy of pkgsrc/textproc/mdocml
and look around a bit.

I think the COMMENT could easily be improved.
The first three words are very imprecise,
the paranthesis is ugly and incomplete.

If you want it short, i'd say just

  manual page formatter

If you want to use the line well, maybe something like

  manual page formatter handling mdoc, man, tbl and partial roff and eqn
or
  convert man pages from mdoc, man and tbl to txt, html, ps or pdf

The DESCR is even worse.  The words "the mdoc library" are quite
misleading for two reasons:  Such a thing doesn't exist, and even
the mandoc library that does exist (handling man(7) as well) is
an internal library contained in the mandoc(1) binary, so it is
not really "interfaced with".

I'd say something like

  The mandoc manual page parser and formatter contains:
   * complete validating parsers for the mdoc and man languages
   * a slightly incomplete parser handling most of the tbl language
   * a very incomplete parser handling a part of the eqn language
   * support for a few selected roff requests that often occur in manuals
   * complete ASCII, UTF8, HTML and XHTML text output formatters
   * simple PostScript and PDF output formatters
   * output formatters producing indented mdoc and man parse trees

  To format manuals for console display, it can be used as a smaller
  and faster drop-in replacement for nroff -mandoc.  Some rare manuals
  using lots of uncommon low-level roff requests may not work with
  mandoc but require a full roff implementation.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv