==================== TENACITY v3 README ==================== ========== Contents ========== 0.0 What TENACITY Is Not 0.1 Why Not MySQL? 1.0 Installation 1.1 Config Settings 1.2 Strict PHP Safe Mode 2.0 Usage 2.1 Uploading Comics 2.2 Filler Images 2.3 Manual Update 2.4 Debug Information 3.0 Creating Styles 3.1 Function Reference 3.2 Rollover Images 4.0 Version History 5.0 Legal ========================== 0.0 What TENACITY Is Not ========================== TENACITY is not a content management system. It is not a blog platform. It is not user-friendly. TENACITY was written for the purpose of streamlining a comic site that would otherwise be written in static HTML. It requires you to know how to manage a static website via FTP, and includes next to no automation to that end. If you're looking to eliminate the hassle of manually creating and editing HTML files with every update and nothing more, TENACITY is for you. If not, you really want to keep looking. ==================== 0.1 Why Not MySQL? ==================== Because I'm lazy. MySQL isn't exactly tough to work out, but it's tough enough. Besides which, I wanted TENACITY to be a little more portable. As in, I want to take the copy on my home computer, upload it to a server with PHP installed, and it will just work. No setup, no headaches, just one little FTP operation. (Not counting the guy with some weird server setting that totally breaks my code into a million pieces.) Besides, I like having a working copy of my website on my local machine, and I have no desire to try and keep MySQL synced between my computer and my webserver. My webserver is in TEXAS. That's a very long Cat5 cable. ================== 1.0 Installation ================== Edit the settings in tenacity_config.php, edit one of the included styles or create one from scratch, upload to your webserver. As long as you keep the directories intact, it should work without a hitch. TENACITY has been tested to work in PHP 4 and 5, and should work on most webhosts, though some folks disable the ability of PHP to write files, which will make TENACITY cry. See section 1.2 for how to fix this. ===================== 1.1 Config Settings ===================== These are all set in tenacity_config.php. It should be fairly easy to set up, and apart from $style you can just leave them all set to their defaults and TENACITY will work just fine. [ $style ] This is fairly self explanitory, it's just the name of the style you're using. If this doesn't point to a valid style, TENACITY will fall back to the default style. DO NOT delete the default style, as the lack thereof could cripple TENACITY and hurt the feelings of several orphans. Usage: $style = "[name of folder in 'styles/']"; Example: $style = "pfs_2k9"; // This will load the file 'styles/pfs_2k9/style.php' Default: 'default' [ $automatic_update ] This is used to stop TENACITY from automatically updating the God File on a system where PHP isn't allowed to write to a file. Shouldn't be a problem on most webservers, but some hosts have really strict Safe Mode settings. If TENACITY doesn't show the newest comic or fails to load at all, this might be the culprit. Usage: $automatic_update = [true/false]; Example: $automatic_update = true; // This will enables the automatic update of the God File Default: true [ $custom_extension ] If your comics use a file extension other than jpg, gif or png, TENACITY won't be able to find them. That's where this setting comes in. Note: Setting this to 'swf' won't work, as Flash doesn't end up on a page via the img tag. Flash support may be added in the future, but if you're a flash developer you can probably make a better CMS using, y'know, Flash. Usage: $custom_extension = ".[filename extension]"; Example: $custom_extension = ".bmp"; // Who in their right mind would actually do this? Default: '.jpeg' [ $comic_dir ] This is where TENACITY looks for comic images. There's really no reason to ever change this. Usage: $comic_dir = "[directory]/"; Example: $comic_dir = "manga/"; // TENACITY will look in the "manga" directory for comics Default: 'comics/' [ $rant_dir ] This is where TENACITY looks for rant files. Setting this to the same directory as $comic_dir will make it a little easier to upload comics and rants at the same time, but that's too cluttered for my tastes. Usage: $rant_dir = "[directory]/"; Example: $rant_dir = "webcest/"; // TENACITY will look in the "webcest" directory for rants Default: 'rants/' [ $filler_dir ] This is where TENACITY will look for filler images. (More on those in section 2.2) Don't set this as the same directory as $comic_dir, as that will probably break something and would be kind of pointless. Usage: $filler_dir = "[directory]/"; Example: $filler_dir = "nsr/"; // TENACITY will look in the "nsr" directory for filler Default: 'filler/' ========================== 1.2 Strict PHP Safe Mode ========================== Some webhosts don't allow PHP to write files. Since TENACITY will, by default, try to rewrite the God File any time there's a newer comic than the one recorded in the God File, it'll break. If this is the case, you're going to have to disable $automatic_update in the config file (see the above section) and manually update the God File for every new comic, but it's not really that hard. Just open god_file.php in notepad or some other text editor, change the number after "$newest_comic = " and save the file. Now you just have to upload the new God File when you upload the comic image. =========== 2.0 Usage =========== Usage is pretty simple. If you know how to use an FTP client, you can update TENACITY. And if you don't, how in god's name did you get it installed in the first place? ====================== 2.1 Uploading Comics ====================== This is pretty simple. First, make sure the comic is named correctly. The filename should be just a number, followed by the extension, as in "13.jpg". It needs to be the next number after your newest comic, so if the newest comic is number 324, then the next one has to be 325. Remember, TENACITY starts counting at zero, so if your first comic is 1.png, the first comic will just be an error message about how TENACITY can't find the comic image. Currently, TENACITY only works with files with the extensions "jpg", "png", or "gif". If you're uploading a rant, it works the same way, but the rant has to be a text file with the extension "txt". Just upload your comic into the "comics" directory, your rant (if you have one) into the "rants" directory, and proceed to the next step. If you named the files correctly, it's really simple. If you didn't, you'll spend about an hour trying to figure out what you did wrong. In this way, using TENACITY is very similar to writing the code for TENACITY. Important: DO NOT put a bunch of zeros in front of the comic filenames. This will prevent TENACITY from finding them, because I'm too lazy to make TENACITY handle that kind of thing intelligently. RIGHT: 0.jpg, 1.png, 2.gif ... 10.jpg, 11.jpg WRONG: 000.jpg, 001.png, 002.gif ... 010.jpg, 011.jpg =================== 2.2 Filler Images =================== Filler images are basically comics that won't show up when reading the archives sequentially. This is basically so random filler doesn't break up the flow of a story comic. Basically, if TENACITY finds an image in the "filler" folder with the same number as the newest comic, it'll display that instead of the newest comic. It won't show up at any other time, unless you specifically tell TENACITY to. Displaying a filler image manually works like displaying a regular comic, except you'd replace the "strip_id=" in the URL with "filler_id=". So to display the filler image 22.jpg, you'd link to "index.php?filler_id=22". If filler_id and strip_id are both in the URL, filler_id takes precedence. =================== 2.3 Manual Update =================== This isn't as easy as the above method, but it won't kill you if you have to do it. TENACITY, being incredibly simple, stores the newest comic number in a file I call the God File, due to the fact that screwing this file up is the single easiest way to break TENACITY. To manually update, just open "god_file.php" in Notepad, vi, or your preferred text editor, and change the number after "$newest_comic =" to the number of the newest comic. If you do this, make a backup copy of the God File first. I seriously doubt that anyone competent enough to use TENACITY will have to worry about screwing up the God File, but make a backup, just in case. I admit it, I just really love typing "God File." And seriously, make a backup. Just to have one around. Just in case. ======================= 2.4 Debug Information ======================= There shouldn't be a need for this unless you edit TENACITY itself (which is just fine) or have some PHP in your style that might be interfering with TENACITY, but there's no reason for me to take it out. If you view the page source, you'll see a comment at the top of the page with about as much debug information as TENACITY is capable of producing. There's not much there, but there's not much of TENACITY. ===================== 3.0 Creating Styles ===================== Making a style for TENACITY is simple. Just make a normal HTML page for your comic, adding in some PHP functions to handle the comic, navigation, and the rant. If you can't do this, you probably shouldn't be using TENACITY in the first place. You can probably do it entirely in Dreamweaver or some other WYSIWYG editor, but I haven't verified this since I write my own markup. (Seriously, people, HTML is not even remotely hard.) You can also add your own PHP to the style itself, though you should probably look over TENACITY's source first to make sure you're not going to break something. It won't take long, TENACITY is less than 200 lines, and most of that is there for readability. One thing to remember, because it drove me nuts for hours before I figured it out myself: Although the images for your style will probably be in the same folder as styles.php (if you're anal like me, at least), any links in your style will be treated by the browser as being relative to index.php. So if your images are in "styles/your_style/images" you'll have to put that in front of every relative link to your images, CSS, etc. Of course, you can put those files anywhere and link to them however you want, so this is only an issue if you're anal about keeping the styles in one place. (And of course, any links in the CSS file will be relative to the CSS file, not index.php. Nice and "simple.") The easiest way to do this is probably to make a copy of the "template" style and work from that, or just edit one of the included styles if you can work out my markup. (I never claimed to be good, just better than Dreamweaver.) ======================== 3.1 Function Reference ======================== comic() Inserts the img tag for the comic into the page. Arguments: image_isnextlink Tells TENACITY whether to make the comic image a link to the next comic. Expected values: "true" or "false" Default: "true" Examples: rant() Displays the 'rant' associated with a comic, if any. Basically, text you want displayed along with a comic. Arguments: rant_show_newest If there is no rant file for the current comic, TENACITY will search back until it finds one. This is useful if you use the rant files for news instead of commentary on a particular comic. Expected values: "true" or "false" Default: "true" Examples: permalink() Insertss a link to the current comic. Mostly it's there so I have an easy way to link directly to new DbD comics, but it's one of those things that's just useful enough to justify the five minutes it took to add it to TENACITY. Arguements: link_text The text it to be inserted. Any HTML that can be wrapped in a link will work, but double quotes need to be escaped by putting a backslash in front of them to keep the PHP from breaking. Expected values: A string Default: "Permalink" rollover Tells TENACITY whether to insert the javascript to support rollover images. Section 3.2 has more information on using rollovers. Expected values: "true" or "false" Default: "false" Examples: ", true); ?> first_link() Inserts a link to the first comic. If the current comic is 0, the text is inserted without a link. Arguments: first_text The text it to be inserted. Any HTML that can be wrapped in a link will work, but double quotes need to be escaped by putting a backslash in front of them to keep the PHP from breaking. Expected values: A string Default: "First comic" rollover Tells TENACITY whether to insert the javascript to support rollover images. Section 3.2 has more information on using rollovers. Expected values: "true" or "false" Default: "false" Examples: ); ?> ", true); ?> prev_link() Inserts a link to the previous comic. If the current comic is 0, the text is inserted without a link. Arguments: prev_text The text to be inserted. Any HTML that can be wrapped in a link will work, but double quotes need to be escaped by putting a backslash in front of them to keep the PHP from breaking. Expected values: A string Default: "Previous comic" rollover Tells TENACITY whether to insert the javascript to support rollover images. Section 3.2 has more information on using rollovers. Expected values: "true" or "false" Default: "false" Examples: ); ?> ", true); ?> next_link() Inserts a link to the next comic. If the current comic is the newest, the text is inserted without a link. Arguments: next_text The text to be inserted. Any HTML that can be wrapped in a link will work, but double quotes need to be escaped by putting a backslash in front of them to keep the PHP from breaking. Expected values: A string Default: "Next comic" rollover Tells TENACITY whether to insert the javascript to support rollover images. Section 3.2 has more information on using rollovers. Expected values: "true" or "false" Default: "false" Examples: ); ?> ", true); ?> latest_link() Inserts a link to the newest comic. If the current comic is the newest, the text is inserted without a link. Arguments: latest_text The text to be inserted. Any HTML that can be wrapped in a link will work, but double quotes need to be escaped by putting a backslash in front of them to keep the PHP from breaking. Expected values: A string Default: "Latest comic" rollover Tells TENACITY whether to insert the javascript to support rollover images. Section 3.2 has more information on using rollovers. Expected values: "true" or "false" Default: "false" Examples: ); ?> ", true); ?> ===================== 3.2 Rollover Images ===================== Rollover images are basically some javascript that switches one image for another when the user mouses over them. I use them to make my navigation links "glow." Currently, rollovers work for the permalink and all of the navigation link functions, and they work in basically the same way. You put two images in the link, giving one the ID "[function_name]_active" and the other "[function_name]_inactive", set their rollover to "true," and TENACITY will make it happen. Note that TENACITY won't insert the rollover script if there isn't a link, so for example the first and previous links won't have rollovers if the current comic is 0. If all that is greek to you, just look in the function reference. Every function that supports rollover images will have at least one rollover example. ===================== 4.0 Version History ===================== 0.10 First version, worked but required too much FTP work for each update, and I'm lazy 0.20 Code for comic verification and search redone. Uses a bit more server overhead, but doesn't require the latest.php file config.php added to store user-definable options which were formerly in latest.php Changed archives.php from a standard HTML form to a loop to make it automatically Added more comments so other people can actually understand the code ^_^ 0.21 Changed the name of the comic, as the original one was already taken ^_^;; 0.30 Comic verification code was rewritten Archive dropdown box was redone (Starts at newest comic instead of oldest) Added support for multiple image formats 0.35 Removed formatting info from core PHP Added skin support. Added default and classic skins Added text.php for text-only display 1.00 Release version! Whee! ^_^ Removed skin system because it served no real purpose Added formatting to index.php Added support for non-talkative days (Searches for previous rant if no rant exists) Layout changed Layout converted to CSS/XHTML Layout validated 1.01 New layout, validated, all that jazz 2.00 New version written from scratch. (Hopefully) easier on server Style info now located in separate files, easy to switch between styles by changing config file Optomised search script No longer searches for newest even when the newest strip number isn't needed Uses more efficient "up by ten, down by one" method. (Hopefully) with more robust comments to aid in hacking the main file Now only works with JPG, PNG, and GIF images, though more would be easy to implement No longer requires a separate info file for each comic, just the image and a rant file (rant doesn't need to have any contents at all to work, just has to exist) Set up to be practically "plug and play," very little setup needed No MySQL support (to ease installation), may write a sister app in the future that runs on MySQL 2.01 Fixed some minor bugs Fixed bug where newest page is displayed twice before user is redirectd to index.php# (now links directly to index from second-to-last page) Fixed bug where "Prior" link on first page redirects to index Tweaked link to first page in style to include an empty anchor, like the index page Actually updated the "last revision" line up there for a change... >_> Added a default version of the NSR style to the distributable version of TENACITY, in addition to the SEP-based style 3.00 Yet another rewrite. Backend code streamlined, should be a bit easier on server hardware Visits to base URL (no specific comic requested) no longer cause dozens of file ops Skinning overhaul Styles now contained in one file instead of three (not counting CSS or images) Comic / rant display and navigation buttons are now functions - much easier to write styles Added God File which tracks newest comic in order to save server resources Added setnewest tag to automatically update God File (if possible) Added style tag to allow manual style selection As it's a debug option, the navigation links won't pass this tag along Added style template 3.01 Added support for javascript rollovers to navigation button functions Moved the last of the function-specific options from config file to functions themselves Added content to the glorified version history file called readme.txt New default style created 3.50 Removed setnewest tag, TENACITY now automatically checks for newer comics and updates the God File as needed 3.55 Changed to creative commons license for TENACITY and stock themes Fixed bug that prevented custom_extension from actually working Added filler support (comics that won't show up when reading the archives) Added manual filler select Added ability to customize rant, filler and comic directories Dropped manual style select for security reasons =========== 5.0 Legal =========== TENACITY is copyright 2006-2010 Devin Goodman. TENACITY is distributed under a Creative Commons Attribution Noncommercial Share Alike 3.0 license. This means you're free to use, modify or redistribute TENACITY so long as you give credit to all contributors, don't try to sell it, and distribute it under a similar CC license. A full summary and links to the legal text of the license can be found at http://creativecommons.org/licenses/by-nc-sa/3.0/ This license applies only to the TENACITY software and stock themes that come with it, not the websites or comics using it.