Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

Re^2: POD as a general documentation system (pod is readable)

by Aristotle (Chancellor)
on Mar 31, 2003 at 09:14 UTC ( #246877=note: print w/replies, xml ) Need Help??

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

But you don't! Any Joe Random User will understand what

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.

Replies are listed 'Best First'.
Re: POD as a general documentation system
by Abigail-II (Bishop) on Mar 31, 2003 at 09:30 UTC
    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.


      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?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://246877]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (2)
As of 2018-07-23 04:28 GMT
Find Nodes?
    Voting Booth?
    It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?

    Results (459 votes). Check out past polls.