Re: Manual pages and POD format
* Tue 2007-09-25 Frank Lichtenheld <djpig AT debian.org>
* Message-Id: 20070925171626.GS24423 AT planck.djpig.de
> On Tue, Sep 25, 2007 at 04:26:33PM +0300, Jari Aalto wrote:
>
>> I noticed that current ones are traditional roff. With POD the pages
>> would be easier to edit and maintain, and diffs would be more clear too.
>>
>> If there would be interest in changing to use the Perl POD format I'll
>> volunteer for the work.
>
> After doing some work on the man pages these last few days I actually
> wondered the same thing. Editing roff directly is just no fun at all...
>
> Before switching to a new format it would be good to research the
> alternatives, though. I personally know docbook-to-man (which is no huge
> win in readability in my opinion ;), POD (very simple, but also somewhat
> limited in what you can express), and asciidoc (has more possibilities
> than POD while still being simple, but the syntax isn't really stable
> [see recent version 7 -> version 8 move] and somehwat underdocumented).
POD is well suited for program manuals. Here is and example I wrote to
demonstrate POD to the Curl author:
http://cante.net/~jaalto/tmp/curl.new/curl.1.html
http://cante.net/~jaalto/tmp/curl.new/curl.1.pod
http://cante.net/~jaalto/tmp/curl.new/curl.1
The good thing is that it's a native Perl format. Generating asciidoc
pages is slower from what I have experiences and would add a extra
dependency.
Jari
--
Welcome to FOSS revolution: we fix and modify until it shines
Reply to: