Re: mandoc & perl documentation

["Pali Rohár" <pali.rohar@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1888 bytes --]

On Thursday 13 September 2018 09:32:48 Anthony J. Bentley wrote:
> 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...

That is not possible for general usage. Documentation for perl modules
are written in POD and would be written also in the future...

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]