| 1 | |||
| 2 | |||
| 3 | |||
| 4 | # = HISTORY SECTION ===================================================================== | ||
| 5 | |||
| 6 | # --------------------------------------------------------------------------------------- | ||
| 7 | # version | date | author | changes | ||
| 8 | # --------------------------------------------------------------------------------------- | ||
| 9 | # 0.01 |09.04.2006| JSTENZEL | new. | ||
| 10 | # --------------------------------------------------------------------------------------- | ||
| 11 | |||
| 12 | # = POD SECTION ========================================================================= | ||
| 13 | |||
| 14 | =head1 NAME | ||
| 15 | |||
| 16 | B<PerlPoint::Import::POD> - a standard PerlPoint import filter for POD | ||
| 17 | |||
| 18 | =head1 VERSION | ||
| 19 | |||
| 20 | This manual describes version B<0.01>. | ||
| 21 | |||
| 22 | =head1 SYNOPSIS | ||
| 23 | |||
| 24 | # command line: process a POD file | ||
| 25 | perlpoint ... IMPORT:file.pod | ||
| 26 | |||
| 27 | ... | ||
| 28 | |||
| 29 | # or, in a PerlPoint source: | ||
| 30 | |||
| 31 | // include a POD file with "pod" extension | ||
| 32 | \INCLUDE{import=1 file="example.pod"} | ||
| 33 | |||
| 34 | // include a POD file without "pod" extension | ||
| 35 | \INCLUDE{import=pod file="example"} | ||
| 36 | |||
| 37 | // import a snippet in POD, | ||
| 38 | // which in turn contains some PerlPoint | ||
| 39 | \EMBED{import=pod} | ||
| 40 | |||
| 41 | =head2 Embedded PerlPoint | ||
| 42 | |||
| 43 | A POD paragraph. | ||
| 44 | |||
| 45 | =for perlpoint It \I<works>! | ||
| 46 | |||
| 47 | \END_EMBED | ||
| 48 | |||
| 49 | |||
| 50 | =head1 DESCRIPTION | ||
| 51 | |||
| 52 | Standard import filters are loaded automatically by the Parser | ||
| 53 | when you import a POD file in one of the ways shown in the | ||
| 54 | I<SYNOPSIS>. | ||
| 55 | |||
| 56 | |||
| 57 | =head1 FUNCTION | ||
| 58 | |||
| 59 | According to the standard import filter API (see C<PerlPoint::Parser>) this | ||
| 60 | module provides one function, C<importFilter()>. I transforms a POD file | ||
| 61 | into PerlPoint. | ||
| 62 | |||
| 63 | =cut | ||
| 64 | |||
| 65 | |||
| 66 | |||
| 67 | |||
| 68 | # check perl version | ||
| 69 | require 5.00503; | ||
| 70 | |||
| 71 | # = PACKAGE SECTION ====================================================================== | ||
| 72 | |||
| 73 | # declare package | ||
| 74 | package PerlPoint::Import::POD; | ||
| 75 | |||
| 76 | # declare package version | ||
| 77 | $VERSION=0.01; | ||
| 78 | |||
| 79 | |||
| 80 | # = PRAGMA SECTION ======================================================================= | ||
| 81 | |||
| 82 | # set pragmata | ||
| 83 | use strict; | ||
| 84 | |||
| 85 | |||
| 86 | # = LIBRARY SECTION ====================================================================== | ||
| 87 | |||
| 88 | # load libraries | ||
| 89 | use Pod::PerlPoint 0.05; | ||
| 90 | |||
| 91 | # declare the filter function | ||
| 92 | sub importFilter | ||
| 93 | { | ||
| 94 | # declare variables | ||
| 95 | my ($pod2pp, $result, $i); | ||
| 96 | |||
| 97 | # get source and sourcefile name | ||
| 98 | my ($pod, $sourcefile)=(join('', "\n\n\n", @main::_ifilterText), $main::_ifilterFile); | ||
| 99 | |||
| 100 | # transform it into PerlPoint | ||
| 101 | { | ||
| 102 | # build a translator object and configure it | ||
| 103 | ($pod2pp, $result)=(new Pod::PerlPoint()); | ||
| 104 | $pod2pp->output_string(\$result); | ||
| 105 | $pod2pp->configure(parser40=>($PerlPoint::Parser::VERSION>=0.40)); | ||
| 106 | |||
| 107 | # parse file | ||
| 108 | my $rc=$pod2pp->parse_string_document($pod); | ||
| 109 | $i++, $pod="\n\n=pod\n\n$pod", redo unless $result or $i; | ||
| 110 | |||
| 111 | # report errors, if any | ||
| 112 | if (exists $pod2pp->{errata}) | ||
| 113 | { | ||
| 114 | warn "\nPOD error detected in $sourcefile:\n\n"; | ||
| 115 | foreach (sort {$a <=> $b} keys %{$pod2pp->{errata}}) | ||
| 116 | {warn "Line $_:\n\n", map {"$_\n"} @{$pod2pp->{errata}{$_}};} | ||
| 117 | |||
| 118 | # flag the error | ||
| 119 | die "\n"; | ||
| 120 | } | ||
| 121 | } | ||
| 122 | |||
| 123 | # supply result (add leading newlines to let the parser detect a *new* | ||
| 124 | # paragraph and therefore recognize the special paragraph menaing of the | ||
| 125 | # dot added by Pod::PerlPoint to the first paragraph) | ||
| 126 | "\n\n$result"; | ||
| 127 | } | ||
| 128 | |||
| 129 | |||
| 130 | # flag successful loading | ||
| 131 | 1; | ||
| 132 | |||
| 133 | |||
| 134 | |||
| 135 | |||
| 136 | # = POD TRAILER SECTION ================================================================= | ||
| 137 | |||
| 138 | =pod | ||
| 139 | |||
| 140 | =head1 NOTES | ||
| 141 | |||
| 142 | None that far. | ||
| 143 | |||
| 144 | =head1 SEE ALSO | ||
| 145 | |||
| 146 | =over 4 | ||
| 147 | |||
| 148 | =item B<Pod::PerlPoint> | ||
| 149 | |||
| 150 | The module implementing POD to PerlPoint conversion. | ||
| 151 | |||
| 152 | =item B<Bundle::PerlPoint> | ||
| 153 | |||
| 154 | A bundle of packages to deal with PerlPoint documents. | ||
| 155 | |||
| 156 | =item B<pod2pp> | ||
| 157 | |||
| 158 | A standalone POD to PerlPoint translator, distributed | ||
| 159 | and installed with this module. | ||
| 160 | |||
| 161 | =back | ||
| 162 | |||
| 163 | |||
| 164 | =head1 SUPPORT | ||
| 165 | |||
| 166 | A PerlPoint mailing list is set up to discuss usage, ideas, | ||
| 167 | bugs, suggestions and translator development. To subscribe, | ||
| 168 | please send an empty message to perlpoint-subscribe@perl.org. | ||
| 169 | |||
| 170 | If you prefer, you can contact me via perl@jochen-stenzel.de | ||
| 171 | as well. | ||
| 172 | |||
| 173 | |||
| 174 | =head1 AUTHOR | ||
| 175 | |||
| 176 | Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2006. | ||
| 177 | All rights reserved. | ||
| 178 | |||
| 179 | This module is free software, you can redistribute it and/or modify it | ||
| 180 | under the terms of the Artistic License distributed with Perl version | ||
| 181 | 5.003 or (at your option) any later version. Please refer to the | ||
| 182 | Artistic License that came with your Perl distribution for more | ||
| 183 | details. | ||
| 184 | |||
| 185 | The Artistic License should have been included in your distribution of | ||
| 186 | Perl. It resides in the file named "Artistic" at the top-level of the | ||
| 187 | Perl source tree (where Perl was downloaded/unpacked - ask your | ||
| 188 | system administrator if you dont know where this is). Alternatively, | ||
| 189 | the current version of the Artistic License distributed with Perl can | ||
| 190 | be viewed on-line on the World-Wide Web (WWW) from the following URL: | ||
| 191 | http://www.perl.com/perl/misc/Artistic.html | ||
| 192 | |||
| 193 | |||
| 194 | =head1 DISCLAIMER | ||
| 195 | |||
| 196 | This software is distributed in the hope that it will be useful, but | ||
| 197 | is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or | ||
| 198 | implied, INCLUDING, without limitation, the implied warranties of | ||
| 199 | MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE. | ||
| 200 | |||
| 201 | The ENTIRE RISK as to the quality and performance of the software | ||
| 202 | IS WITH YOU (the holder of the software). Should the software prove | ||
| 203 | defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR | ||
| 204 | CORRECTION. | ||
| 205 | |||
| 206 | IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, | ||
| 207 | MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO | ||
| 208 | ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even | ||
| 209 | if they arise from known or unknown flaws in the software). | ||
| 210 | |||
| 211 | Please refer to the Artistic License that came with your Perl | ||
| 212 | distribution for more details. | ||
| 213 |