perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/lib/DocSet/DocSet HTML.pm
Date Sun, 21 Apr 2002 07:25:18 GMT
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


Mime
View raw message