Repository: lucy Updated Branches: refs/heads/master 0d6b493f2 -> e1b4fb269
Rework pod2mdtext.pl - Tidy up code. - Rework extraction of name section. - Switch to long options. - Add options for project name. - Per-project index filename. - Use en dash. Project: http://git-wip-us.apache.org/repos/asf/lucy/repo Commit: http://git-wip-us.apache.org/repos/asf/lucy/commit/e1b4fb26 Tree: http://git-wip-us.apache.org/repos/asf/lucy/tree/e1b4fb26 Diff: http://git-wip-us.apache.org/repos/asf/lucy/diff/e1b4fb26 Branch: refs/heads/master Commit: e1b4fb26900c4792223461b2f0565c82181e752e Parents: 0d6b493 Author: Nick Wellnhofer <[email protected]> Authored: Sat Feb 27 18:45:38 2016 +0100 Committer: Nick Wellnhofer <[email protected]> Committed: Sat Feb 27 19:03:26 2016 +0100 ---------------------------------------------------------------------- devel/bin/pod2mdtext.pl | 221 +++++++++++++++++++------------------------ 1 file changed, 96 insertions(+), 125 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucy/blob/e1b4fb26/devel/bin/pod2mdtext.pl ---------------------------------------------------------------------- diff --git a/devel/bin/pod2mdtext.pl b/devel/bin/pod2mdtext.pl index e3db894..bfaf070 100755 --- a/devel/bin/pod2mdtext.pl +++ b/devel/bin/pod2mdtext.pl @@ -15,59 +15,97 @@ # See the License for the specific language governing permissions and # limitations under the License. -use strict; -use warnings; +=head1 NAME -package NameExtractor; +pod2mdtext.pl - Convert POD to mdtext for the Apache CMS -use base qw(Pod::Simple); +=head1 SYNOPSIS -# Extraction of NAME sections. Possibly fragile. + pod2mdtext.pl --name=PROJECT_NAME [--full-name=FULL_NAME] + --version=X.Y.Z -sub _handle_element_start { - my ($parser, $element_name, $attr_hash_r) = @_; +=head1 DESCRIPTION - if ($element_name eq 'head1') { - $parser->{in_head1} = 1; - $parser->{head1_content} = ''; - } -} +This script creates mdtext files from POD. It must be run in the C<perl> +directory and scans all .pod and .pm files found in C<lib>. The resulting +mdtext files are stored in a directory named C<mdtext>. -sub _handle_text { - my ($parser, $text) = @_; +=head1 OPTIONS - if ($parser->{in_head1}) { - $parser->{head1_content} .= $text; - } - elsif ($parser->{after_head1}) { - $parser->{extracted_name} = $text; - $parser->{after_head1} = undef; - } -} +=head2 --name -sub _handle_element_end { - my ($parser, $element_name, $attr_hash_r) = @_; +Short name of the project used for the index filename. - if ($element_name eq 'head1') { - if ($parser->{head1_content} eq 'NAME') { - $parser->{after_head1} = 1; - } - $parser->{in_head1} = undef; - } -} +=head2 --full-name + +Full name of the project used in titles. Defaults to C<--name>. + +=head2 --version -package main; +Version number. + +=cut + +use strict; +use warnings; +use utf8; use File::Find; -use File::Path qw(make_path); +use File::Path qw( make_path ); use File::Slurp; -use Getopt::Std; +use Getopt::Long qw( GetOptions ); use Pod::Simple::HTML; my $out_root = 'mdtext'; +my $usage = join( ' ', + $0, + '--name=PROJECT_NAME', + '[--full-name=FULL_NAME]', + '--version=X.Y.Z', +) . "\n"; + +my ( $project_name, $full_name, $version ); +GetOptions( + 'name=s' => \$project_name, + 'full-name=s' => \$full_name, + 'version=s' => \$version, +); +$project_name or die $usage; +$version or die $usage; +$full_name ||= $project_name; + +my @pod_infos; + +find( { wanted => \&process_file, no_chdir => 1 }, 'lib' ); + +write_index(); + +sub process_file { + my $filename = $_; + my $dir = $File::Find::topdir; + + return if -d $filename || $filename !~ /\.(pm|pod)\z/; + my $content = read_file( $filename, binmode => ':utf8' ); + return if $filename =~ /\.pm$/ && $content !~ /^=head1/m; + $filename =~ s|^$dir/||; + + if ( $content =~ /^=head1\s*NAME\s+(\S+)\s+-\s+(.*?)\s+^=/ms ) { + push(@pod_infos, { + class => $1, + desc => $2, + filename => $filename, + }); + } + else { + print STDERR ("Warning: No valid NAME section found in $filename\n"); + } + + pod2mdtext( $dir, $filename ); +}; + sub pod2mdtext { - my ($base_dir, $filename) = @_; + my ( $base_dir, $filename ) = @_; my @path_comps = split('/', $filename); pop(@path_comps); @@ -76,17 +114,20 @@ sub pod2mdtext { make_path($out_dir); my $out_filename = "$out_root/$filename"; - $out_filename =~ s"(\.[^/.]*)?$".mdtext"; + $out_filename =~ s|(\.[^/.]*)?\z|.mdtext|; - open(my $out_file, '>', $out_filename) + open( my $out_file, '>', $out_filename ) or die("$out_filename: $!"); my $p = Pod::Simple::HTML->new; + my $after_title = " \x{2013} $full_name Documentation\n\n<div>\n"; + # Pod::Simple expects bytes. + utf8::encode($after_title); $p->batch_mode(1); - $p->batch_mode_current_level(scalar(@path_comps) + 1); + $p->batch_mode_current_level( scalar(@path_comps) + 1 ); $p->html_header_before_title('Title: '); - $p->html_header_after_title(" - Apache Lucy Documentation\n\n<div>\n"); + $p->html_header_after_title($after_title); $p->html_footer("\n</div>\n"); $p->html_h_level(2); # Needed to make strip_verbatim_indent work, no idea why. @@ -97,101 +138,31 @@ sub pod2mdtext { $p->parse_file("$base_dir/$filename"); close($out_file); - - my $name_ext = NameExtractor->new; - $name_ext->parse_file("$base_dir/$filename"); - - my $html_filename = $filename; - $html_filename =~ s"(\.[^/.]*)?$".html"; - - return { - name => $name_ext->{extracted_name}, - html_filename => $html_filename, - }; -} - -my %opts; -getopt('v', \%opts); -my $version = $opts{v} - or die("Usage: $0 -v version\n"); - -my @pod_infos; - -for my $dir (qw(lib)) { - my $wanted = sub { - my $filename = $_; - - return if -d $filename; - - if ($filename =~ /\.pm$/) { - my $content = read_file($filename); - return unless $content =~ /^=head1/m; - } - elsif ($filename !~ /\.pod$/) { - return; - } - - $filename =~ s"^$dir/""; - - my $pod_info = pod2mdtext($dir, $filename); - - if (!defined($pod_info->{name})) { - print STDERR ( - "Warning: Section NAME not found in ", - $pod_info->{html_filename}, "\n", - ); - } - else { - push(@pod_infos, $pod_info); - } - }; - - find({ wanted => $wanted, no_chdir => 1 }, $dir); } -my $index_filename = "$out_root/index.mdtext"; -open(my $index_file, '>', $index_filename) - or die("$index_filename: $!"); +sub write_index { + my $lc_project_name = lc($project_name); + my $index_filename = "$out_root/$lc_project_name-index.mdtext"; + open( my $index_file, '>:utf8', $index_filename ) + or die("$index_filename: $!"); -print $index_file (<<EOF); -Title: Perl API documentation for Apache Lucy $version + print $index_file (<<EOF); +Title: Perl API documentation for $full_name $version -## Perl API documentation for Apache Lucy $version +## Perl API documentation for $full_name $version EOF -for my $pod_info (sort { $a->{name} cmp $b->{name} } @pod_infos) { - my $name = $pod_info->{name}; - my $html_filename = $pod_info->{html_filename}; + for my $pod_info ( sort { $a->{class} cmp $b->{class} } @pod_infos ) { + my $class = $pod_info->{class}; + my $desc = $pod_info->{desc}; + my $filename = $pod_info->{filename}; - if ($name !~ /(\S+)\s+-\s+(.*)/) { - print STDERR ("Warning: Invalid NAME in $html_filename: $name\n"); - next; - } + $filename =~ s|(\.[^/.]*)?\z|.html|; - my ($class, $desc) = ($1, $2); - utf8::encode($desc); + print $index_file ("- [$class]($filename) \x{2013} $desc\n"); + } - print $index_file (" - [$class]($html_filename) - $desc\n"); + close($index_filename); } -close($index_filename); - -__END__ - -=head1 NAME - -pod2mdtext.pl - Convert POD to mdtext for the Apache CMS - -=head1 SYNOPSIS - - pod2mdtext.pl -v <version> - -=head1 DESCRIPTION - -This script creates mdtext files from POD. It must be run in the C<perl> -directory and scans all .pod files found in C<lib>. The resulting mdtext -files are stored in a directory named C<mdtext>. - -=cut -
