From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-io1-f52.google.com (mail-io1-f52.google.com [209.85.166.52]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 8f95bcfe for ; Thu, 13 Sep 2018 10:32:52 -0500 (EST) Received: by mail-io1-f52.google.com with SMTP id e12-v6so3453242iok.12 for ; Thu, 13 Sep 2018 08:32:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cathet-us.20150623.gappssmtp.com; s=20150623; h=sender:from:to:subject:in-reply-to:references:comments:mime-version :content-id:content-transfer-encoding:date:message-id; bh=1JDBouyJCTfklMDwG8aBI3zkOZut0wXk+AVwqGHPG88=; b=rlmKlcEOBcBnztd6FWOKzK+SJAS7oAA3TKKWCw117hLMMfkwlD0oRxhGtllI31Zatj HZ0yfU1yTfgH6X8ILciZ3HnZN3ZXU6VYD9N6N9vgXSg9HmK/jP9SnXP/sNvlCjgZkJYs gw7/gcfHiey8u8dRSiHrQEpRqRb8BWP9hYVe10k94o92gt3bJeOEUXnK1b4gxycuIT5A PuzGluev/DRqWRYf0YKPX45JEn8C47kZwoH8YAi8ygSkn88oR0EL4RM2xH+A3gN+M5+m c/LTro36qGkTL2mI3YCV0NBrnWccSPAFce4RPqSCM5wgT2z8QcurPNT598EPoc3oI1bP NYqg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:subject:in-reply-to:references :comments:mime-version:content-id:content-transfer-encoding:date :message-id; bh=1JDBouyJCTfklMDwG8aBI3zkOZut0wXk+AVwqGHPG88=; b=Fg/uECVyzl5eRRin6GA2+R/2vruX3xHhfvmZRJi70CPzz2WqVUVt84ho6c3OkCljA3 HPK0Lu+dttyMJKrscJ+Gn78qhvX9QBP08dp6HEwvJCJL0qNt34UVYp9zQedMrdipd75U 2nQQYmgMzzH/hrGNYoyTbHFcjg3YE65sYnx7sbnesZcx8puO1RU8VtL9HzJevGYTa0Rz yJ3ke3wtY3Hcb2Xj+7sBVf9caaW83uQewahxqywkdCnxPXTLe4T41zHS03iplSasMmDL e1AqCWFe+0A2UqJR6Zbhn/GM3ScGwfIUgHi8iNlZf7WhOoM7p21qmqO64WBTYTvcP5Pl 83Qg== X-Gm-Message-State: APzg51Ap4cQLvrUtkAvq4uAYM6g+sn1VsmWLf8MxkqboXY0xUAqHuiTT 1DY6sYvOCNOo48OVe0GyDlStkhcEP70= X-Google-Smtp-Source: ANB0VdZrae1EgYjh2dCoDfd3YGxR3MVdiGFkyohg5XRhCLoQAN7qShWn7LTqDLb85ibqLWGNNb7J1w== X-Received: by 2002:a6b:7f0c:: with SMTP id l12-v6mr6495226ioq.16.1536852770686; Thu, 13 Sep 2018 08:32:50 -0700 (PDT) Received: from cathet.us. (75-161-98-184.albq.qwest.net. [75.161.98.184]) by smtp.gmail.com with ESMTPSA id e25-v6sm1452278iom.19.2018.09.13.08.32.49 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 13 Sep 2018 08:32:49 -0700 (PDT) Sender: "Anthony J. Bentley" Received: from cathet.us (localhost [127.0.0.1]) by cathet.us. (OpenSMTPD) with ESMTP id dd9b9589 for ; Thu, 13 Sep 2018 09:32:48 -0600 (MDT) From: "Anthony J. Bentley" To: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation In-reply-to: <20180913151226.oaon3nvlvgcqioau@pali> References: <20180913151226.oaon3nvlvgcqioau@pali> Comments: In-reply-to Pali =?utf-8?B?Um9ow6Fy?= message dated "Thu, 13 Sep 2018 17:12:26 +0200." X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-ID: <12167.1536852768.1@cathet.us> Content-Transfer-Encoding: 8bit Date: Thu, 13 Sep 2018 09:32:48 -0600 Message-ID: <18000.1536852768@cathet.us> 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