PerlDocPlugin Development and Discussions

The "itching factor" for this Plugin was the TWiki::Func documentation which needs to be improved (see Codev.LowLevelTWikiDocs). I wanted to keep code and doc in the same place (so that they does not get out of sync) and also get a nice documentation. Perl's POD format is simple to type but I find it to verbose with many empty lines, and unlike JavaDoc not very readable if you intermix POS and doc. Thus, a POD translator is born that understands TWiki markup!

In a similar way, a JavaDocPlugin could be created to show docs of Java files installed in the system. Any taker?

This is the initial release done in a rapid way. Please report any problems here. For one, I notice that it chokes on the large doc of the CGI module.

-- PeterThoeny - 02 Dec 2002

Just wanted to say I'm glad to see this -- I'm glad to see anything that aims to improve documentation.

-- RandyKramer - 03 Dec 2002

Oops, just realized that I forgot to attach the ZIP file. Is done now.

-- PeterThoeny - 07 Dec 2002

Looks like there is a bug when rendering Table of contens (TOC) and header contains some special characters, like "==>". You can see it at TWikiFuncModule: TOC links with "==>" are corrupted. This might be TOC bug, tho. If so, what is the workaround?

-- PeterMasiar - 11 Dec 2002

I've got an enhancement request. Could this plugin take into account modules with their POD in external files? strict.pm in Perl 5.6.1, for example, has its POD in a file called strict.pod in the same directory.

Thanks!

-- JohnWest - 23 Jan 2003

If the following had worked it would have been both a nice use of PerlDocPlugin and a useful feature on TWiki.org's CodevDocumentationProject files.

%PERLDOC{CVSget:twiki/lib/TWiki.pm}%

-- MartinCleaver - 07 May 2003

Further to this, it appears that the TWikiCodebaseHasNoPODDocumentation.

-- MartinCleaver - 07 May 2003

Hm... I cannot figure out what is going on. Look at this: http://twiki.org/cgi-bin/view/Plugins/PerlDocPlugin?qModule=CGI&qFormat=rendered

Or just go to TWiki:Plugins/PerlDocPlugin and try to render documentation for CGI module.

-- IvanGrynov - 18 Aug 2003

It would be nice if the plugin allowed files that are not on the lib path. For example, one could use "%PERLDOC{[full pathname to pod file]}%". From looking at the code, this would be a very simple change.

-- KevinCraft - 23 Mar 2006

Yes, that could be done easily. But: It is a security hole since anyone editing a TWiki topic can point to any file on the system, included NFS mounted ones. A safer approach is to add the additional libs to Perl's lib path.

-- PeterThoeny - 23 Mar 2006

Adding the directory to Perl's lib path is acceptable, however one other problem arises: file extentions. The reason I bring this up is because my team uses POD format to create its man pages (they use a converter to convert from POD to man format). These files are named with the extension ".pod". Currently, the plugun only looks for ".pm". One alternative would be to check if the file exists in the directory before attaching ".pm" to it. You could also just allow the user to specify an extension as a separate argument (%PERLDOC{"somefile" ext="pod"}%).

-- KevinCraft - 30 Mar 2006

I think I'd rather be able to set a preference for the Plugin as a whole specifying a list of allowed extensions in the order they should be prioritized. One less thing to type and think about everytime you drop a PERLDOC tag in somewhere.

-- WesleyCraft - 24 May 2006

I have a patch that implements the 2 above mentioned features...

It adds two new plugin config variables: "INC" which appends a comma separated list of additional search paths, and "EXTENSIONS" which sets the extension search order (defaults to "pod,pm").

What's the protocol for submitting it?

-- MaverickEdwards - 18 Sep 2006

Thanks Maverick for contributing the patch. I just changed the modification policy of this plugin to PleaseFeelFreeToModify. If inclined, please go ahead and create a new plugin version and attach the zip file to the plugin topic. If you want, you can get access to SVN to maintain the plugin there (ReadmeFirst has more). Or, if you prefer, attach your patch here to the dev topic.

-- PeterThoeny - 19 Sep 2006

Where is the Zip file for this? It is not on http://twiki.org/cgi-bin/view/TWiki/PerlDocPlugin!

-- ChuckEhrlich - 22 Sep 2006

It is attached to the Plugins.PerlDocPlugin topic (home of plugin), not the TWiki.PerlDocPlugin (installed on twiki.org).

-- PeterThoeny - 22 Sep 2006

I have updated this plugin to use the registerTagHandler(), rather than the Cairo commonTagsHandler() for our intranet TWiki. I also extended the syntax to support displaying the Pod documentation for an attachment. The new arguments are:

• file - name of attachment
• web - web of attachment
• topic - topic of attachment

I have not completed making this change backward compatible for Cairo (ie. should work under both versions) so I did not post any code, for now.

-- CraigMeyer - 11 Apr 2007

Thanks Craig. I think it is OK to not support Ciaro for this plugin anymore because more than 12 month passed since TWiki 4 is released, and because it is not a major plugin. (HandlingCairoDakarPluginDifferences in a compatible way is extra effort. Going forward we will hopefully be in a better position because of the TWikiRelease04x01Process.)

-- PeterThoeny - 11 Apr 2007

