Front page | perl.perl6.language |
Postings from October 2006
Re: Synposis 26 - Documentation [alpha draft]
Thread Previous
|
Thread Next
From:
Damian Conway
Date:
October 14, 2006 05:24
Subject:
Re: Synposis 26 - Documentation [alpha draft]
Message ID:
4530D4A2.7040703@conway.org
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.
> |file:/shared/docs/std_copyright.pod>
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:
P<file:/shared/docs/std_copyright.pod
|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<http://www.perlfoundation.org/images/onion_64x64.png>, will an onion
> appear in my Pod document? That would obviate custom =Image
> directives.
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.
>
> Um...how 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
> =cut
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. :-)
Damian
Thread Previous
|
Thread Next