I am seeking wisdom on the best way to structure my code as I haven't yet found any examples of anyone else doing what I am trying to do.

I have written a utility with a number of command line front ends that use a single backend module. Up until now there has been a single POD file that covers all the front end scripts, but this means options that are used in one script are documented but unused and useless in the other scripts, and the pod is bloated with unnecessary detail.

To tidy this up I am amending the front end scripts to register what non-common options are used, and keeping the common ones in the back end module, so at build time the pod is generated for each script with only the relevant options.

So far, so good.

In order to be a good international perl citizen, I am also aiming for localising all the options. Since I am now generating the pod to put only the required options in for each script, this means I should also localise the rest of the pod, too, and this is where all the localisation code seems to be getting very messy.

I am currently using Locale::Maketext (I am thinking of swapping eventually to a gettext based module) and I am breaking down the POD into sections, putting each section into my translation module. I almost have all the pod complete, but it looks and feels like a mess (and the last few sections will make this worse). As a result, I can see it will be awkward to maintain and be difficult for a translator to do their work.

So, I do want to generate the pod so it is specific to each script, and I do want to localise as much as I can, but should I also be trying to localise the pod, and what is the "better way" I am missing?

Instead of including code within this post I am providing links to the code in github

Example front end scripts: - https://github.com/duncs/clusterssh/blob/getopt/bin_PL/cssh - https://github.com/duncs/clusterssh/blob/getopt/bin_PL/ccon

Target pod I am working towards - https://github.com/duncs/clusterssh/blob/getopt/bin_PL/expected_cssh.pod I am testing the generated code against the expected with the following: 

perl Build.PL ; ./Build && perldoc bin/cssh > /tmp/cssh.pod.new && per
+ldoc bin_PL/expected_cssh.pod > /tmp/cssh.pod.orig && diff -u /tmp/cs
+sh.pod.orig /tmp/cssh.pod.new | more

[download]

The backend module dealing with parsing of options; the generation of the pod is from line 275 - https://github.com/duncs/clusterssh/blob/getopt/lib/App/ClusterSSH/Getopt.pm

The Locale::Maketext based translation module: - https://github.com/duncs/clusterssh/blob/getopt/lib/App/ClusterSSH/L10N/en.pm

Thanks for any advice or observations provided.

Duncs

In reply to Organising and localising generated POD by duncs

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.