migrate docs: copy .pm files if .pod files don't exist

[wdpypere]

As part of the documentation clean up it was decided to move to single source, e.g. keep the pod documentation in the pm file. We currently copy over the pod files from src to target to make further documentation.

I managed to make maven copy over the pm files (instead of pod) and then rename them to pod. (in this branch: https://github.com/wdpypere/maven-tools/tree/pmdocs) But this would require us to adapt all components at once, which is not really feasible.

I would like to make this conditional:

• if pods still exist, copy them
• else copy over pm and rename them

But to be honest, I find maven really confusing and not very flexible, so if anyone has any tips or pointers, please share. :smile:

[ned21]

I am definitely a maven novice too! Copying the .pm twice, once for the code and once to make the doc seems a bit wrong. Can't we just call pod2man on the existing copy of the .pm, and then again conditionally if .pod exists?

[stdweird]

to be clear, we agreed to move the documentation from the pod to either pm or to the schema :smile:

I thought pod2man could already handle cases where no pod files existed. but i guess it's the maven filter-pod-sources task that is causing problems?

can you paste the errors here (and the command-line you used), to make sure we're talking about the same issue.

[wdpypere]

@stdweird yes, my memory is getting back. :) pod2man.pl was adjusted by you to look at the .pm file instead of the .pod file if the latter does not exist (https://github.com/quattor/maven-tools/commit/9da18256955f069a8876f9f04eb76eca1d2c2bd6). I'll see if I can do the same for the script that does the markdown generating.