doc updates - connecting to services

4 files changed, 188 insertions, 134 deletions

diff --git a/doc/Account-Basics.md b/doc/Account-Basics.md
index 359e9165e..9c6548430 100644
--- a/doc/Account-Basics.md
+++ b/doc/Account-Basics.md
@@ -54,16 +54,6 @@ Otherwise, enter your password. This will have been initially provided in your r
 After your first login, please visit the 'Settings' page from the top menu bar and change your password to something that you will remember.
 
 
-**Facebook Connector**
-
-The Facebook connector is a plugin/addon which allows you to interact with friends on Facebook from within Friendika. If enabled, your Facebook friend list will be imported, and you will see and be able to respond to Facebook posts. Facebook members may also be added to private conversation groups.  
-
-Assuming the Facebook plugin/addon has been installed on your system, it can be enabled by going to your Settings page, clicking "Plugin Settings" near the top of the page, and then select "Facebook Connector Settings" on that page. This will only appear if the Facebook plugin/addon has been installed. Follow the instruction to install or remove the Facebook connector.
-
-You may also choose whether your public postings are posted to Facebook by default. You may toggle this setting at any time from the Permissions settings of the status post editor (click the lock icon). This setting has no effect on private conversations - which will always be delivered to Facebook friends who are included in the permissions.  
-
-(Note: At this time, Facebook contacts will not be able to view any private photos. This will be resolved in a future release. They may however see any public photos you have uploaded.)
-
 
 **See Also**
 
diff --git a/doc/Connectors.md b/doc/Connectors.md
index f1febb09b..45bce8d9a 100644
--- a/doc/Connectors.md
+++ b/doc/Connectors.md
@@ -1,154 +1,63 @@
-Installing Connectors (Facebook/Twitter/StatusNet)
-==================================================
+Connectors
+==========
 
 * [Home](help)
 
+Connectors allow you to connect with external social networks and services. Connectors are only required for posting to existing accounts on Facebook, Twitter, and StatusNet. There is also a connector for accessing your email INBOX.
 
-Friendika uses plugins to provide connectivity to some networks, such as Facebook and Twitter. 
+If the following network connectors are installed on your system, select the following links to visit the appropriate settings page and configure them for your account:
 
-There is also a plugin to post through to an existing account on a Status.Net service. You do not require this to communicate with Status.Net members from Friendika - only if you wish to post to an already existing account.
+* [Facebook](/settings/addon)
+* [Twitter](/settings/addon)
+* [StatusNet](/settings/addon)
+* [Email](/settings)
 
-All three of these plugins require an account on the target network. In addition you (or typically the server administrator) will need to obtain an API key to provide authenticated access to your Friendika server.
+Instructions For Connecting To People On Specific Services
+==========================================================
 
-**Site Configuration**
+**Friendika**
 
-Plugins must be installed by the site administrator before they can be use. This is accomplished through the site
-configuration file ".htconfig.php".
 
-The configuration directive looks like:
+You may connect by providing your Identity Address on the 'Connect' page of any Friendika member. You may also put their Identity Address into the Connect box on your [Contacts](contacts) page. 
 
-```
-$a->config['system']['addon'] = ' ... list of plugins separated by commas ... ';
-```
+**Identi.ca/StatusNet/GNU-Social**
 
-Example:
-To install all of the connector addons in addition to the default Javascript photo uploader this line would look like:
+These are described as the "federated social web" or OStatus contacts. 
 
-```
-$a->config['system']['addon'] = 'js_upload,facebook,twitter,statusnet';
-```
+Please note that there are **no** privacy provisions on the OStatus network. Any message which is delivered to **any** OStatus member is visible to anybody in the world and will negate any privacy settings that you have in effect. These messages will also turn up in public searches. 
 
-You may also add other plugins/addons as your needs require. 
+To connect with an OStatus member insert their profile URL or Identity address into the Connect box on your [Contacts](contacts) page.
 
+The StatusNet connector may be used if you wish posts to appear on an OStatus site using an existing OStatus account. 
 
-Each of the connectors also requires an "API key" from the service you wish to connect with. This is also installed in the
-configuration file. The method for obtaining these keys varies greatly - but almost always requires an existing account on the target service. Once installed, these API keys can usually be shared by all site members.
+It is not necessary to do this, as you may 'follow' OStatus members from Friendika and they may follow you (by placing their own Identity Address into your 'Connect' page).
 
+**Blogger, Wordpress, RSS feeds, arbitrary web pages**
 
