Larry Wall wrote:
So I think a named reference is a good compromise, where the name in
the documentation (in some easily recognized syntactic form) refers
to the next declaration (or set of declarations) of that same name.
Hopefully the pod either knows implicitly or has been told explicitly
how to parse out such declarations for insertion into the document.
(And a positional notation could just be a degenerate case of not
specifying the name (or using a name of * maybe), so it finds the
next declaration of any name. Maybe even some kind of wildcarding
works for hybrid situations.)
The syntax for such named forward references is open for bikeshedding.
(I've intentionally not given any examples in this message to avoid
prejudicing the matter.)
My first instinct for such a thing would be to surround the perl code
to be referenced with POD-like tags:
=code name
class foo
...
=/code
...the idea being that a Perl parser treats the =code and =/code lines
as line comments, while a Pod parser would take the block of lines
that exists between the two and attaches it to 'name', to be rendered
as is whenever 'name' is referenced.
In short, =code and =/code would define a target which could then be
referenced as few or as many times as you want within your regular
perl code using something like
=ref name
...where POD would substitute
class foo
...
every time that it sees
=ref name
--
Expanding on this idea:
* if you don't specify a name on a '=ref' line, you automatically
reference the next '=code' section to be found. If you don't bother
naming a '=code' section, this is the only way that it can be
referenced. If you give '^' as the name, then you automatically
reference the last code section that was found. So:
=begin pod
=ref
=end pod
=code
foo
=/code
=begin pod
=ref ^
=end pod
would render the same as
=begin pod
foo
=end pod
=begin pod
foo
=end pod
* Put a number instead of a name, and it counts up (if negative) or
down (if non-negative) through the code blocks, with -1 being the
previous code block and 0 being the next one. A blank name is
equivalent to 0, and a '^' is equivalent to -1. This should be used
sparingly.
* Add or subtract a number to/from a name, and you count up or down
from that name, with '+1' giving the first code block following the
named codeblock and '-1' giving the last code block prior to it.
* In the same way that '=code'...'=/code' is designed to mimic the
'=begin'...'=end' syntax of POD blocks, you could introduce a
variation of '=code' that mimics the '=for' syntax by grabbing the
next line or block of code (say, '=codeline' and '=codeblock'), where
a block of code is terminated by a blank line.
* the final violation of the separation of Church and State would be
to have the Church ask the State to do something for it. Let a
'=code' line specify a parser (such as perl): Pod passes the block of
code to the specified parser; that parser then (presumably) goes
through its paces with the goal of extracting language-specific
documentation (such as the previously suggested 'is doc' traits),
formatting the result as a text block, and handing that block back to
the POD parser. If Pod can't talk to the language parser or vice
versa, Pod simply uses the code block as is.
--
Jonathan "Dataweaver" Lang
