Docs - expand documentation on custom fields for selects a bit

Summary: ...and fix an error where lines that start with ##X## are rendering incorrectly by switching to alternate syntax `X`. Fixes T5806.

Test Plan: read the docs and they looked good

Reviewers: epriestley

Reviewed By: epriestley

Subscribers: epriestley, Korvin

Maniphest Tasks: T5806

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

src/docs/contributor/javascript_coding_standards.diviner

@@ -107,7 +107,7 @@ see @{article:Javascript Object and Array}.
       break;
   }
 
-##break## statements should be indented to block level. If you don't push them
+`break` statements should be indented to block level. If you don't push them
 in, you end up with an inconsistent rule for conditional ##break## statements,
 as in the ##2## case.
 

src/docs/contributor/php_coding_standards.diviner

@@ -112,7 +112,7 @@ visually and react better to "Find Next..." in editors.
       break;
   }
 
-##break## statements should be indented to block level.
+`break` statements should be indented to block level.
 
 **array literals:**
 

src/docs/contributor/using_oauthserver.diviner

@@ -6,7 +6,7 @@ How to use the Phabricator OAuth Server.
 = Overview =
 
 Phabricator includes an OAuth Server which supports the
-##Authorization Code Grant## flow as described in the OAuth 2.0
+`Authorization Code Grant` flow as described in the OAuth 2.0
 specification:
 
 http://tools.ietf.org/html/draft-ietf-oauth-v2-23

src/docs/flavor/javascript_pitfalls.diviner

@@ -29,7 +29,7 @@ usually after operators.
 
 = ##with## is Bad News =
 