-The details of configuring each service follows (much of this information comes directly from the plugin source files):
+Put the URL into the Connect box on your [Contacts](contacts) page. You will not be able to reply to these contacts. 
 
-**Twitter Plugin for Friendika**
+This will allow you to _connect_ with millions of pages on the internet. All that we require to do this is that the page use a discoverable feed using either the RSS or Atom syndication format, and which provides an author name and a site image in a form which we can extract. 
 
-* Author: Tobias Diekershoff
-* tobias.diekershoff@gmx.net
 
-* License:3-clause BSD license (same as Friendika)
+**Twitter**
 
-Configuration:
-To use this plugin you need a OAuth Consumer key pair (key & secret)
-you can get it from Twitter at https://twitter.com/apps
+To follow a Twitter member, put the URL of the Twitter member's main page into the Connect box on your [Contacts](contacts) page. To reply, you must have the Twitter connector installed, and reply using your own status editor. Begin the message with @twitterperson replacing with the Twitter username.
 
-Register your Friendika site as "Client" application with "Read & Write" access.
-We do not need "Twitter as login". When you've registered the app you get the
-OAuth Consumer key and secret pair for your application/site.
+**Diaspora**
 
-Add this key pair to your global .htconfig.php
+To follow a Diaspora member, put either the URL or the pod address (Identity Address) of the Diaspora member into the Connect box on your [Contacts](contacts) page. It is not currently possible to reply to Diaspora members. This will be provided in a future release (once the Diaspora communication protocols stabilise and are published). 
 
-```
-$a->config['twitter']['consumerkey'] = 'your consumer_key here';
-$a->config['twitter']['consumersecret'] = 'your consumer_secret here';
-```
+**Email**
 
-After this, your user can configure their Twitter account settings
-from "Settings -> Plugin Settings".
+Configure the email connector from your [Settings](settings) page. Once this has been done, you may enter an email addres to connect with using the Connect box on your [Contacts](contacts) page. They must be the sender of a message which is currently in your INBOX for the connect to succeed. You may include email contacts in private conversations.
 
-Documentation: http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/Twitter_Plugin
+**Facebook**
 
+The Facebook connector is a plugin/addon which allows you to interact with friends on Facebook from within Friendika. If enabled, your Facebook friend list will be imported, and you will see and be able to respond to Facebook posts. Facebook members may also be added to private conversation groups. You will not be able to connect with individual Facebook accounts - but will have your entire friend list imported and updated if new friends are added. 
 
-**StatusNet Plugin for Friendika**
+Assuming the Facebook plugin/addon has been installed on your system, it can be enabled by going to your [Plugin Settings](settings/addon) page, and then select "Facebook Connector Settings" on that page. This will only appear if the Facebook plugin/addon has been installed. Follow the instruction to install or remove the Facebook connector.
 
