> I had better luck with: > > ##### > p6doc DBIish > ##### > > ... which produced results similar to that of 'perl6 --doc <filename>' > in the original post, i.e., output to STDOUT, unpaged, sans 'man' > highlighting. > > So, partly this is a question of incorrect or misleading > documentation.
Synopsis 26[1] states that --doc should be capable of most of the things p6doc does now, one of them being capable of finding where a given module (like DBIish here) lives and display its Pod after parsing and formatting it. I see two courses of action here: 1) (proposed on IRC) -- deprecate --doc, possibly rename it to --renderpod and direct people to p6doc instead, since --doc is barely useful to them and quite misleading 2) (which I'll be in favour of) -- stick to original S26 ideas, and improve --doc so it's actually useful for end-users. We already have a precendent in rakudo for delegating some of the optional heavy-lifting-y stuff to modules: perl6-debug requires Debugger::Commandline::UI; --doc=HTML will ask the user to install Pod::To::HTML. I think it's a reasonable step to turn p6doc into this sort of 'second-degree core' module, where --doc will either work as it does now (generate pod from paths), or attempt to load p6doc and delegate work to it, optionally showing an error message that it needs to be installed for it to work. This way the core rakudo installation (the compiler itself) still gives you a usable --doc for your own development, while distributions like Star will ship p6doc with it and make --doc better, as it was originally intended. [1] https://design.perl6.org/S26.html#How_Pod_is_parsed_and_processed
