• Do not register here on develop.twiki.org, login with your twiki.org account.
• Use View topic Item7848 for generic doc work for TWiki-6.1.1. Use View topic Item7851 for doc work on extensions that are not part of a release. More... Close
• Anything you create or change in standard webs (Main, TWiki, Sandbox etc) will be automatically reverted on every SVN update.
Does this site look broken?. Use the LitterTray web for test cases.

Item7707: POD formatting fails after a =pod directive

Item Form Data

AppliesTo: Component: Priority: CurrentState: WaitingFor: TargetRelease ReleasedIn
Extension PerlDocPlugin Normal Closed TWiki:Main.HaraldJoerg    

Edit Form Data

Summary:
Reported By:
Codebase:
Applies To:
Component:
Priority:
Current State:
Waiting For:
Target Release:
Released In:
 

Detail

An extra =pod directive, as for example in the plugin module PerlDocPlugin.pm itself, spoils actual POD formatting by said plugin.

Cause: In sub translatePod2TWiki,

  1. a plain =pod directive switches the parser into twiki mode (bad), which
  2. in turn switches off POD formatting (good).
In my opinion it is quite fine to suppress POD formatting in twiki mode: TWiki isn't POD, and has its own markup syntax. But how come that an explicit =pod switches the parser into twiki mode? Here it becomes dirty.

Many TWiki modules (right now I stumbled over TWiki::Render) start with a =pod directive, followed by TWiki markup. This is just wrong from a POD point of view. The current interpretation of =pod has been introduced in 2007, "in anticipation of it being used by developers for core docs", see Item4093, and TWiki:Codev.DontShipDotPmTopics. So, apparently, a dubious usage of =pod became widely spread as a de-facto-standard for TWiki's module documentation, which in turn motivated a change of PerlDocPlugin to accomodate for that.

I suggest a two-step approach:

  1. Immediately delete the =pod line from PerlDocPlugin.pm - and voila, POD processing works as desired. That's just fixing the symptom, but good enough right now.
  2. In an extra Item yet to be discussed on a release meeting, fix all TWiki module documentation to be conforming to the POD specs.
  3. The third step would be to remove the bad =pod handling from the plugin, but since plugins are intended to be independent of TWiki versions, bad POD will need to be supported until the end of time. Therefore I believe that this third step isn't worth the effort,
Side note: In spite of this bug, PerlDocPlugin usually works quite fine with CPAN modules. The reason is that in traditional POD, the =pod directive is used only in rare edge cases.

-- TWiki:Main/HaraldJoerg - 2015-12-19

ItemTemplate
Summary POD formatting fails after a =pod directive
ReportedBy TWiki:Main.HaraldJoerg
Codebase ~twiki4
SVN Range TWiki-6.0.2-trunk, Sun, 29 Nov 2015, build 29679
AppliesTo Extension
Component PerlDocPlugin
Priority Normal
CurrentState Closed
WaitingFor TWiki:Main.HaraldJoerg
Checkins TWikirev:29704
TargetRelease

ReleasedIn

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2015-12-20 - HaraldJoerg
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback