Converting your perl module documentation into confluence

Short story

perldoc -u myPerlModule.pm | pod2wiki -s confluence > myConfluenceDoc

The key point is to use -u for printing out the original POD code (without any formatting).


Probably it is possible to use perldoc -owiki but I do not know yet how to pass the -s confluence. I will look at that later.

Long story

Today I was documenting some of my perl modules in our Confluence wiki when I decided to paste the POD. First I tried the HTML output copying it between {html}{html} directives, but as the .css was not created, the \blocks where not boxed, and I wanted them boxed.
HTML output

perldoc -ohtml  myPerlModule.pm

Then I made the output in text and used a oneliner to put some confluence markup
But these was not complete and needed some hand curation.
So I search in CPAN and find that Confluence is supported in the Pod::Simple::Wiki and also give you a script for that pod2wiki
pod2wiki accepts POD as input from STDIN, nice, so I printed the pod and passed to pod2wiki: perldoc myPerlModule.pm | pod2wiki -s confluence
NO OUTPUT!!!!!!!!!!
Today I was a bit slow, and took me some time to realize that perldoc does not print 'POD' but man-formatted POD. I did perldoc perldoc to find out how to print the raw POD of the document: option -u
Confluence output

perldoc -u myPerlModule.pm | pod2wiki -s confluence > myConfluenceDoc

Confluence does not have sectional editing, Are you kiding? nop!!!

It's sad but today I realized that confluence does not have sectional editing and they have been discussing about that since 2005!!!!!

[#CONF-5913] Sectional Editing - Atlassian JIRA

Confluence
Sectional Editing

They propose some workaround, but they are not good. Basically they use {include} to include pages but then, you miss the subsections from this pages in the main TOC.

Also this is distracting. Wiki (as aHawiian word) mean quick! and this is the thing that I want. Quick text editing low I like to edit the wiki in markup-txt and sometime I write my wiki pages in emacs and copy/paste to the wiki later. This 'include' workaround breaks one of the good things of the wiki: its flexibility to combine big pages and multilinked micropages. Sometimes you want one thing, sometimes you want the other. Big pages without the sectional editing is a a bad thing because:

• a) you block the whole page for editing preventing other users to contribute
  
• b) difficult to find your text in the only text area (and having confluence headings like h1. h2. instead = =, == == etc does not help)
• c) is very slow to load a page
  
• d) moving from wisiwig to wiki-markup puts you back at the beginning of the text and you need to find your place again