Docs and CSS updates for twbs#21807 (twbs#22336)

* tweak some copy
* fix up scrollspy docs
* remove nav styles that were added
* fix nav-based docs by requiring .nav-item on .nav-link

docs/components/list-group.md

@@ -309,7 +309,7 @@ Activates a list item element and content container. Tab should have either a `d
 
 #### .tab('show')
 
-Selects the given list item and shows its associated pane. Any other list item that was previously selected becomes unselected and its associated pane is hidden. **Returns to the caller before the tab pane has actually been shown** (i.e. before the `shown.bs.tab` event occurs).
+Selects the given list item and shows its associated pane. Any other list item that was previously selected becomes unselected and its associated pane is hidden. **Returns to the caller before the tab pane has actually been shown** (for example, before the `shown.bs.tab` event occurs).
 
 {% highlight js %}
 $('#someListItem').tab('show')
@@ -324,12 +324,12 @@ When showing a new tab, the events fire in the following order:
 3. `hidden.bs.tab` (on the previous active tab, the same one as for the `hide.bs.tab` event)
 4. `shown.bs.tab` (on the newly-active just-shown tab, the same one as for the `show.bs.tab` event)
 
-If no tab was already active, then the `hide.bs.tab` and `hidden.bs.tab` events will not be fired.
+If no tab was already active, the `hide.bs.tab` and `hidden.bs.tab` events will not be fired.
 
 <table class="table table-bordered table-striped table-responsive">
   <thead>
    <tr>
-     <th style="width: 150px;">Event Type</th>
+     <th style="width: 150px;">Event type</th>
      <th>Description</th>
    </tr>
   </thead>

docs/components/navs.md

@@ -358,19 +358,19 @@ Use the tab JavaScript plugin—include it individually or through the compiled
 To help fit your needs, this works with `<ul>`-based markup, as shown above, as well as `<nav>`-based markup shown below.
 
 <div class="bd-example bd-example-tabs" role="tabpanel">
-  <div class="nav nav-tabs" id="nav-tab" role="tablist">
-    <a class="nav-link active" id="nav-home-tab" data-toggle="tab" href="#nav-home" role="tab" aria-controls="home" aria-expanded="true">Home</a>
-    <a class="nav-link" id="nav-profile-tab" data-toggle="tab" href="#nav-profile" role="tab" aria-controls="profile">Profile</a>
+  <nav class="nav nav-tabs" id="nav-tab" role="tablist">
+    <a class="nav-item nav-link active" id="nav-home-tab" data-toggle="tab" href="#nav-home" role="tab" aria-controls="home" aria-expanded="true">Home</a>
+    <a class="nav-item nav-link" id="nav-profile-tab" data-toggle="tab" href="#nav-profile" role="tab" aria-controls="profile">Profile</a>
     <div class="dropdown">
-      <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">
+      <a class="nav-item nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">
         Dropdown
       </a>
       <div class="dropdown-menu">
         <a class="dropdown-item" id="nav-dropdown1-tab" href="#nav-dropdown1" role="tab" data-toggle="tab" aria-controls="dropdown1">@fat</a>
         <a class="dropdown-item" id="nav-dropdown2-tab" href="#nav-dropdown2" role="tab" data-toggle="tab" aria-controls="dropdown2">@mdo</a>
       </div>
     </div>
-  </div>
+  </nav>
   <div class="tab-content" id="nav-tabContent">
     <div class="tab-pane fade show active" id="nav-home" role="tabpanel" aria-labelledby="nav-home-tab">
       <p>Et et consectetur ipsum labore excepteur est proident excepteur ad velit occaecat qui minim occaecat veniam. Fugiat veniam incididunt anim aliqua enim pariatur veniam sunt est aute sit dolor anim. Velit non irure adipisicing aliqua ullamco irure incididunt irure non esse consectetur nostrud minim non minim occaecat. Amet duis do nisi duis veniam non est eiusmod tempor incididunt tempor dolor ipsum in qui sit. Exercitation mollit sit culpa nisi culpa non adipisicing reprehenderit do dolore. Duis reprehenderit occaecat anim ullamco ad duis occaecat ex.</p>
@@ -388,19 +388,19 @@ To help fit your needs, this works with `<ul>`-based markup, as shown above, as
 </div>
 
 {% highlight html %}
-<div class="nav nav-tabs" id="myTab" role="tablist">
-  <a class="nav-link active" id="nav-home-tab" data-toggle="tab" href="#nav-home" role="tab" aria-controls="nav-home" aria-expanded="true">Home</a>
-  <a class="nav-link" id="nav-profile-tab" data-toggle="tab" href="#nav-profile" role="tab" aria-controls="nav-profile">Profile</a>
+<nav class="nav nav-tabs" id="myTab" role="tablist">
+  <a class="nav-item nav-link active" id="nav-home-tab" data-toggle="tab" href="#nav-home" role="tab" aria-controls="nav-home" aria-expanded="true">Home</a>
+  <a class="nav-item nav-link" id="nav-profile-tab" data-toggle="tab" href="#nav-profile" role="tab" aria-controls="nav-profile">Profile</a>
   <div class="dropdown">
-    <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">
+    <a class="nav-item nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">
       Dropdown
     </a>
     <div class="dropdown-menu">
       <a class="dropdown-item" id="nav-dropdown1-tab" href="#nav-dropdown1" role="tab" data-toggle="tab" aria-controls="nav-dropdown1">@fat</a>
       <a class="dropdown-item" id="nav-dropdown2-tab" href="#nav-dropdown2" role="tab" data-toggle="tab" aria-controls="nav-dropdown2">@mdo</a>
     </div>
   </div>
-</div>
+</nav>
 <div class="tab-content" id="nav-tabContent">
   <div class="tab-pane fade show active" id="nav-home" role="tabpanel" aria-labelledby="nav-home-tab">...</div>
   <div class="tab-pane fade" id="nav-profile" role="tabpanel" aria-labelledby="nav-profile-tab">...</div>

docs/components/scrollspy.md

@@ -5,46 +5,27 @@ description: Documentation and examples for the scrollspy plugin with Bootstrap'
 group: components
 ---
 
-Automatically update nav targets based on scroll position.
+Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport.
 
 ## Contents
 
 * Will be replaced with the ToC, excluding the "Contents" header
 {:toc}
 
-{% callout warning %}
-#### Requires Bootstrap nav or list-group
+## How it works
 
-Scrollspy requires the use of a [Bootstrap nav component]({{ site.baseurl }}/components/navs#base-nav) or [Bootstrap list group component]({{ site.baseurl }}/components/list-group/#contents) for proper highlighting of active links / items.
+Scrollspy has a few requirements to function properly:
 
-When used with the nav component, it supports both the `<nav>` and `<ul>` markup and in both cases the element that receives the `.active` class is the `.list-group-item`.
+- It must to be used on a Bootstrap [nav component]({{ site.baseurl }}/components/navs/) or [list group]({{ site.baseurl }}/components/list-group/).
+- Scrollspy requires `position: relative;` on the element you're spying on, usually the `<body>`.
+- When spying on elements other than the `<body>`, be sure to have a `height` set and `overflow-y: scroll;` applied.
+- Anchors (`<a>`) are required and must point to an element with that `id`.
 
-When used with the list group component, the element that receives the `.active` class is the `.nav-link`.
-{% highlight html %}
-<ul class="nav">
-  <li class="nav-item">
-    <a class="nav-link active" href="#target-id">Item</a>
-  </li>
-</ul>
-{% endhighlight %}
-
-{% highlight html %}
-<nav class="nav">
-  <a class="nav-link active" href="#target-id">Item</a>
-</nav>
-{% endhighlight %}
-
-{% endcallout %}
-
-{% callout warning %}
-#### Requires relative positioning
-
-No matter the implementation method, scrollspy requires the use of `position: relative;` on the element you're spying on. In most cases this is the `<body>`. When scrollspying on elements other than the `<body>`, be sure to have a `height` set and `overflow-y: scroll;` applied.
-{% endcallout %}
+When successfully implemented, your nav or list group will update accordingly, moving the `.active` class from one item to the next based on their associated targets.
 
 ## Example in navbar
 
-Scroll the area below the navbar and watch the active class change. The dropdown sub items will be highlighted as well.
+Scroll the area below the navbar and watch the active class change. The dropdown items will be highlighted as well.
 
 <div class="bd-example">
   <nav id="navbar-example2" class="navbar navbar-light bg-faded">
@@ -118,9 +99,9 @@ Scroll the area below the navbar and watch the active class change. The dropdown
 </div>
 {% endhighlight %}
 
-## Example with sub-nav
+## Example with nested nav
 
-The ScrollSpy plugin also works with nested `.nav`s. If a sub-`.nav` is `.active`, it's parents will also be `.active`. Scroll the area next to the navbar and watch the active class change.
+Scrollspy also works with nested `.nav`s. If a nested `.nav` is `.active`, its parents will also be `.active`. Scroll the area next to the navbar and watch the active class change.
 
 <div class="bd-example">
   <div class="row">
@@ -201,7 +182,7 @@ The ScrollSpy plugin also works with nested `.nav`s. If a sub-`.nav` is `.active
 
 ## Example with list-group
 
-The ScrollSpy plugin also works with a `.list-group`. Scroll the area next to the list group and watch the active class change.
+Scrollspy also works with `.list-group`s. Scroll the area next to the list group and watch the active class change.
 
 <div class="bd-example">
   <div class="row">

scss/_nav.scss

@@ -33,15 +33,10 @@
 .nav-tabs {
   border-bottom: $nav-tabs-border-width solid $nav-tabs-border-color;
 
-  .nav-item,
-  .nav-link {
+  .nav-item {
     margin-bottom: -$nav-tabs-border-width;
   }
 
-  .nav-item .nav-link {
-    margin-bottom: 0;
-  }
-
   .nav-link {
     border: $nav-tabs-border-width solid transparent;
     @include border-top-radius($nav-tabs-border-radius);