New Perldoc

TorgoX on 2002-11-11T11:43:37

Dear Log,

New options

ethan on 2002-11-11T13:38:48

On the pod-people list you annouced:

One note about the current dist: since this is just an alpha release, it doesn't replace your perldoc executable, but instead gives you a new executable called "perldoc3". So don't try using the new options with your old perldoc.

What exactly are the new options? I didn't yet find any difference (except for the removal of the annoying taint-checking thing when being root).

Oh, just noticed that: something odd has happened to the -i switch. Doesn't work for my any longer.

Re:New options

TorgoX on 2002-11-11T19:07:53
Whoops, I just realized I forgot to list the new options in the usage screens. It's in "perldoc3 perldoc3" tho. Notably: -T terminal
This specifies that the output is not to be sent to a pager, but is to be sent right to STDOUT.
-d destination-filename
This specifies that the output is to be sent neither to a pager nor to STDOUT, but is to be saved to the specified filename. Example: perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap
-o output-formatname
This specifies that you want Perldoc to try using a Pod-formatting class for the output format that you specify. For example: -oman. This is actually just a wrapper around the -M switch; using -oformatname just looks for a loadable class by adding that format name (with different capitalizations) to the end of different classname prefixes.
For example, -oLaTeX currently tries all of the following classes: Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex Pod::LATEX.
-M module-name
This specifies the module that you want to try using for formatting the pod. The class must must at least provide a parse_from_file method. For example: perldoc -MPod::Perldoc::ToChecker.
You can specify several classes to try by joining them with commas or semicolons, as in -MTk::SuperPod;Tk::Pod.
-w option:value or -w option
This specifies an option to call the formatter with. For example, -w textsize:15 will call $formatter->textsize(15) on the formatter object before it is used to format the object. For this to be valid, the formatter class must provide such a method, and the value you pass should be valid. (So if textsize expects an integer, and you do -w textsize:big, expect trouble.)
You can use -w optionname (without a value) as shorthand for -w optionname:TRUE . This is presumably useful in cases of on/off features like: -w page_numbering.
You can use a "=" instead of the ":", as in: -w textsize=15. This might be more (or less) convenient, depending on what shell you use.

Re:New options

ethan on 2002-11-11T21:08:58
Whoops, I just realized I forgot to list the new options in the usage screens. It's in "perldoc3 perldoc3" tho. Notably: -T terminal

Ah, great! I can directly perldoc into a vim buffer finally or somewhere else(for ease of further processing). Very nice!

I'll think I just add an alias to make perldoc3 a replacement for the current perldoc. Thus, possible bugs should show up most quickly if any.

Re:New options

TorgoX on 2002-11-12T04:12:45
Ah, great! I can directly perldoc into a vim buffer finally or somewhere else(for ease of further processing). Very nice!
That should have worked before (without the explicit -T) -- but sometimes didn't. Now you can use -T to make totally clear "no pager!!".
I'll think I just add an alias to make perldoc3 a replacement for the current perldoc. Thus, possible bugs should show up most quickly if any.
Wow, thanks! I'll be sure to post news, here in my log, of any new Perldoc versions.

thanks

brev on 2002-11-11T15:06:54

Thanks there Mr. X. I have installed it and will let you know how it all pans out.

Anything you'd particularly like tested? The new output formats?

Are you using any bug tracker software?

Re:thanks

TorgoX on 2002-11-11T19:25:27
Nope, I'm not using any particular bug-tracking software; just email me any reports of trouble.
As to what to test: anything and everything -- the whole thing is either all new, or newly refactored. Like someone just told me "-i" isn't working anymore, which I didn't notice because I've been using MSWin, where it's a no-op. I don't remember messing with the "-i" code, but I'll have a look at it now.