From 5333b16d7f1dc70f86c05cd9a718704f4aa71e95 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Mon, 16 Jan 2012 11:45:43 -0800
Subject: [PATCH] Clarify header block documentation

Summary: Make it more explicit that headers are block formatters, see T778.

Test Plan: Read docs.

Reviewers: davidreuss, btrahan, jungejason

Reviewed By: btrahan

CC: aran

Maniphest Tasks: T778

Differential Revision: https://secure.phabricator.com/D1420
---
 src/docs/userguide/remarkup.diviner | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/docs/userguide/remarkup.diviner b/src/docs/userguide/remarkup.diviner
index 5f470b6632..4320ed431d 100644
--- a/src/docs/userguide/remarkup.diviner
+++ b/src/docs/userguide/remarkup.diviner
@@ -14,17 +14,23 @@ This document describes how to format text using Remarkup.
 = Quick Reference =
 
 All the syntax is explained in more detail below, but this is a quick guide to
-formatting text in Remarkup:
+formatting text in Remarkup.
+
+These are inline styles, and can be applied to most text:
 
   **bold** //italic// ##monospaced##
-  = Large Header=
-  == Smaller Header ==
-  > Quoted Text
   D123 T123 rX123   # Link to Objects
   {D123} {T123}     # Link to Objects (Full Name)
   {F123}            # Embed Images
   [[wiki page]]     # Link to Phriction
   @username         # Mention a user
+
+These are block styles, and must be separated from surrounding text by
+empty lines:
+
+  = Large Header=
+  == Smaller Header ==
+  > Quoted Text
   Use "- " or "* " for list items.
   Use ``` or indent two spaces for code.
   Use %%% for a literal block.
@@ -45,10 +51,13 @@ respectively.
 Make **headers** like this:
 
   = Large Header =
+
   == Smaller Header ==
+
   ===== Very Small Header =====
 
-This produces headers like the ones in this document.
+This produces headers like the ones in this document. Make sure you have an
+empty line before and after the header.
 
 Make **lists** by beginning each item with a "-" or a "*":