Re: mandoc & perl documentation

["Anthony J. Bentley" <anthony@anjbe.name>]

Hi Pali,

Pali Rohár writes:
> In perl world is documentation for perl modules or perl scripts writing
> in the POD format. Build process for perl scripts/modules then convert
> POD documentation into manpages and install it into standard system
> location.
>
> I looked at Debian manpages which uses mandoc for converting man pages
> to HTML and basically documentation for perl modules is not good.
>
> For example this is HTMLized manpage for Email::Address::XS perl module:
> https://manpages.debian.org/Email::Address::XS
>
> There is also converting tool which formats POD documentation directly
> into HTML output. And for Email::Address::XS module is looks like:
> https://metacpan.org/pod/Email::Address::XS
>
> So, I would like to ask, how can be HTML output generated from perl
> manpages improved (process: POD --> mandoc --> HTML), so documentation
> would be more close to the native HTML output (process: POD --> HTML)?

LibreSSL's documentation was originally in pod, and was converted to
mdoc by Ingo and myself. We used Kristaps's pod2mdoc(1) as a base, and
fixed up the resulting mdoc source to be more semantic.

https://mandoc.bsd.lv/pod2mdoc/

If you want to keep the source formatting in pod, you could use pod2mdoc
during the build. The result is not incredibly good due to an inherent
lack of semantics in pod, but it is better than pod2man output.

I imagine a nicer result would come from keeping the source in mdoc
format and converting to pod during the build, but I'm not aware of
any such converter yet...

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv