Display linked oembed resources as enclosures if they are of non-html mime types

[quix0rs-gnu-social.git] / README

diff --git a/README b/README
index 2c92a75da8b925f05ebb0c8ccfe7e77498cf6de2..ba4394b797aef0a9a8405e9bf90ac0f79ac1892e 100644 (file)
--- a/README
+++ b/README
@@ -3,7 +3,7 @@ README
 ------
 
 Laconica 0.8.0 ("Shiny Happy People")
 ------
 
 Laconica 0.8.0 ("Shiny Happy People")

-8 July 2009
+15 July 2009

 
 This is the README file for Laconica, the Open Source microblogging
 platform. It includes installation instructions, descriptions of
 
 This is the README file for Laconica, the Open Source microblogging
 platform. It includes installation instructions, descriptions of


@@ -116,6 +116,16 @@ This is a major feature release since version 0.7.4, released May 31
   as default TOS for Laconica sites.
 - Better command-line handling for scripts, including standard options
   and ability to set hostname and path from the command line.
   as default TOS for Laconica sites.
 - Better command-line handling for scripts, including standard options
   and ability to set hostname and path from the command line.

+- An experimental plugin to use Meteor (http://www.meteorserver.org/)
+  for "real-time" updates.
+- A new framework for "real-time" updates, making it easier to develop
+  plugins for different browser-based update modes.
+- RSS 2.0 and Atom feeds for groups.
+- RSS 2.0 and Atom feeds for tags.
+- Attachments can be sent by email.
+- Attachments are encoded as enclosures in RSS 2.0 and Atom.
+- Notices with attachments display in Facebook as media inline.
+

 - Many, many bug fixes.
 
 Prerequisites
 - Many, many bug fixes.
 
 Prerequisites


@@ -124,7 +134,7 @@ Prerequisites
 The following software packages are *required* for this software to
 run correctly.
 
 The following software packages are *required* for this software to
 run correctly.
 

-- PHP 5.2.x. It may be possible to run this software on earlier
+- PHP 5.2.3+. It may be possible to run this software on earlier

   versions of PHP, but many of the functions used are only available
   in PHP 5.2 or above.
 - MySQL 5.x. The Laconica database is stored, by default, in a MySQL
   versions of PHP, but many of the functions used are only available
   in PHP 5.2 or above.
 - MySQL 5.x. The Laconica database is stored, by default, in a MySQL


@@ -252,13 +262,16 @@ especially if you've previously installed PHP/MySQL packages.
    that user's default group instead. As a last resort, you can create
    a new group like "mublog" and add the Web server's user to the group.
 
    that user's default group instead. As a last resort, you can create
    a new group like "mublog" and add the Web server's user to the group.
 

-4. You should also take this moment to make your avatar subdirectory
-   writeable by the Web server. An insecure way to do this is:
+4. You should also take this moment to make your avatar, background, and
+   file subdirectories writeable by the Web server. An insecure way to do
+   this is:

 
          chmod a+w /var/www/mublog/avatar
 
          chmod a+w /var/www/mublog/avatar

+         chmod a+w /var/www/mublog/background
+         chmod a+w /var/www/mublog/file

 
 

-   You can also make the avatar directory writeable by the Web server
-   group, as noted above.
+   You can also make the avatar, background, and file directories
+   writeable by the Web server group, as noted above.

 
 5. Create a database to hold your microblog data. Something like this
    should work:
 
 5. Create a database to hold your microblog data. Something like this
    should work:


@@ -540,25 +553,53 @@ our kind of hacky home-grown DB-based queue solution. See the "queues"
 config section below for how to configure to use STOMP. As of this
 writing, the software has been tested with ActiveMQ (
 
 config section below for how to configure to use STOMP. As of this
 writing, the software has been tested with ActiveMQ (
 

-Twitter Friends Syncing
------------------------
+Twitter Bridge
+--------------
+
+* OAuth
+
+As of 0.8.1, OAuth is used to to access protected resources on Twitter
+instead of HTTP Basic Auth.  To use Twitter bridging you will need
+to register your instance of Laconica as an application on Twitter
+(http://twitter.com/apps), and update the following variables in your
+config.php with the consumer key and secret Twitter generates for you:
+
+      $config['twitter']['consumer_key']    = 'YOURKEY';
+      $config['twitter']['consumer_secret'] = 'YOURSECRET';
+
+When registering your application with Twitter set the type to "Browser"
+and your Callback URL to:
+
+      http://example.org/mublog/twitter/authorization
+
+The default access type should be, "Read & Write".
+
+* Importing statuses from Twitter
+
+To allow your users to import their friends' Twitter statuses, you will
+need to enable the bidirectional Twitter bridge in config.php:
+
+      $config['twitterbridge']['enabled'] = true;
+
+and run the TwitterStatusFetcher daemon (scripts/twitterstatusfetcher.php).
+Additionally, you will want to set the integration source variable,
+which will keep notices posted to Twitter via Laconica from looping
+back.  The integration source should be set to the name of your
+application, exactly as you specified it on the settings page for your
+Laconica application on Twitter, e.g.:

 
 

-As of Laconica 0.6.3, users may set a flag in their settings ("Subscribe
-to my Twitter friends here" under the Twitter tab) to have Laconica
-attempt to locate and subscribe to "friends" (people they "follow") on
-Twitter who also have accounts on your Laconica system, and who have
-previously set up a link for automatically posting notices to Twitter.
+      $config['integration']['source'] = 'YourApp';

 
 

-Optionally, there is a script (./scripts/synctwitterfriends.php), meant
-to be run periodically from a job scheduler (e.g.: cron under Unix), to
-look for new additions to users' friends lists. Note that the friends
-syncing only subscribes users to each other, it does not unsubscribe
-users when they stop following each other on Twitter.
+* Twitter Friends Syncing

 
 

-Sample cron job:
+Users may set a flag in their settings ("Subscribe to my Twitter friends
+here" under the Twitter tab) to have Laconica attempt to locate and
+subscribe to "friends" (people they "follow") on Twitter who also have
+accounts on your Laconica system, and who have previously set up a link
+for automatically posting notices to Twitter.

 
 

-# Update Twitter friends subscriptions every half hour
-0,30 * * * * /path/to/php /path/to/laconica/scripts/synctwitterfriends.php>&/dev/null
+As of 0.8.0, this is no longer accomplished via a cron job. Instead you
+must run the SyncTwitterFriends daemon (scripts/synctwitterfreinds.php).

 
 Built-in Facebook Application
 -----------------------------
 
 Built-in Facebook Application
 -----------------------------


@@ -588,10 +629,10 @@ key and secret, e.g.:
 
 In Facebook's application editor, specify the following URLs for your app:
 
 
 In Facebook's application editor, specify the following URLs for your app:
 

-- Callback URL: http://example.net/mublog/facebook/
-- Post-Remove URL: http://example.net/mublog/facebook/remove
+- Canvas Callback URL: http://example.net/mublog/facebook/
+- Post-Remove Callback URL: http://example.net/mublog/facebook/remove

 - Post-Add Redirect URL: http://apps.facebook.com/yourapp/
 - Post-Add Redirect URL: http://apps.facebook.com/yourapp/

-- Canvas URL: http://apps.facebook.com/yourapp/
+- Canvas Page URL: http://apps.facebook.com/yourapp/

 
 (Replace 'example.net' with your host's URL, 'mublog' with the path
 to your Laconica installation, and 'yourapp' with the name of the
 
 (Replace 'example.net' with your host's URL, 'mublog' with the path
 to your Laconica installation, and 'yourapp' with the name of the


@@ -951,12 +992,12 @@ sslserver: use an alternate server name for SSL URLs, like
 shorturllength: Length of URL at which URLs in a message exceeding 140
                 characters will be sent to the user's chosen
                 shortening service.
 shorturllength: Length of URL at which URLs in a message exceeding 140
                 characters will be sent to the user's chosen
                 shortening service.

-design: a default design (colors and background) for the site.
-        Sub-items are: backgroundcolor, contentcolor, sidebarcolor,
-        textcolor, linkcolor, backgroundimage, disposition.

 dupelimit: minimum time allowed for one person to say the same thing
            twice. Default 60s. Anything lower is considered a user
            or UI error.
 dupelimit: minimum time allowed for one person to say the same thing
            twice. Default 60s. Anything lower is considered a user
            or UI error.

+textlimit: default max size for texts in the site. Defaults to 140.
+           0 means no limit. Can be fine-tuned for notices, messages,
+           profile bios and group descriptions.

 
 db
 --
 
 db
 --


@@ -1218,6 +1259,30 @@ enabled: Set to true to enable. Default false.
 server: a string with the hostname of the sphinx server.
 port: an integer with the port number of the sphinx server.
 
 server: a string with the hostname of the sphinx server.
 port: an integer with the port number of the sphinx server.
 

+emailpost
+---------
+
+For post-by-email.
+
+enabled: Whether to enable post-by-email. Defaults to true. You will
+         also need to set up maildaemon.php.
+
+sms
+---
+
+For SMS integration.
+
+enabled: Whether to enable SMS integration. Defaults to true. Queues
+         should also be enabled.
+
+twitter
+-------
+
+For Twitter integration
+
+enabled: Whether to enable Twitter integration. Defaults to true.
+         Queues should also be enabled.
+

 integration
 -----------
 
 integration
 -----------
 


@@ -1259,6 +1324,8 @@ banned: an array of usernames and/or profile IDs of 'banned' profiles.
         The site will reject any notices by these users -- they will
         not be accepted at all. (Compare with blacklisted users above,
         whose posts just won't show up in the public stream.)
         The site will reject any notices by these users -- they will
         not be accepted at all. (Compare with blacklisted users above,
         whose posts just won't show up in the public stream.)

+biolimit: max character length of bio; 0 means no limit; null means to use
+          the site text limit default.

 
 newuser
 -------
 
 newuser
 -------


@@ -1355,6 +1422,9 @@ Options for group functionality.
 
 maxaliases: maximum number of aliases a group can have. Default 3. Set
             to 0 or less to prevent aliases in a group.
 
 maxaliases: maximum number of aliases a group can have. Default 3. Set
             to 0 or less to prevent aliases in a group.

+desclimit: maximum number of characters to allow in group descriptions.
+           null (default) means to use the site-wide text limits. 0
+           means no limit.

 
 oohembed
 --------
 
 oohembed
 --------


@@ -1419,6 +1489,83 @@ notify third-party servers of updates.
 notify: an array of URLs for ping endpoints. Default is the empty
         array (no notification).
 
 notify: an array of URLs for ping endpoints. Default is the empty
         array (no notification).
 

+design
+------
+
+Default design (colors and background) for the site. Actual appearance
+depends on the theme.  Null values mean to use the theme defaults.
+
+backgroundcolor: Hex color of the site background.
+contentcolor: Hex color of the content area background.
+sidebarcolor: Hex color of the sidebar background.
+textcolor: Hex color of all non-link text.
+linkcolor: Hex color of all links.
+backgroundimage: Image to use for the background.
+disposition: Flags for whether or not to tile the background image.
+
+notice
+------
+
+Configuration options specific to notices.
+
+contentlimit: max length of the plain-text content of a notice.
+              Default is null, meaning to use the site-wide text limit.
+              0 means no limit.
+
+message
+-------
+
+Configuration options specific to messages.
+
+contentlimit: max length of the plain-text content of a message.
+              Default is null, meaning to use the site-wide text limit.
+              0 means no limit.
+
+Plugins
+=======
+
+Beginning with the 0.7.x branch, Laconica has supported a simple but
+powerful plugin architecture. Important events in the code are named,
+like 'StartNoticeSave', and other software can register interest
+in those events. When the events happen, the other software is called
+and has a choice of accepting or rejecting the events.
+
+In the simplest case, you can add a function to config.php and use the
+Event::addHandler() function to hook an event:
+
+    function AddGoogleLink($action)
+    {
+        $action->menuItem('http://www.google.com/', _('Google'), _('Search engine'));
+        return true;
+    }
+
+    Event::addHandler('EndPrimaryNav', 'AddGoogleLink');
+
+This adds a menu item to the end of the main navigation menu. You can
+see the list of existing events, and parameters that handlers must
+implement, in EVENTS.txt.
+
+The Plugin class in lib/plugin.php makes it easier to write more
+complex plugins. Sub-classes can just create methods named
+'onEventName', where 'EventName' is the name of the event (case
+matters!). These methods will be automatically registered as event
+handlers by the Plugin constructor (which you must call from your own
+class's constructor).
+
+Several example plugins are included in the plugins/ directory. You
+can enable a plugin with the following line in config.php:
+
+    addPlugin('Example', array('param1' => 'value1',
+                               'param2' => 'value2'));
+
+This will look for and load files named 'ExamplePlugin.php' or
+'Example/ExamplePlugin.php' either in the plugins/ directory (for
+plugins that ship with Laconica) or in the local/ directory (for
+plugins you write yourself or that you get from somewhere else) or
+local/plugins/.
+
+Plugins are documented in their own directories.
+

 Troubleshooting
 ===============
 
 Troubleshooting
 ===============