Pod-POM-View-Restructured-1.000002/0000700000175000017500000000000013375262426015506 5ustar alexmalexmPod-POM-View-Restructured-1.000002/Makefile.PL0000644000175000017500000000305713375262426017477 0ustar alexmalexm# This file was automatically generated by Dist::Zilla::Plugin::MakeMaker v6.012. use strict; use warnings; use 5.006000; use ExtUtils::MakeMaker; my %WriteMakefileArgs = ( "ABSTRACT" => "View for Pod::POM that outputs reStructuredText", "AUTHOR" => "Alex Muntada", "CONFIGURE_REQUIRES" => { "ExtUtils::MakeMaker" => 0 }, "DISTNAME" => "Pod-POM-View-Restructured", "EXE_FILES" => [ "bin/pod2rst" ], "LICENSE" => "perl", "MIN_PERL_VERSION" => "5.006000", "NAME" => "Pod::POM::View::Restructured", "PREREQ_PM" => { "Carp" => 0, "Data::Dumper" => 0, "ExtUtils::MakeMaker" => "6.48", "Getopt::Long" => 0, "Pod::POM" => 0, "Pod::POM::View::Text" => 0, "base" => 0, "bytes" => 0, "strict" => 0, "warnings" => 0 }, "TEST_REQUIRES" => { "Cwd" => 0, "File::Spec" => 0, "Test::More" => 0 }, "VERSION" => "1.000002", "test" => { "TESTS" => "t/*.t" } ); my %FallbackPrereqs = ( "Carp" => 0, "Cwd" => 0, "Data::Dumper" => 0, "ExtUtils::MakeMaker" => "6.48", "File::Spec" => 0, "Getopt::Long" => 0, "Pod::POM" => 0, "Pod::POM::View::Text" => 0, "Test::More" => 0, "base" => 0, "bytes" => 0, "strict" => 0, "warnings" => 0 ); unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) { delete $WriteMakefileArgs{TEST_REQUIRES}; delete $WriteMakefileArgs{BUILD_REQUIRES}; $WriteMakefileArgs{PREREQ_PM} = \%FallbackPrereqs; } delete $WriteMakefileArgs{CONFIGURE_REQUIRES} unless eval { ExtUtils::MakeMaker->VERSION(6.52) }; WriteMakefile(%WriteMakefileArgs); Pod-POM-View-Restructured-1.000002/META.json0000644000175000017500000000307113375262426017142 0ustar alexmalexm{ "abstract" : "View for Pod::POM that outputs reStructuredText", "author" : [ "Alex Muntada" ], "dynamic_config" : 0, "generated_by" : "Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "Pod-POM-View-Restructured", "prereqs" : { "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "develop" : { "requires" : { "Test::Perl::Critic" : "0" } }, "runtime" : { "requires" : { "Carp" : "0", "Data::Dumper" : "0", "ExtUtils::MakeMaker" : "6.48", "Getopt::Long" : "0", "Pod::POM" : "0", "Pod::POM::View::Text" : "0", "base" : "0", "bytes" : "0", "perl" : "v5.6.0", "strict" : "0", "warnings" : "0" } }, "test" : { "requires" : { "Cwd" : "0", "File::Spec" : "0", "Test::More" : "0" } } }, "release_status" : "stable", "resources" : { "repository" : { "type" : "git", "url" : "https://github.com/cuberat/Pod-POM-View-Restructured", "web" : "https://github.com/cuberat/Pod-POM-View-Restructured" } }, "version" : "1.000002", "x_generated_by_perl" : "v5.28.0", "x_serialization_backend" : "JSON::XS version 3.04" } Pod-POM-View-Restructured-1.000002/INSTALL0000600000175000017500000000036213375262426016542 0ustar alexmalexmCopyright (c) 2010 Don Owens See the COPYRIGHT section in lib/Pod/POM/View/Restructured.pm for usage and distribution rights. INSTALLATION perl Makefile.PL make make test make install or cpan Pod::POM::View::Restructured Pod-POM-View-Restructured-1.000002/MANIFEST0000644000175000017500000000046113375262426016652 0ustar alexmalexm# This file was automatically generated by Dist::Zilla::Plugin::Manifest v6.012. ChangeLog INSTALL LICENSE MANIFEST META.json META.yml Makefile.PL README bin/pod2rst dist.ini lib/Pod/POM/View/Restructured.pm t/00use.t t/01convert.t t/02items.t t/author-critic.t t/test.pl t/test.pod t/test2.pl weaver.ini Pod-POM-View-Restructured-1.000002/weaver.ini0000600000175000017500000000010313375262426017474 0ustar alexmalexm[@CorePrep] [Leftovers] [Legal::Complicated] [Version] format = %v Pod-POM-View-Restructured-1.000002/dist.ini0000600000175000017500000000070413375262426017155 0ustar alexmalexmname = Pod-POM-View-Restructured version = 1.000002 license = Perl_5 copyright_holder = Alex Muntada [@Filter] -bundle = @Basic -remove = Readme [AutoPrereqs] [OurPkgVersion] [Test::Perl::Critic] [PodWeaver] [MetaJSON] [MetaResources] repository.web = https://github.com/cuberat/Pod-POM-View-Restructured repository.url = https://github.com/cuberat/Pod-POM-View-Restructured repository.type = git [Prereqs] ExtUtils::MakeMaker = 6.48 perl = 5.6.0 Pod-POM-View-Restructured-1.000002/LICENSE0000644000175000017500000004365513375262426016542 0ustar alexmalexmThis software is copyright (c) 2018 by Alex Muntada. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- The GNU General Public License, Version 1, February 1989 --- This software is Copyright (c) 2018 by Alex Muntada. This is free software, licensed under: The GNU General Public License, Version 1, February 1989 GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "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 PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. 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 PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (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 PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! --- The Artistic License 1.0 --- This software is Copyright (c) 2018 by Alex Muntada. This is free software, licensed under: The Artistic License 1.0 The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End Pod-POM-View-Restructured-1.000002/ChangeLog0000600000175000017500000000133113375262426017260 0ustar alexmalexmVersion 1.000002 * Fix list items without bullet (thanks to Wouter Depypere) Version 1.000001 * Fix kwalitee issues Version 1.000 * Generate version number in code and POD automatically * Update authors and copyright * Improve style and best practices Version 0.04 * Allow any rst-specific text in "=for pod2rst" (Closes: CPAN RT#114346) * Remove perl highlighting in view_pod (Closes: CPAN RT#124710) * Remove Pod::POM::View::Restructured::Changes Version 0.03 * Apply debian patch to POD (Closes: RT#119200) * Add namespace option to convert links to cross references (Closes: CPAN RT#115777) Version 0.02 * Added callbacks parameter * Fixed bug where the module tried to write to an unopened index file Pod-POM-View-Restructured-1.000002/t/0000700000175000017500000000000013375262426015751 5ustar alexmalexmPod-POM-View-Restructured-1.000002/t/test2.pl0000700000175000017500000001056713375262426017363 0ustar alexmalexm#!/usr/local/bin/perl # Original authors: don # $Revision: $ use strict; use warnings; use Carp; use Getopt::Long qw(:config no_ignore_case bundling); use Data::Dumper (); use Pod::POM; # main { # local($SIG{__DIE__}) = sub { &Carp::confess }; my $self = bless { }; my $opts = $self->get_options([ "help|h" ], { }); $self->check_options($opts, [ ]); # die's on bad options my $top_dir; # Set up @INC to get right version of module use File::Spec (); BEGIN { my $path = File::Spec->rel2abs($0); (my $dir = $path) =~ s{(?:/[^/]+){2}\Z}{}; # unshift @INC, $dir . "/blib/lib", $dir . "/blib/arch"; unshift @INC, $dir . "/lib"; $top_dir = $dir; } my $test_dir = $top_dir . "/test_doc/source"; my $doc_dir = $top_dir . "/test_doc"; my $base_dir = "/owens_lib/cpan"; # my $dest_dir = "$top_dir/test_doc/big_out"; my $dest_dir = "$top_dir/test_doc/source"; use Pod::POM::View::Restructured; my $link_cb = sub { my ($text) = @_; if ($text eq 'DBIx::Wrapper::Request') { return ('DBIx-Wrapper-Request.html', $text); } return; }; my $callbacks = { link => $link_cb }; chdir $dest_dir; my $files = [ { source_file => "$base_dir/Pod-POM-View-Restructured/lib/Pod/POM/View/Restructured.pm", dest_file => "Pod-POM-View-Restructured.rst", callbacks => $callbacks, }, { source_file => "$base_dir/JSON-DWIW/lib/JSON/DWIW.pm", dest_file => "JSON-DWIW.rst", callbacks => $callbacks, }, { source_file => "$base_dir/DBIx/Wrapper/DBIx-Wrapper/lib/DBIx/Wrapper.pm", dest_file => 'DBIx-Wrapper.rst', callbacks => $callbacks, }, { source_file => "$base_dir/DBIx/Wrapper/DBIx-Wrapper/lib/DBIx/Wrapper/Request.pm", dest_file => 'DBIx-Wrapper-Request.rst', callbacks => $callbacks, no_toc => 1, }, ]; my $conv = Pod::POM::View::Restructured->new; my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir); print STDERR Data::Dumper->Dump([ $rv ], [ 'rv' ]) . "\n\n"; chdir $doc_dir or die "couldn't chdir to $doc_dir"; my @cmd = ('make', 'html'); system {$cmd[0]} @cmd; } exit 0; ############################################################################### # Subroutines ########## begin option processing ########## sub print_usage { print STDERR qq{\nUsage: @{[ ($0 =~ m{\A.*/([^/]+)\Z})[0] || $0 ]} options Options: [-h | --help] # this help msg \n}; } sub check_options { my ($self, $opts, $required) = @_; if (not $opts or $opts->{help}) { $self->print_usage; exit 1; } my $opt_ok = 1; $required = [ ] unless $required; foreach my $key (@$required) { if (defined($opts->{$key})) { if (my $v = $opts->{$key}) { if (my $ref = ref($v)) { if ($ref eq 'ARRAY' ) { unless (@$v) { $opt_ok = 0; warn "missing required option '$key' "; } } } } } else { $opt_ok = 0; warn "missing required option '$key'\n"; } } unless ($opt_ok) { $self->print_usage; exit 1; } return $opt_ok; } sub get_options { my ($self, $spec, $defaults) = @_; my %opts = $defaults ? %$defaults : (); $spec = [ ] unless $spec; my $process_opt = sub { my ($key, $val) = @_; if (scalar(@_) > 2) { $opts{$key}{$val} = $_[2]; } else { if ( exists($opts{$key}) and (my $v = $opts{$key}) ) { if (my $ref = ref($v)) { if ($ref eq 'ARRAY' ) { push @{ $opts{$key} }, $val; return 1; } } } $opts{$key} = $val; } }; my $opt_rv = Getopt::Long::GetOptions(map { ($_ => $process_opt) } @$spec); return $opt_rv ? \%opts : undef; } ########## end option processing ########## Pod-POM-View-Restructured-1.000002/t/test.pod0000600000175000017500000000014013375262426017431 0ustar alexmalexm=pod =over =item item1 =item item2 =item * item3 =item + item4 =item - item5 =back =cut Pod-POM-View-Restructured-1.000002/t/test.pl0000700000175000017500000000232413375262426017271 0ustar alexmalexm#!/usr/local/bin/perl # Original authors: don # $Revision: $ use strict; use warnings; use Carp; use Getopt::Long qw(:config no_ignore_case bundling); use Pod::POM; # main { # local($SIG{__DIE__}) = sub { &Carp::confess }; my $self = bless { }; my $top_dir; # Set up @INC to get right version of module use File::Spec (); BEGIN { my $path = File::Spec->rel2abs($0); (my $dir = $path) =~ s{(?:/[^/]+){2}\Z}{}; # unshift @INC, $dir . "/blib/lib", $dir . "/blib/arch"; unshift @INC, $dir . "/lib"; $top_dir = $dir; } my $test_dir = $top_dir . "/test_doc/source"; use Pod::POM::View::Restructured; my $view = Pod::POM::View::Restructured->new; my $parser = Pod::POM->new; my $pom = $parser->parse_file("$top_dir/lib/Pod/POM/View/Restructured.pm"); my $out = $pom->present($view); my $out_file = $test_dir . "/restructured.rst"; open(my $out_fh, '>', $out_file) or die "couldn't open output file $out_file"; binmode($out_fh, ':utf8'); print $out_fh $out; close $out_fh; # print "output:\n\n$out\n"; } exit 0; ############################################################################### # Subroutines Pod-POM-View-Restructured-1.000002/t/02items.t0000600000175000017500000000124613375262426017426 0ustar alexmalexm#!/usr/bin/env perl # use strict; use warnings; use Test::More; use Pod::POM::View::Restructured; my $conv = Pod::POM::View::Restructured->new({namespace => "Pod::POM::View::Restructured"}); isa_ok($conv, 'Pod::POM::View::Restructured'); use Cwd; my $dir = getcwd; my $rv = $conv->convert_file("$dir/t/test.pod"); ok($rv); # An array of RST strings we should get in the output # You will ahve to escape any quanity chars. e.g. ?, *, etc. my @expected = ( '- item1', '- item2', '* item3', '+ item4', '- item5', ); my $count = 0; foreach my $str (@expected) { cmp_ok($rv->{content}, '=~', "\Q$str\E", "string cmp " . $count++); } done_testing(); Pod-POM-View-Restructured-1.000002/t/01convert.t0000600000175000017500000000177713375262426017775 0ustar alexmalexm#!/usr/bin/env perl # # Copyright (c) 2016 Jeff Fearn # # This is free software; you can redistribute it and/or modify it under # the same terms as Perl itself. See perlartistic. use strict; use warnings; use Test::More tests => 6; use Pod::POM::View::Restructured; my $conv = Pod::POM::View::Restructured->new({namespace => "Pod::POM::View::Restructured"}); isa_ok($conv, 'Pod::POM::View::Restructured'); my $rv = $conv->convert_file('lib/Pod/POM/View/Restructured.pm'); ok($rv); # An array of RST strings we should get in the output # You will ahve to escape any quanity chars. e.g. ?, *, etc. my @expected = ( '.. _Pod::POM::View::Restructured:', '.. _Pod::POM::View::Restructured::NAME:', ':ref:`Pod::POM::View::Restructured::Changes `', '`Pod::POM `_' ); my $count = 0; foreach my $str (@expected) { cmp_ok($rv->{content}, '=~', $str, "string cmp " . $count++); } Pod-POM-View-Restructured-1.000002/t/author-critic.t0000644000175000017500000000040313375262426020722 0ustar alexmalexm#!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; use Test::Perl::Critic (-profile => "perlcritic.rc") x!! -e "perlcritic.rc"; all_critic_ok(); Pod-POM-View-Restructured-1.000002/t/00use.t0000700000175000017500000000021413375262426017072 0ustar alexmalexm#!/usr/bin/env perl # $Revision$ use strict; use warnings; use Test::More tests => 1; BEGIN { use_ok('Pod::POM::View::Restructured') } Pod-POM-View-Restructured-1.000002/lib/0000700000175000017500000000000013375262426016254 5ustar alexmalexmPod-POM-View-Restructured-1.000002/lib/Pod/0000700000175000017500000000000013375262426016776 5ustar alexmalexmPod-POM-View-Restructured-1.000002/lib/Pod/POM/0000700000175000017500000000000013375262426017431 5ustar alexmalexmPod-POM-View-Restructured-1.000002/lib/Pod/POM/View/0000700000175000017500000000000013375262426020343 5ustar alexmalexmPod-POM-View-Restructured-1.000002/lib/Pod/POM/View/Restructured.pm0000600000175000017500000004417713375262426023413 0ustar alexmalexm# AUTHOR: Don Owens # AUTHOR: Jeff Fearn # AUTHOR: Alex Muntada # OWNER: 2010 Don Owens # OWNER: 2016 Jeff Fearn # OWNER: 2016-2018 Alex Muntada # LICENSE: Perl_5 use strict; use warnings; use Data::Dumper (); use Pod::POM; package Pod::POM::View::Restructured; our $VERSION = '1.000002'; # VERSION use base 'Pod::POM::View::Text'; sub new { my ($class, $params) = @_; $params = { } unless $params and UNIVERSAL::isa($params, 'HASH'); my $self = bless { seen_something => 0, title_set => 0, params => { } }, ref($class) || $class; my $callbacks = $params->{callbacks}; $callbacks = { } unless $callbacks; $self->{callbacks} = $callbacks; $self->{namespace} = delete($params->{namespace}); return $self; } sub convert_file { my ($self, $source_file, $title, $dest_file, $callbacks) = @_; my $cb; if ($callbacks) { $cb = { %{ $self->{callbacks} }, %$callbacks }; } else { $cb = $self->{callbacks}; } my $view = Pod::POM::View::Restructured->new({ callbacks => $cb, namespace => $self->{namespace} }); my $parser = Pod::POM->new; unless (-r $source_file) { warn "can't read source file $source_file"; return; } my $pom = $parser->parse_file($source_file); $view->{title_set} = 1 if defined($title); my $out = $pom->present($view); if (defined($title)) { $out = $self->_build_header($title, '#', 1) . "\n" . $out; } else { $title = $view->{title}; } if (defined($dest_file) and $dest_file ne '') { my $out_fh; if (UNIVERSAL::isa($dest_file, 'GLOB')) { $out_fh = $dest_file; } else { unless (open($out_fh, '>', $dest_file)) { warn "couldn't open output file $dest_file"; return; } } print $out_fh $out; close $out_fh; } my $rv = { content => $out, title => $title }; return $rv; } sub convert_files { my ($self, $file_spec, $index_file, $index_title, $out_dir) = @_; my $index_fh = $self->_get_file_handle($index_file, '>'); if ($index_fh and defined($index_title) and $index_title ne '') { my $header = $self->_build_header($index_title, '#', 1); # my $line = '#' x length($index_title); # my $header = $line . "\n" . $index_title . "\n" . $line . "\n\n"; print $index_fh $header; print $index_fh "\nContents:\n\n"; print $index_fh ".. toctree::\n"; print $index_fh " :maxdepth: 1\n\n"; } my $count = 0; my $toc = ''; foreach my $spec (@$file_spec) { $count++; my $data = $self->convert_file($spec->{source_file}, $spec->{title}, $spec->{dest_file}, $spec->{callbacks}); my $this_title = $data->{title}; # print STDERR Data::Dumper->Dump([ $this_title ], [ 'this_title' ]) . "\n\n"; unless (defined($this_title) and $this_title !~ /\A\s*\Z/) { $this_title = 'section_' . $count; } my $name = $spec->{dest_file}; if (defined($name)) { $name =~ s/\.rst\Z//; } else { ($name = $this_title) =~ s/\W/_/g; my $dest_file = $out_dir . '/' . $name . '.rst'; my $out_fh; unless (open($out_fh, '>', $dest_file)) { warn "couldn't open output file $dest_file"; return; } print $out_fh $data->{content}; close $out_fh; } unless ($spec->{no_toc}) { $toc .= ' ' . $name . "\n"; } if ($index_fh and not $spec->{no_toc}) { print $index_fh " " . $name . "\n"; } } if ($index_fh) { print $index_fh "\n"; } return { toc => $toc }; } sub _get_file_handle { my ($self, $file, $mode) = @_; return unless defined $file; if (ref($file) and UNIVERSAL::isa($file, 'GLOB')) { return $file; } $mode = '<' unless $mode; my $fh; if ($file ne '') { unless (open($fh, $mode, $file)) { warn "couldn't open input file $file: $!"; return; } } return $fh; } sub view_pod { my ($self, $node) = @_; return $node->content()->present($self); } sub _generic_head { my ($self, $node, $marker, $do_overline) = @_; return scalar($self->_generic_head_multi($node, $marker, $do_overline)); } sub _generic_head_multi { my ($self, $node, $marker, $do_overline) = @_; my $title = $node->title()->present($self); my $content = $node->content()->present($self); $title = ' ' if $title eq ''; # my $section_line = $marker x length($title); my $section = $self->_build_header($title, $marker, $do_overline) . "\n" . $content; # my $section = $title . "\n" . $section_line . "\n\n" . $content; # if ($do_overline) { # $section = $section_line . "\n" . $section; # } $section .= "\n"; return wantarray ? ($section, $content, $title) : $section; } sub _build_header { my ($self, $text, $marker, $do_overline) = @_; my $line = $marker x length($text); my $header = $text . "\n" . $line . "\n"; if ($do_overline) { $header = $line . "\n" . $header; } my $namespace = $self->{namespace}; if($namespace) { my $a = $text; # prepend the namesspace to gaurantee document wide unique names $a = "$namespace\:\:$a" unless($text =~ /^$namespace/); $a =~ s/(?:\s)/-/g; $header = qq{.. _$a:\n\n} . $header; } return "\n" . $header; } sub _do_indent { my ($self, $text, $indent_amount, $dbg) = @_; my $indent = ' ' x $indent_amount; # $indent = "'$dbg" . $indent . "'"; my @lines = split /\n/, $text, -1; foreach my $line (@lines) { $line = $indent . $line; } return join("\n", @lines); } sub view_head1 { my ($self, $node) = @_; my ($section, $content, $title) = $self->_generic_head_multi($node, '*', 1); unless ($self->{seen_something} or $self->{title_set}) { if ($title eq 'NAME') { $self->{seen_something} = 1; if ($content =~ /\A\s*(\w+(?:::\w+)+)\s+-\s+/s) { my $mod_name = $1; $self->{module_name} = $mod_name; $self->{title} = $mod_name; $self->{title_set} = 1; $section = $self->_build_header($mod_name, '#', 1) . $section; # my $line = '#' x length($mod_name); # $section = $line . "\n" . $mod_name . "\n" . $line . "\n\n" . $section; } return $section; } } $self->{seen_something} = 1; return $section; } sub view_head2 { my ($self, $node) = @_; $self->{seen_something} = 1; return $self->_generic_head($node, '='); } sub view_head3 { my ($self, $node) = @_; $self->{seen_something} = 1; return $self->_generic_head($node, '-'); } sub view_head4 { my ($self, $node) = @_; $self->{seen_something} = 1; return $self->_generic_head($node, '^'); } sub view_item { my ($self, $node) = @_; $self->{seen_something} = 1; my $title = $node->title()->present($self); my $content = $node->content()->present($self); $title =~ s/\A\s+//; $title =~ s/\n/ /; $title = "- $title" unless $title =~ / # the line starts with \A # single unordered bullet, (?:(?:[-+] | \\[*]) # or ordered bullet followed by dot, | [1AaIi] \. # or ordered bullet within parens (first optional), | \(? [1AaIi] \) # then finally followed by whitespace. )\s /xms; # Make asterisk an actual bullet $title =~ s/ \A \\ [*]/*/xms; # $content =~ s/\n/\n /g; # $content = ' ' . $content; $self->{view_item_count}++; $content = $self->_do_indent($content, 1, "[[view_item_$self->{view_item_count}]]"); return "\n" . $title . "\n" . $content . "\n\n"; } sub view_over { my ($self, $node) = @_; my $content = $node->content()->present($self); # my $indent = $node->indent(); return "\n" . $content; } sub view_text { my ($self, $node) = @_; my @lines = split /\n/, $node; foreach my $line (@lines) { $line =~ s/\A\s+//; } return join("\n", @lines); } sub view_textblock { my ($self, $text) = @_; return "\n" . $text . "\n"; } sub view_verbatim { my ($self, $node) = @_; # (my $node_part = ' ' . $node) =~ s/\n/\n /g; my $node_part = $self->_do_indent($node . '', 1, '[[view_verbatim]]'); my $block_part = ".. code-block:: perl\n\n"; if (defined($self->{next_code_block})) { my $lang = $self->{next_code_block}; delete $self->{next_code_block}; if ($lang eq 'none') { # FIXME: need to output a preformatted paragraph here, but no highlighting $block_part = ''; } else { $block_part = ".. code-block:: $lang\n\n"; } } my $content = $block_part . $node_part; return "\n\n" . $content . "\n\n"; } sub view_for { my ($self, $node) = @_; my $fmt = $node->format(); # print STDERR "got for: fmt='$fmt', text='" . $node->text() . "'\n"; if ($fmt eq 'pod2rst') { my $text = $node->text(); if ($text =~ /\A\s*next-code-block\s*:\s*(\S+)/) { my $lang = $1; $self->{next_code_block} = $lang; return ''; } return "\n". $node->text() . "\n\n"; } return $self->SUPER::view_for($node); } sub view_seq_code { my ($self, $text) = @_; return '\ ``' . $text . '``\ '; } sub view_seq_bold { my ($self, $text) = @_; $text =~ s/\*/\\*/g; $text =~ s/\`/\\`/g; return '\ **' . $text . '**\ '; } sub view_seq_italic { my ($self, $text) = @_; $text =~ s/\*/\\*/g; $text =~ s/\`/\\`/g; return '\ *' . $text . '*\ '; } sub view_seq_file { my ($self, $text) = @_; $text =~ s/\*/\\*/g; $text =~ s/\`/\\`/g; return '\ *' . $text . '*\ '; } sub view_seq_text { my ($self, $node) = @_; my $text = $node . ''; $text =~ s/\*/\\*/g; $text =~ s/\`/\\`/g; return $text; } sub view_seq_zero { return ''; } sub view_seq_link { my ($self, $text) = @_; # FIXME: determine if has label, if manpage, etc., and pass that info along to the callback, # instead of just the text, e.g., # $link_cb->($label, $name, $sec, $url); my $link_cb = $self->{callbacks}{link}; if ($link_cb) { my ($url, $label) = $link_cb->($text); if (defined($url)) { if ($url eq '' and defined($label) and $label ne '') { $text = $label; } elsif (defined($label) and $label ne '') { $text = qq{`$label <$url>`_}; } else { $text = qq{`$url <$url>`_}; } return $text; } } my $url = ''; my $label = ''; my $module = $text; my $namespace = $self->{namespace}; if ($text =~ m{\A/(.+)}) { (my $section = $1) =~ s/\A"(.+)"/$1/; $text = qq{`$section`_}; } elsif ($text =~ m{\Ahttps?://}) { $text = qq{`$text <$text>`_}; } elsif ($text =~ /::/) { $label = $text; if ($text =~ /\A(.+?)\|(.+::.+)/) { $label = $1; $module = $2; } # Links in this namespace are cross refereneces if (($namespace) and ($text =~ /^$namespace/)) { $module = qq{$namespace\:\:$module} unless($module =~ /^$namespace/); $module =~ s/(?:\s)/-/g; $text = qq{:ref:`$label <$module>`}; } else { $module = $self->_url_encode($module); my $url = "http://search.cpan.org/search?query=$module&mode=module"; $text = qq{`$label <$url>`_}; } } return $text; } sub _url_encode { my ($self, $str) = @_; use bytes; $str =~ s{([^A-Za-z0-9_])}{sprintf("%%%02x", ord($1))}eg; return $str; } 1; __END__ =pod =head1 NAME Pod::POM::View::Restructured - View for Pod::POM that outputs reStructuredText =head1 SYNOPSIS use Pod::POM::View::Restructured; my $view = Pod::POM::View::Restructured->new; my $parser = Pod::POM->new; my $pom = $parser->parse_file("$top_dir/lib/Pod/POM/View/Restructured.pm"); my $out = $pom->present($view); =head1 DESCRIPTION This module outputs reStructuredText that is expected to be used with Sphinx. Verbatim sections (indented paragraphs) in the POD will be output with syntax highlighting for Perl code by default. See L for how to change this for a particular block. For a list of changes in recent versions, see the documentation for L. This module can be downloaded from L. =head1 METHODS =head2 C Constructor. \%params is optional. If present, the following keys are valid: =over 4 =item C See documentation below for C. =item C If a namespace is declared then links to that namespace are converted to cross references and an anchor is added for each head tag. =back =head2 C Converts the POD in C<$source_file> to reStructuredText. If C<$dest_file> is defined, it writes the output there. If C<$title> is defined, it is used for the title of the document. Otherwise, an attempt is made to infer the title from the NAME section (checks if the body looks like C). Returns the output as a string. C<$source_file> and C<$dest_file> can be either file names or file handles. =head2 C Converts the files given in C<$file_spec> to reStructuredText. If C<$index_file> is provided, it is the path to the index file to be created (with a table of contents pointing to all of the files created). If C<$index_title> is provided, it is used as the section title for the index file. C<$out_dir> is the directory the generated files will be written to. C<$file_spec> is a reference to an array of hashes specifying attributes for each file to be converted. The valid keys are: =over 4 =item C File to convert. =item C File to output the reStructuredText. If not provided, a file name will be generated based on the title. =item C Section title for the generated reStructuredText. If not provided, an attempt will be made to infer the title from the NAME section in the POD, if it exists. As a last resort, a title will be generated that looks like "section_(\d+)". =item C<callbacks> A reference to a hash containing names and the corresponding callbacks. Currently the only valid callback is C<link>. It is given the text inside a LE<lt>E<gt> section from the POD, and is expected to return a tuple C<($url, $label)>. If the value returned for C<$label> is undefined, the value of C<$url> is used as the label. =item C<no_toc> Causes the item to not be printed to the index or return in the C<toc> field. =back This method returns a hash ref with a table of contents (the C<toc> field) suitable for a reStructuredText table of contents. E.g., my $conv = Pod::POM::View::Restructured->new; my $files = [ { source_file => "$base_dir/Restructured.pm" }, { source_file => "$base_dir/DWIW.pm" }, { source_file => "$base_dir/Wrapper.pm" }, ]; my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir); =head1 POD commands specifically for reStructuredText The following sequences can be used in POD to request actions specifically for this module. =head2 =Z<>for pod2rst next-code-block: I<lang> This sets up the next verbatim section, i.e., the next indented paragraph to be highlighted according to the syntax of the programming/markup/config language I<lang>. Verbatim sections are assumed to be Perl code by default. Sphinx uses Pygments to do syntax highlighting in these sections, so you can use any value for I<lang> that Pygments supports, e.g., Python, C, C++, Javascript, SQL, etc. =head1 EXAMPLES =over 4 =item Converting a single file using C<pod2rst> =for pod2rst next-code-block: bash pod2rst --infile=Restructured.pm --outfile=restructured.rst =back B<Need to document:> =over 4 =item B<Document example of setting up sphinx build, generating rst from pod, and building> =back =head1 TODO =over 4 =item code highlighting Currently, a verbatim block (indented paragraph) gets output as a Perl code block by default in reStructuredText. There should be an option (e.g., in the constructor) to change the language for highlighting purposes (for all verbatim blocks), or disable syntax highlighting and just make it a preformatted paragraph. There is a way to do this in POD (see L</"POD commands specifically for reStructuredText">), but there should also be an option in the constructor. =item improve escaping Text blocks are not escaped properly, so it is currently possible to invoke a command in reStructuredText by accident. =back =head1 DEPENDENCIES Inherits from L<Pod::POM::View::Text> that comes with the Pod::POM distribution. =head1 SEE ALSO L<Pod::POM> L<Pod::POM::View::HTML> L<pod2rst> (distributed with Pod::POM::View::HTML) reStructuredText: L<http://docutils.sourceforge.net/rst.html> Sphinx (uses reStructuredText): L<http://sphinx.pocoo.org/> Pygments (used by Sphinx for syntax highlighting): L<http://pygments.org/> =head1 AUTHORS Don Owens <don@regexguy.com> Jeff Fearn <Jeff.Fearn@gmail.com> Alex Muntada <alexm@cpan.org> =head1 COPYRIGHT This software is copyright (c) 2010 by Don Owens <don@regexguy.com>, 2016 by Jeff Fearn <Jeff.Fearn@gmail.com>, and 2016-2018 by Alex Muntada <alexm@cpan.org>. This software is available under the same terms as the perl 5 programming language system itself. =head1 VERSION 1.000002 =cut �������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Pod-POM-View-Restructured-1.000002/README�����������������������������������������������������������0000600�0001750�0001750�00000014421�13375262426�016372� 0����������������������������������������������������������������������������������������������������ustar �alexm���������������������������alexm������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME Pod::POM::View::Restructured - View for Pod::POM that outputs reStructuredText SYNOPSIS use Pod::POM::View::Restructured; my $view = Pod::POM::View::Restructured->new; my $parser = Pod::POM->new; my $pom = $parser->parse_file("$top_dir/lib/Pod/POM/View/Restructured.pm"); my $out = $pom->present($view); DESCRIPTION This module outputs reStructuredText that is expected to be used with Sphinx. Verbatim sections (indented paragraphs) in the POD will be output with syntax highlighting for Perl code by default. See "POD commands specifically for reStructuredText" for how to change this for a particular block. For a list of changes in recent versions, see the documentation for Pod::POM::View::Restructured::Changes. This module can be downloaded from <http://www.cpan.org/authors/id/D/DO/DOWENS/>. METHODS "new(\%params)" Constructor. \%params is optional. If present, the following keys are valid: "callbacks" See documentation below for "convert_file()". "namespace" If a namespace is declared then links to that namespace are converted to cross references and an anchor is added for each head tag. "convert_file($source_file, $title, $dest_file, $callbacks)" Converts the POD in $source_file to reStructuredText. If $dest_file is defined, it writes the output there. If $title is defined, it is used for the title of the document. Otherwise, an attempt is made to infer the title from the NAME section (checks if the body looks like "/\A\s*(\w+(?:::\w+)+)\s+-\s+/s"). Returns the output as a string. $source_file and $dest_file can be either file names or file handles. "convert_files($file_spec, $index_file, $index_title, $out_dir)" Converts the files given in $file_spec to reStructuredText. If $index_file is provided, it is the path to the index file to be created (with a table of contents pointing to all of the files created). If $index_title is provided, it is used as the section title for the index file. $out_dir is the directory the generated files will be written to. $file_spec is a reference to an array of hashes specifying attributes for each file to be converted. The valid keys are: "source_file" File to convert. "dest_file" File to output the reStructuredText. If not provided, a file name will be generated based on the title. "title" Section title for the generated reStructuredText. If not provided, an attempt will be made to infer the title from the NAME section in the POD, if it exists. As a last resort, a title will be generated that looks like "section_(\d+)". "callbacks" A reference to a hash containing names and the corresponding callbacks. Currently the only valid callback is "link". It is given the text inside a L<> section from the POD, and is expected to return a tuple "($url, $label)". If the value returned for $label is undefined, the value of $url is used as the label. "no_toc" Causes the item to not be printed to the index or return in the "toc" field. This method returns a hash ref with a table of contents (the "toc" field) suitable for a reStructuredText table of contents. E.g., my $conv = Pod::POM::View::Restructured->new; my $files = [ { source_file => "$base_dir/Restructured.pm" }, { source_file => "$base_dir/DWIW.pm" }, { source_file => "$base_dir/Wrapper.pm" }, ]; my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir); POD commands specifically for reStructuredText The following sequences can be used in POD to request actions specifically for this module. =for pod2rst next-code-block: *lang* This sets up the next verbatim section, i.e., the next indented paragraph to be highlighted according to the syntax of the programming/markup/config language *lang*. Verbatim sections are assumed to be Perl code by default. Sphinx uses Pygments to do syntax highlighting in these sections, so you can use any value for *lang* that Pygments supports, e.g., Python, C, C++, Javascript, SQL, etc. EXAMPLES Converting a single file using "pod2rst" pod2rst --infile=Restructured.pm --outfile=restructured.rst Need to document: Document example of setting up sphinx build, generating rst from pod, and building TODO code highlighting Currently, a verbatim block (indented paragraph) gets output as a Perl code block by default in reStructuredText. There should be an option (e.g., in the constructor) to change the language for highlighting purposes (for all verbatim blocks), or disable syntax highlighting and just make it a preformatted paragraph. There is a way to do this in POD (see "POD commands specifically for reStructuredText"), but there should also be an option in the constructor. improve escaping Text blocks are not escaped properly, so it is currently possible to invoke a command in reStructuredText by accident. DEPENDENCIES Inherits from Pod::POM::View::Text that comes with the Pod::POM distribution. AUTHORS Don Owens <don@regexguy.com> Jeff Fearn <Jeff.Fearn@gmail.com> LICENSE AND COPYRIGHT Copyright (c) 2010 Don Owens <don@regexguy.com>. All rights reserved. Copyright (c) 2016 Jeff Fearn <Jeff.Fearn@gmail.com>. All rights reserved. Copyright (c) 2016-2018 Alex Muntada <alexm@cpan.org>. All rights reserved. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO Pod::POM Pod::POM::View::HTML pod2rst (distributed with Pod::POM::View::HTML) reStructuredText: <http://docutils.sourceforge.net/rst.html> Sphinx (uses reStructuredText): <http://sphinx.pocoo.org/> Pygments (used by Sphinx for syntax highlighting): <http://pygments.org/> �����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Pod-POM-View-Restructured-1.000002/bin/�������������������������������������������������������������0000700�0001750�0001750�00000000000�13375262426�016256� 5����������������������������������������������������������������������������������������������������ustar �alexm���������������������������alexm������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Pod-POM-View-Restructured-1.000002/bin/pod2rst������������������������������������������������������0000700�0001750�0001750�00000011647�13375262426�017612� 0����������������������������������������������������������������������������������������������������ustar �alexm���������������������������alexm������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/usr/local/bin/perl # AUTHOR: Don Owens <don@regexguy.com> # OWNER: 2010 Don Owens <don@regexguy.com> # LICENSE: Perl_5 use strict; use warnings; use Carp; use Getopt::Long qw(:config no_ignore_case bundling); use Pod::POM::View::Restructured; our $VERSION = '1.000002'; # VERSION # main { # local($SIG{__DIE__}) = sub { &Carp::confess }; my $self = bless { }, __PACKAGE__; my $opts = $self->get_options([ "help|h", "in_file|infile|in-file|i=s", "out_file|outfile|out-file|o=s", "title=s", ], { }); $self->check_options($opts, [ ]); # die's on bad options $self->{opts} = $opts; my ($in_fh, $out_fh) = $self->open_files; my $conv = Pod::POM::View::Restructured->new; my $output = $conv->convert_file($in_fh, $opts->{title}, $out_fh); unless (defined($output)) { print STDERR "\n\nFailed to convert!\n\n"; exit 1; } exit 0; } exit 0; ############################################################################### # Subroutines sub open_files { my ($self) = @_; my $opts = $self->{opts}; my $in_fh; my $out_fh; if (defined($opts->{in_file})) { open($in_fh, '<', $opts->{in_file}) or die "couldn't open input file $opts->{in_file}: $!"; } else { $in_fh = \*STDIN; } if (defined($opts->{out_file})) { open($out_fh, '>', $opts->{out_file}) or die "couldn't open output file $opts->{out_file}: $!"; } else { $out_fh = \*STDOUT; } return ($in_fh, $out_fh); } ########## begin option processing ########## sub print_usage { print STDERR qq{\nUsage: @{[ ($0 =~ m{\A.*/([^/]+)\Z})[0] || $0 ]} options Options: --infile # filename for the pod to convert (input taken from # stdin by default) --outfile # filename for the resulting reStructuredText file # (output sent to stdout by default) --title # title for the document (by default an attempt will # be made to extract the title, assuming that the first # section is a head1 called NAME) [-h | --help] # this help msg \n}; } sub check_options { my ($self, $opts, $required) = @_; if (not $opts or $opts->{help}) { $self->print_usage; exit 1; } my $opt_ok = 1; $required = [ ] unless $required; foreach my $key (@$required) { if (defined($opts->{$key})) { if (my $v = $opts->{$key}) { if (my $ref = ref($v)) { if ($ref eq 'ARRAY' ) { unless (@$v) { $opt_ok = 0; warn "missing required option '$key' "; } } } } } else { $opt_ok = 0; warn "missing required option '$key'\n"; } } unless ($opt_ok) { $self->print_usage; exit 1; } return $opt_ok; } sub get_options { my ($self, $spec, $defaults) = @_; my %opts = $defaults ? %$defaults : (); $spec = [ ] unless $spec; my $process_opt = sub { my ($key, $val) = @_; if (scalar(@_) > 2) { $opts{$key}{$val} = $_[2]; } else { if ( exists($opts{$key}) and (my $v = $opts{$key}) ) { if (my $ref = ref($v)) { if ($ref eq 'ARRAY' ) { push @{ $opts{$key} }, $val; return 1; } } } $opts{$key} = $val; } }; my $opt_rv = Getopt::Long::GetOptions(map { ($_ => $process_opt) } @$spec); return $opt_rv ? \%opts : undef; } ########## end option processing ########## __END__ =pod =head1 NAME pod2rst - convert .pod files to .rst files =head1 SYNOPSIS =for pod2rst next-code-block: bash pod2rst --infile=<name> --outfile=<name> --title=<name> =head1 DESCRIPTION Converts files containing POD to reStructuredText format for input to Sphinx. =head1 ARGUMENTS C<pod2rst> takes the following arguments: =over 4 =item infile --infile=<name> Specifies the pod file to convert. Input is taken from stdin by default. =item outfile --outfile=<name> Specifies the reStructuredText file to create. Output goes to stdout by default. =item title --title=<title> Specifies the section title for the file. =back =head1 SEE ALSO L<Pod::POM::View::Restructured>, L<pod2html> Sphinx: L<http://sphinx.pocoo.org/> =head1 AUTHOR Don Owens <don@regexguy.com> =head1 COPYRIGHT This software is copyright (c) 2010 by Don Owens <don@regexguy.com>. This software is available under the same terms as the perl 5 programming language system itself. =head1 VERSION 1.000002 =cut �����������������������������������������������������������������������������������������Pod-POM-View-Restructured-1.000002/META.yml���������������������������������������������������������0000644�0001750�0001750�00000001466�13375262426�017000� 0����������������������������������������������������������������������������������������������������ustar �alexm���������������������������alexm������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������--- abstract: 'View for Pod::POM that outputs reStructuredText' author: - 'Alex Muntada' build_requires: Cwd: '0' File::Spec: '0' Test::More: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 0 generated_by: 'Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Pod-POM-View-Restructured requires: Carp: '0' Data::Dumper: '0' ExtUtils::MakeMaker: '6.48' Getopt::Long: '0' Pod::POM: '0' Pod::POM::View::Text: '0' base: '0' bytes: '0' perl: v5.6.0 strict: '0' warnings: '0' resources: repository: https://github.com/cuberat/Pod-POM-View-Restructured version: '1.000002' x_generated_by_perl: v5.28.0 x_serialization_backend: 'YAML::Tiny version 1.73' ����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������