Bug 529201: Add help for every single field to fields.html

Bugzilla/Field.pm

@@ -547,6 +547,24 @@ sub legal_values {
 
 =over
 
+=item C<is_timetracking>
+
+True if this is a time-tracking field that should only be shown to users
+in the C<timetrackinggroup>.
+
+=back
+
+=cut
+
+sub is_timetracking {
+    my ($self) = @_;
+    return grep($_ eq $self->name, TIMETRACKING_FIELDS) ? 1 : 0;
+}
+
+=pod
+
+=over
+
 =item C<visibility_field>
 
 What field controls this field's visibility? Returns a C<Bugzilla::Field>

page.cgi

@@ -43,7 +43,7 @@ use Bugzilla::Search::Quicksearch;
 
 # For quicksearch.html.
 sub quicksearch_field_names {
-    my $fields = Bugzilla::Search::Quicksearch::FIELD_MAP;
+    my $fields = Bugzilla::Search::Quicksearch->FIELD_MAP;
     my %fields_reverse;
     # Put longer names before shorter names.
     my @nicknames = sort { length($b) <=> length($a) } (keys %$fields);

skins/standard/page.css

@@ -68,3 +68,36 @@
     width: 10em;
 }
 
+/***************/
+/* fields.html */
+/***************/
+
+table.field_value_explanation {
+  table-layout: fixed;
+  border-collapse: collapse;
+}
+
+.field_value_explanation thead h2 {
+  margin: 0;
+}
+
+.field_value_explanation .header_row td {
+  text-align: center;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+.field_value_explanation tbody td {
+  border: 1px solid black;
+  padding: 1em;
+}
+
+.field_value_explanation dt,
+.field_descriptions dt
+{
+  margin-top: 1em;
+}
+
+.field_descriptions dt {
+  font-size: 120%;
+}

template/en/default/bug/field-help.none.tmpl

+[%# 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.
+  #
+  # The Initial Developer of the Original Code is Netscape Communications
+  # Corporation. Portions created by Netscape are
+  # Copyright (C) 1998 Netscape Communications Corporation. All
+  # Rights Reserved.
+  #
+  # Contributor(s): Gervase Markham <gerv@gerv.net>
+  #                 Max Kanat-Alexander <mkanat@bugzilla.org>
+  #%]
+
+[%# This file describes both bug fields and search fields. %]
+
+[% PROCESS "global/field-descs.none.tmpl" %]
+
+[% help_html = {
+
+# Note that all these keys here are in alphabetical order, though
+# search-specific fields are at the bottom.
+
+##############
+# Bug Fields #
+##############
+
+alias =>
+  "A short, unique name assigned to $terms.abug in order to assist with
+   looking it up and referring to it in other places in ${terms.Bugzilla}.",
+
+assigned_to =>
+  "The person in charge of resolving the ${terms.bug}.",
+
+blocked =>
+  "This $terms.bug must be resolved before the $terms.bugs listed in this
+   field can be resolved.",
+
+bug_file_loc =>
+  "$terms.Bugs can have a URL associated with them - for example, a"
+  _ " pointer to a web site where the problem is seen.",
+
+bug_id =>
+  "The numeric id of $terms.abug, unique within this entire installation"
+  _ " of ${terms.Bugzilla}.",
+
+bug_severity =>
+  "How severe the $terms.bug is, or whether it's an enhancement.",
+
+bug_status =>
+  "$terms.Abug may be in any of a number of states.",
+
+cc =>
+  "Users who may not have a direct role to play on this $terms.bug, but who
+   are interested in its progress.",
+
+classification => 
+  "$terms.Bugs are categorised into Classifications, Products and"
+  _ " Components. classifications is the top-level categorisation.",   
+
+component => 
+  "Components are second-level categories; each belongs to a"
+  _ " particular Product. Select a Product to narrow down this list.",
+
+creation_ts =>
+  "When the $terms.bug was filed.",
+
+deadline =>
+  "The date that this $terms.bug must be resolved by, entered in YYYY-MM-DD
+   format.",
+
+delta_ts =>
+  "When this $terms.bug was last updated.",
+
+dependson =>
+  "The $terms.bugs listed here must be resolved before this $terms.bug
+   can be resolved.",
+
+estimated_time =>
+  "The amount of time that has been estimated it will take to resolve
+   this ${terms.bug}.",
+
+keywords =>
+   "You can add keywords from a defined list to $terms.bugs, in order"
+   _ " to tag and group them.",
+
+longdesc =>
+  "$terms.Bugs have comments added to them by $terms.Bugzilla users."
+  _ "You can search for some text in those comments.",
+
+op_sys =>
+  "The operating system the $terms.bug was observed on.",
+
+percentage_complete =>
+  "How close to 100% done this $terms.bug is, by comparing its
+   $field_descs.work_time to its ${field_descs.estimated_time}.",
+
+priority =>
+  "Engineers prioritize their $terms.bugs using this field.",
+
+# Note that this has extra text added below if useclassification is on.
+product =>
+  "$terms.Bugs are categorised into Products and Components.",
+
+qa_contact =>
+  "The person responsible for confirming this $terms.bug if it is"
+  _ " unconfirmed, and for verifying the fix once the $terms.bug"
+  _ " has been resolved.",
+
+remaining_time =>
+  "The number of hours of work left on this $terms.bug, calculated by
+   subtracting the $field_descs.work_time from the 
+   ${field_descs.estimated_time}.",
+
+rep_platform => 
+  "The hardware platform the $terms.bug was observed on.",
+
+reporter =>
+  "The person who filed this ${terms.bug}.",
+
+resolution =>
+  "If $terms.abug is in a resolved state, then one of these reasons"
+  _ " will be given for its resolution.",
+
+see_also =>
+  "This allows you to refer to $terms.bugs in other installations.
+   You can enter a URL to $terms.abug in the 'Add $terms.Bug URLs'
+   field to note that that $terms.bug is related to this one. You can
+   enter multiple URLs at once by separating them with a comma.
+
+   <p>You should normally use this field to refer to $terms.bugs in
+     <em>other</em> installations. For $terms.bugs in this
+     installation, it is better to use the $field_descs.dependson and 
+     $field_descs.blocked fields.</p>",
+
+short_desc =>
+  "The $terms.bug summary is a short sentence which succinctly"
+  _ " describes what the $terms.bug is about.",
+
+status_whiteboard =>
+  "Each $terms.bug has a free-form single line text entry box for"
+  _ " adding tags and status information.",
+
+target_milestone =>
+   "The target_milestone field is used to define when the engineer"
+   _ " the $terms.bug is assigned to expects to fix it.",
+
+version =>
+  "The version field defines the version of the software the"
+  _ " $terms.bug was found in.",
+
+votes =>
+  "Some $terms.bugs can be voted for, and you can limit your search to"
+  _ " $terms.bugs with more than a certain number of votes.",
+
+work_time =>
+  "The total amount of time spent on this $terms.bug so far.",
+
+##########################
+# Search-specific fields #
+##########################
+
+chfield =>
+  "You can search for specific types of change - this field defines"
+  _" which field you are interested in changes for.",
+
+# Duplicated to chfieldto below, also.
+chfieldfrom =>
+  "Specify the start and end dates either in YYYY-MM-DD format
+   optionally followed by HH:mm, in 24 hour clock), or in relative
+   dates such as 1h, 2d, 3w, 4m, 5y, which respectively mean one hour,
+   two days, three weeks, four months, or five years ago. 0d is last
+   midnight, and 0h, 0w, 0m, 0y is the beginning of this hour, week,
+   month, or year.",
+
+chfieldvalue =>
+  "The value the field defined above changed to during that time.",
+
+content =>
+  "This is a field available in searches that does a Google-like
+   'full-text' search on the $field_descs.short_desc and
+   $field_descs.longdesc fields.",
+
+# Duplicated to email2 below, also.
+email1 =>
+  "Every $terms.bug has people associated with it in different"
+  _ " roles. Here, you can search on what people are in what role.",
+
+} %]
+
+[% help_html.email2 = help_html.email1 %]
+[% help_html.chfieldto = help_html.chfieldfrom %]
+[% help_html.deadlinefrom = help_html.deadline %]
+[% help_html.deadlineto = help_html.deadline %]
+
+[% help_all_note = BLOCK %]
+  <strong>Note:</strong> When searching, selecting the option "All"
+  only finds [% terms.bugs %] whose value for this field is literally
+  the word "All".
+[% END %]
+[% FOREACH all_field = ['op_sys', 'rep_platform'] %]
+  [% help_html.$all_field = help_html.$all_field _ ' ' _ help_all_note %]
+[% END %]
+
+[% IF Param('useclassification') %]
+  [% help_html.product = help_html.product 
+      _ " Select a Classification to narrow down this list." %]
+[% END %]
+
+[% FOREACH help_field = bug_fields.keys %]
+  [% type_desc = BLOCK %]
+    The type of [% field_descs.${help_field} FILTER html %] search you 
+    would like.
+  [% END %]
+  [% SET type_name = help_field _ '_type' %]
+  [% help_html.$type_name = type_desc %]
+[% END %]

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

@@ -23,8 +23,9 @@
 
 [% IF cgi.param("help") %]
   <script type="text/javascript"> <!--
-    [% FOREACH h = help_html %]
-      g_helpTexts["[% h.id FILTER js %]"] = "[%- h.html FILTER js -%]";
+    [% FOREACH help_name = help_html.keys %]
+      g_helpTexts["[% help_name FILTER js %]"] = 
+        "[%- help_html.$help_name FILTER js -%]";
     [% END %]
     // -->
   </script>

template/en/default/search/search-advanced.html.tmpl

@@ -55,7 +55,7 @@ var queryform = "queryform"
 [% IF NOT cgi.param("help") %]
   document.write("<p><a href='query.cgi?help=1&amp;format=advanced'>Give me some help<\/a> (reloads page).<\/p>");
 [% ELSE %]
-  [% PROCESS "search/search-help.html.tmpl" %]
+  [% PROCESS "bug/field-help.none.tmpl" %]
   if (generateHelp())
     document.write("<p>For help, mouse over the page elements.<\/p>");
   else

template/en/default/search/search-help.html.tmpl

-[%# 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.
-  #
-  # The Initial Developer of the Original Code is Netscape Communications
-  # Corporation. Portions created by Netscape are
-  # Copyright (C) 1998 Netscape Communications Corporation. All
-  # Rights Reserved.
-  #
-  # Contributor(s): Gervase Markham <gerv@gerv.net>
-  #%]
-  
-[% help_html = [ 
-{ id => "short_desc_type", 
-  html => "The type of summary search you would like" },   
-{ id => "short_desc", 
-  html => "The $terms.bug summary is a short sentence which succinctly  
-           describes <br> what the $terms.bug is about." },   
-{ id => "classification", 
-  html => "$terms.Bugs are categorised into Classifications, Products and Components. classifications is the<br>
-           top-level categorisation." },   
-{ id => "product", 
-  html => Param('useclassification') ?
-       "$terms.Bugs are categorised into Products and Components. Select a Classification to narrow down this list" :
-       "$terms.Bugs are categorised into Products and Components. Product is 
-           the<br>top-level categorisation." },   
-{ id => "component", 
-  html => "Components are second-level categories; each belongs to a<br> 
-           particular Product. Select a Product to narrow down this list." },   
-{ id => "version", 
-  html => "The version field defines the version of the software the 
-           $terms.bug<br>was found in." },   
-{ id => "target_milestone", 
-  html => "The target_milestone field is used to define when the engineer<br>
-           the $terms.bug is assigned to expects to fix it." },   
-{ id => "longdesc",
-  html => "$terms.Bugs have comments added to them by $terms.Bugzilla users.  
-           You can<br>search for some text in those comments." },   
-{ id => "longdesc_type",
-  html => "The type of comment search you would like" },   
-{ id => "bug_file_loc", 
-  html => "$terms.Bugs can have a URL associated with them - for example, a 
-           pointer<br>to a web site where the problem is seen." },   
-{ id => "bug_file_loc_type", 
-  html => "The type of URL search you would like" },   
-{ id => "status_whiteboard", 
-  html => "Each $terms.bug has a free-form single line text entry box for 
-           adding<br>tags and status information." },   
-{ id => "status_whiteboard_type", 
-  html => "The type of whiteboard search you would like" },   
-{ id => "keywords", 
-  html => "You can add keywords from a defined list to $terms.bugs, in order 
-           to<br>tag and group them." },   
-{ id => "keywords_type", 
-  html => "The type of keyword search you would like" },   
-{ id => "bug_status", 
-  html => "$terms.Abug may be in any of a number of states." },
-{ id => "resolution", 
-  html => "If $terms.abug is in a resolved state, then one of these reasons
-           will<br>be given for its resolution." },   
-{ id => "bug_severity", 
-  html => "How severe the $terms.bug is, or whether it's an enhancement." },   
-{ id => "priority", 
-  html => "Engineers prioritize their $terms.bugs using this field." },   
-{ id => "rep_platform", 
-  html => "The hardware platform the $terms.bug was observed on." },   
-{ id => "op_sys", 
-  html => "The operating system the $terms.bug was observed on." },   
-{ id => "email1", 
-  html => "Every $terms.bug has people associated with it in different 
-           roles.<br>Here, you can search on what people are in what role." },
-{ id => "email2", 
-  html => "Every $terms.bug has people associated with it in different 
-           roles.<br>Here, you can search on what people are in what role." },
-{ id => "bug_id", 
-  html => "You can limit your search to a specific set of $terms.bugs ." },   
-{ id => "chfield", 
-  html => "You can search for specific types of change - this field define <br>
-           which field you are interested in changes for." },   
-{ id => "chfieldfrom", 
-  html => "Specify the start and end dates either in YYYY-MM-DD format<br>
-           (optionally followed by HH:mm, in 24 hour clock), or in relative<br>
-           dates such as 1h, 2d, 3w, 4m, 5y, which respectively mean one hour,<br>
-           two days, three weeks, four months, or five years ago. 0d is last<br>
-           midnight, and 0h, 0w, 0m, 0y is the beginning of this hour, week,<br>
-           month, or year." },
-{ id => "chfieldto", 
-  html => "Specify the start and end dates either in YYYY-MM-DD format<br>
-           (optionally followed by HH:mm, in 24 hour clock), or in relative<br>
-           dates such as 1h, 2d, 3w, 4m, 5y, which respectively mean one hour,<br>
-           two days, three weeks, four months, or five years ago. 0d is last<br>
-           midnight, and 0h, 0w, 0m, 0y is the beginning of this hour, week,<br>
-           month, or year." },
-{ id => "chfieldvalue", 
-  html => "The value the field defined above changed to during that time." },   
-] %]