From westerman at purdue.edu  Wed Dec  3 05:19:47 2014
From: westerman at purdue.edu (Rick Westerman)
Date: Wed, 3 Dec 2014 08:19:47 -0500
Subject: [Purdue-pm] Variables in POD docs
Message-ID: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>

Found an interesting way to embed variables into pod.  You might want this so you could report the VERSION both inside pod plus as $VERSION.  But you could also do this for exported modules.  You could make a list of routines plus their descriptions to be shown in pod plus have them in the actual @EXPORT thus avoiding the need have the routine listed twice ? and potentially missing the documentation when a new routine is added to the module.  Another use is to show a hash or array inside pod.


I?ll probably give a short talk on this at the next Mongers meeting.  Dave, in the meantime, could look at my recent PI.pm module for concrete examples.

The idea is to do a here-is capture of the POD comments and then parse out the Perl-runtime information from the captured doc.  There is a small run-time hit in doing the parsing but I do not think that the hit is significant and the ability to not have to have information in two places is powerful.  A short example:


=====

my $version_pod = <<'=cut';

=head1 VERSION 1.0

    Complete re-write to use database and to be more stable. 

=cut

our ($VERSION) = $version_pod =~ m/VERSION\s+(.*)/;

=====



--
Rick Westerman
westerman at purdue.edu





From westerman at purdue.edu  Wed Dec  3 07:53:17 2014
From: westerman at purdue.edu (Rick Westerman)
Date: Wed, 3 Dec 2014 10:53:17 -0500
Subject: [Purdue-pm] Variables in POD docs
In-Reply-To: <37430.1417621745@pier.ecn.purdue.edu>
References: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>
	<37430.1417621745@pier.ecn.purdue.edu>
Message-ID: <BF905139-F5DF-41FF-AE22-56CE52BF3F5D@purdue.edu>

There is no doubt that POD is not very powerful.  I am not overly fond of it myself.  But it is universal and widely accepted.  Given that I force myself to use it.  If I could define Perl variables and insert them into POD instead of vice-versa then I would do that.  But it just isn?t possible.




--
Rick Westerman
westerman at purdue.edu




> On Dec 3, 2014, at 10:49 AM, Mark Senn <mark at ecn.purdue.edu> wrote:
> 
> Rick Westerman <westerman at purdue.edu> wrote on 2014-12-03 at 08:19-0500
> |  Found an interesting way to embed variables into pod.  You might want
> |  this so you could report the VERSION both inside pod plus as $VERSION.
> |  But you could also do this for exported modules.  You could make a list
> |  of routines plus their descriptions to be shown in pod plus have them in
> |  the actual @EXPORT thus avoiding the need have the routine listed twice
> |  ? and potentially missing the documentation when a new routine is added
> |  to the module.  Another use is to show a hash or array inside pod.
> |  
> |  I?ll probably give a short talk on this at the next Mongers meeting.
> |  Dave, in the meantime, could look at my recent PI.pm module for concrete
> |  examples.
> |  
> |  The idea is to do a here-is capture of the POD comments and then parse
> |  out the Perl-runtime information from the captured doc.  There is a
> |  small run-time hit in doing the parsing but I do not think that the hit
> |  is significant and the ability to not have to have information in two
> |  places is powerful.  A short example:
> |  
> |  =====
> |  
> |  my $version_pod = <<'=cut';
> |  
> |  =head1 VERSION 1.0
> |  
> |      Complete re-write to use database and to be more stable. 
> |  
> |  =cut
> |  
> |  our ($VERSION) = $version_pod =~ m/VERSION\s+(.*)/;
> |  
> |  =====
> 
> I like to define things top down instead of from the inside out.
> I don't like POD, I like to use my pro file preprossor along
> with LaTeX typesetting system software for tasks like this---it
> gives me more power and control.  Below is a short example of
> one way it can be done.
> 
> =====
> 
> :: Start Perl program.
> #!/usr/local/bin/perl
> 
> :: Give some gratuitous Emacs advice.
> ::
> :: I set up my .emacs file so typing Control-C Control-D inserts, for example,
> ::     z.pl  2014-12-03  Mark Senn'
> :: if a string like that doesn't exist.  If a string like that does exist
> :: it updates the date in the first matching string.
> .$revised = 'z.pl.pro  2014-12-03  Mark Senn'
> .$created = 'z.pl.pro  2014-12-03  Mark Senn'
> 
> :: Define version in outermost scope.
> .$version = '1.0'
> 
> :: Compute LaTeX file name.
> .($latexfile) = $revised =~ m#^(^[^.]+)#
> .$latexfile .= '.tex'
> 
> :: Produce rest of LaTeX input.
> .divert $latexfile
> \head1{VERSION .<$version>}
> 
>    Complete re-write to use database to be more stable.
> .revert
> 
> :: Produce rest of Perl program.
> print "version is $version\n";
> 
> =====
> 
> -mark


