/ 
Perl6-Perldoc-0.000013
River stage one • 2 direct dependents • 3 total dependents
/ Perl6::Perldoc

NAME

Perl6::Perldoc - Use Perl 6 documentation in a Perl 5 program

VERSION

This document describes Perl6::Perldoc version 0.000013

SYNOPSIS

  use Perl6::Perldoc;

  =comment
      Now you can use Perl 6 style documentation

  =for DATA
      Including Perl 6 style DATA sections

  print <DATA>;

  =for DATA
      Of which there can be more than one

DESCRIPTION

This module preprocesses your code from the point at which the module is first used, stripping out any Perl 6 documentation (as specified in Synopsis 26).

This means that, so long as your program starts with:

use Perl6::Perldoc;

you can document it using the new Pod mark-up notation and it will still run correctly under the Perl 5 interpreter.

In addition, the module detects any =DATA sections in the stripped documentation and makes them available to your program in three ways:

  • As a single concatentated string, in the $DATA package variable

  • As a sequence of strings (one per =DATA block) in the @DATA package variable

  • As a single concatenated input stream in the *DATA filehandle.

INTERFACE

None. You use the module and it takes care of everything.

DIAGNOSTICS

Can't set up *DATA handle (%s)

The filter found at least one =DATA block, but was unable to create a *DATA filehandle in the caller's namespace (for the reason specified in the parens).

CONFIGURATION AND ENVIRONMENT

Perl6::Perldoc requires no configuration files or environment variables.

DEPENDENCIES

Requires the version module and the standard module Filter::Simple.

INCOMPATIBILITIES

None reported.

LIMITATIONS

Unlike Perl 6 itself:

  • This module does not make every Pod block available to the surrounding program, only the =DATA blocks. This is to avoid the unacceptably slow compilation speed that would result from attempting to fully parse the entire embedded Pod markup and then construct an internal representation of it.

  • The contents of =DATA blocks appear in the global variables $DATA and @DATA, and the global *DATA filehandle, rather than in a special $?DATA object. These variables and filehandle are accessible from main and in every other package that is explicitly declared in the file.

  • This module does not honour =encoding directives.

  • If you plan to use the double-angle forms of delimiters (e.g. C«...», etc.) you may need to use utf8 in your source (on some systems).

BUGS

No bugs have been reported.

Please report any bugs or feature requests to bug-perl6-pod@rt.cpan.org, or through the web interface at http://rt.cpan.org.

CRUEL IRONY

The module itself had to be documented in Perl 5 POD

AUTHOR

Damian Conway <DCONWAY@CPAN.org>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Damian Conway <DCONWAY@CPAN.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF STABILITY

This module will attempt to track any future changes to the Perl 6 specification. Hence its features and the Pod syntax it recognizes may change in future releases.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.