[e] (0) Reword the menu item builder to make more sense

Affected topics: HTML

git-svn-id: http://svn.whatwg.org/webapps@8717 340c8d12-0b0e-0410-8428-c7bf67bfef74

complete.html

@@ -37278,7 +37278,7 @@ <h4 id=the-button-element>4.10.6 The <dfn><code>button</code></dfn> element</h4>
      active</a>, abort these steps.<li><p>Let <var>menu</var> be the element's <a href=#designated-pop-up-menu id=the-button-element:designated-pop-up-menu-2>designated pop-up menu</a>, if
      any. If there isn't one, then abort these steps.<li><p><a href=#concept-event-fire id=the-button-element:concept-event-fire>Fire</a> a <a href=#concept-events-trusted id=the-button-element:concept-events-trusted>trusted</a> event with the name <code id=the-button-element:event-show><a href=#event-show>show</a></code> at <var>menu</var>, using the <code id=the-button-element:relatedevent><a href=#relatedevent>RelatedEvent</a></code>
      interface, with the <code id=the-button-element:dom-relatedevent-relatedtarget><a href=#dom-relatedevent-relatedtarget>relatedTarget</a></code> attribute
-     initialised to the <code id=the-button-element:the-button-element-6><a href=#the-button-element>button</a></code> element. The event must be cancelable. <li><p>If the event is not canceled, then <a href=#construct-and-show-a-menu id=the-button-element:construct-and-show-a-menu>construct and
+     initialised to the <code id=the-button-element:the-button-element-6><a href=#the-button-element>button</a></code> element. The event must be cancelable. <li><p>If the event is not canceled, then <a href=#build-and-show-a-menu id=the-button-element:build-and-show-a-menu>build and
      show</a> the menu for <var>menu</var>, with the <code id=the-button-element:the-button-element-7><a href=#the-button-element>button</a></code> element as the
      subject.</ol>
 
@@ -42830,50 +42830,54 @@ <h4 id=the-menu-element>4.11.3 The <dfn id=menus><code>menu</code></dfn> element
 
   <hr>
 
-  <p>A pop-up menu consists of a list of zero or more menu items, which can be any of:</p>
+  <p>A <dfn id=menu-construct>menu construct</dfn> consists of an ordered list of zero or more <dfn id=menu-item-construct>menu item constructs</dfn>, which can be any of:</p>
 
-  <ul class=brief><li><a href=#concept-command id=the-menu-element:concept-command>Commands</a>, which can be marked as default commands (<code id=the-menu-element:the-menuitem-element-2><a href=#the-menuitem-element>menuitem</a></code>)<li>Separators (<code id=the-menu-element:the-hr-element-2><a href=#the-hr-element>hr</a></code>)<li>Other menus, which allows the list to be nested (<code id=the-menu-element:the-menu-element-10><a href=#the-menu-element>menu</a></code>)</ul>
+  <ul class=brief><li><a href=#concept-command id=the-menu-element:concept-command>Commands</a>, which can be marked as <dfn id=default-command>default commands</dfn> (<code id=the-menu-element:the-menuitem-element-2><a href=#the-menuitem-element>menuitem</a></code>)<li><dfn id=concept-separator>Separators</dfn> (<code id=the-menu-element:the-hr-element-2><a href=#the-hr-element>hr</a></code>)<li>Other <a href=#menu-construct id=the-menu-element:menu-construct>menu constructs</a>, each with an associated <dfn id=submenu-label>submenu label</dfn>, which allows the list to be nested (<code id=the-menu-element:the-menu-element-10><a href=#the-menu-element>menu</a></code>)</ul>
 
