BookAdder Docfile:
Files List

BookAdder: Its Component Files and Their Purposes and Uses

This list is more than just a list: it tells you what each file is there for, and in some cases gives you some tips and hints not covered elsewhere in these docfiles. It's well worth running down, even if everything seems to be running ok.

Since any "logical grouping" of files would be subjective, I present them alphabetically (and not subdivided by extension).

(Note that in five cases, those of the .htm files, there is actually a file pair, the .htm file itself and an associated PHP "handler" script; the .htm file is almost, but not quite, a web page in itself--the handler reads it, notes certain specially formatted HTML-comment lines in it, plugs in some data in place of those comment lines, then returns a fully made HTML page to your visitor. That general principle of separating a PHP script from an associated .htm file allows those not comfortable with PHP to nonetheless customize their pages freely, since those .htm files are all just plain HTML; all you have to do is not fiddle much with the special-form comment lines. Details appear in the docfile Further Customizing BookAdder.)

Where particular calls for scripts are discussed below, don't forget that if you have set a password, you will need to add &pw=your phrase into the calling parameters; for simplicity, that is not shown in any calls in the descriptions below.

Finally, this list omits the documentation files whose names each begin with DOC- because those are listed at the bottom of the page, as they are in all the docfiles.

red-cats-books.php

(This is listed first, out of alphabetical order, because its true name will depend on what you chose to call your BookAdder "front page".)

This is a tiny script that merely loads and runs the script realshop.php. It is provided as a way to "alias" realshop.php to whatever name you selected and set at Step 3 in customize.php. See the entry for book-shop.php for more information.

red-cats-books-sitemap-XX.xml.gz

(This also is out of alphabetical order, because its true name will depend on what you chose to call your BookAdder directory.)

This entry covers six (or more) files whose real name will begin with whatever is your BookAdder main directory's name; in the sample heading above, that is red-cats-books, and the part shown as XX would be one of the six two-letter Amazon national-division codes BookAdder uses, a different one for each file. (It is very unlikely, but there could also be other files, of the form red-cats-books-sitemap-XX2.xml.gz--note the 2--if a single map would have had 50,000 or more entries.)

These files are your gzipped xml-format sitemaps, one (or rarely more) per Amazon national-division bookshop (as I keep saying, you really have six distinct bookshops). Almost all browsers "know" how to read gzipped data, so you can look at these files direct with your browser if you care to. These maps are indexed in a single map-index file named Bookshop_index.xml (described farther below), and it is that one file that you register with the search engines, as described at length in the docfile Tuning Your Search.

.htaccess

This file will only have effect on servers powered by the Apache server software package (which is the majority). Under Apache, a file of that name can contain any of numerous different overrides of master server settings of various sorts; any directory or sub-directory can have an .htaccess file in it, and their effects are cumulative: an .htaccess file can override the master settings, or settings made in a similar file in a higher-up directory. A setting can be made and changed and re-made and re-changed on the way "down" through the subdirectory hierarchy. Settings in the lowest-order subdirectory always trump those in higher-order ones, so this one will apply only to the main BookAdder directory and its private subdirectories. Note, however, that the server or some higher-up .htaccess file can contain directives not to allow lower-order ones to override some or all settings--so there is no guarantee that the BookAdder local .htaccess file will really be able to control any or all of what it tries to.

What it tries to do is four things: call unwrapped PHP; disable PHP "Safe Mode" if it was On; allow PHP remote file opens via HTTP if that was disallowed; and turn off PHP's "Register Globals" directive if it was On (a widely recommended safety measure). The final status of those settings can only be determined by running tryme1st.php.

4me.php

This file only exists if you have used makepw.php (described farther below) to make a BookAdder password; if you have, this file contains the 32-character check "hash" for password-matching. If you simply delete this file, password validation is dropped, and you can run anyscript without a password. This whole matter is discussed at some length in the docfile Security-Related Concerns.

abechange.php

This script is called only by abes.php (see below); it allows users to change the search and display criteria used by that script for used books found at Abebooks by either a link from the main title lists or a freeform search from used-books.php (see below). This script gets counted by searchbots, at the rate of two pages per listed title--two because for each title there is an ISBN Abebooks page and a title/author Abebooks page.

abedata.php

This is a complicated module of functions used by the Abebooks-related scripts in BookAdder; its routines are used by too few scripts to be put in the main freebie.php routines, but are too long to be repeated in each place where used.

abes.php

