[Rt-commit] rt branch, 4.4/static-docs-local-link-fixes, created. rt-4.4.2-100-g2098bcead

[? sunnavy]

The branch, 4.4/static-docs-local-link-fixes has been created
        at  2098bceadb4f1e34b2f93d21416bfb2a358d7158 (commit)

- Log -----------------------------------------------------------------
commit 4b011307279ba65fdb691e24024254b44b46859b
Author: sunnavy <sunnavy at bestpractical.com>
Date:   Tue Mar 20 21:56:33 2018 +0800

    Support arbitrary-depth local links starting with docs/
    
    So we can write links like L<docs/query_builder.pod>,
    L<docs/customizing/search_result_columns.pod> and even
    L<docs/customizing/search_result_columns.pod/Column Map Callback>

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 532c5ea51..d46e7ae0f 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -102,6 +102,28 @@ sub _end_head {
     return $self->SUPER::_end_head(@_);
 }
 
+sub handle_text {
+    my ( $self, $text ) = @_;
+    if ( $self->{in_pod} && $self->{scratch} =~ /<a .*href=".+".*>/ && $text =~ /^"(.+)" in docs$/ ) {
+
+        # Tweak default text for local links under docs/, so
+        # q{"customizing/search_result_columns.pod/Column Map" in docs} becomes
+        # q{"Column Map Callback" in customizing/search_result_columns.pod}
+        #
+        # q{"customizing/search_result_columns.pod" in docs} becomes
+        # q{docs/customizing/search_result_columns.pod}
+
+        my $section = $1;
+        if ( $section =~ qr!(.+\.pod)/(.+)! ) {
+            $text = qq{"$2" in docs/$1};
+        }
+        else {
+            $text = "docs/$section";
+        }
+    }
+    $self->SUPER::handle_text( $text );
+}
+
 sub resolve_pod_page_link {
     my $self = shift;
     my ($name, $section) = @_;
@@ -124,6 +146,20 @@ sub resolve_local_link {
 
     $name .= ""; # stringify name, it may be an object
 
+    if ( $name eq 'docs' ) {
+        if ( $section =~ qr!(.+\.pod)/(.+)! ) {
+
+            # support L<docs/writing_extensions.pod/Callbacks>
+            $name .= '/' . $1;
+            $section = $2;
+        }
+        else {
+            # support L<docs/dashboards_reporting.pod>
+            $name .= '/' . $section;
+            undef $section;
+        }
+    }
+
     $section = defined $section
         ? '#' . $self->idify($section, 1)
         : '';

commit 2098bceadb4f1e34b2f93d21416bfb2a358d7158
Author: sunnavy <sunnavy at bestpractical.com>
Date:   Wed Mar 21 00:05:49 2018 +0800

    Run batch_convert twice to make sure local links are linked correctly
    
    On parsing a link, we identify its local-ness by checking if we have the
    linked target parsed already. So if the target hasn't been parsed yet,
    the link will be treated as not-local. E.g.
    "L<writing_extensions/Callbacks>" in
    "docs/customizing/search_result_columns.pod":
    
    Since "docs/writing_extensions.pod" is parsed after
    "docs/customizing/search_result_columns.pod", the link
    "L<writing_extensions/Callbacks>" is converted to
    "../../rt/latest/writing_extensions#Callbacks" instead of the correct
    local version "writing_extensions#Callbacks"
    
    On the 2nd run of batch_convert, since all the local pods have been
    parsed, there is no such order issue any more.

diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 47842d972..942fa1f55 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -185,6 +185,9 @@ system_chmod("+x", $_) for <docs/UPGRADING*>;
 # Convert each POD file to HTML
 $converter->batch_convert( \@dirs, $opts{to} );
 
+# Run it again to make sure local links are linked correctly
+$converter->batch_convert( \@dirs, $opts{to} );
+
 # Remove execution bit from workaround above
 system_chmod("-x", $_) for <docs/UPGRADING*>;
 

-----------------------------------------------------------------------