-  <p>To <dfn id=construct-and-show-a-menu>construct and show a menu</dfn> for a particular <code id=the-menu-element:the-menu-element-11><a href=#the-menu-element>menu</a></code> element and with a
-  particular element as a subject, the user agent must run the following steps:</p>
-
-  <ol><li><p>Let the menu be an empty list of the type described above.<li>
-
-    <p>Run the <a href=#menu-builder id=the-menu-element:menu-builder>menu builder</a> steps for the <code id=the-menu-element:the-menu-element-12><a href=#the-menu-element>menu</a></code> element using the menu
-    prepared in the previous list as the output.</p>
-
-    <p>The <dfn id=menu-builder>menu builder</dfn> steps for a <code id=the-menu-element:the-menu-element-13><a href=#the-menu-element>menu</a></code> element using a specific menu as
-    output are as follows: For each child node of the <code id=the-menu-element:the-menu-element-14><a href=#the-menu-element>menu</a></code> in <a href=#tree-order id=the-menu-element:tree-order>tree order</a>,
-    run the appropriate steps from the following list:</p>
+  <p>To <dfn id=build-and-show-a-menu>build and show a menu</dfn> for a particular <code id=the-menu-element:the-menu-element-11><a href=#the-menu-element>menu</a></code> element
+  <var>source</var> and with a particular element <var>subject</var> as a subject, the user agent
+  must run the following steps:</p>
 
-    <dl class=switch><dt>If the child is a <code id=the-menu-element:the-menuitem-element-3><a href=#the-menuitem-element>menuitem</a></code> element that <a href=#concept-command id=the-menu-element:concept-command-2>defines
-     a command</a><dd>Append the command to the menu, respecting its <a href=#concept-facet id=the-menu-element:concept-facet>facets</a>. If the <code id=the-menu-element:the-menuitem-element-4><a href=#the-menuitem-element>menuitem</a></code> element has a <code id=the-menu-element:attr-menuitem-default><a href=#attr-menuitem-default>default</a></code> attribute, mark the command as being a default
-     command.<dt>If the child is an <code id=the-menu-element:the-hr-element-3><a href=#the-hr-element>hr</a></code> element<dd>Append a separator to the menu.<dt>If the child is a <code id=the-menu-element:the-menu-element-15><a href=#the-menu-element>menu</a></code> element with no <code id=the-menu-element:attr-menu-label-4><a href=#attr-menu-label>label</a></code> attribute<dd>Append a separator to the menu, then run the <a href=#menu-builder id=the-menu-element:menu-builder-2>menu builder</a> steps using this
-     child <code id=the-menu-element:the-menu-element-16><a href=#the-menu-element>menu</a></code> element for the same menu, then append another separator to the
-     menu.<dt>If the child is a <code id=the-menu-element:the-menu-element-17><a href=#the-menu-element>menu</a></code> element with a <code id=the-menu-element:attr-menu-label-5><a href=#attr-menu-label>label</a></code> attribute<dd>Create a new submenu as an empty list of the type described above, and construct it by
-     running the <a href=#menu-builder id=the-menu-element:menu-builder-3>menu builder</a> steps for the child <code id=the-menu-element:the-menu-element-18><a href=#the-menu-element>menu</a></code> element using the
-     new submenu as the output. Then, append the submenu to the menu, using the value of the child
-     <code id=the-menu-element:the-menu-element-19><a href=#the-menu-element>menu</a></code> element's <code id=the-menu-element:attr-menu-label-6><a href=#attr-menu-label>label</a></code> attribute as the label
-     of the submenu.<dt>Otherwise<dd><a href=#ignore id=the-menu-element:ignore>Ignore</a> the child node.</dl>
+  <ol><li><p>Let <var>pop-up menu</var> be the <a href=#menu-construct id=the-menu-element:menu-construct-2>menu construct</a> created by the <a href=#build-a-menu-construct id=the-menu-element:build-a-menu-construct>build a
+   menu construct</a> algorithm when passed the <var>source</var> element.</p>
 
-   <li><p>Remove any submenu with no label, or whose label is the empty string, in the menu or any
-   submenus.<li><p>Remove any menu item with no label, or whose label is the empty string, in the menu or any
-   submenus.<li><p>Collapse all sequences of two or more adjacent separators in the menu or any submenus to a
-   single separator.<li><p>Remove all separators at the start or end of the menu and any submenus.<li>
+   <li>
 
-    <p>Display the menu to the user, and let the algorithm that invoked this one continue.</p>
+    <p>Display <var>pop-up menu</var> to the user, and let the algorithm that invoked this one continue.</p>
 
