Provide better general high-level documentation on mail commands

Summary: Ref T7199. This makes the page look less janky and provides more context about how mail commands work and how to use them.

Test Plan: {F355959}

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T7199

Differential Revision: https://secure.phabricator.com/D12245

src/applications/differential/application/PhabricatorDifferentialApplication.php

@@ -195,7 +195,11 @@ EOTEXT
     return array(
       'revision' => array(
         'name' => pht('Email Commands: Revisions'),
+        'header' => pht('Interacting with Differential Revisions'),
         'object' => new DifferentialRevision(),
+        'summary' => pht(
+          'This page documents the commands you can use to interact with '.
+          'revisions in Differential.'),
       ),
     );
   }

src/applications/maniphest/application/PhabricatorManiphestApplication.php

@@ -147,7 +147,12 @@ final class PhabricatorManiphestApplication extends PhabricatorApplication {
     return array(
       'task' => array(
         'name' => pht('Email Commands: Tasks'),
+        'header' => pht('Interacting with Maniphest Tasks'),
         'object' => new ManiphestTask(),
+        'summary' => pht(
+          'This page documents the commands you can use to interact with '.
+          'tasks in Maniphest. These commands work when creating new tasks '.
+          'via email and when replying to existing tasks.'),
       ),
     );
   }

src/applications/meta/controller/PhabricatorApplicationEmailCommandsController.php

@@ -33,7 +33,54 @@ final class PhabricatorApplicationEmailCommandsController
 
     $content = array();
 
+    $content[] = '= '.pht('Mail Commands Overview');
+    $content[] = pht(
+      'After configuring Phabricator to process inbound mail, you can '.
+      'interact with objects (like tasks and revisions) over email. For '.
+      'information on configuring Phabricator, see '.
+      '**[[ %s | Configuring Inbound Email ]]**.'.
+      "\n\n".
+      'In most cases, you can reply to email you receive from Phabricator '.
+      'to leave comments. You can also use **mail commands** to take a '.
+      'greater range of actions (like claming a task or requesting changes '.
+      'to a revision) without needing to log in to the web UI.'.
+      "\n\n".
+      'Mail commands are keywords which start with an exclamation point, '.
+      'like `!claim`. Some commands may take parameters, like '.
+      '`!assign alincoln`.'.
+      "\n\n".
+      'To use mail commands, write one command per line at the beginning '.
+      'or end of your mail message. For example, you could write this in a '.
+      'reply to task email to claim the task:'.
+      "\n\n".
+
+      "```\n".
+      "!claim\n".
+      "\n".
+      "I'll take care of this.\n".
+      "```\n".
+
+      "\n\n".
+      "When Phabricator receives your mail, it will process any commands ".
+      "first, then post the remaining message body as a comment. You can ".
+      "execute multiple commands at once:".
+      "\n\n".
+
+      "```\n".
+      "!assign alincoln\n".
+      "!close\n".
+      "\n".
+      "I just talked to @alincoln, and he showed me that he fixed this.\n".
+      "```\n",
+      PhabricatorEnv::getDoclink('Configuring Inbound Email'));
+
+    $content[] = '= '.$spec['header'];
+    $content[] = $spec['summary'];
+
     $content[] = '= '.pht('Quick Reference');
+    $content[] = pht(
+      'This table summarizes the available mail commands. For details on a '.
+      'specific command, see the command section below.');
     $table = array();
     $table[] = '| '.pht('Command').' | '.pht('Summary').' |';
     $table[] = '|---|---|';
@@ -84,22 +131,34 @@ final class PhabricatorApplicationEmailCommandsController
     $this->addApplicationCrumb($crumbs, $selected);
     $crumbs->addTextCrumb($title);
 
-    $content_box = id(new PHUIBoxView())
-      ->addMargin(PHUI::MARGIN_LARGE)
-      ->appendChild(
-        PhabricatorMarkupEngine::renderOneObject(
-          id(new PhabricatorMarkupOneOff())->setContent($content),
-          'default',
-          $viewer));
+    $content_box = PhabricatorMarkupEngine::renderOneObject(
+      id(new PhabricatorMarkupOneOff())->setContent($content),
+      'default',
+      $viewer);
 
-    $box = id(new PHUIObjectBoxView())
-      ->setHeaderText($title)
+    $info_view = null;
+    if (!PhabricatorEnv::getEnvConfig('metamta.reply-handler-domain')) {
+      $error = pht(
+        "Phabricator is not currently configured to accept inbound mail. ".
+        "You won't be able to interact with objects over email until ".
+        "inbound mail is set up.");
+      $info_view = id(new PHUIInfoView())
+        ->setErrors(array($error));
+    }
+
+    $header = id(new PHUIHeaderView())
+      ->setHeader($title);
+
+    $document = id(new PHUIDocumentView())
+      ->setHeader($header)
+      ->setFontKit(PHUIDocumentView::FONT_SOURCE_SANS)
+      ->appendChild($info_view)
       ->appendChild($content_box);
 
     return $this->buildApplicationPage(
       array(
         $crumbs,
-        $box,
+        $document,
       ),
       array(
         'title' => $title,