########################################################################
# README                                                               #
########################################################################

(Temporary document until a final documentation draft is finished!)

########################################################################
# UPDATING                                                             #
########################################################################

The automatic update script should find and execute any necessary
changes to the database layout made in different s9y versions beginning
from 0.5. The upgrader will perform its automatic actions, as soon as you
have copied the new s9y files over your old installation and access the start
page of your blog.
You can speed up the process of backing up your data and copying the files by 
using the supplied "upgrade.sh" script. Be sure to edit the file and change 
the variables to your needs.

Usually all DB schema upgrades in previous versions will be used. So
when you upgrade from 0.5 to 0.7 you will get upgrades from 0.5 -> 0.6
and 0.6 -> 0.7.

However, you are always advised to look at the corresponding
SQL update file in sql/db_update* to see which changes were made.

Please bear in mind that the automatic update script is executable by
any user visiting your blog at the time of updating. You should modify
your .htaccess file before upgradding and include this directives:

---- .htaccess
AuthType Basic
AuthName "Authorisation: Serendipity Upgrade IN PROGRESS"
AuthUserFile /absolute/path/to/your/s9y/.htpasswd
require valid-user
----

Then create a file .htpasswd using a simple 'username:md5password'
combination. Look at http://www.advancehost.com/htpasswd.html for an
online generator for .htpasswd files.

---- .htpasswd
s9y:s9QXoc9dcFOT2
----

This would create a user "s9y" with password "s9y" with which you'd have
to log into your blog.

A proper backup of BOTH the file system and your database is suggested.
Whenever you made changes to the distributed files (or to the files like
xml.gif or the smilies) you have to make sure to copy them over the
distributed files after updating.

########################################################################
# NOTES ON UPDATING FROM 0.5/0.5.1 -> 0.6                              #
########################################################################

* [The 0.5.1 release was renamed to 0.6, but there will still be DB
  layout changes applied which are labelled as 0.5.1 - just ignore it.
  It's only to easy migration to CVS-Snapshot users using the
  0.5.1-version]

* The structure of the content_rewrite plugin has changed. It will get
  rewritten automatically by the update script, but if you had output on
  your sidebar before, you need to do this:

  - Add the 'serendipity_plugin_eventwrapper' to the sidebar plugins.
  - Configure the 'serendipity_plugin_eventwrapper' and set it to use
    your existing 'serendpity_event_contentrewrite' plugin.

* Smilies and the XML-button where moved from the '/pixel' subdirectory
  into per-template 'img/' subdirectories. If you modified the original
  files, you need to copy your versions inside the
  'templates/default/img/' directory.

* A home-link has been added to the page headers. For that, two new CSS
  classes have been introduced: .homelink1 (header), .homelink2 (
  subheader). If you have a custom template, you need to adapt to those
  changes. To make them look like your header previously has, insert
  this in your style.css:
  
  a.homelink1,
  a.homelink1:hover,
  a.homelink1:link,
  a.homelink1:visited,
  #serendipity_banner h1 {
    ... your css-definitions ...
    text-decoration: none;
  }

  a.homelink2,
  a.homelink2:hover,
  a.homelink2:link,
  a.homelink2:visited,
  #serendipity_banner h2 {
    ... your css-definitions ...
    text-decoration: none;
  }

########################################################################
# NOTES ON UPDATING FROM 0.4 -> 0.5                                    #
########################################################################

No changes where made to the database scheme in this version.

########################################################################
# NOTES ON UPDATING FROM 0.3 -> 0.4                                    #
########################################################################

Run the file 'sql/db_update_0.3_0.4_mysql.sql' or
'sql/db_update_0.3_0.4_pgsql.sql' to update your database. Apart from
that, just copy over the new files of the distribution.

########################################################################
# THE 'embed' CONFIGURATION DIRECTIVE                                  #
########################################################################

In your serendipity configuration, you can set an 'embed' option to true
or false.

This defines, whether you use your blog as a standalone webpage - or if
you have different content wrapped around your blog, like the menu of
your usual homepage.

By setting the 'embed' option to true, you have to make sure the
following things to get everything to work well:

1. 'indexFile' option.

   This configuration option needs to be set to the wrapper file you
   want to use. Let's say you normally have a 'content.php' file for
   your webpage. This 'content.php' file sets up your internal
   templates, your menu structure and such.
   Now you want this file to be used to include your weblog. A simple
   content.php could look like this:
   
   <?php
   $homepage = new Template_Class;
   $homepage->set_template($_REQUEST['page']);
   $homepage->output_header();
   $homepage->output_content();
   $homepage->output_footer();
   $homepage->track_statistics();
   ?>
   
   So normally your file would be called with 'content.php?page=about'
   to display your 'about' page of your personal homepage.
   
   Now we want this file to be displayed, having the 'page' variable
   being set to 'blog'.
   
   For this, we set up a 'wrapper.php' file:
   
   <?php
   $_REQUEST['page'] = 'blog';
   // Let serendipity generate our content:
   ob_start();
   require 'index.php';
   $blog_data = ob_get_contents();
   ob_end_clean();
   
   // Now we include our normal content building file.
   // This one has to make use of your $blog_data variable to print
   // the content where appropriate!
   require 'content.php';
   ?>
   
   You would then set your 'indexFile' serendipity-option to the
   'wrapper.php' file.
   
  2. Plugin panes & HTML-headers
  
   With the example above, we only get the main blog data printed. One
   of the most visible actions when using the 'embed' option is that the
   plugin panes are not generated. And HTML headers/foooters are also
   not provided by s9y in this case, as this should be done by your
   'content.php' file.
   
   So you have to include them in your 'content.php' file, to have them
   visible in your embedded setup.
   
   You can use this snippet:
   <?php 
   serendipity_plugin_api::generate_plugins('left','div');
   serendipity_plugin_api::generate_plugins('right','div');
   ?>
   somewhere in your 'content.php' file.
  
The 'embed' option is therefore only recommended to be used by advanced
users going for a most flexible setup!

########################################################################
# HOW TO USE SERENDIPITY AS SHARED LIBRARY                             #
########################################################################

******************************************
* WARNING: THIS FEATURE IS EXPERIMENTAL! *
******************************************

You can install ONE s9y distribution and manage multiple users on it by
sharing the core files and then deploying specially crafted files in
each user's directory.

Let's do this using an example. You own the domain 's9yblogs.org'.
You want to have multiple virtual hosts for as many users as you like.
They are going to be called 'username.s9yblogs.org'. We choose the users
'garvin', 'j' and 'tom' for example hosts. We assume that your webserver
runs as user 'www', group 'www'. We also assume that all your users
are called like the subdomains, and they are also in group 'www'. We
further assume that PHP's safe_mod is turned off.

Of course, for security reasons, you should set the open_basedir
directive to the user's document root, so he can't access other
installations on your host.

So your Apache-Webser should contain VirtualHosts like this:

-- httpd.conf
<VirtualHost 42.42.42.42:80>
    ServerName garvin.s9yblogs.org
    DocumentRoot /home/www/garvin.s9yblogs.org/htdocs
    <Directory "/home/www/garvin.s9yblogs.org/htdocs">
        AllowOverride All
    </Directory>
    php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/s9y/:/usr/local/lib/php/s9y/bundled-libs/"
    php_admin_value open_basedir "/usr/local/lib/php/:/usr/local/lib/php/s9y/:/home/www/garvin.s9yblogs.org/"
</VirtualHost>

<VirtualHost 42.42.42.42:80>
    ServerName j.s9yblogs.org
    DocumentRoot /home/www/j.s9yblogs.org/htdocs
    <Directory "/home/www/j.s9yblogs.org/htdocs">
        AllowOverride All
    </Directory>
    php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/s9y/:/usr/local/lib/php/s9y/bundled-libs/"
    php_admin_value open_basedir "/usr/local/lib/php/:/usr/local/lib/php/s9y/:/home/www/j.s9yblogs.org/"
</VirtualHost>

<VirtualHost 42.42.42.42:80>
    ServerName tom.s9yblogs.org
    DocumentRoot /home/www/tom.s9yblogs.org/htdocs
    <Directory "/home/www/tom.s9yblogs.org/htdocs">
        AllowOverride All
    </Directory>
    php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/s9y/:/usr/local/lib/php/s9y/bundled-libs/"
    php_admin_value open_basedir "/usr/local/lib/php/:/usr/local/lib/php/s9y/:/home/www/tom.s9yblogs.org/"
</VirtualHost>
-- httpd.conf

You will unpack the default s9y distribution files in
"/usr/local/lib/php/s9y/". Where you store the directory 's9y' is
not important, as long as you adjust the include_path setting in the
VirtualHosts. But the directory name 's9y' is significant.

Now copy the subdirectories called
 
 * "/usr/local/lib/php/s9y/deployment/"  [core redirection files]
 * "/usr/local/lib/php/s9y/templates/"   [templates so that users can change them]
 * "/usr/local/lib/php/s9y/pixel/"       [core image files]
 * "/usr/local/lib/php/s9y/htmlarea/"    [htmlarea WYSIWYG-editor]

 to each of the user's subdirectories:

