Document the default value for the -o switch

[jidanni]

I found this answer using Unix 'strace'.

P.S., maybe write -o bla, instead of -obla, as that works too, unlike -M, which doesn't tolerate whitespace.

[briandfoy]

There isn't one default. Different situations will choose differently and there are many things that go into it. Start with init_formatter_class_list and opt_o_with if you want to map out what will be chosen. There are several things that the code looks at before it chooses a formatter on its own.

However, we're probably going to revert to preferring ToMan (#36).

If you wonder what perldoc is doing, give it the -D switch:

$ perldoc -D perldoc
Ending switch processing.  Args are [perldoc] with 0 errors.
Pagers: /usr/bin/less -R, more, less, pg, view, cat/usr/local/bin/perldoc => Pod::Perldoc v3.2801

Formatter class Pod::Perldoc::ToMan version 3.28 successfully loaded!
Will format with the class Pod::Perldoc::ToMan

[briandfoy]

If we are going to specify a default value for a switch, it will be next to the switch's documentation. However, there isn't a single value we can document for -o. It might be useful to have a longer section that is just about how Perldoc chooses a formatter, but that's some serious legwork with lots of weird situations.

[jidanni]

You get ToMan, I get ToText

$ env - perldoc -D /dev/null
Ending switch processing.  Args are [/dev/null] with 0 errors.
Pagers: /usr/bin/sensible-pager, more, less, pg, view, cat/bin/perldoc => Pod::Perldoc v3.2801

Formatter class Pod::Perldoc::ToText version 3.28 successfully loaded!
Will format with the class Pod::Perldoc::ToText
Searching for /dev/null
Use of uninitialized value in split at /usr/share/perl/5.36/Pod/Perldoc.pm line 895...
[better check first next time]

Same (except for the error) with perldoc -D perldoc.

[briandfoy]

Yes, we get different things. Note that you also have a different pager as the first in the list. That's the one from the perl config (check perl -V:pager). I don't know the innards or that particular pager well to know how it advertises its capabilities, but that's one of the things that perldoc will check. As I said, there's a lot that goes into perldoc choosing a formatter, so there is not one default that we can document.

Let me know if you'd like to map out that decision process.

[jidanni]

Well I guess the most surprising thing is perldoc is doing a deep investigation into things outside of itself, causing different users to get different results for the same commands. I sure hope the man page makes this clear. (One usually is just used to commands merely checking their own .config/init_files.)

[briandfoy]

Yes, there are various ways we can improve the documentation, but we have to understand what is actually happening and document that correctly,. perldoc does a lot of work to give people the best experience it can across many different platforms and situations with no special config of its own. It's a bit of beast that has broken the spines of more than a few developers.

I do want to improve the docs, but things are not so simple that we can drop a parenthetic note into docs that explains what's going on.

I'm rejecting this PR because it's not correct and it sounds like you aren't improve it. A different patch that addresses the things I pointed out is still welcome though.