[Bioperl-l] bug #1396: *.PL to *.pod conversion is broken, makebailsout

[Hilmar Lapp]

I don't quite understand how this would work in reality, but I trust 
Brian and you can work out something that

	a) makes it relatively difficult to have stale version numbers in 
documentation upon releases (which was the original problem Allen was 
trying to solve),

	b) does not make a documenter's life more miserable by requiring him 
to pay attention to otherwise unnecessary things like hand-escape all 
variables in the text,

	c) is simple enough to enable a willing documenter to create a 
conforming file from scratch without having to take a class,

	d) doesn't break documentation containing code snippets nor causes 
running make to fail, and

	e) doesn't require a user to install esoteric packages for solely this 
purpose

I'll appreciate and welcome whatever Brian and you suggest and 
accomplishes this; if I remain silent on a particular suggestion, it 
doesn't mean that I don't like it, I may just not understand it.

	-hilmar

On Thursday, March 6, 2003, at 06:39  AM, Aaron J Mackey wrote:

>
> Let me just toss in a small recommendation that you might want to 
> consider
> "reversing" the problem; instead of reading/interpolating variable 
> values
> in POD, try providing the values in regular POD format, and using
> Pod::Constants to extract and set the corresponding variables:
>
> use vars qw($VERSION);
> use Pod::Constants VERSION => sub { eval };
>
> =pod
>
> =head2 VERSION
>
> $VERSION = 1.1
>
> =head2 SYNOPSIS
>
>   # perl code that will not be interpolated
>   my @foo = blah_blah('blah');
>
> =cut
>
> On Thu, 6 Mar 2003, Brian Osborne wrote:
>
>> Lincoln,
>>
>> You'd mentioned something about using @@VERSION@@ but my searches 
>> using this
>> word or "@@" didn't turn up anything. Can you direct me to a man page 
>> or Web
>> page or application that discusses this?
>>
>> Brian O.
>>
>>
>> -----Original Message-----
>> From: Hilmar Lapp [mailto:hlapp at gnf.org]
>> Sent: Thursday, March 06, 2003 2:33 AM
>> To: Allen Day
>> Cc: Bioperl; Lincoln Stein; brian_osborne at cognia.com
>> Subject: Re: [Bioperl-l] bug #1396: *.PL to *.pod conversion is 
>> broken,
>> makebailsout
>>
>>
>> On Wednesday, March 5, 2003, at 08:20  PM, Allen Day wrote:
>>
>>> Hey, sorry, I wasn't following this thread.  Has there been a
>>> resolution
>>> on this, or do I need to fix it?
>>>
>>> There had been some variables in other of the converted .pod files, I
>>> tried to separate the pod into two types of sections:
>>>
>>> (1) those where i needed to do variable interpolation from LocalConf
>>> were
>>>     put in <<"HEREDOC" blocks
>>> (2) everything else (including variables in pseudocode) were put in
>>>     non-interpolated <<'HEREDOC' blocks
>>>
>>
>> I'm not sure how a non-interpolated HERE-document looks, but as a
>> matter of fact biodesign.PL and biodatabases.PL were all one document,
>> and variables were interpolated all over the place.
>>
>> Lincoln fixed this by manually escaping all variables.
>>
>>> I don't get any errors during the make, but it might just be my 
>>> system.
>>
>> Most of the interpolated variables do not yield errors. Only the 
>> arrays
>> (@arr) do. Scalars silently result in emptiness.
>>
>> I guess you noticed the move to pub.open-bio.org meanwhile.
>>
>>         -hilmar
>>
>> --
>> -------------------------------------------------------------
>> Hilmar Lapp                            email: lapp at gnf.org
>> GNF, San Diego, Ca. 92121              phone: +1-858-812-1757
>> -------------------------------------------------------------
>>
>>
>> _______________________________________________
>> Bioperl-l mailing list
>> Bioperl-l at bioperl.org
>> http://bioperl.org/mailman/listinfo/bioperl-l
>>
>
> -- 
>  Aaron J Mackey
>  Pearson Laboratory
>  University of Virginia
>  (434) 924-2821
>  amackey at virginia.edu
>
>
>
-- 
-------------------------------------------------------------
Hilmar Lapp                            email: lapp at gnf.org
GNF, San Diego, Ca. 92121              phone: +1-858-812-1757
-------------------------------------------------------------