On 10/7/06, Damian Conway <[EMAIL PROTECTED]> wrote:
The C<I<>> formatting code specifies that the contained text is
to be set in an I<italic style>
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?
=begin item :term('C<http:> and C<https:>')
A standard URL. For example:
This module needs the LAME library
(available from L<http://www.mp3dev.org/mp3/>)
=end item
=begin item :term<C<file:>>
A filename on the local system. For example:
Next, edit the config file (L<file:~/.configrc>).
=end item
=begin item :term<C<man:>>
A link to the system man pages. For example:
This module implements the standard
Unix L<man:find(1)> facilities.
=end item
=begin item :term<C<doc:>>
A link to some other Perldoc documentation, typically a module or core
Perl documentation. For example:
You may wish to use L<doc:Data::Dumper> to
view the results. See also: L<doc:perldata>.
=end item
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>
If a renderer cannot find or access the external data source for a
placement link, it must issue a warning and render the URL directly in
some form. For example:
=begin indent
B<COPYRIGHT>
See: /shared/docs/std_copyright.pod
B<DISCLAIMER>
See: http://www.megagigatera.com/std/disclaimer.txt
=end indent
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>
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.
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?
C<=config> specifications are lexically scoped to the block in which
they're specified.
=config head3 :numbered
=cut
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?
(Actually, I don't see any reference to =cut in this spec. Is it
still there or not?)
--
Brent 'Dax' Royal-Gordon <[EMAIL PROTECTED]>
Perl and Parrot hacker
