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

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

[Thomas Klausner]

FYI.

----- 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

Module Name:	pkgsrc
Committed By:	jperkin
Date:		Thu Sep 12 10:33:29 UTC 2013

Modified Files:
	pkgsrc/textproc/mdocml: Makefile PLIST distinfo
Added Files:
	pkgsrc/textproc/mdocml/patches: patch-Makefile patch-preconv.1
	    patch-roff.7

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.

Bump PKGREVISION.


To generate a diff of this commit:
cvs rdiff -u -r1.34 -r1.35 pkgsrc/textproc/mdocml/Makefile
cvs rdiff -u -r1.7 -r1.8 pkgsrc/textproc/mdocml/PLIST
cvs rdiff -u -r1.26 -r1.27 pkgsrc/textproc/mdocml/distinfo
cvs rdiff -u -r0 -r1.4 pkgsrc/textproc/mdocml/patches/patch-Makefile
cvs rdiff -u -r0 -r1.1 pkgsrc/textproc/mdocml/patches/patch-preconv.1 \
    pkgsrc/textproc/mdocml/patches/patch-roff.7

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.


----- End forwarded message -----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

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

[Ingo Schwarze]

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

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

[Thomas Klausner]

Hi Ingo!

On Sun, Sep 15, 2013 at 02:31:35PM +0200, Ingo Schwarze wrote:
> > 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.

Just to make sure it's clear -- this is only for pkgsrc. NetBSD's base
contains mdocml (used for man pages by default) and parts of groff
(for roff sources). The best-fitting comparison would be to OpenBSD
ports.

To fill in the picture: NetBSD base installs all mandoc man pages in
section 7 as mandoc_foo.7, and of the binaries only mandoc itself.

If NetBSD ever gets rid of groff, they might be renamed back to their
default names, but as long as we have distribution/setup notes in
roff, this won't happen anytime soon.

Btw, what does OpenBSD do with the installation notes, or were they
rewritten in something else but roff?

> 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.

So there is no mandoc package in ports? Then OpenBSD doesn't have this
issue, I agree.

> 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.

I guess more pages would need to be renamed to be consistent. I'm not
sure what to do here, so I just sent it as a FYI.

> 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.

This was the first time I noticed this program too :)

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

Thanks for the comments on the package. I've improved both COMMENT and
DESCR using your words.

Thanks for your suggestions!
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

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

[Ingo Schwarze]

Hi Thomas,

Thomas Klausner wrote on Sun, Sep 15, 2013 at 11:50:48PM +0200:

> Just to make sure it's clear -- this is only for pkgsrc.
> NetBSD's base contains mdocml (used for man pages by default)

Oh really!  When did you switch to using mandoc(1) as the system's
manual page formatter?  I didn't even notice you switched...

[...]
> To fill in the picture: NetBSD base installs all mandoc man pages in
> section 7 as mandoc_foo.7, and of the binaries only mandoc itself.

Oh, i see.

> If NetBSD ever gets rid of groff, they might be renamed back to their
> default names, but as long as we have distribution/setup notes in
> roff, this won't happen anytime soon.
> 
> Btw, what does OpenBSD do with the installation notes, or were they
> rewritten in something else but roff?

Not sure what you are talking about, maybe something like this?

  http://www.openbsd.org/cgi-bin/cvsweb/src/distrib/notes/INSTALL

In any case, no plain roff code remains in OpenBSD, and all roff
macro code is mdoc(7), man(7), and eqn(7) and can be handled
by mandoc(1).

> So there is no mandoc package in ports?

No, in OpenBSD, it is very unusual to have software in ports
that is already available in the base system, with few exceptions.

 - fvwm is old but stable in base, fvwm in ports is GPL
 - httpd is old and audited in base, apache-httpd in ports has a bad license

There may be a few others, but in general, if the version in base is
up to date and maintained, there won't be a port.

>> 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.

> I guess more pages would need to be renamed to be consistent.
> I'm not sure what to do here, so I just sent it as a FYI.

OK, so let's leave it as it is for now and avoid change
that would verge change for change's sake.

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

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

[Thomas Klausner]

On Mon, Sep 16, 2013 at 12:26:38AM +0200, Ingo Schwarze wrote:
> Oh really!  When did you switch to using mandoc(1) as the system's
> manual page formatter?  I didn't even notice you switched...

src/share/mk/bsd.own.mk:

revision 1.695
date: 2012-02-07 20:33:19 +0100;  author: joerg;  state: Exp;  lines: +6 -5;
Switch to using mandoc for formatting man pages as new default.
Stop building catpages by default.

Weird that nobody wrote anything to mdocml-discuss about this :|

> > Btw, what does OpenBSD do with the installation notes, or were they
> > rewritten in something else but roff?
> 
> Not sure what you are talking about, maybe something like this?
> 
>   http://www.openbsd.org/cgi-bin/cvsweb/src/distrib/notes/INSTALL

Yes, this. So you format it manually without roff and use m4 for the
inclusion handling. Perhaps that's an acceptable solution for NetBSD
as well...

Cheers,
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv