----------------------
Personal Weblog v1.0.0
----------------------

Personal Weblog is covered by the GNU General Public License. See the
file "COPYING" in this archive or visit:
	http://www.gnu.org/copyleft/gpl.html

If you are upgrading from a previous version make sure you read
"UPGRADING" contained in this archive.

Features:
* Simple to install and easy to use
* Completely configurable through a web browser
* Entries are categorized by topic
* Search-able by topic, keywords and time
* Supports RSS (Rich Site Summary) for syndication
* Supports multiple weblogs within a single database
* Works under many different operating systems and PHP configurations
* Extensible

Requirements:
* PHP v4
* MySQL or PostgreSQL

I consider the lack of user management, discussion forums and
"slashboxes" a feature for a personal home page. A personal weblog
should meld with your home page, not contain it as a sub-topic.

To see this weblog in use visit:
	http://www.kyne.com.au/~mark/

If you have any problems with the weblog please read the Common
Problems section found near the end of this document.

-------------
Configuration
-------------

Your web server must support PHP, and PHP must support MySQL or
PostgreSQL databases.

1) Setup database server

If your weblog will be hosted by an Internet Service Provider this
step will be done for you.

This step assumes you already have a configured database server. If you
need help with MySQL there is a lot of documentation available at:
	http://www.mysql.com/documentation/

To create your weblog database use:

# mysqladmin create DBNAME
  or
# createdb DBNAME

Depending on your database server set up you may need to modify
permissions so you can use the weblog from your web server. Personal
Weblog requires full access privileges on the database created above.
See "MySQL User Account Management" in the MySQL Reference Manual, or
"Database Users and Permissions" in the PostgreSQL Reference Manual.

2) Insert the initial data

Copy "setup.php", "upgrade.sql" and "weblog.sql" into your web space
and load "setup.php" in your browser. Fill in your weblog database
details and click "Install". If you see errors it may mean:

* The database details given were incorrect (bad user, password, host
  or database name).
* The database was not empty beforehand. If the weblog fails, empty
  the database and try again.

After installing make sure you remove "setup.php", "upgrade.sql" and
"weblog.sql" from your web space.

OR

Cut and paste the SQL from weblog.sql into phpMyAdmin (or similar).
This can be rather error prone so using setup.php is preferred in most
cases.

OR

If you have shell access to the MySQL server you can use:

# mysql DBNAME < weblog.sql

3) Setup PHP files

Copy "weblog.inc" into your web space. To add the weblog to your web
page add the follow code to the start of your weblog page:

	<?php require "weblog.inc";
	      $w = new Weblog("DBNAME", "DBHOST", "DBUSER", "DBPASS"); ?>

"<?php" must be the first characters in the file otherwise PHP will be
unable to use cookies properly. The Weblog code will refuse to work in
this situation.

Change "DBNAME", "DBHOST", "DBUSER", "DBPASS" to the appropriate
values for your database set up. If you are using PostgreSQL DBHOST
may be left blank if the database server is on the same machine as the
web server.

Put the follow code into your HTML where you want the weblog to be
placed:
	<?php $w->insert(); ?>

The weblog variables will determine what HTML is inserted. You will be
able to configure this through the weblog admin pages.

I have included an example in "example.php". You will need to modify
the database settings at the top of the file before it can be used.

4) Weblog admin set up

The weblog is deliberately missing a login form on the main screen.
There is no reason for visitors to see a login which is never intended
for them. To log in use a page similar to "login.html" included in
this package or add "?wl_mode=login" to your URL. For example:

	http://www.your.site/your_page.php?wl_mode=login

The default password is "weblog". Once logged in each entry displayed
will have edit/delete options.  Also at the bottom of the page there
will be "add entry", "edit topics", "edit setup" and "log out"
options.

The first thing you should do is go to "edit setup" and
			CHANGE YOUR PASSWORD.

Now you can customize the variables so the weblog fits your web page
style. The "Edit Setup" page contains help on each of the weblog
variables. I recommend reading all the help on that page to understand
how all the pieces fit together. The weblog will work fine out of the
box with the default values.

The topic icons included in this package are only place holders. You
may like to find some which fit the style of your home page better.

The "Edit Topics" page allows you to add, change and delete topics. To
add a topic just enter the details into the "Name" and "Icon" fields
and hit "add". To change a topic select the topic you want to edit
and fill in the field(s) you want to change - you can leave one blank
if you like.

When deleting a topic you need to specify what you want to do with any
entries currently in that topic. You can delete the entries or have
them moved to another topic of your choice.

The "Edit Entry" page has an option for updating the entry time stamp.
This will move the entry to the top of the weblog and let the user
know of the updated time stamp in addition to the creation time stamp.

The fields within an entry can (and probably should :)) contain HTML
formatting tags.

-------------------------------
External linking to your Weblog
-------------------------------

Personal Weblog uses several CGI variables for searching through the
entries before displaying the main page. Here are some you may find
useful:

wl_topic	A numeric topic ID used to restrict the search.
wl_search	Up to 3 keywords used to search entries through all
		entry bodies.
wl_before	All entries before a time stamp (Unix time_t seconds).
		Useful for displaying the start of the Weblog at a
		particular point in time. For example, this could be
		used to create next/previous day links.