-* Author: Tobias Diekershoff
-* tobias.diekershoff@gmx.net
-
-* License:3-clause BSD license (same as Friendika)
-
-Configuration
-
-When the addon is activated the user has to aquire the following in order to connect to the StatusNet account of choice.
-
-* The base URL for the StatusNet API, for identi.ca this is https://identi.ca/api/
-* OAuth Consumer key & secret
-
-To get the OAuth Consumer key pair the user has to 
-
-(a) ask her Friendika admin if a pair already exists or 
-(b) has to register the Friendika server as a client application on the StatusNet server. 
-
-This can be done from the account settings under "Settings -> Connections -> Register an OAuth client application -> Register new application".
-
-During the registration of the OAuth client remember the following:
-
-* Application names must be unique on the StatusNet site, so we recommend a Name of 'friendika-nnnn', replace 'nnnn' with a random number or your website name.
-* there is no callback url
-* register a desktop client
-* with read & write access
-* the Source URL should be the URL of your Friendika server
-
-After the required credentials for the application are stored in the configuration you have to actually connect your Friendika account with StatusNet. This is done from the Settings -> Plugin Settings page. Follow the Sign in with StatusNet button, allow access and then copy the security code into the box provided. Friendika will then try to acquire the final OAuth credentials from the API. 
-
-If successful the addon settings will allow you to select to post your public messages to your StatusNet account (have a look behind the little lock symbol beneath the status "editor" on your Home or Network pages).
-
-Documentation: http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/StatusNet_Plugin
-
-
-
-**Installing the Friendika/Facebook connector**
-
-* register an API key for your site from developer.facebook.com
-
-This requires a Facebook account, and may require additional authentication in the form of credit card or mobile phone verification. 
-
-a. We'd be very happy if you include "Friendika" in the application name
-to increase name recognition. The Friendika icons are also present
-in the images directory and may be uploaded as a Facebook app icon.
-Use images/friendika-16.jpg for the Icon and images/friendika-128.jpg for the Logo.
-
-b. The url should be your site URL with a trailing slash.
-You may use http://portal.friendika.com/privacy as the privacy policy
-URL unless your site has different requirements, and
-http://portal.friendika.com as the Terms of Service URL unless
-you have different requirements. (Friendika is a software application
-and does not require Terms of Service, though your installation of it might).
-
-c. Set the following values in your .htconfig.php file
-
-```
-$a->config['facebook']['appid'] = 'xxxxxxxxxxx';
-$a->config['facebook']['appsecret'] = 'xxxxxxxxxxxxxxx';
-```
-
-Replace with the settings Facebook gives you.
-
-Visit the Facebook Settings section of the "Settings->Plugin Settings" page.
-and click 'Install Facebook Connector'.
-
-This will ask you to login to Facebook and grant permission to the
-plugin to do its stuff. Allow it to do so.
-
-You're done. To turn it off visit the Plugin Settings page again and
-'Remove Facebook posting'.
-
-Videos and embeds will not be posted if there is no other content. Links
-and images will be converted to a format suitable for the Facebook API and
-long posts truncated - with a link to view the full post.
-
-Facebook contacts will also not be able to view "private" photos, as they are not able to
-authenticate to your site to establish identity. We will address this
-in a future release.
-
-
-
-
- 
+You may also choose whether your public postings are posted to Facebook by default. You may toggle this setting at any time from the Permissions settings of the status post editor (click the lock icon). This setting has no effect on private conversations - which will always be delivered to Facebook friends who are included in the permissions.  
 
+(Note: At this time, Facebook contacts will not be able to view any private photos. This will be resolved in a future release. Facebook contacts may however see any public photos you have uploaded.)
 
diff --git a/doc/Home.md b/doc/Home.md
index c9d09450e..f91895620 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -6,6 +6,7 @@ Friendika Documentation and Resources
 
 * [Account Basics](help/Account-Basics)
 * [Profiles](help/Profiles)
+* [Connectors](help/Connectors)
 * [Making Friends](help/Making-Friends)
 * [Groups and Privacy](help/Groups-and-Privacy)
 * [Tags and Mentions](help/Tags-and-Mentions)
@@ -18,7 +19,7 @@ Friendika Documentation and Resources
 * [Install](help/Install)
 * [Settings](help/Settings)
 * [Plugins](help/Plugins)
-* [Installing Connectors (Facebook/Twitter/StatusNet)](help/Connectors)
+* [Installing Connectors (Facebook/Twitter/StatusNet)](help/Installing-Connectors)
 * [Message Flow](help/Message-Flow)
 * [Developers](help/Developers)
 
