From 025b243e27419a3a471cae677fbcd8df019a7284 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Sat, 16 Apr 2016 08:48:05 -0700
Subject: [PATCH] Document wiki relative link syntax

Summary: Also make `../` work to start relative a link so I don't have to document it as `./../path`.

Test Plan:
  - Used `./`, `../`. `./../`, and normal links (proper title pickup).
  - Used bad links (red).
  - Regenerated documentation:

{F1221692}

Reviewers: hach-que

Reviewed By: hach-que

Differential Revision: https://secure.phabricator.com/D15734
---
 .../markup/PhrictionRemarkupRule.php          |  4 ++--
 src/docs/user/userguide/remarkup.diviner      | 23 +++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/applications/phriction/markup/PhrictionRemarkupRule.php b/src/applications/phriction/markup/PhrictionRemarkupRule.php
index 99a9d1bdd4..2c9ab76284 100644
--- a/src/applications/phriction/markup/PhrictionRemarkupRule.php
+++ b/src/applications/phriction/markup/PhrictionRemarkupRule.php
@@ -19,7 +19,7 @@ final class PhrictionRemarkupRule extends PhutilRemarkupRule {
     $link = trim($matches[1]);
 
     // Handle relative links.
-    if (substr($link, 0, 2) === './') {
+    if ((substr($link, 0, 2) === './') || (substr($link, 0, 3) === '../')) {
       $base = null;
       $context = $this->getEngine()->getConfig('contextObject');
       if ($context !== null && $context instanceof PhrictionContent) {
@@ -33,7 +33,7 @@ final class PhrictionRemarkupRule extends PhutilRemarkupRule {
       }
       if ($base !== null) {
         $base_parts = explode('/', rtrim($base, '/'));
-        $rel_parts = explode('/', substr(rtrim($link, '/'), 2));
+        $rel_parts = explode('/', rtrim($link, '/'));
         foreach ($rel_parts as $part) {
           if ($part === '.') {
             // Consume standalone dots in a relative path, and do
diff --git a/src/docs/user/userguide/remarkup.diviner b/src/docs/user/userguide/remarkup.diviner
index 379c09e5c3..606a9db3e7 100644
--- a/src/docs/user/userguide/remarkup.diviner
+++ b/src/docs/user/userguide/remarkup.diviner
@@ -512,11 +512,34 @@ You can link to Phriction documents with a name or path:
 
   Make sure you sign and date your [[legal/Letter of Marque and Reprisal]]!
 
+By default, the link will render with the document title as the link name.
 With a pipe (`|`), you can retitle the link. Use this to mislead your
 opponents:
 
   Check out these [[legal/boring_documents/ | exciting legal documents]]!
 
+Links to pages which do not exist are shown in red. Links to pages which exist
+but which the viewer does not have permission to see are shown with a lock
+icon, and the link will not disclose the page title.
+
+If you begin a link path with `./` or `../`, the remainder of the path will be
+evaluated relative to the current wiki page. For example, if you are writing
+content for the document `fruit/` a link to `[[./guava]]` is the same as a link
+to `[[fruit/guava]]` from elsewhere.
+
+Relative links may use `../` to transverse up the document tree. From the
+`produce/vegetables/` page, you can use `[[../fruit/guava]]` to link to the
+`produce/fruit/guava` page.
+
+Relative links do not work when used outside of wiki pages. For example,
+you can't use a relative link in a comment on a task, because there is no
+reasonable place for the link to start resolving from.
+
+When documents are moved, relative links are not automatically updated: they
+are preserved as currently written. After moving a document, you may need to
+review and adjust any relative links it contains.
+
+
 = Literal Blocks =
 
 To place text in a literal block use `%%%`: