discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Kristaps Dzonsons <kristaps@bsd.lv>
Cc: discuss@mdocml.bsd.lv
Subject: Re: pod2mdoc, docbook2mdoc
Date: Mon, 31 Mar 2014 18:13:15 +0200	[thread overview]
Message-ID: <20140331161315.GC31866@iris.usta.de> (raw)
In-Reply-To: <533943B9.5080901@bsd.lv>

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Mar 31, 2014 at 12:30:17PM +0200:

> Thank you for doing this!  Though I worry... is this not moving too
> fast? These tools are fresh--real fresh--and moving fast.  Is it not
> too soon for committing to a port?

I wouldn't worry too much about that.  The version number 0.0.5
is telling enough, and the package description can say a few words
too.  So i see no big risk there, but possible benefit allowing
cleaner packaging, installation and deinstallation of experimental
tools.

> pod2mdoc works over all the POD
> I found (not being a Perl junkie, however, I just used what's in the
> Perl distribution), but docbook2mdoc still needs a lot of work.

Indeed.  As far as i can see, the biggest problem right now is that
it usually exits in the middle of each processed file, rendering
merely the beginning.  To be usable, it has to become more resilient.

At first sight, it seems that the "ps->stop = 1;" in the
function xml_elem_start() cause the problem, but i didn't
try to come up with a fix yet.

  cvs.1.xml:33:6: unknown node "indexterm"
  lynx.1.xml:83:0: unknown node "literallayout"
  sqlite3.1.xml:108:0: unknown node "markup"

> Fact is, I just don't know the "real world" landscape of ports using
> docbook (or POD, for that matter).  Would it not be better to have
> somebody using (or porting) POD or DocBook systems to break them in
> before putting them out for general consumption?  Thoughts?

A good corpus of test input would be the man(7) manuals in OpenBSD
base, imho.  As far as these are POD input, they are good testing
candidates for pod2mdoc; i consider the test chain POD -> pod2man ->
man(7) -> doclifter -> DocBook-XML -> docbook2mdoc mostly useless.
As far as they are real man(7), not from POD, they are good testing
candidates for docbook2mdoc, i.e. using the testing chain
man(7) -> doclifter -> DocBook-XML -> docbook2mdoc -> mdoc(7).

At least at first, i think the main use for docbook2mdoc will
be as a postprocessor for doclifter, so getting it to handle
the subset of DocBook-XML produced by doclifter is the second
most useful step to take after preventing it from exiting
prematurely (see above).

In any case, docbook2mdoc seems much more useful than pod2mdoc,
at least in a short-term perspective.

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

  reply	other threads:[~2014-03-31 16:13 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <sfid-H20140330-202333-+022.64-1@spamfilter.osbf.lua>
2014-03-30 18:23 ` Kristaps Dzonsons
2014-03-31  9:09   ` Thomas Klausner
2014-03-31 10:30     ` Kristaps Dzonsons
2014-03-31 16:13       ` Ingo Schwarze [this message]
2014-03-31 19:40         ` Kristaps Dzonsons
2014-03-31 20:57           ` Ingo Schwarze
2014-03-31 21:30             ` Thomas Klausner
2014-03-31 21:54               ` Kristaps Dzonsons
2014-03-31 22:21                 ` Ingo Schwarze
2014-03-31 22:31                   ` Thomas Klausner
2014-04-03 12:02                     ` Kristaps Dzonsons
2014-04-03 12:17                       ` Thomas Klausner
2014-04-03 12:33                         ` Kristaps Dzonsons
2014-04-03 13:53                           ` Ingo Schwarze
2014-04-03 16:51                             ` Kristaps Dzonsons
2014-04-03 22:06                             ` Thomas Klausner
2014-04-04 13:43                               ` Kristaps Dzonsons

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20140331161315.GC31866@iris.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mdocml.bsd.lv \
    --cc=kristaps@bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).