Browse files

basic documentation for upload to CPAN

TODO: complete alternatives, add examples, add links to more info
  • Loading branch information...
1 parent af766fd commit 01b348577d61d99673f9449930656d7b5fa17f0c @leejo committed May 28, 2014
Showing with 194 additions and 11 deletions.
  1. +9 −0 .gitignore
  2. 0 Changes
  3. +6 −0 MANIFEST
  4. +32 −0 Makefile.PL
  5. +47 −0 README
  6. +0 −11 README.md
  7. +68 −0 lib/CGI/Alternatives.pm
  8. +32 −0 t/001_compiles_pod.t
View
9 .gitignore
@@ -0,0 +1,9 @@
+.DS_Store
+MYMETA.json
+MYMETA.yml
+Makefile
+blib/
+pm_to_blib
+*.old
+*.bak
+CGI-Alternatives*.gz
View
0 Changes
No changes.
View
6 MANIFEST
@@ -0,0 +1,6 @@
+Changes
+lib/CGI/Alternatives.pm
+Makefile.PL
+MANIFEST
+README
+t/001_compiles_pod.t
View
32 Makefile.PL
@@ -0,0 +1,32 @@
+#!perl
+
+use strict;
+use warnings;
+
+use ExtUtils::MakeMaker;
+
+WriteMakefile(
+ NAME => 'CGI::Alternatives',
+ ABSTRACT_FROM => 'lib/CGI/Alternatives.pm',
+ VERSION_FROM => 'lib/CGI/Alternatives.pm',
+ AUTHOR => 'Lee Johnson <leejo@cpan.org>',
+ LICENSE => 'perl',
+ PREREQ_PM => {
+ },
+ BUILD_REQUIRES => {
+ 'Test::More' => 0,
+ 'Test::Pod' => 1.48,
+ 'Test::Pod::Coverage' => 1.08,
+ },
+ META_MERGE => {
+ resources => {
+ license => 'http://dev.perl.org/licenses/',
+ homepage => 'https://metacpan.org/module/CGI::Alternatives',
+ bugtracker => 'https://github.com/leejo/cgi-alterntatives/issues',
+ repository => 'https://github.com/leejo/cgi-alternatives'
+ },
+ },
+ test => {
+ TESTS => 't/*.t',
+ },
+);
View
47 README
@@ -0,0 +1,47 @@
+NAME
+ CGI::Alternatives - Documentation for alternative solutions to CGI.pm
+
+VERSION
+ 0.01
+
+DESCRIPTION
+ This module doesn't do anything, it exists solely to document
+ alternatives to the CGI module. This documentation is a work in
+ progress, an example script will be shown in raw CGI.pm and then the
+ equivalent implementation for each alternative will be shown. Resources
+ to further information and documentation will also be included.
+
+BUT WHY?
+ CGI.pm hasn't been considered good practice for many years, and there
+ have been alternatives available for web development in perl for a long
+ time. Despite this there are still some perl developers that will
+ recommend the use of CGI.pm for web development and prototyping. The two
+ main arguments for the use of CGI.pm, often given by those developers,
+ are no longer true:
+
+ 1) "CGI.pm is a core module so you don't have install anything extra."
+ This is now incorrect:
+
+ http://perl5.git.perl.org/perl.git/commitdiff/e9fa5a80
+
+ If you are doing any serious web development you are going to have to
+ use external dependencies, DBI is not in the core for example.
+
+ 2) "CGI.pm scripts are shorter and simpler than alternative
+ implementations." Again, not true and the following examples will show
+ that.
+
+PSGI
+Plack
+Mojolicious
+Dancer
+Catalyst
+Others
+Dependency Handling
+AUTHOR INFORMATION
+ Lee Johnson - `leejo@cpan.org'
+
+ This library is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself.
+
+SEE ALSO
View
11 README.md
@@ -1,11 +0,0 @@
-cgi-alternatives
-================
-
-Documentation for "modern" alternatives to CGI.pm
-
-- PSGI
-- Plack
-- Mojolicious
-- Dancer
-- Catalyst
-- Others
View
68 lib/CGI/Alternatives.pm
@@ -0,0 +1,68 @@
+package CGI::Alternatives;
+
+use strict;
+use warnings;
+
+our $VERSION = '0.01';
+
+1;
+
+=head1 NAME
+
+CGI::Alternatives - Documentation for alternative solutions to CGI.pm
+
+=head1 VERSION
+
+0.01
+
+=head1 DESCRIPTION
+
+This module doesn't do anything, it exists solely to document alternatives
+to the L<CGI> module. This documentation is a work in progress, an example
+script will be shown in raw CGI.pm and then the equivalent implementation
+for each alternative will be shown. Resources to further information and
+documentation will also be included.
+
+=head1 BUT WHY?
+
+CGI.pm hasn't been considered good practice for many years, and there have
+been alternatives available for web development in perl for a long time.
+Despite this there are still some perl developers that will recommend the
+use of CGI.pm for web development and prototyping. The two main arguments
+for the use of CGI.pm, often given by those developers, are no longer true:
+
+1) "CGI.pm is a core module so you don't have install anything extra." This
+is now incorrect:
+
+ http://perl5.git.perl.org/perl.git/commitdiff/e9fa5a80
+
+If you are doing any serious web development you are going to have to use
+external dependencies, DBI is not in the core for example.
+
+2) "CGI.pm scripts are shorter and simpler than alternative implementations."
+Again, not true and the following examples will show that.
+
+=head1 PSGI
+
+=head1 Plack
+
+=head1 Mojolicious
+
+=head1 Dancer
+
+=head1 Catalyst
+
+=head1 Others
+
+=head1 Dependency Handling
+
+=head1 AUTHOR INFORMATION
+
+Lee Johnson - C<leejo@cpan.org>
+
+This library is free software; you can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+=cut
View
32 t/001_compiles_pod.t
@@ -0,0 +1,32 @@
+#!perl
+
+use strict;
+use warnings;
+
+use Test::More;
+use File::Find;
+use Test::Pod;
+use Test::Pod::Coverage;
+
+if(($ENV{HARNESS_PERL_SWITCHES} || '') =~ /Devel::Cover/) {
+ plan skip_all => 'HARNESS_PERL_SWITCHES =~ /Devel::Cover/';
+}
+
+my @files;
+
+find(
+ {
+ wanted => sub { /\.pm$/ and push @files, $File::Find::name },
+ no_chdir => 1
+ },
+ -e 'blib' ? 'blib' : 'lib',
+);
+
+plan tests => @files * 3;
+
+for my $file (@files) {
+ my $module = $file; $module =~ s,\.pm$,,; $module =~ s,.*/?lib/,,; $module =~ s,/,::,g;
+ ok eval "use $module; 1", "use $module" or diag $@;
+ Test::Pod::pod_file_ok($file);
+ Test::Pod::Coverage::pod_coverage_ok($module);
+}

0 comments on commit 01b3485

Please sign in to comment.