http://www.perlmonks.org?node_id=246875


in reply to Re^2: POD as a general documentation system
in thread POD as a general documentation system

POD has hardly changed during the last 2 decades as well, right?

POD didn't even exist 2 decades ago. In fact, POD is less than a decade old, it came with perl5. And, given what's going to happen with perl6, I wouldn't want to bet money on "POD will not change the next decade".

Besides, all POD tools are written in Perl. Having to install a dinosaur like Perl just to be able to deal with general documentation doesn't rock - it sucks. It's hardly any worse than requiring people to install Word or some other tool that reads Word format.

Abigail

  • Comment on Re: POD as a general documentation system

Replies are listed 'Best First'.
Re^2: POD as a general documentation system (pod is readable)
by Aristotle (Chancellor) on Mar 31, 2003 at 09:14 UTC
    But you don't! Any Joe Random User will understand what 
    =HEAD1 SYNOPSIS

    [download]

    means. There's rarely a lot more markup in POD and the spec is very simple - even if it changes in the future, the basic syntax (=FOO) is not going to change. The fact that the tools in existence are written in Perl is a red herring. In their absence, less works just as well. Of course the format is so simple you can easily write parsers in another language. I've used sed once.

    I did mix up the "two decades" thing - code and docs were wrapped before Perl5 too, but I forgot the Perl4 way of doing that was *roff.

    Makeshifts last the longest.

[reply]
[d/l]
      You are over estimating Joe Random User. =head1 isn't clear at all, let alone =head2. Maybe he would have understood =title and =section. And you really think Joe Random User is going to understand =over? Or L<text|name/sec>?

      And if you are going to use a pager to read POD anyway, you'd be better off it it was written in plain ASCII.

      Abigail

[reply]
[d/l]
[select]

        Well, we'll have to disagree about the clarity of the command paragraphs then. The interior sequences might be problematic, but other than complex L<>s and E<> they're easy to ignore. In plaintext, you can't represent references directly anyway; the same solutions you come up with there are likely to work for POD as simple L<>s.

        I did say "in the absence of a POD parser" when I said you can read POD using a pager.

        Makeshifts last the longest.

[reply]

In Section Meditations