From ab9c6f10d06053f2465bc2a7caa13c85d83f5752 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Fri, 17 Feb 2012 19:39:13 -0800
Subject: [PATCH] Improve remarkup documentation

Summary:
Some user feedback:

  - Named link information not present in quick reference.
  - Named link information buried in Phriction docs.
  - Optional omission of trailing "=" in headers not documented.

Fix these things.

Test Plan: generated, read documentation

Reviewers: btrahan, paularmstrong, Josereyes

Reviewed By: btrahan

CC: aran, epriestley

Maniphest Tasks: T884

Differential Revision: https://secure.phabricator.com/D1637
---
 src/docs/userguide/remarkup.diviner | 34 +++++++++++++++++++----------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/docs/userguide/remarkup.diviner b/src/docs/userguide/remarkup.diviner
index 97e4bdf9ac..64c747deb7 100644
--- a/src/docs/userguide/remarkup.diviner
+++ b/src/docs/userguide/remarkup.diviner
@@ -19,16 +19,20 @@ formatting text in Remarkup.
 These are inline styles, and can be applied to most text:
 
   **bold** //italic// ##monospaced##
-  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
+  D123 T123 rX123           # Link to Objects
+  {D123} {T123}             # Link to Objects (Full Name)
+  {F123}                    # Embed Images
+  @username                 # Mention a user
+  [[wiki page]]             # Link to Phriction
+  [[wiki page | name]]      # Named link to Phriction
+  http://xyz/               # Link to web
+  [[http://xyz/ | name]]    # Named link to web
+
 
 These are block styles, and must be separated from surrounding text by
 empty lines:
 
-  = Large Header=
+  = Large Header =
   == Smaller Header ==
   > Quoted Text
   Use "- " or "* " for list items.
@@ -56,6 +60,12 @@ Make **headers** like this:
 
   ===== Very Small Header =====
 
+You can optionally omit the trailing "=" signs -- that is, these are the same:
+
+  == Smaller Header ==
+
+  == Smaller Header
+
 This produces headers like the ones in this document. Make sure you have an
 empty line before and after the header.
 
@@ -176,6 +186,12 @@ If you have a URI with problematic characters in it, like
 
 This will force the parser to consume the whole URI: <http://comma.org/,>
 
+You can also use create named links, where you choose the displayed text. These
+work within Phabricator or on the internet at large:
+
+  [[/herald/transcript/ | Herald Transcripts]]
+  [[http://www.boring-legal-documents.com/ | exciting legal documents]]
+
 = Linking to Objects =
 
 You can link to Differential revisions, Diffusion commits and Maniphest tasks
@@ -270,12 +286,6 @@ opponents:
 
   Check out these [[legal/boring_documents/ | exciting legal documents]]!
 
-You can also use this as an explicit syntax for other web links, either within
-Phabricator or on the internet at large:
-
-  [[/herald/transcript/ | Herald Transcripts]]
-  [[http://www.boring-legal-documents.com/ | exciting legal documents]]
-
 = Literal Blocks =
 
 To place text in a literal block use "%%%":