From 7bee68a763bdd5c2244387a7191941f28f07f56b Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Mon, 30 Jan 2012 15:56:42 -0800
Subject: [PATCH] Document configuration of external editor links

Summary: Provide some documentation for this feature since it's not super
obvious how it works.

Test Plan: Generated documentation, read documentation.

Reviewers: btrahan, vrana, jungejason, nh

Reviewed By: vrana

CC: aran, epriestley

Differential Revision: https://secure.phabricator.com/D1521
---
 ...rUserPreferenceSettingsPanelController.php | 13 +++++-
 .../settings/panels/preferences/__init__.php  |  1 +
 src/docs/userguide/external_editor.diviner    | 46 +++++++++++++++++++
 3 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 src/docs/userguide/external_editor.diviner

diff --git a/src/applications/people/controller/settings/panels/preferences/PhabricatorUserPreferenceSettingsPanelController.php b/src/applications/people/controller/settings/panels/preferences/PhabricatorUserPreferenceSettingsPanelController.php
index 9a5e390972..2ce95ac507 100644
--- a/src/applications/people/controller/settings/panels/preferences/PhabricatorUserPreferenceSettingsPanelController.php
+++ b/src/applications/people/controller/settings/panels/preferences/PhabricatorUserPreferenceSettingsPanelController.php
@@ -51,6 +51,14 @@ function helloWorld() {
 }
 EXAMPLE;
 
+    $editor_doc_link = phutil_render_tag(
+      'a',
+      array(
+        'href' => PhabricatorEnv::getDoclink(
+          'article/User_Guide:_Configuring_an_External_Editor.html'),
+      ),
+      'User Guide: Configuring an External Editor');
+
     $form = id(new AphrontFormView())
       ->setUser($user)
       ->setAction('/settings/page/preferences/')
@@ -72,8 +80,9 @@ EXAMPLE;
         ->setName($pref_editor)
         ->setCaption(
           'Link to edit files in external editor. '.
-          '%f is replaced by filename, %l by line number, %r by repository. '.
-          'Example: editor://open/?file=%f&line=%l&repository=%r')
+          '%f is replaced by filename, %l by line number, %r by repository '.
+          'callsign. '.
+          "For documentation, see {$editor_doc_link}.")
         ->setValue($preferences->getPreference($pref_editor)))
       ->appendChild(
         id(new AphrontFormTextControl())
diff --git a/src/applications/people/controller/settings/panels/preferences/__init__.php b/src/applications/people/controller/settings/panels/preferences/__init__.php
index 363519818b..6e7841731d 100644
--- a/src/applications/people/controller/settings/panels/preferences/__init__.php
+++ b/src/applications/people/controller/settings/panels/preferences/__init__.php
@@ -9,6 +9,7 @@
 phutil_require_module('phabricator', 'aphront/response/redirect');
 phutil_require_module('phabricator', 'applications/people/controller/settings/panels/base');
 phutil_require_module('phabricator', 'applications/people/storage/preferences');
+phutil_require_module('phabricator', 'infrastructure/env');
 phutil_require_module('phabricator', 'view/form/base');
 phutil_require_module('phabricator', 'view/form/control/markup');
 phutil_require_module('phabricator', 'view/form/control/select');
diff --git a/src/docs/userguide/external_editor.diviner b/src/docs/userguide/external_editor.diviner
new file mode 100644
index 0000000000..c66a4e3186
--- /dev/null
+++ b/src/docs/userguide/external_editor.diviner
@@ -0,0 +1,46 @@
+@title User Guide: Configuring an External Editor
+@group userguide
+
+Setting up an external editor to integrate with Diffusion and Differential.
+
+= Overview =
+
+You can configure a URI handler to allow you to open files from Differential
+and Diffusion in your preferred text editor.
+
+= Configuring Editors =
+
+To configure an external editor, go to Settings -> Application Settings ->
+Display Preferences and set "Editor Link" to a URI pattern (see below). This
+will enable an "Open in Editor" link in Differential, and an "Edit" button in
+Diffusion.
+
+In general, you'll set this field to something like:
+
+  lang=uri
+  editor://open/?file=%f
+
+== Configuring: TextMate on OS X ==
+
+TextMate installs a ##txmt://## handler by default, so it's easy to configure
+this feature if you use TextMate.
+
+First, create a local directory with symlinks for each repository callsign. For
+example, if you're developing Phabricator, it might look like this:
+
+  /Users/alincoln/editor_links/ $ ls -l
+  ... ARC -> /Users/alincoln/workspace/arcanist/
+  ... P -> /Users/alincoln/workspace/phabricator/
+  ... PHU -> /Users/alincoln/workspace/libphutil/
+
+Then set your "Editor Link" to:
+
+  lang=uri
+  txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l
+
+== Configuring: Other Editors ==
+
+General instructions for configuring some other editors and environments can be
+found here:
+
+  http://wiki.nette.org/en/howto-editor-link
\ No newline at end of file