This is a "recursive" script, in that it can and often does re-call itself. It is initially called with either just an ISBN or just a title and author as parameters (but also, in each case, a n Amazon national divisions, which defines its "home" currency and shipping rates), from which it constructs the proper call URL to the Abebooks search facility. It can then recursively call itself to display more pages of a listing, or can jump to abechange.php (see above) to change the search and display parameters, after which it is called again with the new parameters as inputs. In its display of available used books, each seller's "offer" is a link to that particular seller offer through Commission Junction, so if a visitor buys a book from these listings, a commission is generated; as detailed elsewhere, you and I split such commissions 50-50 (if you are an Abebooks affiliate). This script counts with searchbots as a "page" of your site for the associated title; in fact, it counts as twelve because it is different for each Amazon national division, and for each has both an ISBN-based value and a title/author-based value.

access.php

This is where you store your Amazon key pair, needed to communicate with the Amazon databases. This file alone is not repermissioned by BookAdder, so that it is always "owned" by you (or rather, your FTP process), and cannot be written to or deleted by any PHP process.

adsense1.php

This is where you put your Google AdSense HTML code. If you don't want AdSense ads on your pages, you can delete all the code in it.

If you need more than one form of AdSense code--for example, for different color combinations, or different display types-- just make more modules, up to 10 total, each named adsenseX.php, where X is a numeral from 0 to 9; then, in the .htm file or files where you want these other Codes to go, place reference lines just like the original, but with the different numbers. An example of an existing call line from an .htm file is:

<!-- ADSENSEDROPIN #1 : puts a particular Google AdSense insert here -->

Just change the 1 to whatever number AdSense module you want called there instead. And you can put any number of such module calls in any of the .htm files, which template all the pages a visitor will see except for the numerous individual-title pages. On the individual-title pages--it seemed to me--putting AdSense ads would be inappropriate, as the visitor is there only to see about that one book, and one muddles the "buy this!" message by using other ads; but, if you want to add some there, too, you can add this little block of code to the PHP script free.php at the point where you want the AdSense ads:

$adsense=file('adsense1.php');
spill($adsense);

(Using, of course, whichever adsenseX.php you want to appear there.)

amazon-logo.gif

This is the small logo that is used where the mandatory Amazon message is called from your bookshop front page. Amazon has others available to Associates, and you can feel free to substitute in whatever other one you may want--just being sure to rename it to the set name of amazon-logo.gif.

amazon-message.php

This is the PHP "handler" script (see the note atop this docfile) for the HTML in the associated file amazonmessage.htm.

amazonmessage.htm

This is the actual HTML page code that goes with the PHP handler script amazon-message.php. As with all the .htm files, you can freely modify it so long as you keep the special-comment lines unchanged (though you can move most about as you like). Do recall, though, that--as it says in this file--Amazon's Terms of Service require that you present the bare message herein. I'd just leave this alone: it's not worth any effort playing with unless you are anal-compulsive about having all your site pages exactly match some format.

attack.php

This is an ancillary tool not actually needed for anything, but included as a little "extra". It is intended for verifying that the spammer-throttle (described later) is working as you expect: it "attacks" the Amazon-message page (arbitrarily chosen by me for this test) by requesting it every N seconds, where you can set N to be anything from 1 to 10. You set that parameter by how you call the script; for example, a call of--

attack.php?every=6

--will generate a request every 6 seconds. When you are happy with the settings in the timer.php script, use this script to verify that request rates slower than or at your cutoff can go on forever, while those faster will eventually be throttled (how quick "eventually" is depends on how much faster than your threshhold the requests come in, as detailed farther below at timer.php).

avails.php

This is a datafile that BookAdder uses to try to translate non-English "Availability" and "Media" (binding) information into English. It is a separate module so that it can easily be updated as Amazon whimsically changes the text they use to denote certain things. A real international business would use set codes that users would then translate into their local language, but Amazon is, as we all know, not a real business--so we have to try to accomodate to their bizarre whims.

I am not an expert linguist: I made these by research and comparison (the obvious course of using a dictionary or translation service yields poor results, as many of these words, especially for "Media", appear to be technical terms of art). If you can improve or augment this module, feel free (but I ask, as a favor, that you e-mail me with any such information, so I can share it in the next BookAdder version).

bomb.php

This is a potentially dangerous script! It can wipe out most of your bookshop in the twinkling of an eye--in fact, that's what it's designed to. It is to be used when upgrading from an older version of BookAdder (or, Lord help us, Freebie). Its use is described in detail in the docfile Upgrading. For safety, it will not run unless a special parameter tail is attached to the call: that way, you cannot inadvertently run it by a misplaced click in a directory list. Read the linked docfile for details.

book-search.php

This is the PHP "handler" script (see note atop this docfile) for the associated HTML file booksearch.htm, which is the general new-book-search page.

book-shop.php

