From c17f168218bcddfac35f172a9ac12a7df56560ce Mon Sep 17 00:00:00 2001 From: Mitch Jackson Date: Sun, 3 Feb 2019 22:33:37 -0500 Subject: [PATCH] RT# 81961 Move POD to HTML code into FS::Misc::Pod2Html module --- FS/FS/Misc/Pod2Html.pm | 132 +++++++++++++++++++++++++++++++++++++++++++++++ FS/bin/freeside-pod2html | 47 +++++++++++++++++ bin/pod2html.pl | 114 ---------------------------------------- 3 files changed, 179 insertions(+), 114 deletions(-) create mode 100644 FS/FS/Misc/Pod2Html.pm create mode 100755 FS/bin/freeside-pod2html delete mode 100755 bin/pod2html.pl diff --git a/FS/FS/Misc/Pod2Html.pm b/FS/FS/Misc/Pod2Html.pm new file mode 100644 index 000000000..08358aa77 --- /dev/null +++ b/FS/FS/Misc/Pod2Html.pm @@ -0,0 +1,132 @@ +package FS::Misc::Pod2Html; +use strict; +use warnings; +use Carp qw( croak ); +use Pod::Simple::HTML; +use Pod::Simple::HTMLBatch; +use Pod::Simple::Search; + +use base 'Exporter'; +our @EXPORT_OK = qw( + fs_pod2html + $include_system_perl_modules + $quiet_mode +); + +our $include_system_perl_modules = 1; +our $quiet_mode = 0; + +=head1 NAME + +FS::Misc::Pod2Html + +=head1 DESCRIPTION + +Generate HTML from POD Documentation + +=head1 SYNOPSIS + +Usage: + + use FS::Misc::Pod2Html 'fs_pod2html'; + fs_pod2html( '/output/directory' ); + +=head2 fs_pod2html /output/directory/ + +Generates Freeside-themed HTML docuemtnation from installed perl modules + +=cut + +our $html_before_title = q{ + <% include( '/elements/header.html', 'Developer Documentation' ) %> + <& /elements/menubar.html, + 'Freeside Perl Modules' => $fsurl.'docs/library/FS.html', + 'Complete Index' => $fsurl.'docs/library/index.html', + &> + +
+

+}; + +our $html_after_title = q{

}; + +our $html_footer = q{
<% include ('/elements/footer.html' ) %>}; + +sub fs_pod2html { + my $html_dir = shift + or croak 'Please specify an output directory'; + + croak "Directory $html_dir: No write access" + unless -w $html_dir; + + my @search_dirs = ( + '/usr/local/share/perl/5.24.1', + '/usr/local/bin', + $include_system_perl_modules ? ( + '/usr/share/perl5', + '/usr/share/perl/5.24', + '/usr/share/perl/5.24.1', + ) : (), + ); + + my $parser = Pod::Simple::HTMLBatch->new; + + $parser->verbose(0) + if $quiet_mode; + + $parser->search_class('Inline::Pod::Simple::Search'); + $parser->html_render_class('Inline::Pod::Simple::HTML'); + $parser->contents_page_start( + "$html_before_title Freeside Documentation Index $html_after_title" + ); + $parser->contents_page_end( $html_footer ); + + $parser->batch_convert( \@search_dirs, $html_dir ); +} + +1; + +=head1 NAME + +Inline::Pod::Simple::Search + +=head2 DESCRIPTION + +Subclass of Pod::Simple::Search + +Enable searching for POD in all files instead of just .pl and .pm + +=cut + +package Inline::Pod::Simple::Search; +use base 'Pod::Simple::Search'; + +sub new { + my $class = shift; + my $self = Pod::Simple::Search->new( @_ ); + $self->laborious(1); + $self; +} +1; + +=head1 NAME + +Inline::Pod::Simple::HTML + +=head2 DESCRIPTION + +Subclass of Pod::Simple::HTML + +Customize parsed HTML output + +=cut + +# Subclass Pod::Simple::HTML to control HTML output +package Inline::Pod::Simple::HTML; +use base 'Pod::Simple::HTML'; + +sub html_header_before_title { $html_before_title } +sub html_header_after_title { $html_after_title } +sub html_footer { $html_footer } + +1; diff --git a/FS/bin/freeside-pod2html b/FS/bin/freeside-pod2html new file mode 100755 index 000000000..991b9fee8 --- /dev/null +++ b/FS/bin/freeside-pod2html @@ -0,0 +1,47 @@ +#!/usr/bin/env perl + +=head1 NAME + +pod2html.pl + +=head1 DESCRIPTION + +Generate HTML from POD documentation + +=head1 SEE ALSO + +L + +=cut + +use strict; +use warnings; +use v5.10; + +use FS::Misc::Pod2Html 'fs_pod2html'; +use FS::UID qw( checkuid ); + +die 'Not running uid freeside!' + unless checkuid(); + +my $html_dir = shift @ARGV + or HELP_MESSAGE('Please specify an OUTPUT_DIRECTORY'); + +HELP_MESSAGE("Directory $html_dir: No write access!") + unless -w $html_dir; + +fs_pod2html( $html_dir ); + +sub HELP_MESSAGE { + my $error = shift; + print " ERROR: $error \n" + if $error; + print " + Generate HTML from Freeside POD documentation + + Usage: pod2html.pl OUTPUT_DIRECTORY + + "; + exit; +} + diff --git a/bin/pod2html.pl b/bin/pod2html.pl deleted file mode 100755 index 935ff1198..000000000 --- a/bin/pod2html.pl +++ /dev/null @@ -1,114 +0,0 @@ -#!/usr/bin/env perl - -=head1 NAME - -pod2html.pl - -=head1 DESCRIPTION - -Generate HTML from POD documentation - -Search directories /usr/local/share/perl and /usr/local/bin - -Output HTML to /var/www/html/freeside-doc - -=cut - -use strict; -use warnings; -use v5.10; - -use Pod::Simple::Search; -use Pod::Simple::HTML; -use Pod::Simple::HTMLBatch; - -# Disable this to only build docs for Freeside modules -# This will cause links to non-freeside packages to be broken, -# but save 30-60secs during build process -my $include_system_perl_modules = 1; - - -my $html_dir = shift @ARGV - or HELP_MESSAGE('Please specify an OUTPUT_DIRECTORY'); - -HELP_MESSAGE("Directory $html_dir: No write access!") - unless -w $html_dir; - - -my $parser = Pod::Simple::HTMLBatch->new; - -# Uncomment to suppress status output to STDIN -# $parser->verbose(0); - -$parser->search_class('Inline::Pod::Simple::Search'); -$parser->html_render_class('Inline::Pod::Simple::HTML'); - -# Customized HTML output -our $html_before_title = q{ - <% include( '/elements/header.html', 'Developer Documentation' ) %> - <& /elements/menubar.html, - 'Freeside Perl Modules' => $fsurl.'docs/library/FS.html', - 'Complete Index' => $fsurl.'docs/library/index.html', - &> - -
-

-}; -our $html_after_title = q{

}; -our $html_footer = q{
<% include ('/elements/footer.html' ) %>}; - -$parser->contents_page_start( - "$html_before_title Freeside Documentation Index $html_after_title" -); -$parser->contents_page_end( $html_footer ); - -my @search_dirs = ( - '/usr/local/share/perl/5.24.1', - '/usr/local/bin', - $include_system_perl_modules ? ( - '/usr/share/perl5', - '/usr/share/perl/5.24', - '/usr/share/perl/5.24.1', - ) : (), -); - -$parser->batch_convert( \@search_dirs, $html_dir ); - -sub HELP_MESSAGE { - my $error = shift; - print " ERROR: $error \n" - if $error; - print " - Tool to generate HTML from Freeside POD documentation - - Usage: pod2html.pl OUTPUT_DIRECTORY - - "; - exit; -} - - - -# Subclass Pod::Simple::Search to render POD from files without -# normal perl extensions like PL and PM -package Inline::Pod::Simple::Search; -use base 'Pod::Simple::Search'; - -sub new { - my $class = shift; - my $self = Pod::Simple::Search->new( @_ ); - $self->laborious(1); - $self; -} -1; - - -# Subclass Pod::Simple::HTML to control HTML output -package Inline::Pod::Simple::HTML; -use base 'Pod::Simple::HTML'; - -sub html_header_before_title { $html_before_title } -sub html_header_after_title { $html_after_title } -sub html_footer { $html_footer } - -1; -- 2.11.0