Changeset 1638

Timestamp:

02/05/05 14:19:45 (4 years ago)

Author:

whmoseley

Message:

Update POD link generation.

TODO: think about a two-pass parsing to build up targets, then when generating links
can lookup targets. This is to solve the problem of multiple targets when a name
is used in both a =head and a =item line.

-v should now report broken links.

Files:

• trunk/swish_website/Plugin/My/POD.pm (modified) (12 diffs)
• trunk/swish_website/bin/build (modified) (3 diffs)

trunk/swish_website/Plugin/My/POD.pm

@@ -4 +4 @@
-use Pod::POM::View::HTML;
-use base 'Template::Plugin';
-
-
+
+
+
+
+
+
+
-
-my $view_mode = 'Pod::POM::View::HTML';  # The view module
@@ -27 +32 @@
-    my ( $class, $context, $content ) = @_;
-
-
-
-
-
+
+
-    my $template_name = $stash->get( 'template.name' );
-
+    # Enable output of debugging messages from Pod::POM
-    my $warn = sub { warn "[$template_name]: @_\n" }
-        if $stash->get( 'self.config.verbose' );
-
-
+
+
+
+
-    my $pom = $parser->parse_text( $content );
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
-    if ( @sections && $sections[0]->title =~ /NAME/ ) {
-
-
-
+
+
+
+
-
-
@@ -68 +68 @@
-    if ( my $cache = $stash->get( 'toc_cache' ) ) {
-        $cache->{ $template_name } = {
-page
-ata{title}
-$data{sections}
+stash->get( 'page.id' )
+oc_title
+\@sections
-        };
-    };
-
-
+    # Structure for returning info to template
+    # the "toc" is the table of contents for the top of the page
+    # the "podparts" is the document broken into sequential parts by
+    # =head*  This allows the template to wrap each section in a <div> and
+    # therefore makes indexing each section with swish-e easy -- allows targeted searches
+
+    my %data = (
+        pom         => $pom,
+        view        => 'My::Pod::View::HTML',
+        toc         => fetch_toc( @sections ),
+        podparts    => [ slice_by_head(@sections) ], # Must be lasts because modifies tree
+        title       => $doc_title,
+    );
+
+
+
-    return \%data;
-}
@@ -81 +97 @@
-
-#-----------------------------------------------------------------------------
+# This function is modified from Stas' DocSet
+# It flattens the recursive structure of the tree into a list of sections by =head
+#
+# Pass in:
+#   @sections = list of head1 sections
+#
+# Returns:
+#   flat list of sections for each headX section
+#
+# Note:
+#   This MODIFIES the original tree!  Should probably clone and build a new tree.
+#
+# This is useful for printing and wrapping each headX section in, say, <div>
-
-sub slice_by_head {
-
+  # these are the sections at the current level.
-    my @body = ();
+
-    for my $node (@sections) {
-        my @next = ();
-        # assumption, after the first 'headX' section, there can only
-        # be other 'headX' sections
-
+
+
+
+
-        my $id = -1;
-        for ($node->content) {
-            $id++;
-
+
+
+
+
+
+
-            @next = splice @{$node->content}, $id;
-            last;
-        }
+
+        # combine all =head nodes (flatten)
-        push @body, $node, slice_by_head(@next);
-    }
-    return @body;
-}
+
+#---------------------------------------------------------------------------
+# Merge verbatim sequential <pre> sections together
-
-sub combine_verbatim_sections_hack {
@@ -124 +167 @@
-
-
+
+#----------------------------------------------------------------------------
+# Grabs the first paragraph from either DESCRIPTION or OVERVIEW -- whichever comes first
+
+
-sub fetch_abstract {
-    my ( $sections ) = @_;
@@ -136 +184 @@
-
-
+#---------------------------------------------------------------------------------
+# Walk tree building up a TOC
+
-sub fetch_toc {
-$
+@
-
-    my @toc = ();
-    my $level = 1;
-$
+
-        push @toc, render_toc_level($node, $level);
-    }
@@ -151 +202 @@
-sub render_toc_level {
-    my( $node, $level) = @_;
-
+->present($view_mode)
-    my $anchor = My::Pod::View::HTML->escape_name( $title );
-
-    my %toc_entry = (
-->present($view_mode), # run the formatting if any
+,
-        link     => "#$anchor",
-    );
@@ -173 +224 @@
-}
-
+
+
+#---------------- Package to override Pod::POM::View::HTML ----------------
+
-package My::Pod::View::HTML;
-use strict;
-use warnings;
-use base 'Pod::POM::View::HTML';
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-sub anchor {
-    my($self, $title) = @_;
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-    my ($self, $text) = @_;
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
-
-# Thes first two fixup L<> links.
-# Pod::POM doesn't provide a way to get at the fragment for escaping,
-do it the hard way here.
+let Pod::POM deal with it and then then update
-
-sub view_seq_link {
@@ -231 +351 @@
-    my $url = $self->SUPER::view_seq_link( @_ );
-    return unless $url;
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
-    return $url;
-}
-
-
-converts the file name part.  Can't call esacpe_name(), so do uri
-escape -- but that will not validate with xhtml in some cases.  So this i
-
+
+allows fixing up links to *other* pages.  In our case, they are mostly to
+other pod pages, which are now lower case and end in .html.
+
-
-sub view_seq_link_transform_path {
-    my ( $self, $link ) = @_;
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
-
-# Modified version of item display that removes the item_ prefix and only takes the first
@@ -276 +386 @@
-#
-# so we take only the first word.  But that breaks if linking to multi-word item.
+#
-
-sub view_item {
@@ -291 +402 @@
-            $anchor =~ s/\s+.*$//;  # strip all trailing stuff from first space on
-            $anchor = $self->escape_name( $anchor );
+
+            $self->save_target( $anchor );
-            $title = qq{<a name="$anchor"></a><b>$title</b>};
-        }
@@ -302 +415 @@
-
-
+package My::pod;
+use strict;
+use warnings;
+
+sub test {
+
+    # From perldoc perlpod:
+    #
+    my @l_tests = (
+        { 
+            in  => ['L<name>'],
+            out => '<a href="name.html">name</a>',
+        },
+
+        {
+            in  => [ 'L<name/"section here">', 'L<name/section here>', ],
+            out => '<a href="name.html#section_here">section here</a>',
+        },
+
+        {
+            in  => ['L</"section here">', 'L</section here>', 'L<"section here">', ],
+            out => '<a href="#section_here">section here</a>',
+        },
+
+
+
+        {   in  => ['L<text here|name>'],
+            out => '<a href="name.html">text here</a>',
+        },
+
+        {
+            in  => ['L<text|name/"sec here">', 'L<text|name/sec here>'],
+            out => '<a href="name.html#sec_here">text</a>',
+        },
+
+        {
+            in  => ['L<text|/"sec">',  'L<text|/sec>', 'L<text|"sec">'],
+            out => '<a href="#sec">text</a>',
+        },
+
+        {
+            in  => ['L<http://host.name/some/path.html#fragment>'],
+            out => '<a href="http://host.name/some/path.html#fragment">http://host.name/some/path.html#fragment</a>',
+        },
+
+        {
+            in => ['L<Link to $foo-E<gt> with & "quotes" and %funny !!? chars>'],
+            out => '<a href="#link_to_foo_with_quotes_and_funny_chars">Link to $foo-&gt; with &amp; "quotes" and %funny !!? chars</a>',
+        },
+        {
+            in => ['L<Some & text|/Link to $foo-E<gt> with & "quotes" and %funny !!? chars>'],
+            out => '<a href="#link_to_foo_with_quotes_and_funny_chars">Some &amp; text</a>',
+        },
+        {
+            in => ['L<SWISH-RUN|SWISH-RUN>'],
+            out => '<a href="swish-run.html">SWISH-RUN</a>',
+        }
+    );
+
+
+    for my $test ( @l_tests ) {
+        for my $input ( @{$test->{in}} ) {
+
+            my $pod = Pod::POM->new( warn => 1 )->parse_text( "=head1 Title\n\n$input" );
+            my $out = My::Pod::Test::HTML->print( $pod );
+
+            warn "input  [$input]\n",
+                 "output [$out]\n",
+                 "test   [$test->{out}]\n\n"
+                        if $out ne $test->{out} || $ENV{VERBOSE};
+        }
+    }
+}
+
+package My::Pod::Test::HTML;
+use strict;
+use warnings;
+use base 'My::Pod::View::HTML';
+
+sub view_textblock {
+    my ($self, $text) = @_;
+    return $text;
+}
+
+sub view_pod {
+    my ($self, $pod) = @_;
+    return $pod->content->present($self);
+}
+
+sub view_head1 {
+    my ($self, $pod) = @_;
+    return $pod->content->present($self);
+}
+
+
-1;
-

trunk/swish_website/bin/build

@@ -407 +407 @@
-    # Create sub-cache for this source, if doesn't exist
-    # When processing a pod file the POD plugin will update its own cache entry
-
-
-key
+  Cache by source directory
+
+src_dir
-
-
@@ -458 +458 @@
-                abslinks    => $abslinks,
-                swish_version => $version,
+                out_file    => $out_file,
-            },
-            mode        => 0644,
@@ -478 +479 @@
-
-    shift @$include_path;  # remove source dir.
+
+    # Check all the L<> links
+    My::Pod::View::HTML::validate_links()
+        if $update_index and $config->verbose;
-}
-