I'm doing a project in Perl where I needed to tidy the HTML in some pages. There's a nifty little Perl package called, appropriately enough, HTML::Tidy. I used CPAN to grab it and got it working, but I'll be darned if I could figure out how to actually get the tidied text back from the package. If you read the man page, I'll bet you can't figure it out either. No useful examples with the code and searching the Web turned up very little. Turns out the clean method returns the cleaned text, although the man page doesn't say that--it says that it returns "true if all went OK, or false if there was some problem calling Tidy, or parsing Tidy's output."
In the process of searching for how to actually use this little gem, I can across the annotated CPAN documentation project. Here's the annotated page for HTML::Tidy. Notice that someone has annotated the page to correct the oversight of telling you where the tidied output will be, along with some other useful information. Very handy idea. One more instance of the writable Web at work.