Brent wrote:

I've probably been hanging around Web standards nazis for too long,
but can we get a separate code to mark the title of a document that
can't be linked to (say, a book) along the lines of HTML's <cite> tag?

Hmmmmmm. Maybe. Care to nominate a letter for that? C<>, I<>, T<>, and E<> are all take already. ;-)

Actually, a couple more link schemes could probably handle my previous request:

   L<Perl 6 and Parrot Essentials|urn:isbn:059600737X>
   L<Parrot Magic Cookies in The Perl Review|urn:issn:1553667X/3/0#11>

Why wouldn't that just be:

     L<Perl 6 and Parrot Essentials|isbn:059600737X>
     L<Parrot Magic Cookies in The Perl Review|issn:1553667X/3/0#11>


Oooh, transclusion--shiny.  Perhaps the pipe character can be used to
provide alternative text:

   P<See standard copyright terms in the distribution.

I like it. The only concern would be that, everywhere else that a pipe is valid, the LHS is rendered instead of the RHS. Here it would be reversed. Arguably, by that measure, it ought to be:

      |See standard copyright terms in the distribution.>

Of course, you could always argue that the LHS is the "text side" and the RHS the "URL side". Hmmmmmmmmm. I need to think about that a little more.

Also, what about non-textual files?  If I type
P<>, will an onion
appear in my Pod document?  That would obviate custom =Image

That would depend on the renderer. The parser will certainly accept it. I'd expect that renderers that can render images would probably do so.

Perldoc provides a mechanism by which you can extend the syntax and semantics of your documentation notation: the C<=use> directive. can this be made to work?  Are renderers going to have to
know about every possible plugin?  Are plugins going to have to know
about every possible renderer?  Will dogs and cats be living together?

To answer your questions in order: Easy. No. No. Hell no!

The parser doesn't change when you extend syntax and semantics. Plugins can only change the syntax of the *contents* of a new block type, not the way the parser parses those blocks. For example, to get Markdown syntax and semantics, you write:

    =use Perldoc::Plugin::Markdown

    =begin Markdown

    *Markdown* syntax and semantics _in this block_

    =end Markdown

The parser would still parse the Markdown block to create a Perldoc::Block::Markdown object, even if you hadn't C<=use>'d the module. The C<=use> merely allows the parser and/or renderer to load the class definition of the Perldoc::Block::Markdown class, so that the object can be constructed correctly (and, presumably, the contents of the block can be interpreted meaningfully).

So, in other words, the syntax of Pod blocks is invariant, allowing the parser to reduce Pod to a standard internal object stream, which each renderer (and any plug-in extension) can do with as it will.

I obviously need to make those points clearer in the synopsis. Thanks.

C<=config> specifications are lexically scoped to the block in which
they're specified.

   =config head3 :numbered

There is no C<=cut> in Perl 6. And in your example it wasn't needed, BTW, since Pod reverts to ambient code after each block unless you're nested inside a =begin...=end pair.

   method foo($bar, $baz) {

   =head3 C<foo(>R<bar>C<, >R<baz>C<)>

Is that =head3 numbered, or is it in a different lexical scope?

Assuming the =cut wasn't there, the =head3 would be numbered, since you'd be in the same lexical scope. Lexical scopes are defined by =begin..=end pairs, not by the "chunking" of Pod within ambient code.

(Actually, I don't see any reference to =cut in this spec.  Is it
still there or not?)

Not. :-)


Reply via email to