Stas Bekman wrote:
> My two main cons about using back-linking to the parent,
>
> is that there is no linking back to the child (and other children).
> so it's somewhat unballanced. I'm thinking about linking to the TOC
> instead, but we already decided not to have TOC for pages with only one
> item, so it won't work.
i agree that this linking is unballanced. on the other side,
if you open almost any of the files 1.0/guide there is bound
to be some naviagtion so i prefer to have unbalanced linking
simply because it's better than nothing. i don't suppose we
can find a proper solution for linking forward and backwards
anyway. a proper browser with a proper back-button will take
the user back to the child if he from that child clicked on
one of that child's parent-links. well, try it.
1) navigate to a nested child [position = level 3]
2) click on one of the parent links [position = level 1]
3) scroll any amount [position = level 1 + some]
4) hit the back-button [position = level 3]
> and yes, it'll add to the download time/size.
yes but also see below ...
> Also there is a problem with source HTML pages, since they are copied as
> is (well, almost).
> Therefore currently there is no way to add numbers to <h[1-4]>. We will
> need to change the
> HTML parser to identify these.
> So first we need to decide whether we want these numbers. Then implement
> this feature in POD and HTML if decided to do that. Then spice up with
> images instead of text if decided to.
>
> patches to DocSet are welcome :)
i have enclosed an ugly hack for pod2html. i don't know
anything about oop so stay calm when you watch the code ;)
someone will have to do the cleanup as i am not qualified (:
but it does actually work (here)!
skipping the bullets completely.
this is the result:
[
level 1 = title of a page
level 2 = 1st sub_item
level 3 = 2nd sub_item etc.
]
- all levels that are larger than 1 will have one or more
digits next to its section-title.
- the digits are clickable apart from the currently active
level. for instrance:
3.1.1.1 APACHE_SRC
^ ^ ^
^ ^ ^ ^ this is active
^ ^ ^ these are clickable
- while doing this i also changed the <a name="*"></a>. this
now consists of these figures sepearted by underscores - the
reason for this is simply to save (quite a lot of) bytes. if
the counting is working correctly these <a name="*"></a>
should always be unique and therefore always work. example:
<h4><a href="#3">3</a>.<a href="#3_1">1</a>.<a
href="#3_1">1</a>.1<a name="3_1_1_1"></a> APACHE_SRC</h4>
- there will have to be changes also to toc_section but i'm
looking at it ....
./allanpackage DocSet::Doc::POD2HTML;
use strict;
use warnings;
use File::Spec::Functions;
use File::Basename ();
use DocSet::Util;
use DocSet::RunTime;
require Pod::POM;
my $view_mode = 'DocSet::Doc::POD2HTML::View::HTML';
use DocSet::Doc::Common ();
*fetch_pdf_doc_ver = \&DocSet::Doc::Common::fetch_pdf_doc_ver;
*fetch_src_doc_ver = \&DocSet::Doc::Common::fetch_src_doc_ver;
use vars qw(@ISA);
require DocSet::Source::POD;
@ISA = qw(DocSet::Source::POD);
my %split_by = map {"head".$_ => 1} 1..4;
sub convert {
my($self) = @_;
set_render_obj($self);
my $pom = $self->{parsed_tree};
my @sections = $pom->content();
shift @sections; # skip the title
# my @body = ();
# foreach my $node (@sections) {
## my $type = $node->type();
## print "$type\n";
# push @body, $node->present($view_mode);
# }
#dumper $sections[$#sections];
my @body = slice_by_head(@sections);
my $vars = {
meta => $self->{meta},
toc => $self->{toc},
body => [EMAIL PROTECTED],
dir => $self->{dir},
nav => $self->{nav},
last_modified => $self->{timestamp},
pdf_doc => $self->fetch_pdf_doc_ver,
src_doc => $self->fetch_src_doc_ver,
};
my $tmpl_file = 'page';
my $mode = $self->{tmpl_mode};
my $tmpl_root = $self->{tmpl_root};
$self->{output} = proc_tmpl($tmpl_root, $tmpl_file, $mode, {doc => $vars} );
unset_render_obj();
}
sub slice_by_head {
my @sections = @_;
my @body = ();
for my $node (@sections) {
my @next = ();
# assumption, after the first 'headX' section, there can only
# be other 'headX' sections
my $count = scalar $node->content;
my $id = -1;
for ($node->content) {
$id++;
next unless exists $split_by{ $_->type };
@next = splice @{$node->content}, $id;
last;
}
push @body, $node->present($view_mode), slice_by_head(@next);
}
return @body;
}
1;
package DocSet::Doc::POD2HTML::View::HTML;
use vars qw(@ISA);
require Pod::POM::View::HTML;
@ISA = qw( Pod::POM::View::HTML);
use DocSet::RunTime;
use File::Spec::Functions;
use File::Basename;
# globalization
my $count_head1 = 0;
my $count_head2 = 0;
my $count_head3 = 0;
my $count_head4 = 0;
my $anchor_head1 = "";
my $anchor_head2 = "";
my $anchor_head3 = "";
my $anchor_head4 = "";
my $store_head1 = 0;
my $store_head2 = 0;
my $store_head3 = 0;
my $store_head4 = 0;
sub view_head1 {
my ($self, $head1) = @_;
$count_head2 = 0; # reset next level counter
$count_head1++;
$store_head1 = $count_head1;
$anchor_head1 = $count_head1;
return "<h1>$count_head1<a name=\"$anchor_head1\"></a> " .
$head1->title . "</h1>\n\n" .
$head1->content->present($self);
}
sub view_head2 {
my ($self, $head2) = @_;
my $pejl = $store_head1;
$count_head2++;
$store_head2 = $count_head2;
$count_head3 = 0; # reset next level counter
$anchor_head2 = $store_head1 . "_" . $store_head2;
return "<h2><a href=\"#$anchor_head1\">$store_head1</a>.$store_head2<a
name=\"$anchor_head2\"></a> " . $head2->title . "</h2>\n\n" .
$head2->content->present($self);
}
sub view_head3 {
my ($self, $head3) = @_;
my $pejl = $store_head2;
$count_head3++;
$store_head3 = $count_head3;
$count_head4 = 0; # reset next level counter
$anchor_head3 = $store_head1 . "_" . $store_head2 . "_" . $store_head3;
return "<h3><a href=\"#$anchor_head1\">$store_head1</a>.<a
href=\"#$anchor_head2\">$store_head2</a>.$store_head3<a
name=\"$anchor_head3\"></a> " . $head3->title . "</h3>\n\n" .
$head3->content->present($self);
}
sub view_head4 {
my ($self, $head4) = @_;
my $pejl = $store_head3;
$count_head4++;
$store_head4 = $count_head4;
$anchor_head4 = $store_head1 . "_" . $store_head2 . "_" . $store_head3 .
"_" . $store_head4;
return "<h4><a href=\"#$anchor_head1\">$store_head1</a>.<a
href=\"#$anchor_head2\">$store_head2</a>.<a
href=\"#$anchor_head2\">$store_head2</a>.$store_head4<a
name=\"$anchor_head4\"></a> " . $head4->title . "</h4>\n\n" .
$head4->content->present($self);
}
sub view_seq_file {
my ($self, $path) = @_;
my $doc_obj = get_render_obj();
my $base_dir = dirname catfile $doc_obj->{src_root}, $doc_obj->{src_uri};
my $file = catfile $base_dir, $path;
#warn "file: $file";
# XXX: may need to test the location at dest_path, not src, to
# make sure that the file actually gets copied
return -e $file ? qq{<a href="$path">$path</a>} : qq{<i>$path</i>};
}
*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;
#*view_seq_link = \&DocSet::Doc::Common::pod_pom_html_view_seq_link;
#use DocSet::Util;
## META: temp override
## the one in superclass screws up URLs in L<>: L<http://foo.bar.com>
## should view_seq_text be called at all on these parts?
#sub view_seq_text {
# my ($self, $text) = @_;
#dumper $self;
##print $self->[CMD];
# return $text;
#}
1;
__END__
=head1 NAME
C<DocSet::Doc::POD2HTML> - POD source to HTML target converter
=head1 SYNOPSIS
=head1 DESCRIPTION
Implements an C<DocSet::Doc> sub-class which converts a source
document in POD, into an output document in HTML.
=head1 METHODS
For the rest of the super class methods see C<DocSet::Doc>.
=over
=item * convert
=back
=head1 Rendering Class
documents using this class are rendered via
C<DocSet::Doc::POD2HTML::View::HTML>, which is a subclass of
C<Pod::POM::View::HTML>.
C<view_head{1-4}()> are overridden to add the E<lt>a nameE<gt> anchors
next to the headers for proper hyperlinking.
view_seq_file() is overriden too. Here we search for the file relative
to the location of the document and if we find it we link to it
otherwise the default behaviour applies (the file path is turned into
italics).
The following rendering methods: view_verbatim(), anchor() and
view_seq_link_transform_path() are defined in the
C<DocSet::Doc::Common> class and documented there.
=head1 AUTHORS
Stas Bekman E<lt>stas (at) stason.orgE<gt>
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
