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

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())

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');

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