From mark at ecn.purdue.edu  Wed Dec  3 08:30:00 2014
From: mark at ecn.purdue.edu (Mark Senn)
Date: Wed, 03 Dec 2014 11:30:00 -0500
Subject: [Purdue-pm] Variables in POD docs
In-Reply-To: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>
References: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>
Message-ID: <5007.1417624200@pier.ecn.purdue.edu>

Rick Westerman <westerman at purdue.edu> wrote on 2014-12-03 at 08:19-0500

|  Found an interesting way to embed variables into pod.  You might want
|  this so you could report the VERSION both inside pod plus as $VERSION.
|  But you could also do this for exported modules.  You could make a list
|  of routines plus their descriptions to be shown in pod plus have them in
|  the actual @EXPORT thus avoiding the need have the routine listed twice
|  ---and potentially missing the documentation when a new routine is added
|  to the module.  Another use is to show a hash or array inside pod.
|
|  I'll probably give a short talk on this at the next Mongers meeting.
|  Dave, in the meantime, could look at my recent PI.pm module for concrete
|  examples.
|
|  The idea is to do a here-is capture of the POD comments and then parse
|  out the Perl-runtime information from the captured doc.  There is a
|  small run-time hit in doing the parsing but I do not think that the hit
|  is significant and the ability to not have to have information in two
|  places is powerful.  A short example:
|
|  =====
|
|  my $version_pod = <<'=cut';
|
|  =head1 VERSION 1.0
|
|      Complete re-write to use database and to be more stable.
|
|  =cut
|
|  our ($VERSION) = $version_pod =~ m/VERSION\s+(.*)/;
|
|  =====

I like to define things top down instead of from the inside out.
I don't like POD, I like to use my pro file preprossor along
with LaTeX typesetting system software for tasks like this---it
gives me more power and control.  Below is a short example of
one way it can be done.

=====

:: Start Perl program.
#!/usr/local/bin/perl

:: Give some gratuitous Emacs advice.
::
:: I set up my .emacs file so typing Control-C Control-D inserts, for example,
::     z.pl  2014-12-03  Mark Senn'
:: if a string like that doesn't exist.  If a string like that does exist
:: it updates the date in the first matching string.
.$revised = 'z.pl.pro  2014-12-03  Mark Senn'
.$created = 'z.pl.pro  2014-12-03  Mark Senn'

:: Define version in outermost scope.
.$version = '1.0'

:: Compute LaTeX file name.
.($latexfile) = $revised =~ m#^(^[^.]+)#
.$latexfile .= '.tex'

:: Produce rest of LaTeX input.
.divert $latexfile
\head1{VERSION .<$version>}

    Complete re-write to use database to be more stable.
.revert

:: Produce rest of Perl program.
print "version is $version\n";

=====

If you don't need the full power of pro and LaTeX but would still
like to defie things in a "top-down" way do a google search for
    perl preprocessor

-mark

From westerman at purdue.edu  Wed Dec  3 08:56:11 2014
From: westerman at purdue.edu (Rick Westerman)
Date: Wed, 3 Dec 2014 11:56:11 -0500
Subject: [Purdue-pm] Variables in POD docs
In-Reply-To: <5007.1417624200@pier.ecn.purdue.edu>
References: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>
	<5007.1417624200@pier.ecn.purdue.edu>
Message-ID: <80AFFCB9-BFA6-4FA4-ABB2-048D139FADBF@purdue.edu>

> =====
> 
> If you don't need the full power of pro and LaTeX but would still
> like to defie things in a "top-down" way do a google search for
>    perl preprocessor
> 
> -mark

This gets away from pure Perl of having a single file that provides POD documentation and allows for execution.     Oh, I suppose there is some pre-processor that can expand my Perl source file into an executable Perl+POD file but if I am going to do ?make & complie? then there are lots of options to explore ? including pro & LaTeX.  

Using a ?source filter? in a ?use? statement doesn?t help out with the POD docs since none of the pod2* programs will touch a ?use? statement.