-##with## is a pretty bad feature, for this reason among others:
+`with` is a pretty bad feature, for this reason among others:
 
   with (object) {
     property = 3; // Might be on object, might be on window: who knows.

src/docs/flavor/php_pitfalls.diviner

@@ -153,13 +153,13 @@ Strongly prefer the ##key## varieties.
 = array_uintersect() and array_udiff() are Definitely Slow Too =
 
 These functions have the problems of both the ##usort()## family and the
-##array_diff()## family. Avoid them.
+`array_diff()` family. Avoid them.
 
 = foreach() Does Not Create Scope =
 
 Variables survive outside of the scope of foreach(). More problematically,
 references survive outside of the scope of foreach(). This code mutates
-##$array## because the reference leaks from the first loop to the second:
+`$array` because the reference leaks from the first loop to the second:
 
   COUNTEREXAMPLE
   $array = range(1, 3);
@@ -276,7 +276,7 @@ This doesn't do what you'd expect it to do in C:
 
 This is because the successor to 'z' is 'aa', which is "less than" 'z'. The
 loop will run for ~700 iterations until it reaches 'zz' and terminates. That is,
-##$c## will take on these values:
+`$c` will take on these values:
 
   a
   b

src/docs/tech/celerity.diviner

@@ -46,7 +46,7 @@ appropriate references to CSS and JS resources. It uses
 resources (so you only have to explicitly include what you're actually using,
 and not all of its dependencies) and any packaging rules (so it may be able to
 generate fewer resource requests, improving performance). It then generates
-##<script />## and ##<link />## references to these resources.
+`<script />` and `<link />` references to these resources.
 
 These references point at ##/res/## URIs, which are handled by
 @{class:CelerityResourceController}. It responds to these requests and delivers

src/docs/tech/chatbot.diviner

@@ -67,7 +67,7 @@ servers and in different languages.
 
 To allow the bot to access Conduit, you need to create a user that it can login
 with. To do this, login to Phabricator as an administrator and go to
-##People -> Create New Account##. Create a new account and flag them as a
+`People -> Create New Account`. Create a new account and flag them as a
 "Bot/Script". Then in your configuration file, set these parameters:
 
   - ##conduit.uri## The URI for your Phabricator install, like

src/docs/tech/conduit.diviner

@@ -44,7 +44,7 @@ handles.
 
 There is a web interface for viewing and testing Conduit called the "Conduit
 Console", implemented by @{class:PhabricatorConduitConsoleController} at
-##/conduit/##.
+`/conduit/`.
 
 A log of connections and calls is stored by
 @{class:PhabricatorConduitConnectionLog} and
@@ -52,6 +52,6 @@ A log of connections and calls is stored by
 @{class:PhabricatorConduitLogController} at ##/conduit/log/##.
 
 Conduit provides a token-based handshake mechanism used by
-##arc install-certificate## at ##/conduit/token/##, implemented by
+`arc install-certificate` at `/conduit/token/`, implemented by
 @{class:PhabricatorConduitTokenController} which stores generated tokens using
 @{class:PhabricatorConduitCertificateToken}.

src/docs/tech/files.diviner

@@ -36,4 +36,4 @@ order to make files actually get written to it, you also need to extend
 @{class:PhabricatorFileStorageEngineSelector}, provide an implementation which
 selects your storage engine for whatever files you want to store there, and then
 configure Phabricator to use your selector by setting
-##storage.engine-selector##.
+`storage.engine-selector`.

src/docs/user/configuration/configuring_accounts_and_registration.diviner

@@ -44,7 +44,7 @@ administrative user.
 = Managing Accounts with the Web Console =
 
 To manage accounts from the web, login as an administrator account and go to
-##/people/## or click "People" on the homepage. Provided you're an admin,
+`/people/` or click "People" on the homepage. Provided you're an admin,
 you'll see options to create or edit accounts.
 
 = Manually Creating New Accounts =

src/docs/user/configuration/configuring_inbound_email.diviner

@@ -179,7 +179,7 @@ If you get a linker error like this:
 
 ...you need to edit your php.ini file so that mbstring.so is loaded **before**
 mailparse.so. This is not the default if you have individual files in
-##php.d/##.
+`php.d/`.
 
 = Local MTA: Configuring Sendmail =
 
@@ -197,13 +197,13 @@ probably means something like this:
   - restart sendmail.
 
 Now, you can actually configure sendmail to deliver to Phabricator. In
-##/etc/aliases##, add an entry like this:
+`/etc/aliases`, add an entry like this:
 
   phabricator: "| /path/to/phabricator/scripts/mail/mail_handler.php <ENV>"
 
 ...where <ENV> is the PHABRICATOR_ENV the script should run under. Run
-##sudo newaliases##. Now you likely need to symlink this script into
+`sudo newaliases`. Now you likely need to symlink this script into
-##/etc/smrsh/##:
+`/etc/smrsh/`:
 
   sudo ln -s /path/to/phabricator/scripts/mail/mail_handler.php /etc/smrsh/
 
@@ -213,7 +213,7 @@ Finally, edit ##/etc/mail/virtusertable## and add an entry like this:
 
 That will forward all mail to @yourdomain.com to the Phabricator processing
 script. Run ##sudo /etc/mail/make## or similar and then restart sendmail with
-##sudo /etc/init.d/sendmail restart##.
+`sudo /etc/init.d/sendmail restart`.
 
 = Local MTA: Configuring Lamson =
 

src/docs/user/configuration/custom_fields.diviner

@@ -59,10 +59,18 @@ value of `maniphest.custom-field-definitions`):
       "type": "int",
       "caption": "Actual number of hours this took."
     },
+    "mycompany:company-jobs": {
+      "name": "Job Role",
+      "type: "select",
+      "options": {
+        "mycompany:engineer": "Engineer",
+        "mycompany:nonengineer": "Other"
+      }
+    },
     "mycompany:favorite-dinosaur": {
       "name": "Favorite Dinosaur",
       "type": "text"
-    }
+    },
   }
 
 The fields will then appear in the other config option for the application