diff --git a/doc/Installing-Connectors.md b/doc/Installing-Connectors.md
new file mode 100644
index 000000000..e43f17fe3
--- /dev/null
+++ b/doc/Installing-Connectors.md
@@ -0,0 +1,154 @@
+Installing Connectors (Facebook/Twitter/StatusNet)
+==================================================
+
+* [Home](help)
+
+
+Friendika uses plugins to provide connectivity to some networks, such as Facebook and Twitter. 
+
+There is also a plugin to post through to an existing account on a Status.Net service. You do not require this to communicate with Status.Net members from Friendika - only if you wish to post to an existing account.
+
+All three of these plugins require an account on the target network. In addition you (or typically the server administrator) will need to obtain an API key to provide authenticated access to your Friendika server.
+
+**Site Configuration**
+
+Plugins must be installed by the site administrator before they can be use. This is accomplished through the site
+configuration file ".htconfig.php".
+
+The configuration directive looks like:
+
+```
+$a->config['system']['addon'] = ' ... list of plugins separated by commas ... ';
+```
+
+Example:
+To install all of the connector addons in addition to the default Javascript photo uploader this line would look like:
+
+```
+$a->config['system']['addon'] = 'js_upload,facebook,twitter,statusnet';
+```
+
+You may also add other plugins/addons as your needs require. 
+
+
+Each of the connectors also requires an "API key" from the service you wish to connect with. This is also installed in the
+configuration file. The method for obtaining these keys varies greatly - but almost always requires an existing account on the target service. Once installed, these API keys can usually be shared by all site members.
+
+
+The details of configuring each service follows (much of this information comes directly from the plugin source files):
+
+**Twitter Plugin for Friendika**
+
+* Author: Tobias Diekershoff
+* tobias.diekershoff@gmx.net
+
+* License:3-clause BSD license (same as Friendika)
+
+Configuration:
+To use this plugin you need a OAuth Consumer key pair (key & secret)
+you can get it from Twitter at https://twitter.com/apps
+
+Register your Friendika site as "Client" application with "Read & Write" access.
+We do not need "Twitter as login". When you've registered the app you get the
+OAuth Consumer key and secret pair for your application/site.
+
+Add this key pair to your global .htconfig.php
+
+```
+$a->config['twitter']['consumerkey'] = 'your consumer_key here';
+$a->config['twitter']['consumersecret'] = 'your consumer_secret here';
+```
+
+After this, your user can configure their Twitter account settings
+from "Settings -> Plugin Settings".
+
+Documentation: http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/Twitter_Plugin
+
+
+**StatusNet Plugin for Friendika**
+
+* Author: Tobias Diekershoff
+* tobias.diekershoff@gmx.net
+
+* License:3-clause BSD license (same as Friendika)
+
+Configuration
+
+When the addon is activated the user has to aquire the following in order to connect to the StatusNet account of choice.
+
+* The base URL for the StatusNet API, for identi.ca this is https://identi.ca/api/
+* OAuth Consumer key & secret
+
+To get the OAuth Consumer key pair the user has to 
+
+(a) ask her Friendika admin if a pair already exists or 
+(b) has to register the Friendika server as a client application on the StatusNet server. 
+
+This can be done from the account settings under "Settings -> Connections -> Register an OAuth client application -> Register new application".
+
+During the registration of the OAuth client remember the following:
+
+* Application names must be unique on the StatusNet site, so we recommend a Name of 'friendika-nnnn', replace 'nnnn' with a random number or your website name.
+* there is no callback url
+* register a desktop client
+* with read & write access
+* the Source URL should be the URL of your Friendika server
+
+After the required credentials for the application are stored in the configuration you have to actually connect your Friendika account with StatusNet. This is done from the Settings -> Plugin Settings page. Follow the Sign in with StatusNet button, allow access and then copy the security code into the box provided. Friendika will then try to acquire the final OAuth credentials from the API. 
+
+If successful the addon settings will allow you to select to post your public messages to your StatusNet account (have a look behind the little lock symbol beneath the status "editor" on your Home or Network pages).
+
+Documentation: http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/StatusNet_Plugin
+
+
+
+**Installing the Friendika/Facebook connector**
+
+* register an API key for your site from developer.facebook.com
+
+This requires a Facebook account, and may require additional authentication in the form of credit card or mobile phone verification. 
+
+a. We'd be very happy if you include "Friendika" in the application name
+to increase name recognition. The Friendika icons are also present
+in the images directory and may be uploaded as a Facebook app icon.
+Use images/friendika-16.jpg for the Icon and images/friendika-128.jpg for the Logo.
+
+b. The url should be your site URL with a trailing slash.
+You may use http://portal.friendika.com/privacy as the privacy policy
+URL unless your site has different requirements, and
+http://portal.friendika.com as the Terms of Service URL unless
+you have different requirements. (Friendika is a software application
+and does not require Terms of Service, though your installation of it might).
+
+c. Set the following values in your .htconfig.php file
+
+```
+$a->config['facebook']['appid'] = 'xxxxxxxxxxx';
+$a->config['facebook']['appsecret'] = 'xxxxxxxxxxxxxxx';
+```
+
+Replace with the settings Facebook gives you.
+
+Visit the Facebook Settings section of the "Settings->Plugin Settings" page.
+and click 'Install Facebook Connector'.
+
+This will ask you to login to Facebook and grant permission to the
+plugin to do its stuff. Allow it to do so.
+
+You're done. To turn it off visit the Plugin Settings page again and
+'Remove Facebook posting'.
+
+Videos and embeds will not be posted if there is no other content. Links
+and images will be converted to a format suitable for the Facebook API and
+long posts truncated - with a link to view the full post.
+
+Facebook contacts will also not be able to view "private" photos, as they are not able to
+authenticate to your site to establish identity. We will address this
+in a future release.
+
+
+
+
+ 
+
+