Luke Palmer wrote:
I don't want to read perlpod to figure out how to write a table.
Well then don't. No one is prying ASCII-art tables out of your hands here.
I just write my table and it works as
long as I indent. Sure, it won't be as pretty when it gets turned into
HTML or LaTeX, but the point is, that it's readable when it gets there
in any case.
The point of documentation isn't to be pretty
Pretty is not the issue. The issue is markup.
If, for example, I happen to be blind, and I'm reading Perl documentation via a text-to-speech program, it may well know how to take an HTML document and read "a table" to me in some reasonable way, but if you hand it a pre-formatted block of text that is supposed to LOOK like a table, I'm pretty (no pun intended) much SOL.
Ok, so that's an extreme example (though, I have a mostly blind friend who might not think so). How about the simple fact that S4 is supposed to be a "living document", but if Larry wants to change that table, he has to go in and re-hand-format that entire ASCII-art picture of it! I know that I've avoided making changes to tables in my documentation at work for EXACTLY that reason. If you have a table markup, then you can add or remove a column with minimal pain.
If you just wanted to draw your documentation using ASCII-art, then there would be no need for POD at all. You would simply write plain text. The point behind POD was to make writing documentation for diverse markup systems more reasonable. Such markup systems all have the ability to format a table, so why exactly would you not want to take advantage of that? What happens when Larry w
Also, you pointed out that my example was hard to read, but you only pointed out the particularly complex example (where I WANTED to demonstrate all of the complex cases), not the simple one. The general case would probably look like:
H< Function | Returns > T< foo | nothing > T< bar | a number between 1 and 1000 > T< baz | your program as a string >
That's certainly no harder to read than an ASCII-art table, and provides you with many more options in terms of presentation, accessibility and the ability to post-process the documentation (e.g. to extract information in an automated way).
