Raiph elucidated:
> Hmm. I was thinking Pod would be parsed by a P6/PGE grammar, one that
> could be relatively easily edited/extended to suit another context, because,
> I thought, it could then be made available as a stock --doc subsystem that
> all PCT based languages get more or less for free.
Sure, that might be possible. The problem is one of syntax. Pod, as currently
specified, defines two syntaxes for magic comments that define documentation.
The difficulty is that both those syntaxes might already be in use in
other languages (the /^ \h* \= <ident>/ syntax most certainly will be),
so you end up having to change the Pod parsing syntax on a per-language
basis. I can't really see that being very attractive to the implementors
of other languages, nor the inconsistency being very attractive to users
of those languages.
>> We need a way of referring to ambient code within Pod, without the
>> Podder having to write more code to get it.
>
> I was thinking it would be possible to reference (compiler) variables
> representing eg. the name and sig of a block being parsed, or a block
> or declaration which has just been parsed, or which is just about to be
> parsed, and that simply referencing these variables would be ok and
> would save the need to create explicit named anchors.
Well, that certainly *is* possible in Pod, which will definitely have
access to any compile-time
Perl variables, including the following usually bits of information:
$?FILE Which file am I in?
$?LINE Which line am I at?
&?ROUTINE Which routine am I in?
&?BLOCK Which block am I in?
$?SCOPE Which lexical scope am I in?
$?PACKAGE Which package am I in?
$?MODULE Which module am I in?
$?CLASS Which class am I in? (as variable)
$?ROLE Which role am I in? (as variable)
$?GRAMMAR Which grammar am I in?
But that's not necessarily enough. I can imagine many other pieces of code that
you might want both in the source and in the documentation, but which it would
not be easy to extract from the introspective variables. For example:
PRE
=alias precondition
{
$_ > 0
}
or:
if ($?TESTING)
=alias example1
{
my $tree = TreeClass.new();
$tree.size() == 0 :ok<Trees start life empty>;
$tree.insert("node value");
$tree.size() == 1 :ok<Insertion increases tree size>;
}
Not to mention all of the clever uses I can't think of yet. ;-)
Damian
