Thank you for downloading Kipper Beta!

Hope we know what we're doing.

Kipper is an archiving system for cartoonists and writers that uses PHP to build static archive pages. The goal is to make the most powerful system possible without a database and without direct access to your server. All you need is PHP.

We use editable configuration files to control details, and page includes to feature content.

Here's what Kipper does:

* Builds multiple archives automatically
* Builds pages directly on the server
* Automatic listings of archives and individual comics
* Automatic include files for homepage
* Treats image and text files both as updates
* Multiple updates a day allowed
* Withholds future updates
* Updates new files with VirtualCron
* Basic web formatting for text files
* No dynamic URLs (none of this archive.php?p=12 junk!)
* Builds homepage

No installation is required. All you have to do is put your comic/story folders in the archive directory, edit some configuration files, and upload the scripts.

You will want to customize your site, as well. This is a generic site using a dummy logo and dummy comics. You only have to edit the header and footer files to change the content, and edit the stylesheet to change the colors and other details.

An important note: where I seem to be having the most trouble is with server permissions. Kipper shouldn't have any trouble writing to the read directory, but if it does, FTP to your server and adjust the settings manually. You may also get error codes when the script tries to write your homepage. Until we have a better way of managing permissions, you may want to remove the homepage section from the maker.php file.

In order to properly view and edit PHP files linked in this document (unless you are viewing this page online), right-click the links and select VIEW SOURCE, preferably in a text editor, if your browser gives you that option.


Quick start!
If you want to see Kipper in action right away, open the root config file, maker-config.php

In the top part of the file, change this line:

$BaseDir="http://www.bookelves.com/Kipper";

Change the URL, but leave /Kipper at the end. Then upload the entire Kipper folder to your website, and CHMOD it to 777. Then, go to your website, and open Kipper/maker.php.

If all goes well, you should be greeted with:

SUCCESS! More Generic comics archive complete.
SUCCESS! Generic blog archive complete.
SUCCESS! Generic comics archive complete.
SUCCESS! Archive index complete.
SUCCESS! Homepage complete.

You have just created a website albeit a generic one. Go to Kipper/index.php and see!

To employ Kipper for your own nefarious purposes, you'll have to understand it a little better.


Structure

In order to make your archive more powerful, it's important that you understand the website structure that Kipper assumes. Instead of one comic strip folder, put as many comic strip folders as you want into the Kipper bin.


File names

It's a common convention to use a date string at the beginning of a comic strip file:

20080505.jpg [yyyymmdd.jpg]

Kipper does not technically require this, but you should, for best formatting results. Files will be sorted alphabetically, in any case.

We suggest that you also include a short bit of text.

20080505-Jerry_hits_the_roof.jpg
20080506-Captain_Buff_gets_drunk.jpg
20080507-Holy_Moly.jpg

There are many good reasons for this. Kipper will strip the underscores from the text for links and page titles, making your site even more navigable and searchable. The random text will also prevent readers from guessing the location of a future update.

If you plan on updating more than once in a day, use letters to keep the updates in alphabetical order:

20080505a-24_hours_a_day.jpg
20080505b-24_hour_marathon.jpg
20080505c-Must_draw_faster.jpg

Use the same file format for jpg, gif, png, and txt files.


Comic folder configuration

Each comic folder should have a file called maker-config.php. This is important. A missing config file will cause the script to stop.

Copy one of the config files from our sample comic folders and edit it with your text editor. Here's what you should see:

<?php
$Title="Generic comics";
$Description="A bunch of junk files, for testing purposes only.";
$Keywords="comics, entertainment, funny.";
$Spoiler="These are just sample comics.";
$NextComicDir="more_generic_comics";
?>

Just edit the information in quotation marks. Let's say one of your comic folders (buck_naked) contains a series called Buck Naked. The config file in buck_naked should read:

$Title="Buck Naked";
$Description="The adventures of the man with the embarrassing name.";

If you have more Buck Naked comics in a second folder called buck_naked_02, you would mention it in the buck_naked configuration file.

$NextComicDir="buck_naked_02";

That way, Kipper will know to create a jump link from the one archive to the next. Otherwise, leave it blank, like this:

$NextComicDir="";

The Spoiler field can be useful for ancillary description, but you can leave it blank, too.

$Spoiler="Despite the name, Buck Naked is work safe!";


Archive folder configuration

There is a maker-config.php file for the bin folder, too. Just be a little more general, since this information appears on the index to all your archives.

<?php
$Title="The Mahatma Kane Jeeves Archive";
$Description="Comics and stories, including the adventures of Buck Naked.";
$Keywords="comics, entertainment, funny";
$Spoiler="Live! Love! Laugh!";
?>


