I intend to use that feature to document the TWiki::Func module, which is used by all Plugin authors.

The question is how to show the TWiki::Func doc:

• We could install the Plugin with the TWiki distribution and create a TWikiFuncModule topic that has a %PERDOC{"TWki::Func"}%. That way we get the up-to-date doc all the time, but there is a small performance impact if the Plugin is installed just for that.

• We could just generate the Doc before a release and include the static TWiki markup in the TWikiFuncModule topic. I prefer this since the API is by definition stable for a particular release.

Also, what value do you see to create POD in TWiki format for the core TWiki modules? I do not see much value since folks who are familiar with the code are working on the core code. I would suggest to put resources into better high level docs.

-- PeterThoeny - 02 Dec 2002

No surprise - I vote for dynamic generation with a slow addition of POD for all TWiki Code as changes are made. That way everyone can easily customise and learn from the core code.. (and maybe use it for other things.). Also, I don't know how things are at other sites, but I am still runing an older version of the core data files with a patched and hacked version of the Dec2001 release of the code.

I would however argue against creating yet another incompatible docco format, even though its more compact. Surely its better to re-use the translator that already exists, and can then be mixed with other POD embedded perl code.

I'm kind of reluctant to update the TWiki and Main data files as there are configuration bit embedded in them that may have changed, while the code I have modded from cvs and can test in parallel with the live twiki data set.

This is my bad, but like at Unisys, the TWiki got install quickly as a trial and then grew into a mission critical resource over time.

-- SvenDowideit - 02 Dec 2002

Pdoc extracts POD from code and publishes it in HTML format ( http://sourceforge.net/projects/pdoc ). Pdoc uses some standard POD formatting to extract richer docs. It's used ie. in bioperl project ( http://www.bioperl.org/ ). Pdoc in action: http://doc.bioperl.org/releases/bioperl-1.0.2/

Correct me if I am wrong, but IMHO it makes little sense to publish POD as Twiki page - we are not suppose to update it anyway, right? InterwikiPlugin should handle outside links from a Twiki page to Pdoc generated page, if needed.

-- PeterMasiar - 02 Dec 2002

Interesting idea, but completely off-focus. Are we ever going to get BeijingRelease?

-- TWikiGuest - 03 Dec 2002

RE: Publish POD as Twiki page: We need improved TWiki::Func docs. Reading the POD source in a Perl module is not very programmer-friendly; it is more useful to look up function call details in a web page or in the Perl module file with a readable help text, aka TWiki format. Think new. Also, the PerlDocPlugin generates XHTML (just look at the rendered TWiki page), which can be pasted into a TWiki topic or saved as a static HTML file.

RE: Off-focus: I do not agree, this is on target because the currently pending stuff is to catch up with the docs; the Plugin-API doc is not yet at a sufficient level for the BeijingRelease. The PerlDocPlugin comes in handy to generate the Plugins-API doc.

-- PeterThoeny - 03 Dec 2002