From 26268c6362bcc4859c1c2bb304f9904f20c51a58 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Mon, 2 Mar 2015 18:17:41 -0800
Subject: [PATCH] Clarify that NOTE, etc., are separate block level elements

Summary: Fixes T6965.

Test Plan: Read documentation.

Reviewers: btrahan, chad

Reviewed By: chad

Subscribers: epriestley

Maniphest Tasks: T6965

Differential Revision: https://secure.phabricator.com/D11941
---
 src/docs/user/userguide/remarkup.diviner | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/docs/user/userguide/remarkup.diviner b/src/docs/user/userguide/remarkup.diviner
index d128861217..8e022c490c 100644
--- a/src/docs/user/userguide/remarkup.diviner
+++ b/src/docs/user/userguide/remarkup.diviner
@@ -258,18 +258,30 @@ You can use `lines=N` to limit the vertical size of a chunk of code, and
   <p>Mangostine</p>
   <p>Melon</p>
 
-You can also use `NOTE:`, `WARNING:`, or `IMPORTANT:` to call out an important
- idea.
+
+You can use the `NOTE:`, `WARNING:` or `IMPORTANT:` elements to call attention
+to an important idea.
+
+For example, write this:
+
+```
+NOTE: Best practices in proton pack operation include not crossing the streams.
+```
+
+...to produce this:
 
 NOTE: Best practices in proton pack operation include not crossing the streams.
 
+Using `WARNING:` or `IMPORTANT:` at the beginning of the line changes the
+color of the callout:
+
 WARNING: Crossing the streams can result in total protonic reversal!
 
 IMPORTANT: Don't cross the streams!
 
 In addition, you can use `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` to get the
 same effect but without `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` appearing in
-the rendered result. For example
+the rendered result. For example, this callout uses `(NOTE)`:
 
 (NOTE) Dr. Egon Spengler is the best resource for additional proton pack
  questions.