You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/04/21 09:25:18 UTC
cvs commit: modperl-docs/lib/DocSet/DocSet HTML.pm
stas 02/04/21 00:25:18
Modified: lib/DocSet Config.pm DocSet.pm RunTime.pm Util.pm
lib/DocSet/DocSet HTML.pm
Log:
- I cannot reproduce the trailing punctuation character bug
(http://foo.com/bar.html.) in automatic POD URLifier, removed from
the TODO list.
- copy_glob => [foo/*] doesn't pick .dot_files in the first level of
subdir, because in unix glob() '*' doesn't match .files.
'copy_glob => [foo]' works correctly. Now this behavior is documented.
also fixed wrong documentation about copy_glob regarding creating
empty dirs.
- improve the logic for searing resources. If I have a setting of
search_paths as:
search_paths => [qw(
docs/1.0
.
)],
and the resource request is for L<foo|win32::binaries> everything is
cool if there is docs/1.0/win32/binaries.pod. However if somebody is
doing a better job and doing a fully qualified request like
L<foo|docs::1.0::win32::binaries> the page used to be reported as not
found, because it's cached in the prescan as 'docs/1.0' =>
'win32/binaries.pod'. Now this problem is solved.
- add a special handling for L<...|foo::bar::index> so only
foo::bar is checked that it's a dir in the search path and
index.html is autogenerated. This allows us to do L<the
guide|guide::index>
- improve the exception handling of incorrect paths in config.cfg,
when a chapter item cannot be found.
Revision Changes Path
1.6 +17 -8 modperl-docs/lib/DocSet/Config.pm
Index: Config.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Config.pm,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Config.pm 22 Mar 2002 02:01:51 -0000 1.5
+++ Config.pm 21 Apr 2002 07:25:18 -0000 1.6
@@ -59,6 +59,8 @@
my($self, $config_file) = @_;
die "Configuration file is not specified" unless $config_file;
+ $self->{config_file} = $config_file;
+
my $package = path2package($config_file);
$self->{package} = $package;
@@ -737,22 +739,29 @@
=item * copy_glob
-Accepts a reference to an array of files and directories to copy. Note
-that you must use shell wildcharacters if you want deep directory
-copies, which also works for things like: C<*.html>. If you simply
-specify a directory name it'll be copied without any contents (this is
-a feature!). For example:
+Accepts a reference to an array of files and directories to copy. The
+items of the array are run through glob(), therefore wild characters
+can be used to match only certain files. But be careful since if you
+say:
+
+ images/*
+
+and there are some hidden files (and dirs) that need to be copied,
+they won't be copied, since C<*> doesn't match them.
+
+For example:
# non-pod/html files or dirs to be copied unmodified
copy_glob => [
qw(
style.css
- images/*
+ images
)
],
-will copy I<style.css> and all the files under the I<images/>
-directory.
+will copy the file I<style.css> and all the files and directories
+under the I<images/> directory into the parallel tree at the
+destination directory.
=item * copy_skip
1.8 +48 -4 modperl-docs/lib/DocSet/DocSet.pm
Index: DocSet.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/DocSet.pm,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- DocSet.pm 3 Apr 2002 11:47:56 -0000 1.7
+++ DocSet.pm 21 Apr 2002 07:25:18 -0000 1.8
@@ -21,7 +21,6 @@
return $self;
}
-
sub init {
my($self, $config_file, $parent_o, $src_rel_dir) = @_;
@@ -177,7 +176,7 @@
my $dst_root = $self->get_dir('dst_root');
my $dst_index = "$dst_root/$src_rel_dir/index.html";
my($should_update, $reason) =
- should_update($cfg_file, $dst_index);
+ $self->should_update($cfg_file, $dst_index);
$docset->modified(1) if $should_update;
note "\n"; # mark the end of scan
@@ -223,7 +222,7 @@
$self->trg_chapters($rel_dst_path) unless $hidden;
### to rebuild or not to rebuild
- my($should_update, $reason) = should_update($src_path, $dst_path);
+ my($should_update, $reason) = $self->should_update($src_path, $dst_path);
if (!$should_update) {
note "--- $src_file: skipping ($reason)";
return undef;
@@ -283,7 +282,7 @@
# to rebuild or not to rebuild
my($should_update, $reason) =
- should_update($src_path, $dst_path);
+ $self->should_update($src_path, $dst_path);
if (!$should_update) {
note "--- skipping cp $src_path $dst_path ($reason)";
next;
@@ -341,6 +340,39 @@
# an abstract method
sub complete {}
+# die with the error, and supply the context in which the error has happened
+sub error {
+ my $self = shift;
+
+ my @context;
+ push @context, "config file: $self->{config_file}";
+
+ die map({"!!! err: $_\n"} @_),
+ "in context:\n", map({"\t$_\n"} @context);
+
+}
+
+sub should_update {
+ my($self, $src_path, $dst_path) = @_;
+
+ unless (-e $src_path) {
+ $self->error("cannot find $src_path");
+ }
+
+ # to rebuild or not to rebuild
+ my $not_modified =
+ (-e $dst_path and -M $dst_path < -M $src_path) ? 1 : 0;
+
+ my $reason = $not_modified ? 'not modified' : 'modified';
+ if (DocSet::RunTime::get_opts('rebuild_all')) {
+ return (1, "$reason / forced");
+ }
+ else {
+ return (!$not_modified, $reason);
+ }
+
+}
+
1;
__END__
@@ -362,6 +394,8 @@
$docset->scan;
$docset->render;
+ my $should_update = $self->should_update($src_path, $dst_path);
+
=head1 DESCRIPTION
C<DocSet::DocSet> processes a docset, which can include other docsets,
@@ -424,6 +458,16 @@
Copies the files which aren't processed (i.e. images, css files, etc.)
and were modified as-is.
+
+=item * should_update
+
+ my $should_update = $self->should_update($src_path, $dst_path);
+
+Compare the timestamps/existance of src and dst paths and return
+(true, reason) if src is newer than dst otherwise return (false,
+reason)
+
+If rebuild_all runtime is on, this always returns (true, reason)
=back
1.5 +47 -12 modperl-docs/lib/DocSet/RunTime.pm
Index: RunTime.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/RunTime.pm,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- RunTime.pm 3 Apr 2002 07:26:24 -0000 1.4
+++ RunTime.pm 21 Apr 2002 07:25:18 -0000 1.5
@@ -6,7 +6,7 @@
use strict;
use warnings;
-use File::Spec::Functions;
+use File::Spec::Functions qw(catdir catfile splitdir);
use File::Find;
use DocSet::Util;
@@ -16,8 +16,9 @@
@ISA = qw(Exporter);
@EXPORT = qw(get_opts find_src_doc set_render_obj get_render_obj unset_render_obj);
-my %src_docs;
-my %exts;
+my @search_paths = ();
+my %src_docs = ();
+my %exts = ();
my $render_obj;
# = (
@@ -81,6 +82,8 @@
sub scan_src_docs {
my($base, $ra_search_paths, $ra_search_exts) = @_;
+ @search_paths = @{$ra_search_paths || []};
+
%exts = map {$_ => 1} @{$ra_search_exts || []};
my @ext_accept_pattern = map {quotemeta($_)."\$"} keys %exts;
@@ -88,7 +91,7 @@
build_matchmany_sub(\@ext_accept_pattern);
my %seen;
- for my $rel_path (@{$ra_search_paths || []}) {
+ for my $rel_path (@search_paths) {
my $full_path = catdir $base, $rel_path;
die "$full_path is not a dir" unless -d $full_path;
@@ -96,25 +99,39 @@
my $rsub_skip_seen =
build_matchmany_sub(\@seen_pattern);
+ # rewrite non / paths to be / as in URI ($rel_path is no more
+ # needed to read from the real fs, will need this fixup for
+ # generating proper URIs.
+ $rel_path = join "/", splitdir $rel_path;
+
my $full_path_regex = quotemeta $full_path;
$src_docs{$rel_path} = {
- map { $_ => 1 }
- map {s|$full_path_regex/||; $_}
- grep $rsub_keep_ext->($_), # get files with wanted exts
- grep !$rsub_skip_seen->($_), # skip seen base dirs
- @{ expand_dir($full_path) }
+ map { m{(.*?/?)[^/]+$} # add autogenerated index.html
+ ? ("$1index.html" => 1, $_ => 1)
+ : ($_ => 1); # shouldn't happen, but just in case
+ }
+ map {join "/", splitdir $_} # rewrite non / paths to be URI's /
+ map {s|$full_path_regex/||; $_} # strip the leading path
+ grep $rsub_keep_ext->($_), # get files with wanted exts
+ grep !$rsub_skip_seen->($_), # skip seen base dirs
+ @{ expand_dir($full_path) }
};
note "Scanning for src files: $full_path";
$seen{$full_path}++;
}
- #dumper \%src_docs;
+# dumper \%src_docs;
}
+# this function returns a URI, so its separators are always /
sub find_src_doc {
my($resource_rel_path) = @_;
+ # push the html extension, because of autogenerated index.html,
+ # which should be found automatically
+ $exts{html} = 1 unless exists $exts{html};
+
for my $path (keys %src_docs) {
for my $ext (keys %exts) {
#print qq{Try: $path :: $resource_rel_path.$ext\n};
@@ -126,6 +143,18 @@
}
}
+ # if we didn't find anything so far, it's possible that the path was
+ # specified with a longer prefix, that was needed (the above
+ # searches only the end leaves), so we cut pathes here in the
+ # search order
+ for my $rel_path (@search_paths) {
+ if ($resource_rel_path =~ s|$rel_path/||) {
+ return find_src_doc($resource_rel_path);
+ }
+ }
+
+#dumper $src_docs{"docs/1.0"};
+ return;
}
# set render object: sort of Singleton, it'll complain aloud if the
@@ -245,7 +274,7 @@
I<~/myproject/src/foo/bar>, I<~/myproject/src/foo> and
I<~/myproject/src>.
-Notice that you must specify the more specific paths first, since for
+Notice that you must specify more specific paths first, since for
optimization the seen paths are skipped. Therefore in our example the
more explicit path I<foo/bar> was listed before the more general
I<foo>.
@@ -256,6 +285,12 @@
then easily converted to the final location and optionally adjusting
the extension, e.g. when the POD file is converted to HTML.
+As a special extension this function automatically assumes that
+C<index.html> will be generated in each directory containing items of
+an interest. Therefore in find_src_doc() it'll automatically find
+things like: L<the guide|guide::index>, even though there was no
+source I<index.pod> or I<index.html> in first place.
+
Only the find_src_doc() function is exported by default.
=over
@@ -264,7 +299,7 @@
=item * find_src_doc($resource_rel_path);
-returns C<undef> if nothing was found.
+returns C<undef> if nothing was found. See the description above.
=back
1.11 +4 -29 modperl-docs/lib/DocSet/Util.pm
Index: Util.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Util.pm,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- Util.pm 19 Apr 2002 02:59:51 -0000 1.10
+++ Util.pm 21 Apr 2002 07:25:18 -0000 1.11
@@ -22,8 +22,8 @@
@EXPORT = qw(read_file read_file_paras copy_file gzip_file write_file
create_dir filename filename_ext require_package dumper
sub_trace note get_date get_timestamp proc_tmpl
- build_matchmany_sub banner should_update confess cluck
- carp format_bytes expand_dir which);
+ build_matchmany_sub banner confess cluck carp
+ format_bytes expand_dir which);
# copy_file($src_path, $dst_path);
# copy a file at $src_path to $dst_path,
@@ -185,30 +185,6 @@
}
-# compare the timestamps/existance of src and dst paths
-# and return (true,reason) if src is newer than dst
-# otherwise return (false, reason)
-#
-# if rebuild_all runtime is on, this always returns (true, reason)
-#
-sub should_update {
- my($src_path, $dst_path) = @_;
-
- die "cannot find $src_path" unless -e $src_path;
-
- # to rebuild or not to rebuild
- my $not_modified =
- (-e $dst_path and -M $dst_path < -M $src_path) ? 1 : 0;
-
- my $reason = $not_modified ? 'not modified' : 'modified';
- if (DocSet::RunTime::get_opts('rebuild_all')) {
- return (1, "$reason / forced");
- } else {
- return (!$not_modified, $reason);
- }
-
-
-}
sub banner {
my($string) = @_;
@@ -260,6 +236,7 @@
}
}
+
sub expand_dir {
my @files = ();
if ($] >= 5.006) {
@@ -344,7 +321,7 @@
require_package($package);
my $output = proc_tmpl($tmpl_root, $tmpl_file, $mode, $vars);
- my $should_update = should_update($src_path, $dst_path);
+
banner($string);
my $sub_ref = build_matchmany_sub($ra_regex);
@@ -383,8 +360,6 @@
=item * require_package
=item * proc_tmpl
-
-=item * should_update
=item * banner
1.5 +0 -1 modperl-docs/lib/DocSet/DocSet/HTML.pm
Index: HTML.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/DocSet/HTML.pm,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- HTML.pm 25 Mar 2002 17:08:04 -0000 1.4
+++ HTML.pm 21 Apr 2002 07:25:18 -0000 1.5
@@ -99,7 +99,6 @@
pdf_doc => $self->pdf_doc,
);
-
# plaster index top and bottom docs if defined (after converting them)
if (my $body = $self->get('body')) {
my $src_root = $self->get_dir('src_root');
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org