This is a bit of a mental progress report on what I'm thinking about with perldoc. I am not content to just fret over the tasks at hand; I also worry about things weeks or months away. So while I'm still working on Pod::Simple, I've got half of a thought about what I'll do once that's done and it's time to modify perldoc to use these new formatters.
One thing I'd like to be able to do, is to tell perldoc "Here, this is the name of a class that I want you to use for formatting", and then perldoc will try to load that class and talk to it via some particular interface that would be, well, the interface between perldoc and a formatter class. So ideally, perldoc would handle all the grunt work of finding the exact Pod source file and paging thru (or running) the formatted output, and all the formatter need do is render input file foo to output file bar (or to a pipe to 'less', or whatever). So the interface will need to express things like whether its output is plaintext (and thus suitable to just going thru with a pager), or whether it needs special treatment, like an RTF file that needs to be opened, instead of looked at with more/less/list.com/etc.. I don't think there will be /dozens/ of potentially useful formatters that you'd want to plug in this way, but I figure I at least need whatever interface would be necessary to being able to drop in a tkpod browser, an RTF converter (whether MSWord, WordpPad, or anything else), an HTML converter, and even just good old plaintext, and have appropriate things happen (if applicable) for temp files and pagers. (I also wouldn't mind making life easy for the cperl-perldoc function under Emacs, but I know little about it, so I'm trying not to think about that just now.) I don't think the interface layer needs to be totally ambitious -- I won't be terribly bothered if it ends up being incapable of handling the case where some user wants to have "perldoc Foo::Bar" queue up Velvet Underground /White Light White Heat/ on his ogg player. But I think that if it can handle the cases of *roff, plaintext, tkpod, HTML, and RTF under Unix and MSWin, we should be fine. I've also been thinking about caching in that system, and it seems quite problematic. It's a bit of at 80/20 problem. That is, imagine a fairly naive situation like just having "perldoc Foo::Bar" check to see if there's a (recent?) formatted copy at /someplace/pod-cache/format/Foo-Bar.whatever, and if so, just off and viewing that. That'd make things nice and zippy and correct for most invocations of perldoc. But the remaining cases not covered will go quite badly, because of failing to perceive when the cached copy is actually not the right copy anymore, because it's a cached formatted version of Pod that has been replaced (whether by an older or newer version, whether by replacing the older file itself, or superceding it in an earlier on @INC directory). I'm a bit torn on that whole situation. I can think of some quite tidy solutions that regrettably fail in the real world because of things like permissions and even race conditions. And some things just aren't worth caching -- like perldoc -q things, or just anything that doesn't correspond to a whole Pod document. Anyway, caching aside, I'm also just generally thinking about what to do with perldoc. At this point, I have to admit I'm not enthused by the idea of tossing it out and rewriting from scratch -- but it seems like a good idea to at least balkanize it into more modular components (just for sake of sanity -- and maybe eventual rewriteability!), and also to use already-existing components like Pod::Find to good advantage. Then ideally the perldoc(.bat) itself would just be a little wrapper around perl -MPod::Perldoc [plus options]. It'd also be nice if one could pass formatter-specific options via the command line -- I have a few ideas about how to do that, which are easier for me to just code up and show off, than to explain in detail. Ideally, the user should be able to specify what formatter class to use (or a list in descending order of preference) in an environment variable, or as a command line option. And maybe we could even implement what the current edition of /Programming Perl/ says about "perlman" and all the various Pod-searching options! -- Sean M. Burke http://www.spinn.net/~sburke/
