Thanks, Damien for synposis 26 on pod. I am not sure where to suggest additional features, so let me try it here.

Suggestion #1:

It would be nice if I could designate some snippets to become both code and pod. For example, I may want to define a syntax for a parser in my perl program, 

my %syntax = {
   beginning  =>  qw( keywords ),
   center     =>  qw( code text musings music ),
   end        =>  qw( goodbye )
}

I would want my pod readers to see this to understand the syntax that my parser program allows. alas, this means that I have to maintain two versions: the one in the pod and the identical one in the code--and hope I don't forget to update both appropriately.

it would be great if we had a mechanism that would allow me to tell pod that the following code snippet should make it into the pod formatted output, too.

Suggestion #2:

A more ambitious (and probably to be rejected) suggestion would be to allow me to label a block, and insert it somewhere else. This way, I could define a section 

=head1 SUBROUTINES
=insertrefs allsubs

Now I can keep my subroutine documentation with the subroutines themselves (something like 

=labelfor allsubs
=head2 my function
...

the pod formatter would simply take all subroutine documentation and insert the snippets sequentially where the =insertref allsubs appeared.

of course, maybe I missed it and these two are already possible.

regards, /iaw

Replies are listed 'Best First'.
Re: pod6 --- code+pod suggestion
by rodion (Chaplain) on Dec 17, 2006 at 23:38 UTC
    I have needed both these features, and add my vote to both your suggestions. Regarding Suggestion 1, Pod::Usage is an excellent solution where it's relevant, but it only covers a narrow set of cases. There are many cases where information needs to be in both code and documentation, especially version related information.

    I've also needed your Suggestion 2. I try to make documentation convenient for whoever will maintain the module (and so make it more likely to be maintained), and to make it readable for those who use the module. It's often tough to put code in the module, in the right place to make the user documentation come out the way it should.

[reply]
Re: pod6 --- code+pod suggestion
by jdporter (Paladin) on Dec 18, 2006 at 17:19 UTC

    Based on Synopsis 26, I'd say what you're asking for will already be possible. (Note that it's called Perldoc, not pod6.)

    Synopsis 2 states:

    any POD stream in the current file can be accessed via a filehandle, named as %=POD{'DATA'} and such. Alternately, you can treat a pod stream as a scalar via $=DATA or as an array via @=DATA.

    which is pretty much exactly what I suggested in RFC 79, but since that isn't listed in Apocalypse 2, I don't know if it was ignored or if the idea was simply considered too obvious to require citation, or what.

    We're building the house of the future together.
[reply]
      Though that's useful, that doesn't seem to be the same thing. The OP was asking for a way to have code embedded in the docs, and still be treated as code. What you're talking about seems to be a way to access the docs as data from within code. Now, you might be able to get there from here (read the docs, parse out the code, and run eval), but at the very best that's ugly.
[reply]

        Oh, yeah, you're right.

        In that case I think it's safe to say that RFC 79 was implicitly rejected, if not outright ignored.

        We're building the house of the future together.
[reply]
Re: pod6 --- code+pod suggestion
by Errto (Vicar) on Dec 29, 2006 at 22:47 UTC
[reply]

Back to Meditations