BookAdder: Installation

But First!

Please be sure you have read the preceding BookAdder docfile About BookAdder for an overview before you plunge into these procedures. It only takes a moment or two, and leaves you better equipped to understand what you're doing and why. Please: RTFM!

The Full Very Easy Instructions

-- These are for new installations. If you are upgrading, read the docfile Upgrading BookAdder --

Step 1: Make The BookAdder Home Directory

You will, of course, already have unzipped the ZIPfile in which BookAdder comes (or you wouldn't be reading this). Ideally, you will have made a separate subdirectory on your local computer for these files, so they don't get mixed up with anything else. If that should not be the case, I strongly recommend you stop here and now and make such a separate subdirectory, then move all the BookAdder files into it--then come back to here.

(You can, of course, name that directory anything at all, but you are best to give it the same name your actual directory on the server will have; that, in turn, should be something of SEO value, using site keywords. For example, if your site is about red cats, call the directory something like red-cats-books.)

Next, you need to make a directory on the computer hosting your site. I recommend you place it just off your site's root (main) directory. If those terms confuse you, your "root" directory is the directory containing the page your visitors would come to by just entering your site's basic URL into their browsers; say I entered http://seo-toys.com in my browser--the directory containing the page you see there is in my site's "root" directory. BookAdder should work properly no matter where placed on your site, but you do need to give it a subdirectory of its own, and there's no special reason to go any farther down from your root than just under it.

If, however, you have multiple "sub-domains", then the logical place to put each one's BookAdder subdirectory is just below that sub-domain's chief directory (which may be a couple of levels below the true domain root); no problems, BookAdder just works wherever it is.

(I cannot tell you how to use your ftp software to work with files on your host--there is altogether too much variation in products. I can only tell you what you need to do. If you have trouble with this, perhaps--because, after all, using ftp software is a rather basic webmaster skill--you should obtain help from a professional in maintaining your site.

Select a name for your BookAdder directory. As just suggested, use good SEO principles, and select a name that tells the search robots something about the directory contents: something like red-cats-books is better than something like books. (Never run directory or file name words together--as in redcatsbooks--and always use hyphens, not underscores, to separate words--otherwise searchbots may not be able to properly read your keywords.)

Create the directory. Then, if you are hosted on a Unix-based host system, set that new directory's "permissions" to either 777 or rwxrwxrwx (those are simply two different ways of specifying the same thing--some displays show permissions one way, some the other). If those terms seem "magical" to you, read the BookAdder docfile on Security-Related Concerns, which explains the basics of "permissions". The chances are that simply creating the new subdirectory will leave it permissioned at 755 (which is rwxr-xr-x); if so (and that varies from host to host, but 755 is common), you will need to explicitly change the permissions to 777. If you don't do this, there's a good chance that BookAdder will be unable to install.

If you have the misfortune to be hosted on a server running on one or another Windows operating system, "permissions" in the Unix sense don't exist. As one ISP tech wrote in an online article on the subject, "Microsoft's permissions scheme is a train wreck." In the best of worlds, simply creating the wanted directory with your FTP software will have resulted in a folder that is properly "permissioned" (as Windows understands that concept), that is, one in which anyone, including "guests", can read and write files. I suggest that at first try, you just create the folder, then proceed. If you have problems, the later instructions will direct you to a docfile that tries to help.

Step 2: Enter Your Keys, Then Populate The BookAdder Home Directory

Step 2a: Enter Your Amazon Keys:

Using any simple text editor, open the package file named access.php. In the preceding DOC file, you were told how to get your Amazon key pair--what Amazon calls the Access Key ID and the Secret Access Key. In access.php, replace the strings of zeroes with your corresponding actual Amazon keys: obviously, $accesskey is your "Access Key ID", and $secretkey is your "Secret Access Key". Be very, very sure to change nothing at all in the access.php file except for the actual keys as placed between the single-quote marks. You should end up with something that looks sort of like this:

Step 2b: Upload the Files:

Now that you have a home on your host for the BookAdder files, simply upload them to it--all of them. (Do be sure to keep the originals on your local system as an emergency backup if anything ever corrupts the "live" ones on your host; that's wildly unlikely, but paranoics live longer.)

Once you have the package files uploaded, switch to reading this DOCfile from the copy on your server (as opposed to the local copy I presume you are reading from now). Then continue reading from this point.

Step 3: Verify Usability

Presumably you know this, but to be sure I'll say it here once for all:

You "run" a PHP script by simply loading it into your browser like any web page.

PHP is a "scripting language". When your host receives a request for an ordinary web page, as indicated by an extension of .html or .htm or .shtml (or whatever else it's been set up to recognize as specifying HTML pages), it just fetches the file and delivers it over the internet to your browser. But when you request a page with a .php extension (or, again, whatever the server has been told specifies a PHP script), it fetches the file but first runs it through the PHP processor, which can do many things, including generate output lines; the server then takes the output from the PHP processor and sends that back to your browser. Typically, a .php page will contain a mix of PHP script instructions and normal HTML (internally marked so the PHP processor knows which lines are what), though a "PHP script" could be 100% plain, ordinary HTML--or have zero plain HTML. In that way, a PHP script can make a "dynamic" web page by constructing the page "on the fly" based on many changing things: what parameters your browser supplied in its call, the contents of certain local files (like, say, an inventory list), or even the time of day. That's how, for example, one BookAdder script can be the "front door" for six different national bookshops: it "knows" which shop it's supposed to be from a parameter supplied in the call, and serves the corresponding version of itself.

Your first step, once the BookAdder files have all been uploaded, is to run the script appropriately named tryme1st.php  The URL will depend on what you named your new directory and where you placed it, but if we assume that your website is www.friends-of-red-cats.com and that you named the new directory red-cats-books and that you place it right off your root directory, you'd run the script by entering this into your browser's URL bar:

http://www.friends-of-red-cats.com/red-cats-books/tryme1st.php

Or, if you followed directions and are reading this docfile from your server, you can actually start that script now, in a new browser tab or window (depending on your browser's settings) by just clicking this link: TryMe1st.

In the best (and most common) of cases, its output will look something like this, depending in part on your browser's window size and font settings (and with, of course, your site's data showing instead). If it reads a little different, don't worry, so long as there are no error messages:

In some cases, that display may also contain (just below the top headline) a message box that looks something like this:

That's pretty much self-explanatory, but there's a little more about it in the BookAdder docfile on Security-Related Concerns. The caution is just that: a caution--it does not mean that BookAdder will not work for you. But you should speak to your host about the matter.

(As noted elsewhere, if you are on an Apache-powered server, the BookAdder package includes a local .htaccess file (one that is placed in BookAdder's home directory and affects no other parts of your site) that tries to turn off "register globals" if it is on by default. So if you see that warning message, it signifies that that local .htaccess file was unable to override the register_globals setting--possibly because it's not allowed by settings in higher directories, possibly because you're on a Windows server.)

If you got the OK screen, with or without the caution just described, and you have verified that all the data shown are correct (but see the note immediately below about your email address), you may now proceed with installation. But, if either you got that screen but one or more of the data were wrong (except, maybe, the email), or if you got an error message (with or without the warning just described), then you need to move to the docfile explaining those errors and what--if anything--you can do to cure the associated problem: click here for the BookAdder docfile Installation Problems.

About the "Your email" datum: if it is not correct--which could easily happen if you do not own the domain on which you are hosted--you will need to make an explicit email-address entry when you move on to the initial customizing (you can't change it till then). If the domain for the site is friend-of-red-cats.com, the default email address will be webmaster@friends-of-red-cats.com, which is fine (presumably you have your email filters set so that that address and postmaster@friends-of-red-cats.com will always reach you). But if, instead, you don't own a true domain and are hosted on a shared system, with a URL something along the lines of red-cat-friends.bighostingcompany.com, the default email address for you would be (in that example) webmaster@bighostingcompany.com, which is not what you want. So be alert. (As I said, if you need to change the listed default, you'll have your chance in a few minutes.)

You can verify the path on your server by what your FTP program shows, but be aware that Unix-based servers--and the majority are--have something called "symbolic links" that allows files and directories to have an "alias"; thus, the path you see in your ftp software may seem to differ from the one being reported on-screen and yet be the same. If they do not look identical, simply use your FTP software to try to reach the directory just as shown on screen. Typical differences might look like this:

 · FTP software says: /usr/home/catfiend/public_html/catsite/red-cats-books/

 · screen reports: /usr/www/users/catfiend/catsite/red-cats-books/

In that example, the screen is reporting the "correct" (real) directory path, while the FTP software is set to a "linked" path that ends up pointing into the identical directory. To verify, you would tell your FTP software to access what the screen reports and check that it is indeed the same place.

Step 4: Run The Installer

Since you're still reading, presumably you got no fatal-error messages and verified that the reported data are all correct. Excellent--now onwards: click the button (on the tryme1st screen page, not here) labelled Start the install now.

(Note that tryme1st, as part of its testing, erases a little dummy file included solely to be erased, named pigeon, as in "clay pigeon"; thus, if you ever want, for some reason, to re-run tryme1st, you will need to re-upload a copy of that file.)

The PHP script named finstall.php will now ("now" meaning after you clicked the Install-start button on the previous page) come up and run automatically. Its output messages are color-coded: green for ok, grey for non-action notices, yellow for "note this", and red for problem warnings. Ideally, the display will look like this (with, of course, your directory names instead):

Don't worry too much about what all that means: the crux is that there be no messages in red. If there are any such messages--which ought never to happen if tryme1st.php threw no errors--consult the docfile Installation Problems. Otherwise, you can click the button at the bottom of the finstall page and move on.

(For the fervently curious, the display lines record the installer's activities: first, it deletes the server copy of a couple of more or less dangerous scripts meant only for very special, occasional uses; then it creates all the subdirectories it needs and permissions them as required; then it sees if it needs to make a custom "front page" for your shop; then it re-permissions and also makes a reference "originals" copy of each file it finds in its main directory; then it examines your current robots.txt file--if any--and places a suggested replacement named robots.new--which we will discuss later--in the main BookAdder directory, and concludes by making a new Index file for your future sitemap files.

Note that finstall, as it informs you at the end, will--if it did not detect any errors in its run--erase itself. It is a file meant to be run only once. Re-running it does not create any immediate or obvious problems, but can interfere with the backing-up scheme (which is only a frill, not an essential part of the package). But you should never need to run it again once it has done its job, so don't re-upload it. (You use the ancillary tool script reperm.php if you later need to upload other or editied files to the main BookAdder directory.)

Step 5: Do The Initial Customization

While you can do this by just using a plain text editor (not a word processor or HTML editor) to edit the BookAdder file cleverly named customize.php, the easier way is to use the interactive package script setup.php. To ease your way, the finstall.php script will--if there were no fatal errors--give you a simple click-on pushbutton to take you on to that page, as you saw above. The interactive page, like the raw file itself, is so heavily annotated that it is really self-explanatory, but let's go over it together anyway--remember again, measure twice, cut once.

The top of the interactive screen conveys general information about customizing the package; below that is a section headed The Data, which contains step-by-step directions on revising the default values (mostly dummies for demonstration purposes) initially present in the file. Following an introductory paragraph are the seven individual data-entry steps. Let's take them one by one. The first looks like this:

You just change that sample entry to whatever you want, heeding the caution about marking any apostrophes and the advice about where and how to force long names to line-split when in larger type sizes. Just to clarify that point, let's assume the name of your site is rather long, as in the example: This Great Big Wonderful Super Web Site of Mine and you use a Break as suggested. Then, if running text on a BookAdder page contains the name of your web site, it will appear simply as itself, say as in--

We here at This Great Big Wonderful Super Web Site of Mine really care about our visitors.

--but if the name appears in a section heading of some sort, it will be broken, like this:

This Great Big Wonderful
Super Web Site of Mine

See?

This datum should need no further explanation.

The next data area down is just a hair more complicated, in that it has two sub-parts; it starts like this:

Exactly because you are not yet ready to tune your search, I urgently suggest that for the moment you leave these two data just as they are set: they will make a nice, simple test case to see if everything is working, after which you can return to setting your own actual phrases.

But, since here we are in order, let's take a look at them, so you'll know what you're doing when you come back to them later. The first sub-datum entry, #2a, will look like this:

That's probably as self-explanatory as we need to get till you've read up in the docfiles about choosing an exact search phrase. (And, again, remember that there is a separate interactive helper script, bookcount.php, that will help you evaluate and fine-tune your search term.)

There is also a datum #2b, which is really just a "dressed for company" version of #2a; it looks like this:

By "dressed for company", I mean that it is suitable for display to your visitors as showing what sorts of books your bookshop has sought out for them. In simple cases, you could just use the bare search term as you enter it at #2a (though, again, mind capitalizations, as you would want it to look right). But often the exact search term will look ugly or bizarre or incomprehensible to the average visitor, so BookAdder allows you to separately specify the phrase visitors will see as what you search for on their behalf. The example above should make that point clear enough.

The next data area, #3, is a short and simple one:

You don't have to change this datum, now or ever. But it is wise to follow basic SEO principles and give your "front door" a meaningful name to help the searchbots in determining what your pages are focussed on. In the silly little example we have been using, you might call that page red-cats-books.php. Don't "keyword stuff" the title, but do make it legitimately meaningful: use the same principles you would in naming it for human reading. Don't be afraid to give it the same name as the directory itself--in fact, that's probably a good choice.

The installer will use whatever name it finds here--book-shop.php or what you set instead--as the name of a simple little file it makes at install time, and which file just points on to the real bookshop page, which is always realshop.php.

The next data area down, #4, is even shorter and simpler:

This is worth a comment. If you already have a favicon image file, just put it in here. But if you don't (and leave the entry blank), you are missing a small but neat way to make your site a little more professional and memorable--though BookAdder will use (just on its pages that visitors see) its default favicon, a small stack of books. You will see that icon in your browser's URL bar when the actual setup.php script is running (but not on this docfile page). If you don't already have a site-wide favicon, you can just leave the entry field blank and BookAdder will use that default. But if you don't have a site-wide icon, I suggest that it's a good idea to make a distinctive, memorable one.

(If you don't already know, a favicon is that little icon image that you see for many sites up in your browser's URL bar, just before the actual site URL. Your having a simple, distinctive favicon image helps your visitors remember and feel comfortable with your site--it's a small thing, but successes are built of many small things done right. Use your favorite search engine to seek out information on how to make and use a favicon file (you use it by calling it in the <head> area of your HTML pages. My only advice is the classic KISS (keep it simple, stupid). The images are very small, so keep yours clean and simple and easily grasped.)

The next data area, #5, may look daunting owing to its length, but is actually very simple:

As the package runs, getting its data from Amazon, it keeps a fairly detailed step-by-step log. The times in that log are set by what you enter here: if you leave it as it is, entering nothing, times (and dates) will be reported in Greenwich Mean Time (also called Coordinated Standard Time or Universal Coordinated Time). The reason this datum exists is that often the server hosting your site is not in the same time zone as you are, and it is annoying and confusing to have to continually do mental conversions from server time to your own time; enter your "home" time zone here, and the logs will report events in it. If, for example, you are in California, click the PST button.

The next two data areas are for your Amazon and Abebooks associate ID codes. In the Amazon case (Step #6), shown below, you can enter a code for any or all of the six national Amazon divisions; remember again that each division issues its own distinct code--you cannot use one division's code at another. (Well, you probably can, but you wouldn't get paid for any sales!) Here is that entry area:

Be sure to be clear on what you need to enter. You do not enter your "Access Key ID" or "Subscription ID"; you enter your associate ID, which typically looks something vaguely like redcats-20. The IDs, on the other hand, are long strings of nonsense letters and numbers jumbled together. You don't have to have any Amazon associations at all to actually start and run BookAdder, and you can insert individual divisional associate IDs as you get them: each will take effect immediately on your uploading of the revised customize.php file.

The next data area, Step #7, is the Abebooks one. Though there are several Abebooks national divisions, BookAdder deals only with the main one. That is because unlike Amazon's pattern, all Abebooks "divisions" access the exact same database; why the separate divisions even exist is unclear (perhaps it is just to make things simpler for Abebooks affiliates who don't know or want to learn how to elicit nationalized data from the database--you and your visitors can customize Abebooks results to select booksellers anywhere in the world, for delivery anywhere in the world, with prices in virtually any existing currency.

(Abebooks sales commissions are handled by Performics--nowadays also known as the Google Affiliate Network. You need to register through them to get an Abebooks affiliate identity and code.)

The entry area looks like this:

If you are unsure what your "Abebooks Publisher ID Code" is, do this: log into the Performics web site with your Performics userid and password; at the first page you come to after login, run your cursor over the word Links in the blue heading line, which will drop down a sub-menu--then click on By Advertiser in that sub-menu. When that page loads, locate the Abebooks horizontal area; in the drop-down menus at the far right of it, for Select an action... choose View/Get Links then click the Go button. When that page loads, you should see a bunch of sample ads and corresponding URLs down the left side of the page. Look at the HTML for either Tracking URL or Creative URL for any ad and find the part that reads pid=00000000000000000, where--of course--the zeros shown here are actually some number there (I think it's 17 digits long, but that may vary). That number is your Performics Abebooks Publisher ID Code, and is what you need to enter (just the number, not the "pub=" part) for this BookAdder datum.

The last data area, Step #8, is an email address for you as webmaster of the site. As the notes below say, BookAdder sends you a heads-up email whenever any of your log files get as big as a megabyte; to do that, it obviously needs an email address. The default, which should always work, is simply webmaster@friends-of-red-cats.com (or whatever your site's actual domain is).

Note! However you have your email for a given site set up, there are two addresses that should always get through to you: webmaster@yoursite.com and postmaster@yoursite.com. Note that BookAdder does not place this, or any, email address on any of its pages--it is purely for its own use in communicating with you.

The entry area looks like this:

Note that once a logfile hits a megabyte, you will get an email every time BookAdder runs--which should be daily--till you do something about it; the main Shop.Log file will take a year or more to hit such a size, but if you change the default for logging over-fast hits (set in timer.php--see "Spammer-Attack Timeouts" in Further Customizing BookAdder for details), that logfile can blow up to monster size awfully fast.

At this point, you must heed the message that appears next on the page:

If you do not, all your entries will be lost when you leave the page.

When you click the button, not much will seem to happen--you will see this same page again. But this time, the values you read are from the customize.php data file, to show you that they have been correctly entered. You can review them--and, if anything seems wrong, re-enter that datum (or those data) and again click the Apply button.

(There is also, as a last-ditch back-out if you have gotten thoroughly lost and confused in this process--which I cannot imagine, it being so simple--a "reset" button, labelled Click here to apply the original default values, which will do just what it says, so you can start over.

You are now done with the initial customization for BookAdder. After some brief testing, you will--as copiously explained above--want to spend some time devising an Amazon search phrase that works right for your needs, as the other docfiles will explain, then come back here and revise Data #2a and #2b accordingly, after which you'll be fully ready to rock and roll.

So now you're ready for a trial run. To embark on it, you need only click on another pushbutton on that page, as shown below:

Step 6: Do A Test Run

Step 6a: Do the Actual Run:

This is why we left the Amazon-search-phrase data alone: so we could quickly get a short, simple, more or less predictable result from this first search. If there are no snags, you should now see a new screen that develops more or less like this:

I say "develop" because that won't all show up at once: it will take something between one to two minutes to appear in its entirety.

The reason this page looks fairly stark is that this is not a process you normally need to be looking at--in fact, if you're not in Test Mode, you won't even see this much. Let's see, though, what these lines are telling us.

The first line tells us the Process ID of the run (something your server uses to keep track of running software); one could use that with external monitoring software on the server to get some information on the process (memory usage, CPU usage, and so on), though this process will finish so quickly that you'd have to be mighty fast on the draw to get a listing screen before the process ends. But it can be a handy datum if debugging is needed.

Next, we are alerted that the script is running in Test Mode (a BookAdder term meaning, in essence, verbose output, though it affects other things, too, such as whether the process can run as a daemon (which it cannot in Test Mode). This, too, is really just for debugging purposes, as is, really, everything on this screen.

monitor is the name of the PHP script that is running; it is called that because it starts, monitors, and to some extent controls other "child" processes.

Every time monitor starts, it checks all the files in your main BookAdder directory against the reference "originals" it stored when first installing (see the grey info block "About Backup Files" near the top of the docfile BookAdder Files); if any now in your main directory differ from the reference versions (or don't have a corresponding reference version, meaning they are new or added), monitor makes a backup copy of the changed/new file, as a general safety precaution for you. Note that BookAdder keeps generational backups: if a backup exists and the file changes again, both old and new backups will be kept (sequentially numbered), without limit. In this example, monitor backed up your customize.php file and your newly made custom-bookshop red-cats-books.php file.

The foreign-exchange currency rates are the most recent available (they are normally published once a day on business days), and are used in BookAdder to give prices in all Amazon-division currencies (which is handy for visitors, but which also has the merit of likely being different every day, so your numerous BookAdder pages are always changing by the day even when nothing is really new).

Finally, the actual Amazon search is begun; that is accomplished by the separate BookAdder script findbooks.php, which monitor.php starts as a child process and then monitors--hence its name--checking on FindBooks once a minute. (That is a technique useful on those servers--not uncommon--that don't give any individual process much memory, so that a process can suddenly die mid-operation if the server kills it for excess memory use; if that happens to FindBooks, Monitor will detect it and will re-start FindBooks from where it was in its run--monitor itself uses little memory and should be robust, though host servers are infamously quirky things.)

Because the search on "Spokane" is so brief, FindBooks completes it in under a minute, so the first time Monitor checks, FindBooks has "announced" to it that it is done. Normal searches, if you choose your search term wisely, will take 45 minutes to an hour to fully complete.

Finally, having completed the search and updated all your BookAdder files accordingly, Monitor starts makemaps.php, another "child" script that generates search-engine-friendly sitemaps of your entire BookAdder bookshop (as the public, or searchbots, would see it). MakeMaps, if it runs without difficulty, will typically finish in under a minute, even for a full long search run. When MakeMaps finishes making its maps, it then notifies the Big Three search engines that new maps are available (but in Test Mode, which this runs is, notification is bypassed, so you aren't notifying the engines of dummy results).

Monitor then reads you out a summary of its run and announces its final completion (and exits).

Step 6b: Check The Results:

As noted, you are not going to sit at a screen watching data fetches for an hour every day. Normally, the nightly run will take place automatically and out of your sight (we'll discuss later how to set up such automated runs). But you can always see what's happening or has happened by using the script called, appropriately, status.php. That script is your Swiss Army Knife of BookAdder status information, as you will see below. When run, it reports--among many other things--whether or not any of the three regular-run scripts (monitor.php, findbooks.php, makemaps.php) is running at that moment, and, if so, some data for each. It also, though, gives you the last "block" of entries (successive lines set off by a blank line before) from the package logging file, named simply Shop.Log and found in the logs subdirectory the installer put in the BookAdder directory you made at the outset.

status.php reports dynamically--that is, run while a search is in progress, it will "snapshot" the partial results. Because the initial test sample run (on spokane) is so brief, we didn't try to catch the run in progress: it would have been a fast-fingers race. But we can see what we got (shrunken here to better fit the page):

   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:26:25 am, PST: no copy of myself running--starting anew.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:26:29 am, PST: Latest FRB currency values obtained and stored.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:26:29 am, PST: found FindBooks (68224) defunct--will start new FindBooks.
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:31 am, PST: starting anew--initializing.
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:32 am, PST: starting in us at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:35 am, PST: completed us: 38 raw titles, 26 passed, 26 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:35 am, PST: starting in uk at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:38 am, PST: completed uk: 12 raw titles, 12 passed, 12 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:38 am, PST: starting in ca at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:47 am, PST: completed ca: 32 raw titles, 30 passed, 30 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:47 am, PST: starting in de at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:51 am, PST: completed de: 24 raw titles, 23 passed, 23 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:51 am, PST: starting in fr at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:53 am, PST: completed fr: 11 raw titles, 6 passed, 6 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:53 am, PST: starting in jp at #1:
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:57 am, PST: completed jp: 23 raw titles, 23 passed, 23 unique editions
      findbooks (PID 69246) Mon, 22 Dec 2008 @ 09:26:57 am, PST: completed all search work.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:27:36 am, PST: found FindBooks (69246) completed OK--will now do maps.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:27:36 am, PST: finished search, keyword phrase "spokane", having taken 1 minutes, 11 seconds.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:27:36 am, PST: starting sitemapping.
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: starting:
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping us
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping uk
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping ca
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping de
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping fr
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: completed mapping jp
      mapper (PID 64810) Mon, 22 Dec 2008 @ 09:27:37 am, PST: No changes since last mapping, so no search engines notified.
   monitor (PID 68712) Mon, 22 Dec 2008 @ 09:27:42 am, PST: finished job, keyword phrase "spokane", having taken 1 minutes, 17 seconds.

That should all be pretty clear, but let's look in detail anyway. In the upper block, Current By-Division Data, we see the end results of the run. "Raw" titles means the actual total number of titles Amazon gave back for our search; this should be very similar to (but may not always exactly match) what the bookcount.php script told us to expect (as discussed in the next docfile, Tuning Your Search.) The rest of the columns are explained at the bottom of this first block, but most are diagnostic; the only one that really matters is the last, Site pages, because that's what we're interested in, total pages added to our site. As you see, even this silly little test example would add many hundreds.

The second block of information shows what its title says: the Current Status Data. Our quick initial run is now over, and as thus expected all three run processes are reported as NOT running now. (Later, in another docfile, we'll see what a check looks like mid-run.) But the logfile entry block, though the actual numbers reflect the small results for this sample run, are what any full run should show. monitor begins and at once checks to be sure there is not already a copy of itself running (so you can't accidentally start two or more runs going simultaneously); it also checks to see if a prior copy of itself somehow died before completing. If not (as here, and almost always), it starts "anew". It then, as you now know, gets the latest foreign-exchange currency-exchange rates, and checks to see if a copy of findbooks.php is currently running; if not (as here and normally, unless findbooks had died before completing), it will start new FindBooks, as it says. The next log entries are from the newly started findbooks (check both the line starts and the indents). findbooks reports that it was not in the middle of anything when last stopped, and so will start "anew", and initializes its data files. It then begins, and tells us where it's beginning from: in us at #1. As it finishes searching each Amazon national division for titles, it reports the completion, and tells us the "raw" count of titles it got from Amazon, the number of those that "passed" (were legitimate books, not "non-book" trash), and finally the number of final editions (that is, passed titles after eliminating any duplicates accidentally included by Amazon, which does happen at times). Finally (for findbooks, it reports that it is finished: completed all search work. monitor then takes back control, also noting that the searching is done. It then separately reports that it will start the sitemapping, how long the searching took, and that the mapper is actuallty being started. The next entries are from the makemaps.php script: it reports each division, in turn, as having been mapped; it then reports either that it notified the search engines of the new maps or that nothing has changed since the last mapping (so no need to notify the engines). Finally, monitor enters its concluding summary line.

The lower part of the Status Report page repeats the sorts of data gotten when we ran tryme1st, and which it is always handy to have available.

Now to see how the actual bookshop looks. Just point your browser at your bookshop front-door file, the one you named back in customize.php--let's say it's red-cats-books.php, so (in this example) you'd be looking at:

http://www.friends-of-red-cats.com/red-cats-books/red-cats-books.php

The page you see should look like this, except that it will have your site's actual data. Note that our search term, "Spokane", is inappropriate for the site, but this was just a test: the real thing comes next, after you look around and verify that everything seems right. Note that the links on this docfile page to your other bookshop pages and functions should work--but it's the real page that you need to be playing around on, so as to verify proper operation.

Our Amazon U.S.A. 'Cats' Book Shop     Select the Amazon division of interest to you:      Amazon US Amazon UK Amazon CA Amazon DE Amazon FR Amazon JP       (The division shown here is currently in effect.) (Select a division in the box above the button . . .    . . .  then click the button to activate your choice.) The Friends of Red Cats Society Web Site and Books Sponsored links: New Books Those interested in Spokane may reasonably be assumed to also have some interest in books about Spokane. There are many places on the internet that sell new books, but if you run any reasonable number of random samples through a price-comparison service, you will reliably find that for new books Amazon Books delivers the lowest price in the great majority of cases. Moreover, Amazon has free delivery with any order of new books above a reasonable minimum, and you can "save up" book orders till your total reaches that minumum. For new books, Amazon is the obvious choice. (Click on the image above to see a message from Amazon.) New Books About Spokane While we have a general Amazon book-search facility that we will discuss more in a moment (and it's better than Amazon's own), let's talk first about the subject of this site: Spokane. Our software goes out every night and, through a special data interface, queries Amazon for all books it carries related to "Spokane", which is normally a very great many titles. That software then combs through that vast horde of listings and discards the ones (typically a large majority) that are not really available right then (Amazon continues to list many books that have gone unavailable); the software then lists the truly available Spokane books on a set of web pages here. Today, we have 26 books on Spokane that you can read about and conveniently one-click buy from right here, right now, through Amazon U.S.A.. (We do not ourselves categorize these titles: they are what Amazon returns for the search phrase "Spokane". Amazon often includes in its results a few books that seem to bear little relation to the search phrase--sometimes to the point of being amusing--but the vast majority in these lists are "on point".) Here's how you can see all those titles: There are two lists. The one most easily used is a set of 27 pages (one for each letter of the alphabet, and one for titles that begin with something other than a letter). Books are listed on those pages by the first word of their title, except for titles beginning with A, An, or The, which are listed by their second word. The second list is a single "master list"--everything on one page--of all of the numerous "Spokane" books available. It is a long page (and may take a while to load if you have a slow internet connection), and it is straight text, not web text like the other lists. Its purpose is to allow you to search in one place for titles containing, but not starting with, some word or phrase, or for particular authors. You can search the page on line, with your browser's Search facility, or you can download the page and use any text editor to examine it. (All modern browsers can directly display this master file, which is in a special compressed form; if yours cannot, you can download the file and then "gunzip" it; but if that's your case, look at the nice click-on bar at the very bottom of this page and get your free Firefox browser.) A typical entry on one of the alphabetical set of book-title pages might look like this: The Little Spokane Tom I. Davis Paperback: 2000-05-01 (Lost Horse Press) $10.00 (Usually ships in 24 hours) or search Abebooks for this book used That's all pretty simple and self-evident: the book's title, which is a click-on link; the book's author; the "medium"; the publication date and publisher; the Amazon price to you and best current shipping estimate; and a link to an Abebooks search (of which more in a moment, under Used Books) for used copies of the same title. To see the page you'd get if you clicked on the title, well, click on the title (that sample above works). Before you do, though, let us note that the page you go to will have more or less the same information--only updated the instant you click, so you can be sure the price and availability are exactly up to the minute--plus a really large image of the book's cover (if Amazon has an image, which it usually but not always does), information on whether the book qualifies toward the free-shipping minimum (and a link to more information on Amazon's free-shipping policies), and a one-click button that will put the book in your Amazon "Shopping Cart" (or let you create a Cart if you are one of those ever-fewer folk who haven't bought from Amazon before). Plus: that page will also have all editorial and reader reviews of the book that Amazon has (and the reader reviews are listed in the order that other readers have voted them "useful"). (Those links will bring up new browser windows--just close them when you're through looking and this page will still be here.) A last thought: don't be afraid to add books to your Shopping Cart. You haven't actually bought any books till you go through Amazon's checkout procedure. Till you do, you can add other items to your cart or remove any items already in it (you use Amazon's pages to do those things). New Books on Other Subjects We make it easy for you to locate books on Spokane, but you are not limited to such books. After all, Amazon sells pretty much every single title actually in print! You could, of course, visit Amazon own pages and use their search to locate books. But experienced internet book buyers know that Amazon's searches are imperfect in several ways: they usually don't return all available editions on the first pass, they commonly return all sorts of "non-books" (calendars, post cards, and suchlike junk), and nowadays their "internal search" returns ridiculously long sets of results from which it is hard to find actual books you want. And they clutter up your screen with all sorts of peripheral "information" (read ads) not much related to what you are searching for. This site has a book-search page for Amazon that is similar to but, many feel, much better than Amazon's own. While our page is simple and intuitive to use, it nonetheless has an extensive introduction that points out some Amazon "gotchas" and various ways to improve your search experience. But, even if you read all of that long introduction, you'll only need to go through it once; thereafter, when you visit that search page (we hope you'll bookmark it and use it as your regular new-book shopping tool) you can use the "jump to box" link atop the page to get right to the search box (or you can just bookmark the box once you've jumped to it). If you want, you can visit and test our Amazon book-search page right now--the page will open in a separate browser window, so this page will still be here when you're through looking there. Each result turned up by our searches is roughly similar to the one of the Spokane-book listings on our alphabetical pages (except that it also shows a small image of the cover, something we don't do on our book-list pages because otherwise they'd take forever to load). When you click on any of the results, you'll be taken to a page exactly like the pages you get to from our lists, which you have probably already seen. They are, like the search-results pages themselves, clean, neat, simple, and easy to look over, unlike the ad-jammed pages Amazon sends you. Our search, like our Spokane-book lists, defaults to showing you only real books that are really available--but you can very easily change those defaults if you want to see unavailable items (for information purposes) or are interested in related goods (what the trade calls "nonbooks"). Used Books If, instead of books available new, you are interested--whether for price or availability reasons--in used books, of any kind (Spokane or other, that is), we have a nice, simple used-book search page for you; it searches the listings on Abebooks, a listing service with a really huge number of internet used-book-selling members--virtually all internet used-book sellers are Abebooks-listed, from the big guys down to most mom'n'pop operations. If you want, you can visit and test our used-book search page right now--the page will open in a separate browser window, so this page will still be here when you're through looking there. Like the new-book search, this is a very simple, easy-to-use search facility. All The "Spokane"-Book Pages · "Spokane" Books Available New Today:      By Title:       A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | numerals etc.      The "Spokane"-Books "Master List" (large textfile for special searching) · Search for Any New Book at Any Amazon National Division · Search for Any Used Book at Abebooks This page was designed in accordance with international standards for HTML as set forth by the W3C (World Wide Web Consortium) for Extensible HyperText Markup Language (XHTML) Protocol v1.0 (Transitional). Not all browsers correctly render standard HTML; Internet Explorer, for one, does not. We strongly recommend the widely praised free, multi-platform Firefox browser. Click on the image below to read all about it.

I repeat that you should now play around on the real front page, clicking on links and seeing that everything goes where it should and looks about right (and click on links from those pages, too). When you're satisfied that--for this test run on "spokane"--everything looks right, it's time to move on to selecting a real search phrase for your bookshop and doing your first real run.

(By the way, note that if you run your cursor over any of the images on the "front page", a neat little message will pop up at the cursor.)

If anything--in the Status Report, on the front page, on any other page, anywhere--seems wrong at this point, and especially if it seems very wrong, double-check your customizations in customize.php. If you can't find any errors, e-mail me; try to describe the problem in as much detail as you can, and don't forget to give me the URL of your BookAdder directory.

If--as will normally be the case--everything looks good, it's time to move on to Step 7 and set you up with a real search phrase and get you going (you are not ready to open up yet). For that, we move on to a whole other docfile, as described below.

Moving On

BookAdder Documentation Files Available

They are:

• About BookAdder - a useful overview of what BookAdder does, how, and why
• Installing BookAdder - this file
• 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 - the purpose of every file in BookAdder: worth reading for tips'n'tricks

What to Read Next

You are ready to pick your real search phrase. Click on to proceed to the Tuning Your Search docfile.