From: "Pali Rohár" <email@example.com> To: firstname.lastname@example.org Subject: Re: mandoc & perl documentation Date: Thu, 13 Sep 2018 17:36:21 +0200 [thread overview] Message-ID: <20180913153621.yj2nxsgkfxcq7c6i@pali> (raw) In-Reply-To: <email@example.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 firstname.lastname@example.org [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 195 bytes --]
next prev parent reply other threads:[~2018-09-13 15:36 UTC|newest] Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-09-13 15:12 Pali Rohár 2018-09-13 15:32 ` Anthony J. Bentley 2018-09-13 15:36 ` Pali Rohár [this message] 2018-10-11 7:52 ` Pali Rohár 2018-10-11 8:54 ` Jan Stary 2018-10-23 17:45 ` Ingo Schwarze 2018-10-24 8:03 ` Pali Rohár 2018-10-25 1:51 ` Ingo Schwarze 2018-10-25 8:10 ` Pali Rohár 2018-10-25 21:30 ` Ingo Schwarze 2018-10-26 8:15 ` Pali Rohár 2018-11-24 19:31 ` Ingo Schwarze 2018-11-25 13:34 ` Pali Rohár 2018-11-25 18:20 ` Ingo Schwarze 2018-11-26 8:48 ` Pali Rohár 2019-02-28 16:45 ` Ingo Schwarze 2019-03-02 17:09 ` Ingo Schwarze 2019-01-17 8:02 ` Ingo Schwarze 2018-11-04 20:00 ` Pali Rohár
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=20180913153621.yj2nxsgkfxcq7c6i@pali \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: mandoc & perl documentation' \ /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
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).