On 2009-Aug-18, at 3:29 am, Jan Ingvoldstad wrote:
In general, executable documentation is a bad thing. It's been shown to be a bad thing many times over.
Well, tons of programs have --help options, which could be considered executable documentation, and it's very useful. Emacs brags about being self-documenting.
It's worth it because it's more work the computer can do instead of humans (and often do a lot better). It's annoying when a printed book says "the default setting is $foo" when it isn't because somebody changed the defaults, or "the config file is at $some/$path" when it isn't because it was installed using a non-standard layout -- but it's understandable, because there's not much you can do about that. It's a lot more frustrating when you're looking at docs on a programmable computer that actually knows the real settings/paths/etc. and *could* tell you, but doesn't.
But it's a lot more than that: although it can help the end-user, it also helps authors. I can weave together my (il)literate POD in the most convoluted way Pod6::Order::Labyrinthine can handle. I can have it pull values out of my code so that's impossible for the docs to get out of date because I forgot to change them. That's still a big help even if my end users look only at a static copy of the docs once they're produced.
If we absolutely must have some sort of executable documentation, then if I could, I would insist that it wouldn't be a feature complete language. That is: absolutely no IO in the language, no way of executing code that's foreign to the doc, and so on.
Well, perl-doc can't run any POD-executing modules that never get installed. But surely it's possible to forbid IO, no? Disallow any actual IO functions, as well as anything that could be used to sneak them in (eval). I guess you'd want to allow Perl itself to load installed modules (but maybe nothing from the current dir, or outside the official library location). Having perl-doc run in lock-down mode, or run in display-precompiled-static-file-only mode by default might be a good idea, though I'm not convinced it's completely necessary.
-David
