Russ Allbery wrote:
>
> Presenting it in
> the RFC as part of a testing framework is actually a bit confusing, since
> the impact of the primitive is a lot broader.
I'll gladly tweak the RFC to be more sensical, for instance by including
your =also for abstract example. The testing example was what made me
think of C<=also>, and I've not thought of any other applications that
would occur when using POD as code documentation. I figured there might
be some application in literate programming, but I'm not a practitioner
of that art. Though I'd hate to think of myself as an illiterate
programmer ;-).
> Currently, =for/=begin are exclusive; they name one or more output formats
> the code is for and all others ignore them.
> What you're doing is
> proposing a fundamentally different kind of translator, one that only
> includes tagged paragraphs rather than defaulting to including everything,
I've wanted that for a while, but to give credit where credit's due,
Michael Schwern put it out in an RFC "Embedded Tests and =test". I kinda
pooh-poohed the =test directive, but I like the =for test/=begin test...=end
test idea. It just needs something like =also to make it work for examples.
I call this new class "POD Extractors", FWIW, since they extract portions
of the POD.
> and then adding a way to tag a paragraph as something that should be
> included by that translator *as well as normal translators*.
Yup.
> This basic idea has other possible uses; one that I can think of
> immediately is C<=also for abstract> which tags the following paragraph as
> the abstract of the document and would let an abstract extractor pull it
> out. (Note that this isn't suitable for indexes, since in general the
> index text shouldn't be translated as part of the document.)
Those sound like things I should put in the RFC.
> What I still don't like about the syntax is that C<=also for>, C<=also
> begin>, and C<=also end> are really keywords in their own right; if we
> implement these sorts of tags, I think we should avoid keywords that
> contain spaces. Something like C<=alsofor> instead would be better, IMO.
Sounds fine to me. If others agree, or at least don't dissent, I'll
tweak them in the RFC.
> The most abstracted way of viewing this is "paragraph tagging"; these new
> keywords tag a bunch of POD input as being associated with some keyword
> that special translators use. Viewed in that light, I can see the utility
> (although I'd like to hammer down the definition; we've suffered a lot
> from the fact that the way the argument to =for/=begin is treated is
> rather ill-defined); it's worth considering whether =also is the best name
> for it.
I try to spell out simple handling rules in the RFC, boiling =also down
to being invisible to normal translators, and being just like "=for ...",
"=begin ...", or "=end ..." for extractors.
Hammer away, I'll tweak the RFC when we're done.
- Barrie
