#53870, better help text for menu.module, patch by dww

2 files changed, 30 insertions, 34 deletions

diff --git a/modules/menu.module b/modules/menu.module
index c36e68798..28aac9898 100644
--- a/modules/menu.module
+++ b/modules/menu.module
@@ -12,21 +12,21 @@
 function menu_help($section) {
   switch ($section) {
     case 'admin/help#menu':
-      $output = t('<p>The menu module allows for customization of the menus. Menus are useful for providing navigation in your site. The main menu for navigation is called the "navigation" menu. Menus appear in blocks on your site.</p>
-<p>There is a special case for the display of "primary links" and "secondary links" (which are implemented as menus). These are sets of links which are usually displayed in the header of each page (depending on the currently active theme). Any menu can serve as the primary or secondary links, by modifying the settings for the menu module.</p>
+      $output = t('<p>Menus are a collection of links (menu items) used to navigate a website. The menu module provides an interface to control and customize the powerful menu system that comes with Drupal.  Menus are primarily displayed as a hierarchical list of links using Drupal\'s highly flexible <a href="%admin-block">blocks</a> feature. Each menu automatically creates a block of the same name. By default, new menu items are placed inside a built-in menu labelled %navigation, but administrators can also create custom menus.</p>
+<p>Drupal themes generally provide out-of-the-box support for two menus commonly labelled %primary-links and %secondary-links. These are sets of links which are usually displayed in the header or footer of each page (depending on the currently active theme). Any menu can be designated as the primary or secondary links menu via the <a href="%menu-settings">menu settings page</a>.</p>
+Menu administration tabs:
 <ul>
-<li>On the administer menu page administrators can "edit" to change the title, description, parent or weight of the menu item. Under the "operations" column, click on "enable/disable" to toggle the menu item on or off. Menu items which are disabled are not deleted; they are merely not available for navigating the site in the sidebar menu block. Note that the default menu items generated by the menu module cannot be deleted, only disabled.</li>
-<li>Using the "add menu" tab submit a title for a new custom menu. Once submitted, the new menu will appear in a list toward the bottom of the administer menu page underneath the main navigation menu.</li>
-<li>Use the "add menu item" tab to create new links in either the navigation or a custom menu. Select the parent item to place the new link within an existing menu structure. For top level menu items, choose the name of the menu in which the link is to be added. This tab is also the way to define primary or secondary links for your site (by adding items to whatever menu is selected as your primary links menu).</li>
-</ul>
-');
+  <li>On the administer menu page, administrators can "edit" to change the title, description, parent or weight of a menu item. Under the "operations" column, click on "enable/disable" to toggle a menu item on or off. Only menu items which are enabled are displayed in the corresponding menu block. Note that the default menu items generated by the menu module cannot be deleted, only disabled.</li>
+  <li>Use the "add menu" tab to submit a title for a new custom menu. Once submitted, the menu will appear in a list toward the bottom of the administer menu page underneath the main navigation menu. Under the menu name there will be links to edit or delete the menu, and a link to add new items to the menu.</li>
+  <li>Use the "add menu item" tab to create new links in either the navigation or a custom menu (such as a primary/secondary links menu). Select the parent item to place the new link within an existing menu structure. For top level menu items, choose the name of the menu in which the link is to be added.</li>
+</ul>', array('%navigation' => theme('placeholder', 'Navigation'), '%primary-links' => theme('placeholder', 'primary links'), '%secondary-links' => theme('placeholder', 'secondary links'), '%admin-block' => url('admin/block'), '%menu-settings' => url('admin/settings/menu')));
       $output .= t('<p>You can</p>
 <ul>
-<li>administer menus at <a href="%admin-menu">administer &gt;&gt; menus</a>.</li>
-<li>turn menus blocks on and off in the <a href="%admin-block">administer &gt;&gt; blocks</a>.</li>
-<li>add a menu at <a href="%admin-menu-menu-add">administer &gt;&gt; menus &gt;&gt; add menu</a>.</li>
-<li>add a menu item at <a href="%admin-menu-item-add">administer &gt;&gt; menus &gt;&gt; add menu item</a>.</li>
-<li>modify menu settings (in particular, to specify a menu to use for primary or secondary links) at <a href="%admin-settings-menus">administer &gt;&gt; settings &gt;&gt; menus</a>.</li>
+  <li>administer menus at <a href="%admin-menu">administer &gt;&gt; menus</a>.</li>
+  <li>add a menu at <a href="%admin-menu-menu-add">administer &gt;&gt; menus &gt;&gt; add menu</a>.</li>
+  <li>add a menu item at <a href="%admin-menu-item-add">administer &gt;&gt; menus &gt;&gt; add menu item</a>.</li>
+  <li>modify menu settings (in particular, to specify a menu to use for primary or secondary links) at <a href="%admin-settings-menus">administer &gt;&gt; settings &gt;&gt; menus</a>.</li>
+  <li>manage menu blocks at <a href="%admin-block">administer &gt;&gt; blocks</a>.</li>
 </ul>
 ', array('%admin-menu' => url('admin/menu'), '%admin-block' => url('admin/block'), '%admin-menu-menu-add' => url('admin/menu/menu/add'), '%admin-menu-item-add' => url('admin/menu/item/add'), '%admin-settings-menus' => url('admin/settings/menu')));
       $output .= '<p>'. t('For more information please read the configuration and customization handbook <a href="%menu">Menu page</a>.', array('%menu' => 'http://drupal.org/handbook/modules/menu/')) .'</p>';
@@ -34,13 +34,11 @@ function menu_help($section) {
     case 'admin/modules#description':
       return t('Allows administrators to customize the site navigation menu.');
     case 'admin/menu':
-      return t('<p>Select an operation from the list to move, change, or delete a menu item.</p>');
+      return '<p>'. t('Menus are a collection of links (menu items) used to navigate a website. The list(s) below display the currently available menus along with their menu items. Select an operation from the list to manage each menu or menu item.', array('%admin-settings-menus' => url('admin/settings/menu'), '%admin-block'=>url('admin/block'))) .'</p>';
     case 'admin/menu/menu/add':
-      return t('<p>Enter the name for your new menu. Remember to enable the newly created block in the <a href="%blocks">blocks administration page</a>.</p>', array('%blocks' => url('admin/block')));
+      return '<p>'. t('Enter the name for your new menu. Remember to enable the newly created block in the <a href="%blocks">blocks administration page</a>.', array('%blocks' => url('admin/block'))) .'</p>';
     case 'admin/menu/item/add':
-      return t('<p>Enter the title, path, position and the weight for your new menu item.</p>');
-    case 'admin/settings/menu':
-      return t('<p>Customize the menu settings.</p>');
+      return '<p>'. t('Enter the title, path, position and the weight for your new menu item.') .'</p>';
   }
 }
 
diff --git a/modules/menu/menu.module b/modules/menu/menu.module
index c36e68798..28aac9898 100644
--- a/modules/menu/menu.module
+++ b/modules/menu/menu.module
@@ -12,21 +12,21 @@
 function menu_help($section) {
   switch ($section) {
     case 'admin/help#menu':
-      $output = t('<p>The menu module allows for customization of the menus. Menus are useful for providing navigation in your site. The main menu for navigation is called the "navigation" menu. Menus appear in blocks on your site.</p>
-<p>There is a special case for the display of "primary links" and "secondary links" (which are implemented as menus). These are sets of links which are usually displayed in the header of each page (depending on the currently active theme). Any menu can serve as the primary or secondary links, by modifying the settings for the menu module.</p>
+      $output = t('<p>Menus are a collection of links (menu items) used to navigate a website. The menu module provides an interface to control and customize the powerful menu system that comes with Drupal.  Menus are primarily displayed as a hierarchical list of links using Drupal\'s highly flexible <a href="%admin-block">blocks</a> feature. Each menu automatically creates a block of the same name. By default, new menu items are placed inside a built-in menu labelled %navigation, but administrators can also create custom menus.</p>
+<p>Drupal themes generally provide out-of-the-box support for two menus commonly labelled %primary-links and %secondary-links. These are sets of links which are usually displayed in the header or footer of each page (depending on the currently active theme). Any menu can be designated as the primary or secondary links menu via the <a href="%menu-settings">menu settings page</a>.</p>
+Menu administration tabs:
 <ul>
-<li>On the administer menu page administrators can "edit" to change the title, description, parent or weight of the menu item. Under the "operations" column, click on "enable/disable" to toggle the menu item on or off. Menu items which are disabled are not deleted; they are merely not available for navigating the site in the sidebar menu block. Note that the default menu items generated by the menu module cannot be deleted, only disabled.</li>
-<li>Using the "add menu" tab submit a title for a new custom menu. Once submitted, the new menu will appear in a list toward the bottom of the administer menu page underneath the main navigation menu.</li>
-<li>Use the "add menu item" tab to create new links in either the navigation or a custom menu. Select the parent item to place the new link within an existing menu structure. For top level menu items, choose the name of the menu in which the link is to be added. This tab is also the way to define primary or secondary links for your site (by adding items to whatever menu is selected as your primary links menu).</li>
-</ul>
-');
+  <li>On the administer menu page, administrators can "edit" to change the title, description, parent or weight of a menu item. Under the "operations" column, click on "enable/disable" to toggle a menu item on or off. Only menu items which are enabled are displayed in the corresponding menu block. Note that the default menu items generated by the menu module cannot be deleted, only disabled.</li>
+  <li>Use the "add menu" tab to submit a title for a new custom menu. Once submitted, the menu will appear in a list toward the bottom of the administer menu page underneath the main navigation menu. Under the menu name there will be links to edit or delete the menu, and a link to add new items to the menu.</li>
+  <li>Use the "add menu item" tab to create new links in either the navigation or a custom menu (such as a primary/secondary links menu). Select the parent item to place the new link within an existing menu structure. For top level menu items, choose the name of the menu in which the link is to be added.</li>
+</ul>', array('%navigation' => theme('placeholder', 'Navigation'), '%primary-links' => theme('placeholder', 'primary links'), '%secondary-links' => theme('placeholder', 'secondary links'), '%admin-block' => url('admin/block'), '%menu-settings' => url('admin/settings/menu')));
       $output .= t('<p>You can</p>
 <ul>
-<li>administer menus at <a href="%admin-menu">administer &gt;&gt; menus</a>.</li>
-<li>turn menus blocks on and off in the <a href="%admin-block">administer &gt;&gt; blocks</a>.</li>
-<li>add a menu at <a href="%admin-menu-menu-add">administer &gt;&gt; menus &gt;&gt; add menu</a>.</li>
-<li>add a menu item at <a href="%admin-menu-item-add">administer &gt;&gt; menus &gt;&gt; add menu item</a>.</li>
-<li>modify menu settings (in particular, to specify a menu to use for primary or secondary links) at <a href="%admin-settings-menus">administer &gt;&gt; settings &gt;&gt; menus</a>.</li>
+  <li>administer menus at <a href="%admin-menu">administer &gt;&gt; menus</a>.</li>
+  <li>add a menu at <a href="%admin-menu-menu-add">administer &gt;&gt; menus &gt;&gt; add menu</a>.</li>
+  <li>add a menu item at <a href="%admin-menu-item-add">administer &gt;&gt; menus &gt;&gt; add menu item</a>.</li>
+  <li>modify menu settings (in particular, to specify a menu to use for primary or secondary links) at <a href="%admin-settings-menus">administer &gt;&gt; settings &gt;&gt; menus</a>.</li>
+  <li>manage menu blocks at <a href="%admin-block">administer &gt;&gt; blocks</a>.</li>
 </ul>
 ', array('%admin-menu' => url('admin/menu'), '%admin-block' => url('admin/block'), '%admin-menu-menu-add' => url('admin/menu/menu/add'), '%admin-menu-item-add' => url('admin/menu/item/add'), '%admin-settings-menus' => url('admin/settings/menu')));
       $output .= '<p>'. t('For more information please read the configuration and customization handbook <a href="%menu">Menu page</a>.', array('%menu' => 'http://drupal.org/handbook/modules/menu/')) .'</p>';
@@ -34,13 +34,11 @@ function menu_help($section) {
     case 'admin/modules#description':
       return t('Allows administrators to customize the site navigation menu.');
     case 'admin/menu':
-      return t('<p>Select an operation from the list to move, change, or delete a menu item.</p>');
+      return '<p>'. t('Menus are a collection of links (menu items) used to navigate a website. The list(s) below display the currently available menus along with their menu items. Select an operation from the list to manage each menu or menu item.', array('%admin-settings-menus' => url('admin/settings/menu'), '%admin-block'=>url('admin/block'))) .'</p>';
     case 'admin/menu/menu/add':
-      return t('<p>Enter the name for your new menu. Remember to enable the newly created block in the <a href="%blocks">blocks administration page</a>.</p>', array('%blocks' => url('admin/block')));
+      return '<p>'. t('Enter the name for your new menu. Remember to enable the newly created block in the <a href="%blocks">blocks administration page</a>.', array('%blocks' => url('admin/block'))) .'</p>';
     case 'admin/menu/item/add':
-      return t('<p>Enter the title, path, position and the weight for your new menu item.</p>');
-    case 'admin/settings/menu':
-      return t('<p>Customize the menu settings.</p>');
+      return '<p>'. t('Enter the title, path, position and the weight for your new menu item.') .'</p>';
   }
 }