#197730 by keith.smith: standardize on a much more user friendly cron...

#197730 by keith.smith: standardize on a much more user friendly cron reference in help texts, explain its importance with more examples in INSTALL.txt

INSTALL.txt

@@ -177,12 +177,16 @@ INSTALLATION
    on an existing site, remember to copy all files from the original location
    to the new location.
 
-8. CRON TASKS
+8. CRON MAINTENANCE TASKS
 
-   Many Drupal modules (such as the search functionality) have periodic tasks
-   that must be triggered by a cron job. To activate these tasks, call the cron
-   page by visiting http://www.example.com/cron.php --this will pass control to
-   the modules and the modules will decide if and what they must do.
+   Many Drupal modules have periodic tasks that must be triggered by a cron 
+   maintenance task, including search module (to build and update the index 
+   used for keyword searching), aggregator module (to retrieve feeds from other
+   sites), ping module (to notify other sites about new or updated content), and
+   system module (to perform routine maintenance and pruning on system tables).
+   To activate these tasks, call the cron page by visiting 
+   http://www.example.com/cron.php, which, in turn, executes tasks on behalf
+   of installed modules.
 
    Most systems support the crontab utility for scheduling tasks like this. The
    following example crontab line will activate the cron tasks automatically on
@@ -190,9 +194,9 @@ INSTALLATION
 
    0   *   *   *   *   wget -O - -q -t 1 http://www.example.com/cron.php
 
-   More information about the cron scripts are available in the admin help pages
-   and in the Drupal handbook at drupal.org. Example scripts can be found in the
-   scripts/ directory.
+   More information about cron maintenance tasks are available in the help pages
+   and in Drupal's online handbook at http://drupal.org/cron. Example scripts can
+   be found in the scripts/ directory.
 
 DRUPAL ADMINISTRATION
 ---------------------

modules/aggregator/aggregator.admin.inc

