RE: [GT] POD changes

["Weigert, Thomas" <weigert AT mst.edu>]

There are two ways of dealing with documentation. 

One is to study it source file by source file, and in that case, the
perldoc command is the simplest. Some users like to get an overview and
want to generate all the documentation in one place, for those users,
pod2latex is a good strategy.

In either way, the documentation should be in a consistent format and
should generate correct output. There were a number of places where this
was not the case. E.g., headers were off, descriptions were not properly
terminated, teletype font is misused at times, etc. While you did get
some output, it did not always look good.

So while I phrased below in terms of the resultant file when the
documentation is created all in one place, the same is true for perldoc.

This set of updates makes the documentation more readable and
consistent. Albeit there are still differences as different styles were
used in various parts of the system. But it is much closer now....

Th.

> -----Original Message-----
> From: Robert A. Schmied [mailto:ras
AT
acm.org]
> Sent: Wednesday, June 11, 2008 1:21 AM
> To: devel
AT
geniustrader.org
> Subject: Re: [GT] POD changes
> 
> 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.
> >