Re: [GT] POD changes

["Robert A. Schmied" <ras AT acm.org>]

Weigert, Thomas wrote:
> I have a large number of changes fixing documentation. These 
>
>    - allow generation of latex from the POD snippets
>    - correct some inconsistencies in the POD snippets
>    - achieve better formatting of the resultant latex docs

i'd like to see a gt_package_doc.pod file that provides the boiler
plate skeleton to be used for pod found in gt packages. maybe a
similar file for gt_scripts. having such files would provide guidance
for users to follow when developing new packages/scripts or making
pod improvements to the current ones.

why a pod file. this is a perl system-application, doc should be pod.
plus automatic website presentation: i believe any file under GT or Scripts
dir-trees with the extensions .pm, .pl and .pod will automatically have
the 'pod' displayed via html on the website doc pages, plus simplicity;
i'm far more accustomed to doing
   perldoc -t <whatever>
than
   acroread <*.pdf>
and don't have a latex installation. lastly i would not be against t/roff
format but i'm fairly confident others would be ;-)

> As many changes are always disruptive, even if they only affect
> non-executable portions of the files, would you prefer these to be
> checked into the main trunk or the experimental branch?

i really don't have a preference, but there might be version
maintenance issues (maybe concerns is a better word than issues)
if pod changes are made to the truck and not immediately merged
onto the exp branch. the consequence would be the need to ensure
that desired truck pod changes don't get reverted when the experimental
gets merged back onto the trunk. svn should be able to handle it, but
it might depend on using the proper process/sequence.

but the same concerns would apply to an altered experimental version
getting updated pod off the trunk version.

any way you slice it there's gonna be more work involved.


ras

> Please advise.
>
> Th.