Site configuration

There is one file called maker-config.php right inside the main Kipper folder. Most of it you don't have to change at all. You will need to enter your name and the current year, for copyright purposes.

You will also need to enter the location you will put the scripts and folders. For example,

$BaseDir="http://www.website.com";

or

$BaseDir="http://www.website.com/Kipper";

...just depends where you are running the script from. You decide what Kipper's root location is. You will have to be responsible for having things in the right place.

In this file, you will also set the number of minutes to check for updates. Set it to 1440 minutes for 24 hour updates, 720 minutes to check every half day, and 60 minutes or less if you're marathoning.

You may want to include a Paypal link for donations. Enter (or edit) the code here.


Including the updates in the home page

Open our sample copy of index.txt to see how it's done.

<?php include("read/generic_comics/updated.txt"); ?>

<?php include("read/generic_blog/updated.txt"); ?>

Include any archive by changing the name of the archive folder in the code. For instance, our old pal, Buck:

<?php include("read/buck_naked/updated.txt"); ?>

The files named updated.txt are automatically generated by Kipper. All you have to do is point to them.

Kipper does not add break tags to the index page file, because we make the assumption that you will want more control over this layout than on most other pages.


Editing the header and footer files

Look at the sample header and footer files for ideas. The included setup uses styles to arrange the page elements, and is designed to allow your central page content to load before the sidebar, even though it is on the left.

You can use this design, if you want. Anything you want in the sidebar, for instance, simply include in the sidebar section in the footer file. Be sure to replace the logo in the header file with your own.

Note the use of $BaseDir, $Author, and $Copyright in the sample files. Kipper replaces these fields with information you filled out in the config file. Your logo, for example, should be linked something like this:

<img src="$BaseDir/images/bucknaked-logo.gif" ... />

This is to make sure that the images and other files are linked correctly in the archive.


Tweaking the navigation

The default navigation bar has a lot of buttons. If you want to leave some off, especially the donation button at the end, delete the lines of code that create them. Open make-navi.php and look near the end for:

$Navi=$Navi."<a href=\"".$PaypalLink."\" id=\"cg_kaching\"><span>Donate</span></a>";

Just delete this line if you don't want the donation button to appear.


Upload and run

Upload the files and open maker.php in your browser. Unless something goes horribly wrong, Kipper will loop through the bin directory, and create matching archive pages in a new directory called read (assuming that you haven't changed these directories in the config file).

If you run this folder without doing anything but editing the location of the root directory, you should get this output:

SUCCESS! Generic comics archive complete.
SUCCESS! Generic blog archive complete.
SUCCESS! More Generic comics archive complete.
SUCCESS! Archive index complete.
SUCCESS! Homepage complete.
SUCCESS! readme.php complete.


Tips, advice, cautions

Make sure all your archive folders have config files!

Do not upload the sample read directory! Let Kipper build it, or else you will have to reset all the permissions by hand.

Keep your directories clean! Kipper reads the entire bin directory in order to build the archive.

Kipper does not delete orphaned directories. For a clean rebuild, delete the entire read folder before running maker.php.

To keep people from messing around with the script, change the name of maker.php to something only you can find. You will also have to go into the main maker-config and redirect the Cron job script. The Kipper engine, make-it.php, won't process anything without maker.php.

Kipper creates archive navigation, and includes links back to the homepage as often as possible, but is not responible for overall site navigation. Include your own menu in the header file, or in the sidebar of the footer file.

If you number directories, try to use two digits instead of one. 01-10 stay in order; but computers will list 10 in between 1 and 2.

Get a web server for your desktop. Instead of Apache, try Abyss, which is both free and easy to install. Abyss even gives you pretty good instructions for installing PHP. Once you've done that, you can run Kipper on your desktop, which makes it very easy to test. And it's nice having a desktop copy of your archives!


Inspiration
It's probably hard to tell at this point, but this script originally started as a series of minor tweaks to ComicGallery. There's almost nothing left of it now but the navigation CSS.

VirtualCron is a PHP class by Giorgos Tsiledakis.

And, of course, we're actively stealing as much as possible from the immortal AutoKeen.

I'm not a programmer, myself. It's just that I've been waiting ten years for somebody to do this, and I finally just had to sit down with a copy of O'Reilly's Webmaster in a Nutshell and try to make things work until they worked. Having said that, email me if you run into any trouble. I offer this script free as is--I can't offer tech help, but I can try to fix what doesn't work.

Mainly, this is my chance to give something back. I truly hope this helps somebody somewhere somehow.


To do

* Better management of file and folder permissions
* RSS/Atom feed
* Slightly more advanced text file processing
* Simple non-archive content management