@@ -82,8 +90,8 @@ When defining custom fields using a configuration option like
     - **int**: An integer, rendered as a text field.
     - **text**: A string, rendered as a text field.
     - **bool**: A boolean value, rendered as a checkbox.
-    - **select**: Allows the user to select from several options, rendered
+    - **select**: Allows the user to select from several options as defined
-      as a dropdown.
+      by **options**, rendered as a dropdown.
     - **remarkup**: A text area which allows the user to enter markup.
     - **users**: A typeahead which allows multiple users to be input.
     - **date**: A date/time picker.

src/docs/user/installation_guide.diviner

@@ -73,7 +73,7 @@ document for you:
 
 If those work for you, you can skip directly to the
 @{article:Configuration Guide}. These scripts are also available in the
-##scripts/install## directory in the project itself.
+`scripts/install` directory in the project itself.
 
 Otherwise, here's a general description of what you need to install:
 

src/docs/user/userguide/arcanist_lint_unit.diviner

@@ -57,13 +57,13 @@ When you run ##arc list --trace##, you should see a message to the effect that
 it has loaded your library.
 
 For debugging or testing, you can also run Arcanist with the
-##--load-phutil-library## flag:
+`--load-phutil-library` flag:
 
   arc --load-phutil-library=/path/to/library <command>
 
 You can specify this flag more than once to load several libraries. Note that
 if you use this flag, Arcanist will ignore any libraries listed in
-##.arcconfig##.
+`.arcconfig`.
 
 = Use the Class =
 

src/docs/user/userguide/diffusion_symbols.diviner

@@ -61,7 +61,7 @@ write such a script, and run this command to see its output:
   $ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
 
 To actually build the symbol index, pipe this data to the
-##import_project_symbols.php## script, providing the project name:
+`import_project_symbols.php` script, providing the project name:
 
   $ ./scripts/symbols/import_project_symbols.php yourproject < symbols_data
 
@@ -77,7 +77,7 @@ configuration.
 To configure Differential integration, you need to tell Phabricator which
 projects have symbol indexes you want to use, and which other projects they
 should pull symbols from. To do this, go to
-##Repositories -> Arcanist Projects -> Edit## as an administrator. You need to
+`Repositories -> Arcanist Projects -> Edit` as an administrator. You need to
 fill out these fields:
 
   - **Repository**: Associate the project with a tracked repository.

src/docs/user/userguide/libraries.diviner

@@ -80,7 +80,7 @@ step.
 But, if you intend to use this library with Phabricator, you need to define its
 dependency on Phabricator by creating a ##.arcconfig## file which points at
 Phabricator. For example, you might write this file to
-##libcustom/.arcconfig##:
+`libcustom/.arcconfig`:
 
   {
     "project.name" : "libcustom",
@@ -134,7 +134,7 @@ invoke, so your code will keep working as the upstream changes.
 
 When developing libraries to work with libphutil, Arcanist and Phabricator, you
 should respect method and property visibility and extend only classes marked
-##@stable##. They are rendered with a large callout in the documentation (for
+`@stable`. They are rendered with a large callout in the documentation (for
 example: @{class@libphutil:AbstractDirectedGraph}). These classes are external
 interfaces intended for extension.
 

src/docs/user/userguide/mail_rules.diviner

@@ -35,7 +35,7 @@ Phabricator sends a variety of mail headers that can be useful in crafting rules
 to route and manage mail.
 
 Headers in plural contain lists. A list containing two items, ##1## and
-##15## will generally be formatted like this:
+`15` will generally be formatted like this:
 
   X-Header: <1>, <15>
 

src/docs/user/userguide/remarkup.diviner

@@ -213,7 +213,7 @@ This produces a block like this:
   }
 
 You can use ##lines=N## to limit the vertical size of a chunk of code, and
-##name=some_name.ext## to give it a name. For example, this:
+`name=some_name.ext` to give it a name. For example, this:
 
   lang=text
   lang=html, name=example.html, lines=12, counterexample