You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by nw...@apache.org on 2016/02/27 19:04:29 UTC
lucy git commit: Rework pod2mdtext.pl
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 <we...@aevum.de>
Authored: Sat Feb 27 18:45:38 2016 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
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
-