This is a tiny script that merely loads and runs the script realshop.php. It is provided as a way to "alias" realshop.php to book-shop.php ; that is not, in my opinion, an optimum name for your shop's "front-door" page, and ideally you will have set another in customize.php (described below and in the installation docfile. If you have set another, better name, the installer simply copies book-shop.php to that other name (so calling book-shop.php will always bring up your front page, even if some other, better name also does). This file is also copied to the name index.php, so that anyone using just your bookshop directory as a URL call will get your front page instead of either a listing of the contents of your bookshop directory or a "Listing Forbidden" message, depending on how your server is set.

bookcount.php

This is the PHP script that allows you to find title counts for any search phrase in all Amazon national divisions; called with no parameters, it defaults to the search term set in your customize.php file.

books.ico

This is a default icon file used by BookAdder as its "favicon" if you do not specify one in the customize.php file.

booksearch.htm

This is the HTML "handled by" (see the note atop this docfile) by the PHP script book-search.php, described farther above. It includes a complex form for specifying search parameters that will be passed to search.php (described farther below), the script that does the actual searching and reporting.

bookshop.htm

This is the HTML "handled by" (see the note atop this docfile) by the PHP script book-shop.php, described farther above.

bookworm.jpg

This is one of the images used on your bookshop's "front page".

Bookshop_index.xml

This XML file, made at installation time, is the master sitemaps-index for all the six sitemaps that BookAdder makes of itself at every search run (something ideally done daily). For the mapping to be of use to you, you must register the index with the search engines; the whole topic is discussed at length (with links to the search-engine site pages you need) in the docfile Tuning Your Search.

calltest.php

This script is only for diagnostic-test purposes. It takes as its only call parameter an ASIN (?asin=xxxxxxxxxx), and shows the generated calls to each Amazon division and the responses those divisions send back. (Its calls duplicate those of free.php.)

coopads.php

This little "include" file is read by runcoopads.php, described farther below. It controls only two things: whether or not Digitalpoint Co-op Network ads are to appear on any of your pages, and--if so--the name of the Co-op-supplied PHP script to use for getting those ads.

This module defaults to being NON-operative! If you are a Co-op member, you must edit this file (as described in the docfile on customizing) to change the NO to YES.

(The file itself also contains explanation, for your convenience.)

