The documentation would have to improve considerably to be atrocious, the module has some head scratching limitations, and is slow.
Installation on Darwin 8.5.0/perl 5.8.6 was a nightmare of dependency resolution, whether by hand or by cpan. The author might have mentioned that the htmltidy source and headers have to be present before installation in the instructions. While the documentation does mention to "tell the makefile that you're using ranlib", that convoluted set of instructions doesn't actually address the problem I had.
That aside, on first glance, there's really no way to tell to tell if this is module is useful, since the documentation doesn't actually say how to use it. Fortunately, there is some useful chatter on annocpan that gives hints.
Worst of all, the module forces you to load an external configuration file to do any changes to alter formatting or tags. Not only is this slow, it defeats the purpose of altering the markup programmatically.
Any developer is probably better off doing a system or exec call to the tidy binary than trying to use this exceptionally aggravating waste of time.
Fails make test and aborts on SuSE 10.0, Perl 5.8.7. Looks like I'm not alone in that regard, either.
Unfortunately required for a module for a module for a module for a module that Wombat uses.
Nothing like having a useful utility blow up because of a dependency nested 5 deep.