From 5114a4758d9b26fc5ecb30f4f4d2e544d0a1e434 Mon Sep 17 00:00:00 2001
From: Andrew Murphy <aavmurphy@users.noreply.github.com>
Date: Wed, 18 Oct 2017 22:28:09 +0100
Subject: [PATCH] Use the 'spacing' template. More examples

The most important change is to say "for the named breakpoint ( `sm`, `md`, `lg`, `xl`) and above".
The existing "hiding elements para" (not yet live) is exactly what's needed.
Keep simple for "english as a second language" people (e.g. hide not hidden)
---
 docs/4.0/utilities/display.md | 69 ++++++++++++++++++++---------------
 1 file changed, 40 insertions(+), 29 deletions(-)

diff --git a/docs/4.0/utilities/display.md b/docs/4.0/utilities/display.md
index bfb7f091ea..f62f5cd47e 100644
--- a/docs/4.0/utilities/display.md
+++ b/docs/4.0/utilities/display.md
@@ -6,20 +6,34 @@ group: utilities
 toc: true
 ---
 
-## Common `display` values
+## How it Works
 
-The [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) accepts a handful of values and we support many of them with utility classes. We purposefully don't provide every value as a utility, so here's what we support:
+Change the `display` value of elements with our responsive-friendly display utility classes.
 
-- `.d-none`
-- `.d-inline`
-- `.d-inline-block`
-- `.d-block`
-- `.d-table`
-- `.d-table-cell`
-- `.d-flex`
-- `.d-inline-flex`
+The [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/display) property accepts lots of values, and we support many of them with utility classes. We purposefully don't provide them all.
 
-Put them to use by applying any of the classes to an element of your choice. For example, here's how you could use the inline, block, or inline-block utilities (the same applies to the other classes).
+## Notation
+
+The classes are named using the format 
+* `d-{display}` - for all content
+* `d-{breakpoint}-{display}` - ** for the named breakpoint ( `sm`, `md`, `lg`, `xl`) and above.**
+
+Where *display* is one of:
+
+* `none`
+* `inline`
+* `inline-block`
+* `block`
+* `table`
+* `table-cell`
+* `flex`
+* `inline-flex`
+
+For example, `d-lg-none` sets `display:none` on screens larger than the lg breakpoint.
+
+Combine these classes to get the effect you need.
+
+## Examples
 
 {% example html %}
 <div class="d-inline bg-success">d-inline</div>
@@ -28,25 +42,9 @@ Put them to use by applying any of the classes to an element of your choice. For
 
 {% example html %}
 <span class="d-block bg-primary">d-block</span>
+<span class="d-block bg-primary">d-block</span>
 {% endexample %}
 
-{% example html %}
-<div class="d-inline-block bg-warning">d-inline-block</div>
-<div class="d-inline-block bg-warning">d-inline-block</div>
-{% endexample %}
-
-Responsive variations also exist for every single utility mentioned above.
-
-{% for bp in site.data.breakpoints %}
-- `.d{{ bp.abbr }}-none`
-- `.d{{ bp.abbr }}-inline`
-- `.d{{ bp.abbr }}-inline-block`
-- `.d{{ bp.abbr }}-block`
-- `.d{{ bp.abbr }}-table`
-- `.d{{ bp.abbr }}-table-cell`
-- `.d{{ bp.abbr }}-flex`
-- `.d{{ bp.abbr }}-inline-flex`{% endfor %}
-
 ## Hiding Elements
 
 For faster mobile-friendly development, use responsive display classes for showing and hiding elements by device. Avoid creating entirely different versions of the same site, instead hide element responsively for each screen size.
@@ -70,9 +68,14 @@ To show an element only on a given interval of screen sizes you can combine one
 | Visible only on lg | `d-none d-lg-block d-xl-none` |
 | Visible only on xl | `d-none d-xl-block` |
 
+{% example html %}
+<div class="d-lg-none">hide on screens wider than lg</div>
+<div class="d-none d-lg-block">hide on screens smaller than lg</div>
+{% endexample %}
+
 ## Display in print
 
-Change the `display` value of elements when printing with our print display utilities.
+Change the `display` value of elements when printing with our print display utility classes.
 
 | Class | Print style |
 | --- | --- |
@@ -80,3 +83,11 @@ Change the `display` value of elements when printing with our print display util
 | `.d-print-inline` | Applies `display: inline` to the element when printing |
 | `.d-print-inline-block` | Applies `display: inline-block` to the element when printing |
 | `.d-print-none` | Applies `display: none` to the element when printing |
+
+The print and display classes can be combined.
+
+{% example html %}
+<div class="d-print-none">Screen Only (hide on print)</div>
+<div class="d-none d-print-block">Print Only (hide on screen)</div>
+<div class="d-none d-lg-block d-print-block">(lg or wider) screen and print only. Hide on smaller than lg screen.</div>
+{% endexample %}