Zahatski Aliaksandr > Perl6-Pod > Perl6::Pod::Directive::use

Download:
Perl6-Pod-0.60.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Source  

NAME ^

Perl6::Pod::Directive::use - handle =use directive

SYNOPSIS ^

Load the corresponding Perldoc module:

    =use Test::Tag
    =for Tag
    text data

Define own formatting code:

    =use Perldoc::TT
    =config TT<>  :allow<E>
    head1 Overview of the M<TT: $CLASSNAME > class

DESCRIPTION ^

Perldoc provides a mechanism by which you can extend the syntax, semantics, or content of your documentation: the =use directive.

Specifying a =use causes a Perldoc processor to load the corresponding Perldoc module at that point, or to throw an exception if it cannot.

Such modules can specify additional content that should be included in the document. Alternatively, they can register classes that handle new types of block directives or formatting codes.

Note that a module loaded via a =use statement can affect the content or the interpretation of subsequent blocks, but not the initial parsing of those blocks. Any new block types must still conform to the general syntax described in this document. Typically, a module will change the way that renderers parse the contents of specific blocks.

A =use directive may be specified with either a module name or a URI:

    =use MODULE_NAME  OPTIONAL CONFIG DATA
    =                 OPTIONAL EXTRA CONFIG DATA
    
    =use URI

If a URI is given, the specified file is treated as a source of Pod to be included in the document. Any Pod blocks are parsed out of the contents of the =use'd file, and added to the main file's Pod representation at that point.

If a module name is specified with any prefix except pod:, or without a prefix at all, then the corresponding .pm file (or another language's equivalent code module) is searched for in the appropriate module library path. If found, the code module require'd into the Pod parser (usually to add a class implementing a particular Pod extension). If no such code module is found, a suitable .pod file is searched for instead, the contents parsed as Pod, and the resulting block objects inserted into the main file's representation

Any options that are specified after the module name:

    =use Perldoc::Plugin::Image  :Jpeg  prefix=>'http://dev.perl.org'

are passed to the internal require that loads the corresponding module.

Collectively these alternatives allow you to create standard documentation inserts or stylesheets, to include Pod extracted from other code files, or to specify new types of documentation blocks and formatting codes:

NOTES ^

Perl6::Pod handle exended syntax:

    =use MODULE_NAME FORMAT_CODE<> OPTIONAL CONFIG DATA
    =                 OPTIONAL EXTRA CONFIG DATA

    =use MODULE_NAME BLOCK_NAME OPTIONAL CONFIG DATA
    =                 OPTIONAL EXTRA CONFIG DATA

Fo example:

    =comment Overwrite default class for standart formatting code
    =use Perldoc::TT B<>

    =comment Define custom BlockNames
    =use Perldoc::TT Alias1
    =use Perldoc::TT Alias2

Perl6::Pod also handle ${PERL6POD} variable in package namespace. It used for evalute Pod chunk for loaded Module.

For package contains variable $PERL6POD:

    package UserDefined::Lib;
    use strict;
    use warnings;
    our $PERL6POD = <<POD;
    =begin pod
    =use UserDefined::Module
    =use UserDefined::Image
    =end pod
    POD
    1;

We can evalute Pod in the Pod file:

    =begin pod
    =comment Evalute $PERL6POD
    =use UserDefined::Lib
    =comment Now will use =Image  block
    =Image http://example.com/image.png
    =end pod

SEE ALSO ^

http://zag.ru/perl6-pod/S26.html, Perldoc Pod to HTML converter: http://zag.ru/perl6-pod/, Perl6::Pod::Lib

AUTHOR ^

Zahatski Aliaksandr, <zag@cpan.org>

COPYRIGHT AND LICENSE ^

Copyright (C) 2009-2010 by Zahatski Aliaksandr

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: