duncs has asked for the wisdom of the Perl Monks concerning the following question:

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

Replies are listed 'Best First'.
Re: Organising and localising generated POD
by ww (Archbishop) on Jun 11, 2014 at 21:53 UTC
[reply]

      ww, you cannot violate advice, its advice, its not the law

[reply]
Re: Organising and localising generated POD
by Anonymous Monk on Jun 12, 2014 at 01:07 UTC

    How is l10n/i18n generated "pod" going to work (how is the user going to care about it, experience it ... how will you package it )?

    _generate_pod would not appear to belong inside App::ClusterSSH::Getopt ... how your project generates documentation is important stuff that should be documented (in pod) for you and other developers of this app of yours

    I think its common to seperate code based on if its for-users-of-your modules and for-writers-of-your-module

    How pod is generated doesn't sound like something users-of-your-module need to be cluttered with :)

    I've seen a few distributions generate pod but they don't take l10n into account

    So, Locale::Maketext way of organizing the localization data ( Handel::L10N::fr/Apache::MP3::L10N::fr ) sounds good ; esp if you avoid the pitfalls ( Rassie's Doghouse » On the state of i18n in Perl )

    Generating pod sounds good ... be sure to add the headings  =head NAME to your i18n data

    So I don't really see anything too messy ... it is what it is ;)

[reply]
[d/l]

      Thanks for these comments - it has helped me work out what I want to do :)

      I have simplified all the code such that I can swap to Locale::TextDomain in the future

      Duncs

[reply]
Re: Organising and localising generated POD (Class Responsibility Collaboration(crc))
by Anonymous Monk on Jun 12, 2014 at 03:23 UTC

    To help you organize this project (or feel better about it), read these Class Responsibility Collaboration(crc) links, and writeup a version of these cards for your project (you can use asciio (if you got Gtk2) when you've got a version you want to share)

    html version (no overlapping or closeness)

    Read more... (1228 Bytes)

    YAML (HoHoA), (no overlapping or closeness)

    Read more... (851 Bytes)

    App::asciio text diagram, both overlapping and closeness

    Read more... (2 kB)
[reply]
[d/l]
[select]

      Thanks, thats a good idea - not heard of that before but I can see how it works.

      I'll try it out and see how I get on.

      Duncs

[reply]

Back to Seekers of Perl Wisdom