-    <p>If the user selects a menu item that corresponds to an element that still represents a <a href=#concept-command id=the-menu-element:concept-command-3>command</a> when the user selects it, then the UA must invoke that
+    <p>If the user selects a <a href=#menu-item-construct id=the-menu-element:menu-item-construct>menu item construct</a> that corresponds to an element that still represents a <a href=#concept-command id=the-menu-element:concept-command-2>command</a> when the user selects it, then the UA must invoke that
     command's <a href=#command-facet-action id=the-menu-element:command-facet-action>Action</a>. If the command's <a href=#command-facet-action id=the-menu-element:command-facet-action-2>Action</a> is defined as <a href=#fire-a-click-event id=the-menu-element:fire-a-click-event>firing
     a <code>click</code> event</a>, either directly or via the <a href=#run-synthetic-click-activation-steps id=the-menu-element:run-synthetic-click-activation-steps>run
-    synthetic click activation steps</a> algorithm, then the <code id=the-menu-element:dom-mouseevent-relatedtarget><a href=#dom-mouseevent-relatedtarget>relatedTarget</a></code> attribute of that <code id=the-menu-element:event-click><a href=#event-click>click</a></code> event must be initialised to the subject passed to this
-    <a href=#construct-and-show-a-menu id=the-menu-element:construct-and-show-a-menu>construct and show a menu</a> algorithm.</p>
+    synthetic click activation steps</a> algorithm, then the <code id=the-menu-element:dom-mouseevent-relatedtarget><a href=#dom-mouseevent-relatedtarget>relatedTarget</a></code> attribute of that <code id=the-menu-element:event-click><a href=#event-click>click</a></code> event must be initialised to <var>subject</var>.</p>
 
     <p>Pop-up menus must not, while being shown, reflect changes in the DOM. The menu is constructed
     from the DOM before being shown, and is then immutable.</p>
 
    </ol>
 