I grant that there are many other solutions beside the ?single file? one.  But are any standard in the Perl community?  I think not.  Certainly CPAN ? the granddaddy of modules ? requires single file POD + executable code.   



? Rick

  

From gizmo at purdue.edu  Wed Dec  3 10:43:28 2014
From: gizmo at purdue.edu (Joe Kline)
Date: Wed, 03 Dec 2014 13:43:28 -0500
Subject: [Purdue-pm] Variables in POD docs
In-Reply-To: <80AFFCB9-BFA6-4FA4-ABB2-048D139FADBF@purdue.edu>
References: <23FF9714-C089-4CFF-8744-D14C5A7F29A0@purdue.edu>	<5007.1417624200@pier.ecn.purdue.edu>
	<80AFFCB9-BFA6-4FA4-ABB2-048D139FADBF@purdue.edu>
Message-ID: <547F59D0.4070905@purdue.edu>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ingy as part of his PPW 2014 keynote talked about SWIM

https://metacpan.org/pod/Swim

He likes the structure of POD but wants the Markdown syntax.

https://www.youtube.com/watch?feature=player_detailpage&v=vDRLIjojlhg#t=1897

Interesting idea.

joe
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)

iEYEARECAAYFAlR/Wc8ACgkQb0mzA2gRTpkDiACfZ0oAsWpXAHylncOsauSLXj7J
tgwAoJW+jBQQKcZstg/3qT9pQLqpMCvv
=A2uj
-----END PGP SIGNATURE-----

From gizmo at purdue.edu  Wed Dec  3 11:48:29 2014
From: gizmo at purdue.edu (Joe Kline)
Date: Wed, 03 Dec 2014 14:48:29 -0500
Subject: [Purdue-pm] Variables in POD docs
In-Reply-To: <1260656060.109551.1417633818259.JavaMail.root@mailhub020.itcs.purdue.edu>
References: <1260656060.109551.1417633818259.JavaMail.root@mailhub020.itcs.purdue.edu>
Message-ID: <547F690D.3060902@purdue.edu>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Rick,

I haven't got that far into it.

- From the video I don't think there is SWIM in a Perl program, but I
could be wrong.

I only say that since it uses a Markdown like syntax which gets compiled
to POD. Which Ingy likes because POD gets compiled to HTML better than
Markdown in his opinion.

joe
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)

iEYEARECAAYFAlR/aQwACgkQb0mzA2gRTpndKQCeNarTmeDLn4fNN6E0yzmVQ9Pr
tCgAn0T3eWLskyz0UFGJ+vbm1EDfsi/l
=Ee2v
-----END PGP SIGNATURE-----

From mark at purdue.edu  Fri Dec  5 09:29:43 2014
From: mark at purdue.edu (Mark Senn)
Date: Fri, 05 Dec 2014 12:29:43 -0500
Subject: [Purdue-pm] interpolate perl variables in pod
Message-ID: <40694.1417800583@pier.ecn.purdue.edu>

Another followup to Rick's message about sharing Perl
variable values in Perl and POD.

>From http://www.perlmonks.org/?node_id=714673

    As JavaFan and GrandFather have already mentioned, no, you can't
    directly. However, there's nothing to stop you from generating a POD
    document from a perl script:

    open (my $pod, '>', 'filename.pod') or die "Can't write pod file: $!";
    my $my_perl_variable = 'something';
    print $pod <<EOF;
    =head1 Imaginary Interpolation
    This was defined previously: C<$my_perl_variable>
    =cut
    EOF

    Of course, this would mean that you'd have to trigger the re-writing
    process somehow ... if you were to give an interface for updating
    whatever your variables were, you could regenerate the pod
    afterwards. I personally couldn't see the advantage of doing this,
    but I don't know what your full intentions are.

http://www.perlmonks.org/?node_id=714673 links to
    http://www.perlmonks.org/?node_id=515663
which has some more ideas.

http://www.perlmonks.org/?node_id=714673 also links to
    http://www.perlmonks.org/?node_id=48645
which didn't contain much usefil information in my opinion.

(Or, maybe just replace, for example ---VERSION---, in
a program.pl-replace file with sed to make a program.pl file.
This has the advantage if you want to sync version numbers
on multiple programs and/or docs without making any file changes.
I used this type of thing for a project I did years ago
and it worked out prettty well.)

-mark

