split out and tweek content for advancd and faqs

docs/extensions/advanced.md

+# Advanced patterns
+
+[]( FIXME remove this banner after review)
+>> NOTE: Some of these instruction maybe deprecated and superceded by better
+>> approaches.
+
+## Web Services
+
+There are three options to create an ajax or web-service callback:
+
+-   **Full control:**Add a basic page. Remove the parent::run() call
+    from the run() function, and at the bottom of the run() function,
+    perform your own output (eg "*echo json\_encode($data)*") and then
+    short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so
+    that neither Smarty nor the CMS modify the output.
+-   **Using ajax helpers (CiviCRM 4.5 and above**): Generate a page with
+    civix as above. Build your data in the run() function. If the
+    client-side request includes *snippet=json* in the url, just append
+    your data to *$this-\>ajaxResponse* array and the rest will happen
+    automatically. If not, you can directly call
+    CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run
+    function. See [Ajax Pages and
+    Forms](/confluence/display/CRMDOC/Ajax+Pages+and+Forms)
+    documentation.
+-   **Using the API:** Add an API function using `civix`.
+    The API function can be called with the API's [AJAX
+    Interface](http://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
+    This automatically handles issues like encoding and decoding the
+    request/response.
+
+## Standalone PHP scripts
+
+Instead of creating a standalone script, consider one of these options:
+
+-   Add an API function (using the instructions above). The API function
+    can be called many different ways – cv, PHP, REST, AJAX, CLI, Drush,
+    Smarty, cron, etc. CiviCRM used to include a number of standalone
+    scripts – many of these have been migrated to API functions because
+    this approach is simpler and more flexible.
+-   Add a basic page (using the instructions above). At the bottom of
+    the run() function, call "*CRM\_Utils\_System::civiExit()*" to
+    short-circuit theming and CMS processing.
+
+Creating a pure standalone PHP script is a tricky proposition and likely to be
+brittle compared with the above.
+
+If the script is truly standalone and
+does not require any services from the CRM or CMS, then you can just add a
+new `.php` file to the extension... but it won't have access to CiviCRM's
+APIs, databases, classes, etc. If the standalone script needs those
+services, then it will need to ***bootstrap*** CiviCRM and the CMS. This
+is challenging for several reasons:
+
+-   The bootstrap mechanics are different in each CMS (Drupal, Joomla,
+    etc).
+-   The bootstrap mechanics are different for single-site installations
+    and multi-site installations
+-   To initiate a bootstrap from a script, one needs to determine the
+    local-path to the CiviCRM settings. However, the local-path of the
+    script is entirely independent of the local-path to the settings –
+    these are determined at the discretion of the site administrator.
+
+If you really need to do it, it's theoretically possibly to emulate an
+example like
+"[bin/deprecated/EmailProcessor.php](http://svn.civicrm.org/civicrm/branches/v4.1/bin/deprecated/EmailProcessor.php)".
+The results will likely be difficult for downstream users to
+install/use.
+
+
+## Cron jobs
+
+One can add an API function (using the instructions above) and create a
+schedule record. In CiviCRM 4.3, the schedule record can be
+automatically created; to do this, call "civix
+[generate:api](http://generateapi)" with the option "–schedule Daily"
+(or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet
+the stated schedule.
+
+In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record
+won't be created automatically. The site administrator must manually
+insert a scheduling record by navigating to "Administer =\> System
+Settings =\> Scheduled Jobs".
+

docs/extensions/civix.md

@@ -545,101 +545,3 @@ how to write a test class:
     PHPUnit.](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html)
 -   Review the example code in
     [org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests)
-
-# Frequently asked questions
-
-### How does one add an ajax/web-service callback?
-
-There are three options:
-
--   **Full control:**Add a basic page. Remove the parent::run() call
-    from the run() function, and at the bottom of the run() function,
-    perform your own output (eg "*echo json\_encode($data)*") and then
-    short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so
-    that neither Smarty nor the CMS modify the output.
--   **Using ajax helpers (CiviCRM 4.5 and above**): Generate a page with
-    civix as above. Build your data in the run() function. If the
-    client-side request includes *snippet=json* in the url, just append
-    your data to *$this-\>ajaxResponse* array and the rest will happen
-    automatically. If not, you can directly call
-    CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run
-    function. See [Ajax Pages and
-    Forms](/confluence/display/CRMDOC/Ajax+Pages+and+Forms)
-    documentation.
--   **Using the API:** Add an API function using the instructions above.
-    The API function can be called with the API's [AJAX
-    Interface](http://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
-    This automatically handles issues like encoding and decoding the
-    request/response.
-
-### How does one add a standalone PHP script?
-
-This is tricky proposition. If the script is truly standalone and
-doesn't require any services from the CRM/CMS, then you can just add a
-new .php file to the extension... but it won't have access to CiviCRM's
-APIs, databases, classes, etc. If the standalone script needs those
-services, then it will need to ***bootstrap*** CiviCRM and the CMS. This
-is challenging for several reasons:
-
--   The bootstrap mechanics are different in each CMS (Drupal, Joomla,
-    etc).
--   The bootstrap mechanics are different for single-site installations
-    and multi-site installations
--   To initiate a bootstrap from a script, one needs to determine the
-    local-path to the CiviCRM settings. However, the local-path of the
-    script is entirely independent of the local-path to the settings –
-    these are determined at the discretion of the site administrator.
-
-If you really need to do it, it's theoretically possibly to emulate an
-example like
-"[bin/deprecated/EmailProcessor.php](http://svn.civicrm.org/civicrm/branches/v4.1/bin/deprecated/EmailProcessor.php)".
-The results will likely be difficult for downstream users to
-install/use.
-
-Instead of creating a standalone script, consider one of these options:
-
--   Add an API function (using the instructions above). The API function
-    can be called many different ways – PHP, REST, AJAX, CLI, Drush,
-    Smarty, cron, etc. CiviCRM used to include a number of standalone
-    scripts – many of these have been migrated to API functions because
-    this approach is simpler and more flexible.
--   Add a basic page (using the instructions above). At the bottom of
-    the run() function, call "*CRM\_Utils\_System::civiExit()*" to
-    short-circuit theming and CMS processing.
-
-### How does one add a cron job?
-
-One can add an API function (using the instructions above) and create a
-schedule record. In CiviCRM 4.3, the schedule record can be
-automatically created; to do this, call "civix
-[generate:api](http://generateapi)" with the option "–schedule Daily"
-(or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet
-the stated schedule.
-
-In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record
-won't be created automatically. The site administrator must manually
-insert a scheduling record by navigating to "Administer =\> System
-Settings =\> Scheduled Jobs".
-
-# Troubleshooting
-
-1.  I've created the files and edited them but I don't see the expected
-    changes.\
-     A: Did you install and enable your extension?
-    (<site\>/civicrm/admin/extensions?reset=1)\
-     \
-
-2.  I get Error: "Cannot instantiate API client -- please set connection
-    options in parameters.yml"\
-     A: You might have missed the step about setting
-    'civicrm\_api3\_conf\_path'
-    ([https://github.com/totten/civix/](https://github.com/totten/civix/)),
-    or it didn't get set properly for some reason.\
-     \
-3.  I've tried to generate a page/report/search/upgrader/etc but it's
-    not working.\
-     A: For all of the various types, you must first run
-    [generate:module](http://generatemodule), and then \`cd\` into the
-    folder (e.g. com.example.myextension) before running one of the
-    other \`generate:\` commands.
-

docs/extensions/troubleshooting.md

+# Troubleshooting
+
+If you are struggling, the best thing to do is reach out to the
+[CiviCRM community](../basics/community).
+
+If you cannot find the answer in this guide or by searching in the
+[CiviCRM StackExchange site](http://civicrm.stackexchange.com/)
+then please [ask](http://civicrm.stackexchange.com/questions/ask). Asking
+questions on StackExchange not only helps you but may well help others who
+follow you.
+
+That said, this is a small list of some of the commoner problems extension
+writers encounter.
+
+## Extension not doing anything
+
+[]( ###### arguably this list should be removed altogether?? #### )
+
+Q: I've created the files and edited them but I don't see the expected
+changes.
+
+A: Did you install and enable your extension?
+(<site\>/civicrm/admin/extensions?reset=1)
+
+## Civix error messages
+
+Q: I get Error: "Cannot instantiate API client -- please set connection
+options in parameters.yml"
+
+A: You might have missed the step about setting
+'civicrm\_api3\_conf\_path'
+([https://github.com/totten/civix/](https://github.com/totten/civix/)),
+or it didn't get set properly for some reason.
+
+Q: I've tried to generate a page/report/search/upgrader/etc with civix
+but it's not working.
+
+A: For all of the various types, you must first run
+[generate:module](http://generatemodule), and then \`cd\` into the
+folder (e.g. com.example.myextension) before running one of the
+other \`generate:\` commands.
+

mkdocs.yml

@@ -25,8 +25,10 @@ pages:
    - All Available Hooks: hooks-db.md
 - Writing Extensions:
   - Basics: extensions/basics.md
-  - civix: extensions/civix.md
+  - Using civix: extensions/civix.md
   - Anatomy of Files: extensions/files.md
+  - Advanced Patterns: extensions/advanced.md
+  - Troubleshooting: extensions/troubleshooting.md
   # - Using hooks: extensions/using-hooks.md
   # - Customizing Screens: extensions/customize-screens.md
   # - Creating Pages: Forms/extensions/create-page.md