@@ -77,7 +77,7 @@ function aggregator_form_feed(&$form_state, $edit = array('refresh' => 900, 'tit
     '#title' => t('Update interval'),
     '#default_value' => $edit['refresh'],
     '#options' => $period,
-    '#description' => t('The length of time between feed updates. (Requires a correctly configured <a href="@cron">Cron maintenance task</a>.)', array('@cron' => url('admin/reports/status'))),
+    '#description' => t('The length of time between feed updates. (Requires a correctly configured <a href="@cron">cron maintenance task</a>.)', array('@cron' => url('admin/reports/status'))),
   );
 
   // Handling of categories:
@@ -223,7 +223,7 @@ function aggregator_admin_settings() {
   $form['aggregator_clear'] = array(
     '#type' => 'select', '#title' => t('Discard items older than'),
     '#default_value' => variable_get('aggregator_clear', 9676800), '#options' => $period,
-    '#description' => t('The length of time to retain feed items before discarding. (Requires a correctly configured <a href="@cron">Cron maintenance task</a>.)', array('@cron' => url('admin/reports/status')))
+    '#description' => t('The length of time to retain feed items before discarding. (Requires a correctly configured <a href="@cron">cron maintenance task</a>.)', array('@cron' => url('admin/reports/status')))
   );
 
   $form['aggregator_category_selector'] = array(

modules/aggregator/aggregator.module

@@ -13,7 +13,7 @@ function aggregator_help($path, $arg) {
   switch ($path) {
     case 'admin/help#aggregator':
       $output = '<p>'. t('The aggregator is a powerful on-site syndicator and news reader that gathers fresh content from RSS-, RDF-, and Atom-based feeds made available across the web. Thousands of sites (particularly news sites and blogs) publish their latest headlines and posts in feeds, using a number of standardized XML-based formats. Formats supported by the aggregator include <a href="@rss">RSS</a>, <a href="@rdf">RDF</a>, and <a href="@atom">Atom</a>.', array('@rss' => 'http://blogs.law.harvard.edu/tech/rss', '@rdf' => 'http://www.w3.org/RDF/', '@atom' => 'http://www.atomenabled.org')) .'</p>';
-      $output .= '<p>'. t('Feeds contain feed items, or individual posts published by the site providing the feed. Feeds may be grouped in categories, generally by topic. Users view feed items in the <a href="@aggregator">main aggregator display</a> or by <a href="@aggregator-sources">their source</a>. Administrators can <a href="@feededit">add, edit and delete feeds</a> and choose how often to check each feed for newly updated items. The most recent items in either a feed or category can be displayed as a block through the <a href="@admin-block">block administration page</a>. A <a href="@aggregator-opml">machine-readable OPML file</a> of all feeds is available. A correctly configured <a href="@cron">Cron maintenance task</a> is required to update feeds automatically.', array('@aggregator' => url('aggregator'), '@aggregator-sources' => url('aggregator/sources'), '@feededit' => url('admin/content/aggregator'), '@admin-block' => url('admin/build/block'), '@aggregator-opml' => url('aggregator/opml'), '@cron' => url('admin/reports/status'))) .'</p>';
+      $output .= '<p>'. t('Feeds contain feed items, or individual posts published by the site providing the feed. Feeds may be grouped in categories, generally by topic. Users view feed items in the <a href="@aggregator">main aggregator display</a> or by <a href="@aggregator-sources">their source</a>. Administrators can <a href="@feededit">add, edit and delete feeds</a> and choose how often to check each feed for newly updated items. The most recent items in either a feed or category can be displayed as a block through the <a href="@admin-block">block administration page</a>. A <a href="@aggregator-opml">machine-readable OPML file</a> of all feeds is available. A correctly configured <a href="@cron">cron maintenance task</a> is required to update feeds automatically.', array('@aggregator' => url('aggregator'), '@aggregator-sources' => url('aggregator/sources'), '@feededit' => url('admin/content/aggregator'), '@admin-block' => url('admin/build/block'), '@aggregator-opml' => url('aggregator/opml'), '@cron' => url('admin/reports/status'))) .'</p>';
       $output .= '<p>'. t('For more information, see the online handbook entry for <a href="@aggregator">Aggregator module</a>.', array('@aggregator' => 'http://drupal.org/handbook/modules/aggregator/')) .'</p>';
       return $output;
     case 'admin/content/aggregator':

modules/dblog/dblog.admin.inc

@@ -18,7 +18,7 @@ function dblog_admin_settings() {
     '#title' => t('Discard log entries above the following row limit'),
     '#default_value' => variable_get('dblog_row_limit', 1000),
     '#options' => drupal_map_assoc(array(100, 1000, 10000, 100000, 1000000)),
-    '#description' => t('The maximum number of rows to keep in the database log. Older entries will be automatically discarded. Requires crontab.')
+    '#description' => t('The maximum number of rows to keep in the database log. Older entries will be automatically discarded. (Requires a correctly configured <a href="@cron">cron maintenance task</a>.)', array('@cron' => url('admin/reports/status')))
   );
 
   return system_settings_form($form);

modules/ping/ping.module

@@ -13,7 +13,7 @@ function ping_help($path, $arg) {
   switch ($path) {
     case 'admin/help#ping':
       $output = '<p>'. t('The ping module is useful for notifying interested sites that your site has changed. It automatically sends notifications, or "pings", to the <a href="@external-http-pingomatic-com">pingomatic</a> service about new or updated content. In turn, <a href="@external-http-pingomatic-com">pingomatic</a> notifies other popular services, including weblogs.com, Technorati, blo.gs, BlogRolling, Feedster.com, and Moreover.', array('@external-http-pingomatic-com' => 'http://pingomatic.com/')) .'</p>';
-      $output .= '<p>'. t('The ping module requires <code>cron</code> or a similar periodic job scheduler to be enabled.') .'</p>';
+      $output .= '<p>'. t('The ping module requires a correctly configured <a href="@cron">cron maintenance task</a>.', array('@cron' => url('admin/reports/status'))) .'</p>';
       $output .= '<p>'. t('For more information, see the online handbook entry for <a href="@ping">Ping module</a>.', array('@ping' => 'http://drupal.org/handbook/modules/ping/')) .'</p>';
       return $output;
   }

modules/search/search.admin.inc

@@ -55,7 +55,7 @@ function search_admin_settings() {
 
   // Indexing throttle:
   $form['indexing_throttle'] = array('#type' => 'fieldset', '#title' => t('Indexing throttle'));
-  $form['indexing_throttle']['search_cron_limit'] = array('#type' => 'select', '#title' => t('Items to index per cron run'), '#default_value' => variable_get('search_cron_limit', 100), '#options' => $items, '#description' => t('The maximum amount of items that will be indexed in one cron run. Set this number lower if your cron is timing out or if PHP is running out of memory.'));
+  $form['indexing_throttle']['search_cron_limit'] = array('#type' => 'select', '#title' => t('Number of items to index per cron run'), '#default_value' => variable_get('search_cron_limit', 100), '#options' => $items, '#description' => t('The maximum number of items indexed in each pass of a <a href="@cron">cron maintenance task</a>. If necessary, reduce the number of items to prevent timeouts and memory errors while indexing.', array('@cron' => url('admin/reports/status'))));
   // Indexing settings:
   $form['indexing_settings'] = array('#type' => 'fieldset', '#title' => t('Indexing settings'));
   $form['indexing_settings']['info'] = array('#value' => t('<p><em>Changing the settings below will cause the site index to be rebuilt. The search index is not cleared but systematically updated to reflect the new settings. Searching will continue to work but new content won\'t be indexed until all existing content has been re-indexed.</em></p><p><em>The default settings should be appropriate for the majority of sites.</em></p>'));
@@ -82,4 +82,4 @@ function search_admin_settings_validate($form, &$form_state) {
     drupal_set_message(t('The index will be rebuilt.'));
     search_wipe();
   }
-}
\ No newline at end of file
+}

modules/search/search.module

@@ -97,7 +97,7 @@ function search_help($path, $arg) {
   switch ($path) {
     case 'admin/help#search':
       $output = '<p>'. t('The search module adds the ability to search for content by keywords. Search is often the only practical way to find content on a large site, and is useful for finding both users and posts.') .'</p>';
-      $output .= '<p>'. t('To provide keyword searching, the search engine maintains an index of words found in your site\'s content. To build and maintain this index, a correctly configured <a href="@cron">cron maintenance task</a> is required. Indexing behavior can be adjusted using the <a href="@searchsettings">search settings page</a>; for example, the <em>Items to index per cron run</em> sets the maximum number of items indexed in a single cron run. If necessary, reduce this number to prevent timeouts and memory errors when indexing.', array('@cron' => url('admin/reports/status'), '@searchsettings' => url('admin/settings/search'))) .'</p>';
+      $output .= '<p>'. t('To provide keyword searching, the search engine maintains an index of words found in your site\'s content. To build and maintain this index, a correctly configured <a href="@cron">cron maintenance task</a> is required. Indexing behavior can be adjusted using the <a href="@searchsettings">search settings page</a>; for example, the <em>Number of items to index per cron run</em> sets the maximum number of items indexed in each pass of a <a href="@cron">cron maintenance task</a>. If necessary, reduce this number to prevent timeouts and memory errors when indexing.', array('@cron' => url('admin/reports/status'), '@searchsettings' => url('admin/settings/search'))) .'</p>';
       $output .= '<p>'. t('For more information, see the online handbook entry for <a href="@search">Search module</a>.', array('@search' => 'http://drupal.org/handbook/modules/search/')) .'</p>';
       return $output;
     case 'admin/settings/search':

modules/statistics/statistics.admin.inc

@@ -197,7 +197,7 @@ function statistics_access_logging_settings() {
     '#title' => t('Discard access logs older than'),
     '#default_value'   => variable_get('statistics_flush_accesslog_timer', 259200),
     '#options' => $period,
-    '#description' => t('Older access log entries (including referrer statistics) will be automatically discarded. Requires crontab.'));
+    '#description' => t('Older access log entries (including referrer statistics) will be automatically discarded. (Requires a correctly configured <a href="@cron">cron maintenance task</a>.)', array('@cron' => url('admin/reports/status'))));
 
   // count content views settings
   $form['content'] = array(

modules/system/system.install

@@ -101,7 +101,7 @@ function system_requirements($phase) {
     // Cron error threshold defaults to two weeks.
     $threshold_error = variable_get('cron_threshold_error', 1209600);
     // Cron configuration help text.
-    $help = $t('Please check the help pages for <a href="@url">configuring cron jobs</a>.', array('@url' => 'http://drupal.org/cron'));
+    $help = $t('For more information, see the online handbook entry for <a href="@cron-handbook">configuring cron jobs</a>.', array('@cron-handbook' => 'http://drupal.org/cron'));
 
     // Determine when cron last ran. If never, use the install time to
     // determine the warning or error status.

modules/trigger/trigger.module

@@ -18,7 +18,7 @@ function trigger_help($path, $arg) {
     case 'admin/build/trigger/node':
       return $explanation .'<p>'. t('Below you can assign actions to run when certain content-related triggers happen. For example, you could remove a post from the front page when the post is updated.') .'</p>';
     case 'admin/build/trigger/cron':
-      return $explanation .'<p>'. t('Below you can assign actions to run when cron runs. More information on cron is available in the <a href="@system">System module help page</a>.', array('@system' => url('admin/help/system'))) .'</p>';
+      return $explanation .'<p>'. t('Below you can assign actions to run during each pass of a <a href="@cron">cron maintenance task</a>.', array('@cron' => url('admin/reports/status'))) .'</p>';
     case 'admin/build/trigger/taxonomy':
       return $explanation .'<p>'. t('Below you can assign actions to run when certain taxonomy-related triggers happen. For example, you could send an e-mail to an administrator when a term is deleted.') .'</p>';
     case 'admin/build/trigger/user':