stas 02/04/29 10:36:55
Modified: lib/DocSet Cache.pm Config.pm DocSet.pm NavigateCache.pm
lib/DocSet/Doc POD2HTML.pm
lib/DocSet/DocSet HTML.pm
Log:
sync with DocSet
- implemented a special docset type: "sitemap" which automatically
generates a sitemap from the root of the docset the sitemap is
located in and all the way down including all sub-docsets.
- implemented the down() method in the NavigateCache class. Now it's
possible to traverse the whole set of docsets in both directions
starting from any node in any docset.
Revision Changes Path
1.5 +11 -1 modperl-docs/lib/DocSet/Cache.pm
Index: Cache.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Cache.pm,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Cache.pm 21 Apr 2002 15:36:53 -0000 1.4
+++ Cache.pm 29 Apr 2002 17:36:54 -0000 1.5
@@ -8,7 +8,7 @@
use Storable;
use Carp;
-my %attrs = map {$_ => 1} qw(toc meta order);
+my %attrs = map {$_ => 1} qw(toc meta order child_cache_path);
sub new {
my($class, $path, $update) = @_;
@@ -230,6 +230,16 @@
$self->{cache}{_parent}{rel_path})
: (undef, undef, undef);
}
+}
+
+# get the child node's cache if any
+sub child_cache_path {
+ my($self, $id) = @_;
+ croak "must specify a id" unless defined $id;
+
+ return exists $self->{cache}{$id}{child_cache_path}
+ ? $self->{cache}{$id}{child_cache_path}
+ : undef;
}
1.8 +60 -14 modperl-docs/lib/DocSet/Config.pm
Index: Config.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Config.pm,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Config.pm 21 Apr 2002 15:36:53 -0000 1.7
+++ Config.pm 29 Apr 2002 17:36:54 -0000 1.8
@@ -54,7 +54,7 @@
}
-my %attr = map {$_ => 1} qw(chapters docsets links);
+my %attr = map {$_ => 1} qw(chapters docsets links sitemap);
sub read_config {
my($self, $config_file) = @_;
die "Configuration file is not specified" unless $config_file;
@@ -364,21 +364,26 @@
}
-sub docsets {
- my $self = shift;
- return exists $self->{docsets} ? @{ $self->{docsets} } : ();
-}
+#sub docsets {
+# my $self = shift;
+# return exists $self->{docsets} ? @{ $self->{docsets} } : ();
+#}
-sub links {
- my $self = shift;
- return exists $self->{links} ? @{ $self->{links} } : ();
-}
+#sub links {
+# my $self = shift;
+# return exists $self->{links} ? @{ $self->{links} } : ();
+#}
-sub src_chapters {
+sub sitemap {
my $self = shift;
- return exists $self->{chapters} ? @{ $self->{chapters} } : ();
+ return exists $self->{sitemap} ? $self->{sitemap} : ();
}
+#sub src_chapters {
+# my $self = shift;
+# return exists $self->{chapters} ? @{ $self->{chapters} } : ();
+#}
+
# chapter paths as they go into production
# $self->trg_chapters(@paths) : push a chapter(s)
# $self->trg_chapters : retrieve the list
@@ -460,11 +465,13 @@
$self->get_file($key);
$self->get_dir($dir_name);
- my @docsets = $self->docsets();
- my @links = $self->links();
- my @chapters = $self->src_chapters();
+#XXX my @docsets = $self->docsets();
+#XXX my @links = $self->links();
+#XXX my @chapters = $self->src_chapters();
my @chapters = $self->trg_chapters();
+ my $sitemap = $self->sitemap();
+
$self->cache($cache);
my $cache = $self->cache();
@@ -665,22 +672,54 @@
linked to after it gets copied via I<copy_glob> attribute in the same
or another docset.
+=item * sitemap
+
+Sitemap is a special kind of chapter rendered by calling the
+C<sitemap> template, which usually traverses the caches and builds a
+nested tree of all documents in the docset and below it. Note that if
+using this attribute in the inner docsets, it'll work the same as
+using it in the outmost docset, but the tree will show only the from
+the inner docset and below it. DWIM.
+
+The specification is exactly like the I<links> attribute, but there
+can be only one sitemap entry per config file, therefore its value is
+a reference to a hash with the same keys as the I<links> nodes. In the
+example below you can see how it get specified. The only thing to
+think about is the link entry:
+
+ link => 'sitemap.html',
+
+which says where the file will be generated relative to the directory
+I<config.cfg> resides in. So normally you will just use the same entry
+as the one in the example that follows.
+
+As we mentioned, the autogenerated sitemap will be automatically
+linked together with chapters, docsets and links, depending on where
+the I<sitemap> attribute has been added in the configuration file. Of
+course if you desire to link to the sitemap in a different way, you
+can always define it in the I<hidden> container, as it'll be explained
+later.
+
=back
This is an example:
docsets => ['docs', 'cool_docset'],
+
chapters => [
qw(
about/about.html
)
],
+
docsets => [
qw(
download
)
],
+
chapters => 'foo/bar/zed.pod',
+
links => [
{
id => 'asf',
@@ -689,6 +728,13 @@
abstract => "There many other ASF Projects",
},
],
+
+ sitemap => {
+ id => 'sitemap',
+ link => 'sitemap.html',
+ title => "The Site Map",
+ abstract => "You reach any document on our site from this sitemap",
+ },
Since normally books consist of parts which group chapters by a common
theme, we support this feature as well. So the index can now be
1.11 +27 -2 modperl-docs/lib/DocSet/DocSet.pm
Index: DocSet.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/DocSet.pm,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- DocSet.pm 21 Apr 2002 16:36:35 -0000 1.10
+++ DocSet.pm 29 Apr 2002 17:36:54 -0000 1.11
@@ -121,7 +121,9 @@
} elsif ($type eq 'links') {
$self->link_scan_n_cache($data, $hidden);
# we don't need to process links
-
+ } elsif ($type eq 'sitemap') {
+ $self->sitemap_cache($data, $hidden);
+ # we don't need to process links
} else {
# nothing
}
@@ -187,7 +189,7 @@
my $docset = $self->new($config_file, $self, $src_rel_dir);
$docset->scan;
- # cache the children meta data
+ # cache the child docset's meta data
my $id = $docset->get('id');
$self->cache->add($id);
my $meta = {
@@ -195,9 +197,17 @@
title => $docset->get('title'),
link => "$src_rel_dir/index.html",
abstract => $docset->get('abstract'),
+ rel_path => $src_rel_dir,
};
$self->cache->set($id, 'meta', $meta, $hidden);
+ # add the location of the cache file, so later we can traverse the
+ # nodes, by just reading the cache files, which are linked to each
+ # other both ways.
+ my $mode = $self->get('tmpl_mode');
+ my $child_cache_path = "$src_root/$src_rel_dir/cache.$mode.dat";
+ $self->cache->set($id, 'child_cache_path', $child_cache_path);
+
note "\n"; # mark the end of scan
return $docset;
@@ -215,6 +225,21 @@
$self->cache->set($id, 'meta', \%meta, $hidden);
}
+sub sitemap_cache {
+ my($self, $link, $hidden) = @_;
+ my %meta = %$link; # make a copy
+ my $id = delete $meta{id};
+ $meta{title} = $meta{stitle} unless exists $meta{title};
+ $meta{stitle} = $meta{title} unless exists $meta{stitle};
+ $self->cache->add($id);
+ $self->cache->set($id, 'meta', \%meta, $hidden);
+
+ # we will need to raise this flag to render the doc
+ # XXX: consider creating a Sitemap class, so we can handle this
+ # generically as chapters and docsets
+ $self->{sitemap} = \%meta;
+ # see Config::sitemap method
+}
sub chapter_scan_n_cache {
my($self, $src_file, $hidden) = @_;
1.3 +36 -13 modperl-docs/lib/DocSet/NavigateCache.pm
Index: NavigateCache.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/NavigateCache.pm,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- NavigateCache.pm 5 Feb 2002 10:27:19 -0000 1.2
+++ NavigateCache.pm 29 Apr 2002 17:36:54 -0000 1.3
@@ -16,7 +16,7 @@
use DocSet::Cache ();
[EMAIL PROTECTED] = qw(DocSet::Cache);
-use constant OBJ => 0;
+use constant CACHE => 0;
use constant ID => 1;
use constant CUR_PATH => 2;
use constant REL_PATH => 3;
@@ -26,14 +26,16 @@
my($class, $cache_path, $id, $rel_path) = @_;
croak "no cache path specified" unless defined $cache_path;
- croak "no id specified" unless defined $id;
my $cache = get_cache($cache_path);
my $self = bless [], ref($class)||$class;
- $self->[OBJ] = $cache;
+ $self->[CACHE] = $cache;
$self->[CUR_PATH] = $cache_path;
$self->[REL_PATH] = $rel_path if $rel_path;
- $self->[ID] = $id;
+
+ # get the first (#0) node if id wasn't provided
+ $self->[ID] = defined $id ? $id : $cache->seq2id(0);
+ return undef unless defined $self->[ID]; # an empty docset
return $self;
}
@@ -46,7 +48,7 @@
# get next item's object or undef if there are no more
sub next {
my($self) = @_;
- my $cache = $self->[OBJ];
+ my $cache = $self->[CACHE];
my $seq = $cache->id2seq($self->[ID]);
my $last_seq = $cache->total_ids - 1;
@@ -70,7 +72,7 @@
# get prev node's object or undef if there are no more
sub prev {
my($self) = @_;
- my $cache = $self->[OBJ];
+ my $cache = $self->[CACHE];
my $seq = $cache->id2seq($self->[ID]);
# if the current node is hidden, it's like there is no prev
@@ -94,7 +96,7 @@
# get the object of the first item on the same level
sub first {
my($self) = @_;
- my $cache = $self->[OBJ];
+ my $cache = $self->[CACHE];
# it's possible that the whole docset is made of hidden objects.
# since the hidden objects, if any, are always coming last
@@ -117,13 +119,13 @@
# the index node of the current level
sub index_node {
my($self) = @_;
- return $self->[OBJ]->index_node;
+ return $self->[CACHE]->index_node;
}
# get the object of the parent
sub up {
my($self) = @_;
- my($path, $id, $rel_path) = $self->[OBJ]->parent_node;
+ my($path, $id, $rel_path) = $self->[CACHE]->parent_node;
$rel_path = "." unless defined $rel_path;
if (defined $self->[REL_PATH] && length $self->[REL_PATH]) {
@@ -145,18 +147,30 @@
}
}
+# get the first child node
+sub down {
+ my($self) = @_;
+
+ if (my $path = $self->[CACHE]->child_cache_path($self->[ID])) {
+ return $self->new($path);
+ }
+ else {
+ return undef;
+ }
+}
+
# retrieve the meta data of the current node
sub meta {
my($self) = @_;
- return $self->[OBJ]->get($self->[ID], 'meta');
+ return $self->[CACHE]->get($self->[ID], 'meta');
}
# retrieve the node groups
sub node_groups {
my($self) = @_;
#print "OK: ";
-#dumper $self->[OBJ]->node_groups;
- return $self->[OBJ]->node_groups;
+#dumper $self->[CACHE]->node_groups;
+ return $self->[CACHE]->node_groups;
}
sub id {
@@ -207,6 +221,10 @@
$p = $p->up;
}
+ # access the docsets of the child nodes
+ $child_docset = $nav->down()
+
+
=head1 DESCRIPTION
C<DocSet::NavigateCache> navigates the cache created by docset objects
@@ -244,7 +262,10 @@
C<$cache_path> is the path of the cache file to read.
-C<$id> is the id of the current node.
+C<$id> is the id of the current node. if not specified the id for the
+first item (0) is retrieved.
+
+If the docset is empty (no items) new returns undef.
C<$rel_path> is optional and passed if an object has a parent node. It
contains a relative path from the current node to its parent.
@@ -258,6 +279,8 @@
=item * first
=item * up
+
+=item * down
=item * index_node
1.5 +13 -0 modperl-docs/lib/DocSet/Doc/POD2HTML.pm
Index: POD2HTML.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Doc/POD2HTML.pm,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- POD2HTML.pm 22 Mar 2002 02:01:51 -0000 1.4
+++ POD2HTML.pm 29 Apr 2002 17:36:55 -0000 1.5
@@ -136,6 +136,19 @@
return -e $file ? qq{<a href="$path">$path</a>} : qq{<i>$path</i>};
}
+#sub view_for {
+# my $self = shift;
+# my ($for) = @_;
+# return $self->SUPER::view_for(@_) if $for->format() =~ /\bhtml\b/;
+# if ($for->format() =~ /\btt2\b/) {
+# my $text = $for->text();
+#print "$text\n";
+#return $text;
+## "WHOOOOOOOOOOOOOOOOOOOOOOO";
+## $self->parse_sequence($text);
+# }
+#}
+
*anchor = \&DocSet::Doc::Common::pod_pom_html_anchor;
*view_verbatim = \&DocSet::Doc::Common::pod_pom_html_view_verbatim;
*view_seq_link_transform_path =
\&DocSet::Doc::Common::pod_pom_html_view_seq_link_transform_path;
1.6 +40 -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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- HTML.pm 21 Apr 2002 07:25:18 -0000 1.5
+++ HTML.pm 29 Apr 2002 17:36:55 -0000 1.6
@@ -37,13 +37,52 @@
note "\n";
banner("[render] HTML DocSet: " . $self->get('title') );
+ $self->write_sitemap_file() if $self->sitemap;
+
$self->write_index_file();
}
+# generate the sitemap.html of the docset below the current root
+##################################
+sub write_sitemap_file {
+ my($self) = @_;
+
+ my $cache = $self->cache;
+
+ my $dir = {
+ abs_doc_root => $self->get_dir('abs_doc_root'),
+ rel_doc_root => $self->get_dir('rel_parent_root'),
+ path_from_base => $self->get_dir('path_from_base'),
+ };
+
+ my $meta = $self->sitemap;
+ my $file = exists $meta->{link} ? $meta->{link} : "sitemap.html";
+
+ my $navigator = DocSet::NavigateCache->new($self->cache->path,
$self->get('id'));
+ my %args = (
+ nav => $navigator,
+ meta => $meta,
+ dir => $dir,
+ version => $self->get('version')||'',
+ date => get_date(),
+ last_modified => get_timestamp(),
+ );
+
+ my $dst_root = $self->get_dir('dst_html');
+ my $dst_file = "$dst_root/$file";
+ my $mode = $self->get('tmpl_mode');
+ my $tmpl_file = 'sitemap';
+ my $vars = { doc => \%args };
+ my $tmpl_root = $self->get_dir('tmpl');
+ my $content = proc_tmpl($tmpl_root, $tmpl_file, $mode, $vars);
+ note "+++ Creating $dst_file";
+ DocSet::Util::write_file($dst_file, $content);
+}
+
# generate the index.html based on the doc entities it includes, in
# the following order: docsets, books, chapters
#
-# Using the same template file create the long and the short index
+# XXX: Using the same template file create the long and the short index
# html files
##################################
sub write_index_file {
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