From westerman at purdue.edu  Fri Dec  5 09:51:53 2014
From: westerman at purdue.edu (Rick Westerman)
Date: Fri, 5 Dec 2014 12:51:53 -0500 (EST)
Subject: [Purdue-pm] interpolate perl variables in pod
In-Reply-To: <40694.1417800583@pier.ecn.purdue.edu>
Message-ID: <1961749825.115533.1417801913868.JavaMail.root@mailhub020.itcs.purdue.edu>

Mark's links, especially 

http://www.perlmonks.org/?node_id=515663

were ones that I had already read and were the ones that gave me the idea to extract variables from POD.

I think that we all agree that POD is outdated -- a different document engine within Perl would be nice.  And we probably all agree that a two-step method -- compile'n'run or pro'n'latex or POD-preprocessor -- would provide for a more powerful solution albeit at the cost of having two or more files for every program.  However what I am trying to show is a neat POD hack within the confines of what is universal -- POD inside the single executable file. 



----- Original Message -----
> Another followup to Rick's message about sharing Perl
> variable values in Perl and POD.
> 
> From http://www.perlmonks.org/?node_id=714673
> 
> As JavaFan and GrandFather have already mentioned, no, you can't
> directly. However, there's nothing to stop you from generating a POD
> document from a perl script:
> 
> open (my $pod, '>', 'filename.pod') or die "Can't write pod file: $!";
> my $my_perl_variable = 'something';
> print $pod <<EOF;
> =head1 Imaginary Interpolation
> This was defined previously: C<$my_perl_variable>
> =cut
> EOF
> 
> Of course, this would mean that you'd have to trigger the re-writing
> process somehow ... if you were to give an interface for updating
> whatever your variables were, you could regenerate the pod
> afterwards. I personally couldn't see the advantage of doing this,
> but I don't know what your full intentions are.
> 
> http://www.perlmonks.org/?node_id=714673 links to
> http://www.perlmonks.org/?node_id=515663
> which has some more ideas.
> 
> http://www.perlmonks.org/?node_id=714673 also links to
> http://www.perlmonks.org/?node_id=48645
> which didn't contain much usefil information in my opinion.
> 
> (Or, maybe just replace, for example ---VERSION---, in
> a program.pl-replace file with sed to make a program.pl file.
> This has the advantage if you want to sync version numbers
> on multiple programs and/or docs without making any file changes.
> I used this type of thing for a project I did years ago
> and it worked out prettty well.)
> 
> -mark

-- 
Rick Westerman 
westerman at purdue.edu

Bioinformatics specialist at the Genomics Facility.
Phone: (765) 494-0505           FAX: (765) 496-7255
Department of Horticulture and Landscape Architecture
625 Agriculture Mall Drive
West Lafayette, IN 47907-2010
Physically located in room S049, WSLR building

From gizmo at purdue.edu  Tue Dec 16 08:10:32 2014
From: gizmo at purdue.edu (Joe Kline)
Date: Tue, 16 Dec 2014 11:10:32 -0500
Subject: [Purdue-pm] Mongering today, yes?
Message-ID: <54905978.4070503@purdue.edu>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)

iEYEARECAAYFAlSQWXcACgkQb0mzA2gRTplkcwCgizjbCl45z73y1vu38CUi4hGI
/7kAn17KmsIj5e/FSv6qeGEeZRNarjGT
=fZ7m
-----END PGP SIGNATURE-----

From djacoby at purdue.edu  Tue Dec 16 08:34:50 2014
From: djacoby at purdue.edu (djacoby)
Date: Tue, 16 Dec 2014 11:34:50 -0500
Subject: [Purdue-pm] Mongering today, yes?
Message-ID: <idquowt80spwlb2roscl611u.1418747690687@email.android.com>

I'm here, but looks like my announce code didn't fire off


Sent from my pocket supercomputer

<div>-------- Original message --------</div><div>From: Joe Kline <gizmo at purdue.edu> </div><div>Date:12/16/2014  11:10 AM  (GMT-05:00) </div><div>To: Purdue Perl Mongers <purdue-pm at pm.org> </div><div>Subject: [Purdue-pm] Mongering today, yes? </div><div>
</div>-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)

iEYEARECAAYFAlSQWXcACgkQb0mzA2gRTplkcwCgizjbCl45z73y1vu38CUi4hGI
/7kAn17KmsIj5e/FSv6qeGEeZRNarjGT
=fZ7m
-----END PGP SIGNATURE-----
_______________________________________________
Purdue-pm mailing list
Purdue-pm at pm.org
http://mail.pm.org/mailman/listinfo/purdue-pm
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.pm.org/pipermail/purdue-pm/attachments/20141216/81b4c589/attachment.html>