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

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.

Comment on Re^2: POD as a general documentation system (pod is readable) Download Code

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. Abigail	[reply] [d/l] [select]
Re^4: POD as a general documentation system (yes, pod _is_ readable) by Aristotle (Chancellor) on Mar 31, 2003 at 12:47 UTC
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]


laziness, impatience, and hubris
	PerlMonks