For the module to work, the Digitalpoint-provided PHP script ad_network_NNN.php (where NNN is the current Digitalpoint serial number) must be in the main BookAdder directory or any directory above it--up to 9 levels up--and that Digitalpoint script must be able to find its datafile ad_network_ads.txt (it's usually put in the same directory as ad_network_NNN.php). Incidentally, these are server-file-system directories, not site-based directories, so if you have several sites off one primary server directory, you don't need to have multiple copies of the Digitalpoint files.

cronf.php

This script is callable like any other PHP script (via browser, that is), and, if so called, will run for 5 or 6 seconds, then quit--during which time it has started, as a silent, "daemon" process, the entire updating process of searching each Amazon division for all titles relevant to your search phrase. So you can start this guy, then go about your life while, on your server, the scripts are doing their long, tedious work. But the real purpose of this script is to allow you to start your update job--which I strongly recommend you do once a day--as a cron job: you set cron to run this script daily, and that's all she wrote. Setting up automatic recurring operation is described at length in the BookAdder docfile Tuning Your Search; I again emphasize that it is really important that you set the search runs up as an automatically done daily job.

customize.php

This file controls your most important customizations of BookAdder; it is heavily annotated internally, plus and it is explained at vast length in the docfile Installing BookAdder.

docs.html

This is just a quick mini-menu of all the DOCfiles available in the BookAdder package (each DOCfile listing is a link). It exists to save your having to type in the rather long and complicated names of the various DOCfiles to see one: instead, just go to docs.html and click the appropriate link.

exterminate.php

This script is described in the docfile Security-Related Concerns. You should be very careful with it. For that reason, the installer erases it from the BookAdder directory; to use it, you need to upload it. I urgently recommend that if you ever do want to use it, you upload it, use it, and erase it again; you do not want it lying about where you might accidentally click on it, or where an attacker could get at it.

This script will erase whatever one file you specify in its parameter string using the &spec= syntax. It will only work on one file at a time--no wildcarding of any sort works. Also, it will only erase a file in the main BookAdder directory or some subdirectory thereof. Also, you must upload it to the main BookAdder directory; to erase a file in a subdirectory, use the relative filespec (such as logs/Fake.Log). Remember that on Unix-based systems, case is in filespecs--logs/fake.log and logs/Fake.Log are two different specs.

This whole rigmarole is provided for the highly unlikely case that permissions and Safe Mode have conspired to leave you with one or more files that PHP "owns" that you don't want but cannot erase via FTP because you don't own the files. This will not work on subdirectories, only on files. You'll almost certainly never need it, but it's there in case.

findbooks.php

This PHP script is the actual search workhorse; it searches all Amazon divisions for all books returned by Amazon at each in response to the search phrase you set in customize.php, and lists them as HTML Table "drop-ins" in 27 files (per division) placed in the /bookpages subdirectory of your main BookAdder directory, each such file named along the lines of dropins-B.ca.

Note that findbooks has a fail-safe for those days when Amazon is having a bellyache: it will not replace the previous day's search results if the current ones are not at least 80% as many titles. That way, a failed, corrupted, or interrupted search will not partly or wholly wipe out your bookshop's inventory.

While this script is running in "daemon" mode--meaning not directly through your browser--it can be killed by uploading to the main BookAdder directory a file, whose contents are immaterial, named findbooks.kill. The findbooks script checks every 5 seconds or so, and if it finds that file, it first erases it then exits.

finstall.php

This is, yes, the BookAdder installer. Its work is described at length in the docfile Installing BookAdder, but here in summary are the things it does:

• It permissions--or tries to--all BookAdder files to either 666 (rwxrwxrwx) or 644 (rw-r--r--), depending on whether it detects cgi-wrapping of PHP on your server (666 if not).

• It makes--if they do not yet exist--and permissions all the subdirectories needed in the BookAdder main directory; it sets them at either 777 or 744, depending on whether it detects cgi-wrapping (777 if not).

• It copies book-shop.php to whatever name you set forth in customize.php (if nothing, it makes no copy).

• It reads your current robots.txt file and generate a revised version, named robots.new, that you can substitute for your current version after eyeball double-checking.

• It makes a master Bookshop_index.xml file.

• It makes an initial foreign-exchange-rates data file.

• And it tells you whether PHP's "Safe Mode" is On of Off on your server, and what "Server Interface" PHP is detecting (typically either CGI or Apache module).

Note well that the first time that finstall runs with no errors detected, it erases itself. That is to prevent it from being re-run, so that it cannot later erroneously add file copies to the base originals/ subdirectory or the backups/ subdirectory. Do not re-upload finstall.php unless you are sure you have a very clear need, and are sure you understand the structure of the originals/ and backups/ subdirectories.

firefox.jpg

This is a graphic used in the default rollyourown.php for the Firefox browser promo.

forex.php

This script duplicates one of the functions built into monitor.php (described farther below), that of obtaining the latest currency-exchange rates for the currencies of the six nations hosting Amazon divisions. (Like monitor, it stores the results where BookAdder expects to find them.)

free.php

This is the individual-edition "buy"-data display script. It needs two data to work: the Amazon "ASIN" code (for real books, that's the ISBN with no hyphens) and the identity code of the Amazon national division. That would look like:

free.php?in=ca&asin=0123456789

You rarely if ever need to know that: this script is what is linked by the listings in the 27 title-list pages, and anywhere else a particular book edition is linked. It comes without any Google AdSense code, as described at adsense1.php, farther above; but--as it notes there--you can manually re-code the script to include it. (I think it better not to: here is where a visitor is focussed on possibly buying a particular book, so AdSense might distract that visitor--you earn a few pennies on the AdSense click-through, and maybe lose a dollar or two on the book sale.)

freebie.php

This is a workhorse "include" file that has in it the data, functions, and various calculations used by virtually all the various runnable BookAdder PHP scripts. It is included into every PHP script in BookAdder, and is essential for all.

Among many other tasks, this module auto-detects where BookAdder is in your file structure, and supplies that information to all the BookAdder scripts.

freepasses.php

This little file is read by the timer.php script, described farther below; it is a place where you can list any IP addresses (in number form) to which you want to give a "free pass"--that is, allow to hit your server more often than the parameters in timer.php allow (you might, for example, allow outsiders one hit every 5 seconds maximum, but allow some other site of your own a hit every second).

Note that the site in which the package is installed always has an automatic free pass, so you don't have to put that in; this is only if you have other sites that might be checking your files on this one. You should have few concerns about search-engine robots, as most will honor a Crawl-delay directive in your robots.txt file, and any bot that ignores it deserves what it gets. (Google does not recognize the Crawl-delay directive, but--supposedly--never hits any one site more often than once in 5 seconds anyway [giggle, snort].)

There is more information on those matters at timer.php, farther on in this document.

ganalytics.php

This is a file into which--if you are using Google Analytics--you drop the Google-provided code; it is automatically included, at the correct page location, into every BookAdder page on which it needs to appear.

hold.htm

This is the HTML handled by the PHP script holder.php, cited just below.

This is the actual HTML page code that goes with the PHP handler script holder.php. It controls the layout of the 27 title-listing pages.

holder.php

This is the PHP "handler" script (see the note atop this docfile) for the HTML in the associated file hold.htm.

This script generates each of the 27 title-listing pages. It requires some parameters--

holder.php?in=ca<r=B

--would specify the letter-B titles found for Amazon Canada. You normally do not run this manually, but call it from links on other pages.

index.php

This is a tiny script that merely loads and runs the script realshop.php. It is provided so that anyone just using just your bookshop directory as a URL call will get your front page instead of either a listing of the contents of your bookshop directory or a "Listing Forbidden" message, depending on how your server is set.

LgNoImage.jpg

This is the image that free.php (described farther above) serves if Amazon does not have a "large" image of a book's cover; it is simply a white rectangle of a suitable size with the words "Sorry! There is no cover image available." in a pleasing type font.

looknfeel.php

This script is discussed at length in the docfile Further Customizing BookAdder; it allows you to set many "look-and-feel" elements of your bookshops' pages, from background, border, and text colors to type sizes, colors, and font faces.

makeindex.php

Your Bookshop_index.xml master sitemaps-index file is made once and, supposedly, for all at install time; but if you ever need or want to re-make it anew, this script will do that. (If a copy already exists, it will make the new index file as Bookshop_index.xml.NEW.)

makemaps.php

Updated sitemaps are normally made automatically during each daily (you do have it set to go daily, don't you?) search run. But if you ever want or need to make or re-make them manually, this script will do it for you. It is normally used by the regular nightly-run script monitor.php to generate the six sitemaps of your bookshop (one map for each Amazon-divisional shop). It automatically updates the master-index file Bookshop_index.xml (described farther above) when finished, and then automatically notifies selected search engines (see pings.php) of the update.

makepw.php

The functioning of this script is described in detail in the docfile Security-Related Concerns. It lets you password-protect all your BookAdder runnable PHP scripts (except those that visitors normally run). A BookAdder password is not iron-clad security, but will keep the casually nosy out of your private stuff. Because it is a nuisance to forever be typing the password in at every script run, don't make one till BookAdder is fully installed and working to your satisfaction. The password check hash is stored in the file 4me.php, described farther above.

makestatic.php

This script will list all files in your site, except those within the BookAdder directory and its child subdirectories and those excluded by your robots.txt file. Its operation is described in great detail in the docfile Tuning Your Search. It is intended as an aid to those first mapping their site for the search engines; it does not, because it cannot, do a full mapping--it cannot know, for example, what different sets of parameters a PHP script file may take, where each set might make that script file look like a different site page to visitors and searchbots; nor can it reliably know the "change frequency" for any given file (though it tries to make an intelligent guess, based on each file's last-modified date).

This script is not an inherent function of BookAdder, but is supplied as an "extra". Make such use of it as seems useful to you. Your bookshop pages are all indexed separately by BookAdder itself, with their own sitemap-index file (see Bookshop_index.xml, farther above); those maps are completely independent of any other sitemapping anywhere on your site.

MedNoImage.jpg

This is the image that free.php (described farther above) serves if Amazon does not have a "small" image of a book's cover; it is simply a white rectangle of a suitable size with the words "Sorry! There is no cover image available." in a pleasing type font.

monitor.php

This PHP script first fetches the latest currency-exchange rates for the six national Amazon divisions' native currencies, then calls findbooks.php (explained below), which does the real books-search work. It is the script that is started by cronf.php (cited above). It also calls the sitemap-maker script when the update work is done (unless it is run in Test Mode, by supplying &test=y. in the parameter string).

This PHP script--as its name suggests--monitors the status of the actual search workhorse script findbooks.php (described farther below); that is done so that if findbooks.php ever "dies" before completion (as can happen on resource-limited servers), the search process can pick up from where it left off, rather than begin afresh (which coul be a disastrous waste of time, and might never finish).

While this script is running in "daemon" mode--meaning not directly through your browser--it can be killed by uploading to the main BookAdder directory a file, whose contents are immaterial, named monitor.kill. The monitor script checks for that file every time it checks on findbooks, and if it finds that file, it first erases it, then kills any running findbooks, then exits.

nationals.php

This module sets a small host of parameters that vary depending on which Amazon national division is being addressed. It is used by freebie.php (described farther above) and some other BookAdder scripts.

nonbooks.php

This module holds a list used to determine, during a free-form search, what sorts of "Media", and what "magic" title words, will be used to exclude a book from the results if the user has selected the "Real Books Only" option. Putting these in a distinct include module makes it easy to update or modify them.

(Note that the list is almost certainly incomplete as to non-English-language terms; if you can augment it, please let me know, so I can pass it on in the next version upgrade.)

notify.php

This module duplicates a small portion of the functions of makemaps.php: it does not do any mapping, but simply notifies the selected search engines (see pings.php) of a maps update. It is useful if you have hand-modified some map file, or if the mapper somehow died after completing mapping but before completing notifications.

old_books.jpg

This is one of the images displayed on your shop's "front page".

phpinfo.php

Another little "extra": all this does when called is return a lengthy display of parameters relating to both the PHP setup on your server and also some general server information (as php sees it). That information can be very handy at times.

pigeon

This dummy little file is a "clay pigeon" that the tryme1st.php script (described farther below) deletes during its initial environment testing; if it is unable to delete pigeon, it knows something is wrong, and terminates with a warning message. Because it's erased during a successful install, you won't later find it in your BookAdder directory.

pings.php

This module works in partnership with the makemaps.php script described above. It contains the auto-notification URLs of all the "selected" search engines to be notified whenever a sitemap has been updated. It is internally annotated so you can freely and easily add or subtract engines (that's why it was put in a separate module).

pull.php

The findbooks.php script (described farther above) has a built-in failsafe for those days when Amazon is having a bellyache: it will not replace the previous day's search results if the current ones are not at least 80% as many titles, so as to avoid having a screwed-up search wipe out your shops' inventories. But once in a while--for example, if you decide to change your search phrase such that you are getting materially fewer titles--a legitimate search may trip the failsafe. This script forces a use of the extant search results, even if they are less than 80% of the last ones. You call it with just the usual divisions ID parameter:

pull.php?in=ca

It will report what exactly it is doing. Note that this does not run a new search: it just uses the data gathered during the most recent one.

(Note also that you really should always be using a search phrase that returns "saturation-level" counts of titles (at least 4,000--Amazon's current maximum); so if you change phrases, you should still follow the procedures and advice in the docfile Tuning Your Search to max out those title counts.)

putback.php

This is a tool you should rarely if ever need. When called, it checks all files currently in your BookAdder backups/ subdirectory; for each basic filespec (such as customize.php, it determines the most recent generational version. (For example, if customize.php.backup0, customize.php.backup1, and customize.php.backup2 existed, it would identify customize.php.backup2 as the most recent generational backup.) For each basic filespec that has a backup, it deletes the current version in your main BookAdder directory and substitutes the most recent generational backup present.

Note that it will restore backups of files that do not exist in the main directory; thus, whether an original is accidentally corrupted or accidentally erased altogether, this script will put back the most recent backup made. (Recall that monitor verifies and makes, as needed, backups at every job run, so your backups are always up to date with no action required from you.) If you are unclear on this, review the info block on Backed-Up Files to be found at the head of this docfile.

pwmake.php

This module works in partnership with the makepw.php script described above. When a new password is made, one submits it to the other for actual processing.

READ_ME.NOW

You presumably already did.

realshop.php

This is the PHP "handler" script (see the note atop this docfile) for the HTML in the associated file bookshop.htm. The various other "bookshop" PHP scripts (book-shop.php, index.php, and whatever you custom-named your "real" front-door page) are minimal dummies that each simply load and run this script.

recommendedbooks.php

As discussed at length in the docfile Further Customizing BookAdder, this module allows you to easily place on your six bookshops' front pages a few particular "specially recommended" books that you select and hand-enter into this module. The idea is to make your front pages look thoroughly personalized, not generic. There are explanations and instructions right inside the file itself, besides those in the docfile just cited.

reperm.php

Whenever you upload a file to your BookAdder directory, you need to be sure it is permissioned correctly. You can re-run finstall.php to do that, but this little tool does the same thing, only without the rest of the finstall screen clutter. In fact, it is simply finstall.php with the other parts stripped out (also, it does not deliver screen listings for files it did not need to adjust). You can safely run it again and again at any time--but always run it right after uploading any files, whether or not you have changed those files.

robots.new

This file is generated by running the finstall.php script; it is a suggested replacement for your current main-site robots.txt file, and should include everything already in that file plus the exclusions and inclusions wanted for the BookAdder package. Before substituting it in for your existing file (if you have one), be sure to "eyeball" validate it! And make sure you understand the robots protocol and syntax before doing so!

rollyourown.php

This module is not only a demonstration of how easy it is to add in material of any sort to the package pages, it is also functional: it contains a Google AdSense referral to the Firefox browser (if you are a Google AdSense publisher, you can--and should--plug in a referral script coded with your Firefox-referral data). If you are not a publisher, you can just leave it as is, or you can plug in whatever pleases you. This module's contents are always just plain, straight HTML, and the HTML-comment-caller in the appropriate .htm file calls it and displays the HTML. The module is described more fully in the docfile Further Customizing BookAdder, and is internally documented as well.

runcoopads.php

This module is for the convenience of those who are members of the Digitalpoint Co-operative Ad Network. Depending on how coopads.php (described farther above) is set, this module will or will not display Co-op Network reciprocal ads on BookAdder bookshop pages; if that file is set to display, this file will cause displays--as required by the network--on all visitor-viewable pages.

The module as supplied will insert 5 text-only ads in a small table with a pale yellow background and disclaimer comments. (It also modifies the supplied ads so that they are valid XHTML code, which--at least at one time--they were not always.) You can rather easily modify the module because the salient parts are basic HTML, just with each line included in some PHP boilerplate; that is--:

echo '     <font size="1">Here are links to some other sites you might find interesting or useful:'.$crlf;

is simply equivalent to plain HTML that reads--

<font size="1">Here are links to some other sites you might find interesting or useful:

--so you can change the display around to suit your tastes and needs.

search.php

This is the script that does the search work called out in book-search.php (and its associated HTML file booksearch.htm), described farther above. It takes a zillion specialized parameters, and should not be played with.

setup.php

This is the script with which you enter your basic customization data, as described at great length in the docfile Installing BookAdder.

sha256.php

This script allows use of BookAdder on servers lacking more recent versions of PHP that include certain encrypting functions. The script was created by Perry McGee and is Copyright (C) 2006,2007,2008,2009 Nanolink Solutions; it is included with this package under the terms of GNU Lesser General Public License, which permits such distribution. Full terms and statements appear in that file. More information about the script can be found at its host website.

showstyle.php

This script makes it easy for you to see the effects of most of the parameters set in looknfeel.php (described farther above), to experiment with trial new values for them without actually effecting the corresponding changes, and then to effectuate any new values if and when you like. The whole business is described more fully in the docfile Further Customizing BookAdder.

status.php

This script examines several BookAdder work-product files and returns a comprehensive report on your bookshops' exact current status, even to whether or not they are running a search at the moment. It needs no parameters when called. This is a very useful way to get a snapshot overview of your entire bookshops setup.

Note that status can be used mid-search: that is, it will show dynamic partial results if a search is currently in progress/

sunny_bookcase_small.jpg

This is another of the images displayed on your bookshop's "front page".

timer.php

This is the spammer-throttle referred to several times above. There is extensive descriptive text in it, plus a write-up in the docfile Further Customizing BookAdder, but the essence of it is this: you select a maximum average "hit rate" at which you will allow any one visitor to take files, and a time period over which the averaging should take place. Any visitor--human or robot--that takes files at or more slowly than the rate you have specified will be totally unaffected; visitors that take files faster than that will accumulate "penalty points", so to speak; when those points get too high, they will be blocked for some period (which you select), and will, during that period, receive a 503 "Service Temporarily Unavailable" message and HTTP Code. (Further attempts during the blocked period will extend their penalty time yet more.)

For background, Google says somewhere or other that it will never hit files from some one site more often than every six seconds, while most other search engines honor the robots.txt directive--

Crawl-delay: 5

--where 5 (or whatever you specify in your robots.txt file) is the minimum number of seconds allowed between hits. Hit rates much above once every 5 seconds can, as the cliché goes, bring a server to its knees, effectively amounting to a "denial of service" attack. They are also characteristic of spammy "harvesters", whose runs can wildly jack up your site's bandwidth use, which can cost you severe bucks (I speak from experience, not theory).

The module comes set with a minimum allowed average hit pace of once every 5 seconds, as averaged over a moving 60-second window; the penalty time is 10 minutes (which, believe me, is not severe enough--I still get spammers with dozens of log entries, meaning they took the penalty and came back dozens of times).

Speaking of logs: the module logs all denials, with the IP Address, the "user agent" as given (very unreliable, as most spammers spoof someone or something else), and the exact date and time of the denial. The default log name is ErrantIPs.Log, and it can grow to an astonishing size with astonishing quickness, since spammers are now endemic; thus, the default is that logging is off. You can turn it on in the timer.php module; if you do, BookAdder will auto-email you whenever the logfile size is over a megabyte (and will re-email you at every run--presumably daily--till the file is pruned, renamed, or erased). The log is, frankly, not of much practical use, but can be entertaining.

Let me clarify a few points. First, the rate is calculated on a moving-windoww basis, so a visitor who takes a few files in rapid succession does not automatically incur a penalty--visitors need to have taken more than X files in the most recent window period. Second, throttling is not instantaneous: a visitor who is exceeding your specified rate by only a little (say a file every four seconds instead of every five) will have to go on like that for a good while before being throttled, whereas one who is grossly exceeding the "speed limit" (say a file every second, or even faster) will get throttled very quickly, in barely over the window-size period (say, a minute). That is both logical and fair.

This module, whose basic idea and implementation is not mine, seems to me like the greatest thing since the peelable banana. No more trying to block based on user agent, which is usually spoofed by spammers, or by particular IP Address, which spammers change more often than their underwear: now you control access based on rapid real-time evaluation of bad behavior, period the end.

(Note that if the /trapfiles subdirectory simply does not exist, timer.php will quietly (meaning no warning messages) do nothing, and your visitors will not be throttled. If for some strange reason you do not want throttling in effect at all, simply erase that subdirectory (after emptying it, of course. The reason for this bypass is to prevent obscure warning messages during set-up, before the new subdirectories have been made.)

tryme1st.php

This is a one-time-use auxiliary script intended to verify that BookAdder should not encounter any insurmountable problems being installed and running on your host. Its use is described at great length in the docfiles Installing BookAdder and Installation Problems, but to summarize what it does, it:

• checks that you do not seem to have the fatal combination of PHP's "Safe Mode" being On and no CGI interface (that combination, found only on a few quite ill-managed hosts, makes almost all PHP operation impossible);

• determines from PHP, and displays for your verification, a few key data, mainly concerning where on your server BookAdder resides;

• tests whether it can delete an uploaded file;

• tests whether it can use HTTP to open a remote file;

• attempts to write, read back, then erase a small test file, just to be sure that it has the necessary file-access rights on your server;

• and, if for some reason the write-read-erase test fails, the script attempts to repermission the main BookAdder directory, then repeat the test. It reports its results.

unavails.php

Analogous to nonbooks.php (described farther above), this module is a list used to determine, during both regular and free-form searches, what sorts of "Availability" descriptive terms will be excluded from the results as "unavailable" (in free-form searches, the user can elect to bypass this filter and see all listed items, available or not). Putting these in a distinct include module makes it easy to update or modify them.

(Note that the list is possibly incomplete, especially as to non-English-language terms; if you can augment it, please let me know, so I can pass it on in the next version upgrade.)

used-books.php

This is the PHP "handler" script (see note atop this docfile) for the associated HTML file used-books.htm, which is the general used-book-search page. Note that because Abebooks can deal with a huge number of destination countries (and, correspondingly, national currencies), the "in=" parameter, designating an Amazon divisional host country, is valid and distinguishes content.

usedbooks.htm

This is the HTML "handled by" (see the note atop this docfile) by the PHP script used-books.php (described above). It includes a complex form for specifying search parameters that will be passed to abes.php (described farther above), the script that does the actual searching and reporting.

watch.php

Another little extra, useful beyond the purposes of this package, watch.php calls an operating-system utility that reports data on running processes and displays it for you every so many seconds. Since this script uses a *nix system call, it will not work on Windows-based servers. The data it reports are described as:

• USER: The owner of the process, typically the user who started it
• PID: The process' unique ID number. These are assigned sequentially as processes start; when they reach 30,000 or so, the numbers start over again from zero, though processes 0-5 are usually low-level operating system processes which never exit.
• %CPU: Percentage of the CPU's time spent running this process.
• %MEM: Percentage of total memory in use by this process
• VSZ: Total virtual memory size, in 1K blocks.
• RSS: Real Set Size, the actual amount of physical memory allocated to this process.
• TTY: Terminal associated with this process. A ? indicates the process is not connected to a terminal.
• STAT: Process state codes. Common states are S = Sleeping, R = Runnable (on run queue), N = Low priority task, Z = Zombie process
• START: When the process was started, in hours and minutes, or a day if the process has been running for a while.
• TIME: CPU time used by process since it started.
• COMMAND: The command name. This can be modified by processes as they run, so don't rely on it abolutely.

The script's default report period is every 5 seconds, but you can call it with a parameter to set the value to whatever you want. For example--

watch.php?every=10

--would call a new display every 10 seconds. It will continue to run till you stop it.

Note that by default, the script reports on all processes (which can make a lengthy and complicated display). There is, however, a second parameter you can use, pid=xxxx; that will cause it to report only on some one process, that identified by the xxxx parameter you supply. That can be useful in BookAdder because most BookAdder scripts (at leat if run in Test Mode) report their own PID, so you can use watch to monitor such a process--for instance, to see how much CPU time or memory it is using. You would use (assuming, for demonstration purposes, process 87021)--

watch.php?pid=87021

--or, to combine the two--

watch.php?every=10&pid=87021

Moving On

BookAdder Documentation Files Available

They are:

• About BookAdder - a useful overview of what BookAdder does, how, and why
• Installing BookAdder - getting BookAdder initially set up and functioning
• Installation Problems - causes and cures for snags encountered when installing
• Tuning Your Search - how to easily optimize your search phrase
• Further Customizing BookAdder - ad displays, look-and-feel, and other aspects of customizing
• Security-Related Concerns - understanding the hows and whys of several related matters
• Upgrading - how to proceed if you have an earlier version installed
• BookAdder Files List - this file

What to Read Next

There is nothing in particular, since this docfile is a side creek not in the stream of installation progress. By now, you have probably read all the others anyway.