Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

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

=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.


Comment on Re^2: POD as a general documentation system (pod is readable)
Download Code
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.

    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
Node Status?
node history
Node Type: note [id://246877]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (5)
As of 2014-08-23 18:41 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (178 votes), past polls