$ cp -r /usr/local/lib/php/s9y/deployment/* /home/www/garvin.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/templates /home/www/garvin.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/pixel /home/www/garvin.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/htmlarea /home/www/garvin.s9yblogs.org/htdocs/
$ chown -R garvin.www /home/www/garvin.s9yblogs.org/htdocs/*
$ chmod go+rwx /home/www/garvin.s9yblogs.org/htdocs
$ chmod go+rwx /home/www/garvin.s9yblogs.org/htdocs/uploads/

$ cp -r /usr/local/lib/php/s9y/deployment/* /home/www/j.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/templates /home/www/j.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/pixel /home/www/j.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/htmlarea /home/www/j.s9yblogs.org/htdocs/
$ chown -R j.www /home/www/j.s9yblogs.org/htdocs/*
$ chmod go+rwx /home/www/j.s9yblogs.org/htdocs
$ chmod go+rwx /home/www/j.s9yblogs.org/htdocs/uploads/

$ cp -r /usr/local/lib/php/s9y/deployment/* /home/www/tom.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/templates /home/www/tom.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/pixel /home/www/tom.s9yblogs.org/htdocs/
$ cp -r /usr/local/lib/php/s9y/htmlarea /home/www/tom.s9yblogs.org/htdocs/
$ chown -R tom.www /home/www/tom.s9yblogs.org/htdocs/*
$ chmod go+rwx /home/www/tom.s9yblogs.org/htdocs
$ chmod go+rwx /home/www/tom.s9yblogs.org/htdocs/uploads/

For later management access, it is advised you keep a list of all URLs
for your s9y-managed blogs. We suggest to create a SQL table like
'my_managed_s9y_blogs':

sql> CREATE TABLE my_managed_s9y_blogs (url varchar(255) default null);
sql> INSERT INTO my_managed_s9y_blogs (url) VALUES ('http://garvin.s9yblogs.org/');
sql> INSERT INTO my_managed_s9y_blogs (url) VALUES ('http://j.s9yblogs.org/');
sql> INSERT INTO my_managed_s9y_blogs (url) VALUES ('http://tom.s9yblogs.org/');  

Now you are almost ready for take-off. We assume that every user has
access to a seperate SQL database where his blog-data is later stored
in. You can already see, that the steps needed above shouldn't be to
hard to put into a customized script.sh file for use in your setup.

Open up your http://garvin.s9yblogs.org/ file. You should now see s9y's
installation screen. Enter the database- and username and the
corresponding password. Everything else can be left to the user.

Now every user can manage his/her blog just as if it were a standalone
installation.

SPECIAL NOTES:
========================================================================

* Each blog is still a standalone blog.

* If you update the core library files from version 0.5 to 0.6 (for
  example) every user of your core library will get the default s9y-
  Upgrader script to see and needs to update his local configuration.
  
  As a provider for s9y blogs to your users, you are advised to migrate
  the user's blogs on your own. To do so, it is best that you always
  have a "spare" testing blog installed just like your user's blogs.
  
  Open that installation and look at the upgrader. Execute it and see
  that it completes without errors. If that happened, you should cycle
  through a list of ALL your s9y-managed blogs like this:

  <?php
  $sql = mysql_query('SELECT url FROM my_managed_s9y_blogs');
  while ($row = mysql_fetch_array($sql, MYSQL_ASSOC)) {
     $fp = fopen($row['url'] . 'serendipity_admin.php?serendipity[action]=upgrade');
  }
  ?>
  
  So basically all you need to do is call that script for every s9y-
  powered blog you host.

########################################################################
# NOTES FOR CONDITIONAL GET IN RSS FEEDS                               #
########################################################################

Serendipity supports an HTTP-cache compatible way of only showing items
in an RSS feed which where modified since the last request from a
client.

Typically, an RSS reader fetches your RSS feeds (15 items, per default).
It then remembers the timestamp when those items where fetched. By the
time your RSS reader updates the feed (typically after 1 hour)
Serendipity will now only serve all new or modified items since the last
time of refresh. If no entries where updated since then, serendipity
will only serve the 304 Header (Not Modified) and saves a lot of
bandwidth for both client and server on periodical updates.

Technically an RSS reader catches the "Last-Modified" Header of the RSS
output as well as a special "ETag"-Header. Both are set to the last
modification time of your article base. On the next fetch, those
received headers are sent as "IF_MODIFIED_SINCE" (= Last-Modified) and
"IF_NONE_MATCH" (= ETag) Headers and will affect your rss feed. This
saves a lot of bandwidth on both client and server side.

Users who have been watching your feed and where not able to catch up
the latest articles may miss some of them, because you usually only get
15 items per feed. In case your reader provides the IF_MODIFIED_SINCE
header the client can now catch all items (resp. a maximum of 50
articles to prevent abuse).

If you want to permanently disable that feature (whatever the reasons
are) you can either set a "$_REQUEST['nocache'] = true" inside your
rss.php file (first line) or append the '&nocache=true' request variable
to your feed so that it looks like:
http://example.host/serendipity/rss.php?version=2.0&nocache=true.

Of course, the usual feed behaviour is not affected if none of the
caching headers are provided. So if you use syndication methods to embed
content from a blog inside an application, just tune your application to
either send the 'nocache'-Variable to a Serendipity blog, or to not send
the caching headers.

The syndication plugin can be configured to append that variable to your
feed URLs from your blog.

########################################################################

Serendipity Weblog - http://s9y.org

Licensed under the BSD License

# $Id: README,v 1.6.4.1 2004/04/07 06:43:11 garvinhicking Exp $