wl_start	The ID of the first entry to be displayed on the page.

For example, if you wanted to link to an announcement with ID 7 on the
main page add "?wl_start=7" to your web page URL.

Linking directly to the announcement on the "more" page can be done
with "?wl_mode=more&wl_eid=7".

Displaying all entries can be done through the "archive" page using
"?wl_mode=archive".

Displaying all entries containing the keywords "insect" and "photo"
can be done with "?wl_search=insect+photo".

Personal Weblog also uses several internal variables in addition to
the ones mentioned above.

---------------
Editing entries
---------------

Personal Weblog automatically format paragraphs in an entry if they
are separated by a blank line. To enable this feature change the
"paragraph_split" variable in "edit setup" to contain a non empty
value.

----------------------------
Restricting Topics Displayed
----------------------------

Personal Weblog allows you to specify which topics should appear on a
page. This allows your site to share weblog topics between different
pages.

For example, show only topics with IDs 1 and 3 under the DBNAME
database:

$w = new Weblog("DBNAME", "DBHOST", "DBUSER", "DBPASS", array(1,3));

The topics IDs can be found on the "Edit topics" admin page.

Using this feature you can have several separate weblog pages which
share a common set of topic(s). Another advantage is this technique
makes it easy to merge a topic into another page using "delete topic".

----------------
Multiple Weblogs
----------------

Personal Weblog can support multiple weblogs per database. This is
useful if you would like several weblogs on a single site and the
service provider will only supply a single database. To configure
additional weblogs configure the weblog as described above, with the
following exceptions:

* When using "setup.php" specify a unique prefix for your new weblog.

* When initializing your new weblog specify the prefix you would like
  to use:

  $w = new Weblog("DBNAME", "DBHOST", "DBUSER", "DBPASS", TOPICS, "PREFIX");

If you are not using topic restriction use "" for TOPICS. Each weblog
is completely separate from the other weblogs within the database. For
example, searching and topics are not shared between weblogs.

----------
PostgreSQL
----------

To use a PostgreSQL database with Personal Weblog specify "postgresql"
at the end of your Weblog() paramter list. If you are not using topic
restiction or prefixes replace TOPICS and/or PREFIX with "". For
example:

  $w = new Weblog("DBNAME", "DBHOST", "DBUSER", "DBPASS",
                  TOPICS, "PREFIX", "postgresql");

If the database is located on the same machine as the web server
DBHOST will usually need to be left blank ("").

-------------------------------
Rich Site Summary support (RSS)
-------------------------------

Personal Weblog supports generating an RSS document describing the
current state of your site. Other sites can use your RSS document to
link directly to your articles.

To enable RSS support enter "edit setup" and fill in the "rss_title"
variable with the name of your site, and the "rss_description"
variable with a description of your site. If "rss_title" is blank, RSS
support will be disabled.

Once RSS is enabled you can link to the feed by appending
"?wl_mode=rss" to your site URL.

To make your RSS feed easier to automatically locate you can add the
following tag to the HEAD section of your HTML document:

<link rel="alternate" type="text/xml" title="XML"
      href="http://SITE/?wl_mode=rss" />

Make sure SITE is a valid hostname.

For more information on RSS visit: http://www.voidstar.com/rssfaq

--------
Advanced
--------

Personal Weblog supports extensions via hooks and sub-classing to
allow more customization by PHP programmers. Currently there are two
hooks available:

* subst_local()

You can embed @REF@xxx@ references into your weblog entries (title,
body, more). Just before the entry is displayed also @REF@ tokens will
be replaced with the output of "subst_local(xxx)".

* entry_save_local()

After an entry is saved "entry_save_local()" is called with the entry
details.

See "local.inc" for an example of extending the weblog through
sub-classing.

---------------
Page Refreshing
---------------

Some browsers may not notice changes immediately. There are several
possible solutions:

* Use "shift-reload" (or "shift-refresh") to reload the page.
* Click the "Search" or "Find all" button to reload the page.
* Change your "document compared to the network" setting to "Always".

---------------
Common Problems
---------------

* If PHP fails to work with your database make sure it has been
  compiled with MySQL or PostgreSQL support, or that the relevant module
  has been installed. Linux distributions often put the database modules
  in separate packages.

* When extracting the ZIP archive under Windows some programs convert
  linefeeds to CRLF. This conversion should be disabled before extracting.

* When previewing a new entry some of the links requiring an entry ID
  are broken. This is unavoidable since the entry hasn't been saved in
  the database at this point. Only the weblog admin will see this minor
  cosmetic flaw.

* Netscape Navigator 4.x has issues rendering transparent PNG icons.
  Most other browsers will work fine. To make your pages render
  correctly under more browsers you can "flatten" the PNG icons with a
  background matching your web page, or use a white background in your
  HTML to match the non transparent background used by the default
  Personal Weblog icons.

* Konqueror fails to reload the main page when clicking on the back
  link after editing settings, topics or adding an entry. This bug in
  Konqueror is documented at http://bugs.kde.org/db/32/32240.html.
  Shift-reload will correctly reload the page.

--------------

Feel free to email me any bug reports, comments or suggestions. You
can find the latest version at:
	http://www.kyne.com.au/~mark/software/weblog.php

Mark Pulford
mark@kyne.com.au
