Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re: POD as a general documentation system

by Abigail-II (Bishop)
on Mar 31, 2003 at 09:00 UTC ( [id://246875]=note: print w/replies, xml ) Need Help??


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

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

    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.

      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

        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.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://246875]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others goofing around in the Monastery: (6)
As of 2024-03-28 22:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found