[gnome-devel-docs] hig: refine the app menu changes

[Allan Day <allanday src gnome org>]

commit e84d2f7200253f43b218aa114ea4f8e31481dd2f
Author: Allan Day <allanpday gmail com>
Date:   Wed Aug 29 16:03:59 2018 +0100

    hig: refine the app menu changes
    
    Polish the pages on app menus, primary menus and secondary menus.

 hig/C/application-menus.page |  2 +-
 hig/C/primary-menus.page     | 11 ++++++-----
 hig/C/secondary-menus.page   | 12 ++++++------
 3 files changed, 13 insertions(+), 12 deletions(-)
---
diff --git a/hig/C/application-menus.page b/hig/C/application-menus.page
index ce01cb9e..9f286a3f 100644
--- a/hig/C/application-menus.page
+++ b/hig/C/application-menus.page
@@ -16,7 +16,7 @@
 
 <media type="image" mime="image/svg" src="figures/patterns/application-menu.svg"/>
 
-<p><em>Application menus are no longer a recommended design pattern. See <link 
xref="primary-menus">primary</link> and <link xref="secondary-menus">secondary menus</link> as 
alternatives.</em></p>
+<p><em>Application menus are no longer recommended, and will not be displayed in GNOME 3's top bar from 
GNOME 3.32. <link xref="primary-menus">Primary</link> and <link xref="secondary-menus">secondary menus</link> 
should be used as alternatives.</em></p>
 
 <p>Application menus provide access to global, top level actions and options for your application. These 
include standard items for accessing documentation and information about the application.</p>
 
diff --git a/hig/C/primary-menus.page b/hig/C/primary-menus.page
index 845373ae..5bb01417 100644
--- a/hig/C/primary-menus.page
+++ b/hig/C/primary-menus.page
@@ -17,14 +17,14 @@
 
 <media type="image" mime="image/svg" src="figures/patterns/primary-menu.svg"/>
 
-<p>A menu that is located at the right side of a <link xref="header-bars">header bar</link>, which contains 
the top-level menu items for an application, including Preferences, Help and About, as well as menu items for 
functionality that doesn't fit into the rest of the view. The button which activates the menu has the 
menu-open icon, which is made up of three stacked horizontal lines.</p>
+<p>Primary menus are a standard design pattern that is found in most applications. They are labelled with 
the menu icon (named <code>menu-open</code>) and contain the top-level menu items for the application. This 
can include standard items like <gui>Preferences</gui>, <gui>Help</gui> and <gui>About</gui>, as well as 
other application-specific items.</p>
 
-<p>When used in combination with a sidebar list, a primary menu is placed on the right above the list.</p>
+<p>Primary menus are typically located on the right side of the header bar. When used in combination with a 
<link xref="sidebar-lists">sidebar list</link>, the primary menu should be placed above the sidebar list.</p>
 
 <section id="when-to-use">
 <title>When to use</title>
 
-<p>Most applications have primary menus, since they are the standard location for About, which every 
application is expected to have.</p>
+<p>Most applications have primary menus, since they are the standard location for <gui>About</gui>, which 
every application is expected to have.</p>
 
 </section>
 
@@ -33,9 +33,10 @@
 
 <list>
 <item><p>Primary menus can contain items for both the current window or view, as well as the application as 
a whole. This differentiates them from <link xref="secondary-menus">secondary menus</link>, which only 
contain menu items that relate to a specific view or item.</p></item>
-<item><p>Follow the <link xref="menus">standard guidelines for menus</link>.</p></item>
+<item><p>Applications which use in-window navigation should only show the primary menu on the top-level view 
(typically the main view that is shown when the app is launched). Child views, such as those that show 
individual items of content, should use <link xref="secondary-menus">secondary</link> rather than primary 
menus.</p></item>
+<item><p>Follow the <link xref="menus">standard guidelines for menus</link> when deciding on primary menu 
content and arrangement.</p></item>
 <item><p>A primary menu is contained within a <link xref="popovers">popover</link>. As such, a header bar 
menu can include a variety of controls, such as groups of buttons.</p></item>
-<item><p>Primary menus shouldn’t include menu items for close quit. Windows can already be closed from the 
header bar, and it can be ambiguous as to what a close menu item refers to. Users don't readily differentiate 
between quit and close, and it can therefore be misleading.</p></item>
+<item><p>Primary menus shouldn’t include menu items for close or quit: windows can already be closed using 
the close button in the header bar, and it can be ambiguous as to what a close menu item refers to. Users 
don't readily differentiate between quit and close, and it can therefore be misleading.</p></item>
 </list>
 
 </section>
diff --git a/hig/C/secondary-menus.page b/hig/C/secondary-menus.page
index 2cbda856..5ebe8002 100644
--- a/hig/C/secondary-menus.page
+++ b/hig/C/secondary-menus.page
@@ -17,14 +17,14 @@
 
 <media type="image" mime="image/svg" src="figures/patterns/secondary-menu.svg"/>
 
-<p>A menu that contains menu items for the current view or content item. A secondary menu is different from 
a <link xref="primary-menus">primary menu</link>, in that it is only shown on sub-views/pages, and doesn't 
contain global application items like <gui>Preferences</gui> and <gui>About</gui></p>.
-
-<p>Secondary menus are opened with a button that has the view-more icon. They are located at the right side 
of a header bar or, when used in combination with a <link xref="sidebar-lists">sidebar list</link>, to the 
right above the list.</p>
+<p>Secondary menus are located in the header bar and include menu items for the current view or content 
item. This differentiates them from <link xref="primary-menus">primary menus</link>, which include menu items 
that relate to an entire application (such as <gui>Preferences</gui> and <gui>About</gui>).</p>
 
 <section id="when-to-use">
 <title>When to use</title>
 
-<p>Most applications have primary menus, since they are the standard location for About, which every 
application is expected to have.</p>
+<p>Secondary menus can be used to host controls that relate to a particular content item which is being 
displayed in the application window (such as a document, contact, conversation or photo). They are typically 
used in combination with in-window navigation or <link xref="sidebar-lists">sidebar lists</link>, since both 
these arrangements feature separate views or areas for content items to be shown.</p>
+
+<p>Secondary menus are optional and only need to be used if there are enough controls to require a menu.</p>
 
 </section>
 
@@ -33,8 +33,8 @@
 
 <list>
 <item><p>Secondary menus generally shouldn't reproduce menu items that are included in <link 
xref="primary-menus">primary menus</link>, like <gui>Preferences</gui> and <gui>About</gui>. However, it can 
sometimes be useful to show <gui>Help</gui>.</p></item>
-<item><p>Follow the <link xref="menus">standard guidelines for menus</link>.</p></item>
-<item><p>A primary menu is contained within a <link xref="popovers">popover</link>. As such, a header bar 
menu can include a variety of controls, such as groups of buttons.</p></item>
+<item><p>The <link xref="menus">standard guidelines for menus</link> can be followed when designing 
secondary menus.</p></item>
+<item><p>A secondary menu is contained within a <link xref="popovers">popover</link>. As such, a header bar 
menu can include a variety of controls, such as groups of buttons.</p></item>
 <item><p>Secondary menus shouldn’t include menu items for close or quit.</p></item>
 </list>