Peter, I am happy to report I figured out a way to support both! Using a BEGIN block, and then a conditional eval, based on the TWiki version. The idea being to only defined the commonTagHandler() if it is Cairo, otherwise use a _TagHandler() routine. Factor out common init, and processing code into common internal routines.

package TWiki::Plugins::PerlDocPlugin;

BEGIN {
    use vars qw(
                $TWIKI_BASE
                );

    $VERSION = '1.002';

    $TWIKI_BASE = '?Unknown?';
    if( $TWiki::Plugins::VERSION < 1 ) {
        $TWIKI_BASE = 'OLD';
    } elsif( $TWiki::Plugins::VERSION == 1 ) {
        $TWIKI_BASE = 'CAIRO';
    } else {
        $TWIKI_BASE = 'DAKAR';
    }
#    print STDERR "PerlDocPlugin: [$TWIKI_BASE]\n";
} # BEGIN
.
.
.
inside initPlugin {
   if( $TWIKI_BASE eq 'DAKAR' ){
       if( $enable ){
           TWiki::Func::registerTagHandler( 'PERLDOC', \&_PerlDoc );
       }
       return(1);
   } elsif( $TWIKI_BASE eq 'CAIRO' ){
       # Plugin correctly initialized
       return( $enable );
   }
.
.
.
} # initPlugin


Then the following conditional eval
my($code_def);
if( $TWIKI_BASE eq 'CAIRO' ){
   $code_def = q[sub commonTagsHandler { ..... } ];
} elsif( $TWIKI_BASE eq 'DAKAR' ){
   $code_dev = q[ sub _PerlDoc { ... } ];
}
eval $code_def;
...

Does this look ok to you? It works on my Dakar version, I have the Cairo tarball, and I will try with that also.

I have attached my version here. Note I have only verified on Dakar (right now), I will install Cairo and test (tomorrow). If this idea works, I will use the same trick for the TagMePlugin. (Merging into the current code base)

-- CraigMeyer - 11 Apr 2007

Turns out, I made a slight error in the Cairo vs. Dakar check. The code should be:

    $TWIKI_BASE = '?Unknown?';
    if( $TWiki::Plugins::VERSION < 1 ) {
        $TWIKI_BASE = 'OLD';
    } elsif( $TWiki::Plugins::VERSION < 1.1 ){
        $TWIKI_BASE = 'CAIRO';
    } else {
        $TWIKI_BASE = 'DAKAR';
    }

Peter, I have tested this with "TWiki version 04 Sep 2004 $Rev: 1742 $, Plugin API version 1.025" which is Cairo, and it works! So, I have updated the attachment.

-- CraigMeyer - 12 Apr 2007

Great, thanks Craig. The version check looks fine, you can compare this with the BlackListPlugin code if you like. Please feel free to update the plugin package (edit the plugin topic with Cairo to stay compatible with the topic format; see other hints), and check it into SVN's MAIN branch.

-- PeterThoeny - 13 Apr 2007

JoenioCosta contributed the PodPlugin, useful to use TWiki collaboratively to create POD for Perl programs. (The PerlDocPlugin is used to extract POD from Perl code.)

-- PeterThoeny - 28 May 2008

This plugin could be used to create an equivalent to the perldoc command, or the podwebserver which comes with CPAN:Pod::WebServer, for use with modules that contain TWiki-style API documentation. I love the fact that it handles both POD and TWiki-style documentation!

In my opinion, an easy improvement would be to move (or copy) the form from the top of the PerlDocPlugin page to a dedicated topic, without the installation info and stuff appended. With a "standardized" name for the new topic with the form, hyperlinking to other modules' documentation should also be feasible to implement - maybe not perfect, but helpful in many cases.

-- Harald Jörg - 2015-12-19

Sounds good, please feel free to hack away.

-- Peter Thoeny - 2015-12-19

Here is another idea: Create a standalone script using this module. That way it could be used as part of an automated build process, as well as part of a TWiki workflow in conjunction with the IfThenActionPlugin.

-- Peter Thoeny - 2015-12-19

That was my first idea: Creating a separate script, a TWiki equivalent to perldoc, so that I could point the browser to .../twiki/twikidoc?module=TWiki::Time and get the description. While perldoc works from the console/xterm, I didn't want to spend the time to write a plaintext renderer for TWiki, so feeding it to the TWiki rendering machine is quite fine. Then you pointed me to the PerlDocPlugin, which does practically the same with a combination of view, PERLDOC, and URLPARAM, getting the rendering engine for free, so I am about to abandon that idea.

As for the automated build process: There is already an offlne script core/tools/gendocs.pl which can be used for this purpose. It is ten years old, isn't exactly well documented, makes smelly assumptions about POD syntax, but this is how SourceCode is generated. An overhaul of this procedure might be due, I commented on a shortcoming on that topic.

Anyway, that's a different purpose: When creating docs as part of a build process, only TWiki modules are processed. What I'd like to have is a way to view docs while developing, not having to distinguish between CPAN and TWiki modules in my habits to read the docs, and not going through a build process for all documents too often. As a positive side effect, I hope to spot shortcomings in the TWiki documentation while I'm in developing mode, so fetching the offending module, fixing the docs and reloading the page gives immediate positive feedback when I need it.

-- Harald Jörg - 2015-12-19