+  <p>To <dfn id=build-a-menu-construct>build a menu construct</dfn> for an element <var>source</var>, the user agent must run
+  the following steps, which return a <a href=#menu-construct id=the-menu-element:menu-construct-3>menu construct</a>:</p>
+
+  <ol><li><p>Let <var>generated menu</var> be an empty <a href=#menu-construct id=the-menu-element:menu-construct-4>menu construct</a>.<li>
+
+    <p>Run the <a href=#menu-item-generator id=the-menu-element:menu-item-generator>menu item generator</a> steps for the <code id=the-menu-element:the-menu-element-12><a href=#the-menu-element>menu</a></code> element using <var>generated menu</var>
+    as the output.</p>
+
+    <p>The <dfn id=menu-item-generator>menu item generator</dfn> steps for a <code id=the-menu-element:the-menu-element-13><a href=#the-menu-element>menu</a></code> element using a specific <a href=#menu-construct id=the-menu-element:menu-construct-5>menu construct</a> <var>output</var> as
+    output are as follows: For each child node of the <code id=the-menu-element:the-menu-element-14><a href=#the-menu-element>menu</a></code> in <a href=#tree-order id=the-menu-element:tree-order>tree order</a>,
+    run the appropriate steps from the following list:</p>
+
+    <dl class=switch><dt>If the child is a <code id=the-menu-element:the-menuitem-element-3><a href=#the-menuitem-element>menuitem</a></code> element that <a href=#concept-command id=the-menu-element:concept-command-3>defines
+     a command</a><dd>Append the <a href=#concept-command id=the-menu-element:concept-command-4>command</a> to <var>output</var>, respecting the command's <a href=#concept-facet id=the-menu-element:concept-facet>facets</a>. If the <code id=the-menu-element:the-menuitem-element-4><a href=#the-menuitem-element>menuitem</a></code> element has a <code id=the-menu-element:attr-menuitem-default><a href=#attr-menuitem-default>default</a></code> attribute, mark the <span>command</span> as being a <a href=#default-command id=the-menu-element:default-command>default
+     command</a>.<dt>If the child is an <code id=the-menu-element:the-hr-element-3><a href=#the-hr-element>hr</a></code> element<dd>Append a <a href=#concept-separator id=the-menu-element:concept-separator>separator</a> to <var>output</var>.<dt>If the child is a <code id=the-menu-element:the-menu-element-15><a href=#the-menu-element>menu</a></code> element with no <code id=the-menu-element:attr-menu-label-4><a href=#attr-menu-label>label</a></code> attribute<dd>Append a <a href=#concept-separator id=the-menu-element:concept-separator-2>separator</a> to <var>output</var>, then run
+     the <a href=#menu-item-generator id=the-menu-element:menu-item-generator-2>menu item generator</a> steps for this child <code id=the-menu-element:the-menu-element-16><a href=#the-menu-element>menu</a></code> element, using
+     <var>output</var> as the output, then append another <a href=#concept-separator id=the-menu-element:concept-separator-3>separator</a> to <var>output</var>.<dt>If the child is a <code id=the-menu-element:the-menu-element-17><a href=#the-menu-element>menu</a></code> element with a <code id=the-menu-element:attr-menu-label-5><a href=#attr-menu-label>label</a></code> attribute<dd>Let <var>submenu</var> be the result of running the <a href=#build-a-menu-construct id=the-menu-element:build-a-menu-construct-2>build a menu construct</a> steps for the child <code id=the-menu-element:the-menu-element-18><a href=#the-menu-element>menu</a></code> element. Then, append <var>submenu</var> to <var>output</var>, using the value of the child
+     <code id=the-menu-element:the-menu-element-19><a href=#the-menu-element>menu</a></code> element's <code id=the-menu-element:attr-menu-label-6><a href=#attr-menu-label>label</a></code> attribute as the <a href=#submenu-label id=the-menu-element:submenu-label>submenu label</a>.<dt>Otherwise<dd><a href=#ignore id=the-menu-element:ignore>Ignore</a> the child node.</dl>
+
+   <li><p>Remove from <var>output</var> any <a href=#menu-construct id=the-menu-element:menu-construct-6>menu construct</a> whose <a href=#submenu-label id=the-menu-element:submenu-label-2>submenu
+   label</a> is the empty string.<li><p>Remove from <var>output</var> any <a href=#menu-item-construct id=the-menu-element:menu-item-construct-2>menu item construct</a> representing a <a href=#concept-command id=the-menu-element:concept-command-5>command</a> whose <a href=#command-facet-label id=the-menu-element:command-facet-label>Label</a> is
+   the empty string.<li><p>Collapse all sequences of two or more adjacent <a href=#concept-separator id=the-menu-element:concept-separator-4>separators</a> in <var>output</var> to a single <a href=#concept-separator id=the-menu-element:concept-separator-5>separator</a>.<li><p>If the first <a href=#menu-item-construct id=the-menu-element:menu-item-construct-3>menu item construct</a> in <var>output</var> is a <a href=#concept-separator id=the-menu-element:concept-separator-6>separator</a>, then remove it.<li><p>If the last <a href=#menu-item-construct id=the-menu-element:menu-item-construct-4>menu item construct</a> in <var>output</var> is a <a href=#concept-separator id=the-menu-element:concept-separator-7>separator</a>, then remove it.<li><p>Return <var>output</var>.</ol>
+
   <hr>
 
   <p>The <dfn id=dom-menu-type><code>type</code></dfn> IDL attribute must <a href=#reflect id=the-menu-element:reflect>reflect</a>
@@ -43197,7 +43201,7 @@ <h5 id=processing-model-5>4.11.5.2 Processing model</h5>
   to <var>subject</var>. The event must be cancelable. </p>
 
   <p>If <em>this</em> event (the <code id=processing-model-5:event-show-2><a href=#event-show>show</a></code> event) is not canceled, then
-  the user agent must <a href=#construct-and-show-a-menu id=processing-model-5:construct-and-show-a-menu>construct and show</a> the menu for
+  the user agent must <a href=#build-and-show-a-menu id=processing-model-5:build-and-show-a-menu>build and show</a> the menu for
   <var>menu</var> with <var>subject</var> as the subject.</p>
 
   <p>The user agent may also provide access to its default context menu, if any, with the context