Bug 316127: Implement an infrastructure to link to the documentation - Patch by…

Bugzilla/Config/Common.pm

@@ -195,6 +195,15 @@ sub check_urlbase {
     return "";
 }
 
+sub check_url {
+    my ($url) = (@_);
+    return '' if $url eq ''; # Allow empty URLs
+    if ($url !~ m:/$:) {
+        return 'must be a legal URL, absolute or relative, ending with a slash.';
+    }
+    return '';
+}
+
 sub check_webdotbase {
     my ($value) = (@_);
     $value = trim($value);

Bugzilla/Config/Core.pm

@@ -54,6 +54,13 @@ sub get_param_list {
   },
 
   {
+   name => 'docs_urlbase',
+   type => 't',
+   default => 'docs/html/',
+   checker => \&check_url
+  },
+
+  {
    name => 'sslbase',
    type => 't',
    default => '',

skins/standard/global.css

@@ -287,6 +287,17 @@ body
     }
 /* generic (end) */
 
+div#docslinks {
+    float: right;
+    border: 1px solid black;
+    padding: 1ex;
+    font-size: 80%;
+}
+
+#docslinks h2 {
+    margin: 0;
+}
+
 .bz_obsolete { text-decoration: line-through; }
 .bz_inactive { text-decoration: line-through; }
 .bz_closed,

template/en/default/account/auth/ldap-error.html.tmpl

@@ -27,6 +27,8 @@
 
 [% PROCESS global/variables.none.tmpl %]
 
+[% admindocslinks = {'extraconfig.html#bzldap' => 'Setting up LDAP authentication'} %]
+
 [% SWITCH auth_err_tag %]
   [% CASE "cannot_retreive_attr" %]
     The specified LDAP attribute [% info.attr FILTER html %] was not found.

template/en/default/admin/params/core.html.tmpl

@@ -32,6 +32,12 @@
   urlbase => "The URL that is the common initial leading part of all $terms.Bugzilla " _
              "URLs.",
 
+  docs_urlbase => "The URL that is the common initial leading part of all " _
+                  "$terms.Bugzilla documentation URLs. " _
+                  "It may be an absolute URL, or a URL relative to urlbase " _
+                  "above. " _
+                  "Leave this empty to suppress links to the documentation.",
+
   sslbase => "The URL that is the common initial leading part of all HTTPS " _
              "(SSL) $terms.Bugzilla URLs.",
 
@@ -65,4 +71,4 @@
   shutdownhtml => "If this field is non-empty, then $terms.Bugzilla will be completely " _
                   "disabled and this text will be displayed instead of all the " _
                   "$terms.Bugzilla pages." }
-%]
\ No newline at end of file
+%]

template/en/default/global/code-error.html.tmpl

@@ -39,6 +39,8 @@
 
 [% error_message = BLOCK %]
   [% IF    error == "action_unrecognized" %]
+    [% docslinks = {'query.html' => "Searching for $terms.bugs",
+                    'list.html'  => "$terms.Bug lists"} %]
     I don't recognize the value (<em>[% action FILTER html %]</em>)
     of the <em>action</em> variable.
   
@@ -70,6 +72,7 @@
     the error [% bug.error FILTER html %].
     
   [% ELSIF error == "chart_data_not_generated" %]
+    [% admindocslinks = {'extraconfig.html' => 'Setting up Charting'} %]
     [% IF product %]
       Charts for the <em>[% product FILTER html %]</em> product are not
       available yet because no charting data has been collected for it since it
@@ -93,6 +96,7 @@
     Unable to open the chart datafile <tt>[% filename FILTER html %]</tt>.
   
   [% ELSIF error == "chart_lines_not_installed" %]
+    [% admindocslinks = {'installation.html#install-perlmodules' => 'Installing perl modules necessary for Charting'} %]
     Charts will not work without the Chart::Lines Perl module being installed.
     Run checksetup.pl for installation instructions.
 
@@ -104,6 +108,7 @@
     and <code>[% type FILTER html %]</code> together.
 
   [% ELSIF error == "gd_not_installed" %]
+    [% admindocslinks = {'installation.html#install-perlmodules' => 'Installing perl modules necessary for Charting'} %]
     Charts will not work without the GD Perl module being installed.
     Run checksetup.pl for installation instructions.
 
@@ -344,6 +349,11 @@
   [% PROCESS global/header.html.tmpl %]
 [% END %]
 
+[% PROCESS global/docslinks.html.tmpl
+   docslinks      = docslinks
+   admindocslinks = admindocslinks
+%]
+
 <tt>
   <p>
     [% terms.Bugzilla %] has suffered an internal error. Please save this page and send

template/en/default/global/docslinks.html.tmpl

+[%# 1.0@bugzilla.org %]
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # Contributor(s): Marc Schumann <wurblzap@gmail.com>
+  #%]
+
+[%# INTERFACE:
+  # docslinks: hash. Hash keys will be used as text of the documentation links,
+  #            hash values will be used as links to the document, relative to
+  #            the main Bugzilla documentation directory.
+  #            Example: If you want a 'FAQ' link to point to, the "faq-general"
+  #            named anchor on faq.html, assign
+  #               { 'FAQ' => "faq.html#faq-general" }
+  #            to docslinks.
+  #            You may only link to sections by their given ID; it is not allowed
+  #            to link to a section which is not given an ID (thus getting
+  #            assigned an automatically generated ID). Otherwise, the link
+  #            would break on a recompilation of the documentation.
+  # admindocslinks: hash. Same as docslinks, but will only be displayed to
+  #                 members of the admin group.
+  #%]
+
+[% IF Param('docs_urlbase') &&
+      docslinks.keys.size || (admindocslinks.keys.size && user.in_group('admin')) %]
+  <div id="docslinks">
+    <h2>Related documentation</h2>
+    <ul>
+      [% IF user.in_group('admin') %]
+        [% PROCESS docslinkslist docstype = admindocslinks %]
+      [% END %]
+      [% PROCESS docslinkslist docstype = docslinks %]
+    </ul>
+  </div>
+[% END %]
+
+[% BLOCK docslinkslist %]
+  [% FOREACH docslink = docstype.keys %]
+    <li>
+      <a href="[% Param('docs_urlbase') %]
+               [% docslink FILTER none %]">[% docstype.$docslink FILTER html %]</a>
+    </li>
+  [% END %]
+[% END %]