Re: pod2mdoc, docbook2mdoc

[Kristaps Dzonsons <kristaps@bsd.lv>]

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

Ingo,

Thank you for your input!  This looks logical to me.  I'll drop a note 
here when I bump versions in a meaningful way--does that work?  Note for 
those with commit access that the modules are in 
/usr/vhosts/mdocml.bsd.lv/pod2mdoc and so.  (The commit hook in CVSROOT 
should probably be updated to mail commits on the new modules...)

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

Yes.  This is because I don't support a huge set of docbook elements 
yet--and the parser exits when it encounters an unknown one to spur me 
to add as many new ones as possible.  My plan (as you've noted below) is 
to start by having it accept all of doclifter's DocBook, then focus on 
the rest, possibly relaxing the parser to accept unknown nodes if we get 
lazy.

Fortunately, it's easy to add new nodes to docbook2mdoc!  They need an 
entry in extern.h, then the rules of parenting (this is the most 
annoying part--both children and parents need to be added in) in 
rules.c, then a handler in pnode_print().  Most handler types have 
already been implemented, so it's just putting together the blocks and 
going by example.  Attributes work more or less the same way.

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

This is by design--it just means that I need to add a NODE_INDEXTERM, 
etc.  As mentioned, I'm going to start with doclifter's nodes.

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

Agreed!

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

My general thought on pod2mdoc was to avoid invoking perl(1) just to run 
pod2man(1) in the normal chain of looking at POD documents.  I also 
thought that, with a few more pod2mdoc smarts, we'll be able to deeply 
mine those documents with mandocdb.  From what I understand, they're 
kinda opaque right now.

Best,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv