Create a new directory on your hard drive, floppy, or other writable drive. "C:\actipub" will work fine. The total installation uses less than a megabyte. Open the "actipub.zip" file with any ZIP file extractor, and extract the files in the ZIP file to the new directory. Several subdirectories will be created and loaded with ActiPub files, and these are described in the documentation. There is no "setup.exe" executable. ActiPub includes one small executable program, but it is ready to run once extracted from the ZIP file.
The ActiPub ZIP file is smaller than a megabyte, and the total space used by the contained files is also less than one megabyte. The documentation describes some strategies for long term usage, but in general, the ZIP file can be deleted once the contained files are extracted. There are about 2000 files in the whole ActiPub distribution, so the use of a floppy will be time consuming, even though the files are small.
To un-install ActiPub, simply delete the files. No changes to the Windows registry are made, and no DLLs are used.
See the file purchase.txt for shareware licensing information. See the file license.txt for legalese. You're now reading doc.html, which contains the documentation for the software. hyper.pdf contains a more detailed description of hyperfiction as an art form, with some additional discussion of how ActiPub helps.
doc.html should be opened in a web browser. Most users should be able to simply "double click" on the file icon in a file explorer window or desktop. If this doesn't work, try the browser's File -> Open... menu command, and browse to the doc.html file.
Some files in the ActiPub distribution are PDF 4.0 files. A free reader for these files can be obtained from www.adobe.com. Users of older versions of the PDF reader might need to upgrade their readers (for free) in order to read the ActiPub files. Critical information, such as documentation, is provided in .txt or .html formats.
There are five directories consisting of images and .htm files:
These directories contain subdirectories for .htm files and images, named la (left), lc (left center), rc (right center), rt (right). These refer to the location of the .htm files in the "story tree".
Graphs and Trees
We have to discuss a little bit of math here in order to define what is meant by a tree. A graph is a set of interconnected nodes. For the purposes of ActiPub, a node is an HTML file, and the nodes (files) are connected by HTML links from each file to others. A tree is a rather linear form of graph where a root node is connected to child nodes, which are further connected to more child nodes. A tree is a graph with leaf nodes, which have no children. When you draw this, it looks sort of like a genealogical family tree.
A binary tree is a tree in which each node has two children, except for the leaf nodes. A trinary tree is a tree in which each node has three children, except for the leaf nodes. That big drawing you see each year for the NCAA basketball tournament is a binary tree.
The ActiPub user will choose one of the four hyperfiction template directories, binfancy, binplain, trifancy, triplain. The choice depends on whether the user wants his or her hyperfiction appearance to be fancy or plain, and whether each file of the story should link to two, or three, subsequent files.
Not Purely Binary/Trinary
During testing, it was found that a more interesting overall work develops more quickly if the very first file links to more than two or three files. Therefore, in all four cases, the first file of an ActiPub work links to four files. From then on, the files link to either two or three files, depending on the directory. The first file of the story, in each of the four main directories, is named index.htm.
What the Reader Sees
The reader of a work of hyperfiction will start with index.htm, and click on the links shown in the browser window. With each click, a new page appears, with new links. This is how the ultimate reader will traverse the story tree, i.e., read the story. The reader decides which file to read next, and the author decides what the choices are. Starting with index.htm, the reader can click seven times (in a binary directory) and five times (in a trinary directory) before reaching a file with no more links (a leaf node). Of course, the HTML can be edited, and the story doesn't have to end there, but this describes the default ActiPub setup. Each .htm file can contain any amount of story text.
How the Files are Sorted
As was stated above, each index.htm file links to four other .htm files. These four files are stored in separate subdirectories named la (left), lc (left center), rc (right center), rt (right). This terminology refers to the sections of the tree contained in each directory, but it has no real bearing on the literature being written. They're just four arbitrary names. Each of the four main directories (binfancy, binplain, trifancy, triplain) has four subdirectories (la, lc, rc, rt). The fancy directories also have an images subdirectory.
A List is Provided
Each main directory contains one .txt file that contains a table naming each file in the four subdirectories, its parent file (the file that links to it), and its child files (the two or three files that it links to). Some files are leaf nodes and have no child files. These files are named binfmap.txt, binpmap.txt, trifmap.txt, tripmap.txt. These mapping files contain the entire list of files from all four subdirectories, in alphabetical order. Note that the file names in each of the subdirectories starts with the directory name itself. For example, lc210001.htm is in the lc directory. This fact can be used to make the map table a little narrower, by not repeating the directory name. The map file is intended to be used to check off which .htm files have been edited so far.
In each binary tree directory, binfancy and binplain, there are 509 .htm files. In each trinary tree directory, trifancy and triplain, there are 485 .htm files. The number used in a story can be reduced fairly easily, as will be described later.
Images
The fancy directories contain an images directory. This contains .gif files to be used as the background images for the root file (index.htm) and the files in each subdirectory. There are also images to denote the user's choice. These files can be edited or duplicated to achieve various simple or sophisticated effects. ActiPub does not provide a .gif file image editor, but there are many such editors available, some for free. Each file in a whole work can use the same background, or each of the four subdirectories can be different from each other. More complicated effects can be achieved with more HTML work, but ActiPub provides an easy way to change certain blocks of files, as is described in more detail in the editing section.
Normally, the ActiPub user will
Virtually any text editor will work well, but if something more sophisticated than Notepad is desired, try out Arachnophilia.
This documentation provides customized instructions for editing ActiPub's files. This documentation does not provide general HTML editing instructions. For general help, refer to:
Editing Page One
Each of the four story tree directories contains a file named index.htm. If you're really a novice at editing HTML files, first double-click on this file to see what it looks like when viewed in a browser.
Open index.htm in your text editor. In binplain and triplain, you'll see a line in the middle:
You'll also see the line:
Change the Copyright Notice!
At the end of index.htm, you'll see:
Don't Delete ...
Don't delete lines containing <html>, <head>, </html>, </head>, <body ...>, </body>, <pre>, </pre>. In the <body ...> line, you might want to change the image name, but there is more on this later. These instructions are intended for authors who aren't necessarily HTML experts, and experts will know that there are many ways to write an HTML file. If you think you know what you're doing, you can take my warnings with a grain of salt.
Links to the next page(s)
The basic form of a link to another file looks like:
The point of ActiPub is to avoid editing the file name that follows href=. ActiPub provides a set of hundreds of interlinked files. If you change the links inside the files, you'll also have to change the file names, and then it gets messy. However, if you feel like editing the HTML code, it's perfectly reasonable and permitted.
Setting the Background and Choice Images in index.htm
In the fancy directories, index.htm uses a background image file. Look for the line near the top,
index.htm also includes four "choice" images. By default, this file links to four subsequent files in the story tree, and the fancy directories include an image that indicates the choices being offered. These images are in the images subdirectory with the names rootch1.gif, rootch2.gif, rootch3.gif, and rootch4.gif. The basic form of an image reference looks like:
The images are optional. You can delete the image reference and leave just the link, which begins with <a href=.... The sample directory has examples.
Editing the Rest of the Pages
The subsequent pages in the story tree are similar to index.htm, except that they link to only two or three files, instead of four. Some of the files don't link to any files, except for the previous file; these are the leaf nodes mentioned earlier. These files are endpoints of the hyperfiction work; they don't go anywhere except the previous page.
The story tree contains four mini-trees in subdirectories la, lc, rc, rt. This was done to make it easier to delete portions of the story tree, which will be discussed later. The file naming scheme is similar for each directory, except that the file name begins with its subdirectory name. Don't try to figure out the numbering convention; it's just a mathematical anomaly of the process used to create the files.
Each of the four main directories contains a map file. See the next section, Use the Map.
Each fancy file contains:
ActiPub users may determine that, for their stories, the title or images or reference to the previous page is distracting. It's easier to delete the text than it is to create it if you want it, and you have to edit every file in your story anyway, so you can do the deletions while you're there.
Note that each fancy subdirectory's (la, lc, rc, rt) files refer to a different background image. By default, the image is plain white. ActiPub's setup allows the user to simply edit the four background .gif files (bgleft.gif, bglftctr.gif, bgrgtctr.gif, bgright.gif) to achieve a different background image for each of the four mini-trees. In other words, index.htm links to four files, one in each of the mini-trees. The ActiPub user could cause the first choice to link to a mini-tree of pages with a green background, while the second choice links to a mini-tree of pages with a marble patterned background, and so on. Of course, if the user wants all four mini-trees to have the same background image, but not the default white, then all four .gif files must be changed, but that's better than editing all 500 files.
Note that each fancy subdirectory's (la, lc, rc, rt) files refer to a different set of "choice" images. By default, the images are Roman numerals. ActiPub's setup allows the user to simply edit the choice .gif files (leftch1.gif, leftch2.gif, leftch3.gif, lfctrch1.gif, lfctrch2.gif, lfctrch3.gif, rctrch1.gif, rctrch2.gif, rctrch3.gif, rightch1.gif, rightch2.gif, rightch3.gif) to achieve different choice images for each of the four mini-trees. In other words, index.htm links to four files, one in each of the mini-trees. The ActiPub user could cause the first choice to link to a mini-tree of pages with Roman numeral choice images, while the second choice links to a mini-tree of pages with bullet choice images, and so on. Of course, if the user wants all four mini-trees to have the same choice images, but not the default Roman numerals, then all of the .gif files must be changed, but that's better than editing all 500 files.
Use the Map
Each of the four main directories contains a map file, binfmap.txt, binpmap.txt, trifmap.txt, or tripmap.txt. This map describes, for each file, which files it links to, and which file links to it. As you edit the files to write your hyperfiction, check them off in the notes column, or put a date, or whatever seems helpful. The story does not proceed through the files alphabetically, and the map is a reminder of where the next file is. The map is really handy if you decide to delete the link to the parent, but as the author, you need to know. In general, an ActiPub user would not publish the map with his or her hyperfiction. That would be like a magician giving away the secret, but there are precedents.
Yes, but it's not hard to reduce the size of the story tree. Remember that if you delete files, you must also delete the links to those files.
The number of files is large because it's easier to delete them than to create them. If you're writing a conventional novel, it's going to have a couple hundred pages, right? ActiPub's 500+ pages aren't meant to imply that you'll be rewriting Moby Dick. Your ActiPub files can include any amount of story text, so don't be afraid to "prune the tree" when you're at the end and don't need any more files.
To reduce the number of files in your story, you'll need to
As described above, the reference to the choice image, if any, looks like
It's OK to delete some links, but not others. Maybe you want index.htm to link to just three files, for example. In this case, you could delete the link to, say, rc/rc110001.htm, and then delete the whole rc directory and its files. Such an action would reduce the story tree by 127 pages, and all you had to do was edit out one link and delete one directory. That's why the story tree is split into four directories.
As noted in the Graphs and Trees section, ActiPub provides files linked together into a tree. A tree has a root node. veripub starts at the root node and follows the links to the ends (leaf nodes) of the tree. If it finds a link that it can't follow, it reports an error. If veripub follows all the links and there are untouched files left over (known as orphan files), their names are reported.
veripub does not appear in its own window; it runs in an "MS-DOS Prompt" window. You should be able to find the command for this in your Start menu. If not, select the Run command from the Start menu and enter command.com. You must start an MS-DOS Prompt window in order to run veripub.
When the prompt window opens, you'll see a cursor flashing next to the name of the "current" directory. The default current directory is probably not where ActiPub is installed; it's probably something like "C:\WINDOWS". That's OK, you'll enter ActiPub's directory. The form for the command is:
Let's say that ActiPub is installed in "C:\Program Files\ActiPub", and the hyperfiction story tree is in "A:\stuff\story". Since the installation directory name has a space in it, the name must be enclosed in double quotes when running the command. Here's what you'd enter:
The hyperfiction work, if it follows the ActiPub default structure, has four subdirectories, and each subdirectory must be verified separately, e.g.:
The ActiPub user may change the story structure; the original binary or trinary trees can be modified, such as by using more links, circular paths, etc. This requires extensive HTML hacking, but it's not unreasonable. If a story graph is circular, that means that there is at least one way to read the story such that at least one file can be reached twice. The reader could, if desired, reread the same sequence of story files over and over. veripub is smart enough not to get hung up in an infinite analysis loop.
In general, the argument given to veripub should be the first page (root node) of the story tree in the chosen directory. This is not the index.htm file found in the main directory for the whole story. For the ActiPub default files, the root file in a subdirectory has a name that ends in ...10001.htm. The first three characters of the file name depend on the directory. The example above shows this sort of name.
The file sample\la\la110001.htm contains errors. If that directory is processed:
Bad Links
If veripub finds a link in one file that refers to another file that can't be found, it reports the following:
filename 1 is the name of the HTML file being analyzed, and it contains a link to filename 2, but veripub was unable to find filename 2. The ultimate reader of the file can click on the link, but the browser will report an error message. The cause could be a typo, or possibly, the hyperfiction author deleted the file, either accidentally or intentionally.
Orphan Files
veripub starts with the root file and "follows the links". In other words, when a link in the root file points to another file in the directory, that file is then analyzed. When all of the links are followed, it's possible that one or more HTML files in the directory will not have been analyzed. These are orphan files. They're not part of the story tree, and the ultimate reader won't see them unless there is a link from some other directory. veripub reports the following:
The cause could be a typo in another file, i.e., there might also be a bad link reported, as described above; when the bad link is repaired, rerun veripub, and the orphan file will no longer be an orphan. Another possible cause is that the original link to the file was intentionally deleted, but the ActiPub user forgot to delete the file. After deleting the file, rerun veripub, and the orphan file error will not be reported.
ActiPub is not smart enough to know whether an orphan file should be linked to, or should be deleted. Only the ActiPub user will know what the correct fix should be.
veripub's limitations
veripub was written to verify an ActiPub set of HTML files, using the directory structure as released with the product. If the ActiPub user does a lot of HTML editing, he or she will reduce the usefulness of veripub.
* Only the named directory is searched for files.
When running veripub, the user provides a directory name. The root file is either named or assumed, but it's in that directory. When the links are followed, only HTML files in the same directory are analyzed. If a file is linked to, but is in a different directory or server, the file is verified for existence, but it is not analyzed.
For example, try to analyze the main directory of the sample directory:
Only one HTML file (index.htm) will be found, even though it links to four other HTML files. Those files are checked for existence, but they're not analyzed because they're in different directories. If the rt directory is processed:
* Links to other drives or servers are not followed.
If a link to a file contains a colon, such as:
* The 'equals' sign is used to find links to files.
Sophisticated use of HTML commands, such as when specifying the width and height of an image, will confuse veripub. A link to a file is found by looking for an 'equals' sign in each line in the file. This is a simple assumption, and will be improved in future versions. For now, veripub assumes that the original ActiPub HTML commands are pretty much unchanged.
Also note that, when the story or poetry text uses an equals sign, this will cause veripub to report an error. Such an error report is annoying, but can be ignored. This will be improved in future versions.
Some users may have configured their systems so that double-clicking doesn't work. In this case, use the browser's File menu to open the index.htm file, or whatever file represents the beginning of the story.
For hyperfiction stories already published to the Internet, the index.htm file is opened like any other web page. This is usually how the ultimate reader will access the story. Once the first page is viewed in the browser, the links will be available, and the mouse can be used to get to subsequent files.
The ultimate readers will only see what the hyperfiction author wants them to see. Usually, the map will not be published, i.e., the author doesn't want the reader to open each file directly. The author wants the reader to view the files in a controlled manner, i.e., in the order specified by the links. However, there is no reason that the map files provided with ActiPub can't be published.
The directory structure must be kept intact. If one file links to another file in another directory, that second directory must exist on the host web site. The ActiPub files, as provided by default, use "relative addressing". In other words, the links point to simple file names, not to fully named web site addresses. Therefore, once the reader finds the first page, the subsequent pages are assumed to be on the same web site, and the links will work.
If the links don't work, check for problems with the case of the file names. Some servers may have case-sensitive file names. In other words, a file that links to the file la110001.htm may report an error if the file is actually named LA110001.htm. It doesn't matter which case is used, upper case or lower case, but the links in the files should use the same case as the actual file names.
Another way to publish a work of hyperfiction would be to package the work in an archive, such as a ZIP file. The ultimate reader would download or otherwise obtain the ZIP file and extract the HTML files.
For more information on publishing files to your ISP's web site, refer to your ISP's documentation.
www.gocek.org may agree to provide links from the ActiPub home page to stories created using licensed versions of ActiPub. There will generally be no charge for such a link, but Gary Gocek reserves the right to decide which links will be added to the ActiPub home page. www.gocek.org will not provide web space for stories.
To purchase an ActiPub license, visit the following web site:
Editing the .htm Files
The primary use for ActiPub is to select a story tree (binfancy, binplain, trifancy, triplain) and edit its .htm files, and possibly its .gif files, in the course of developing a work of hyperfiction. The first thing to do is to copy your selected story directory into a new place. Leave the originally installed files alone, and edit the copies. In this manner, you can write as many hyperfiction works as you wish, and you'll always have the ActiPub originals to start from. Of course, if you forget, and edit the originals, you can get them again from the ActiPub home page, and you don't need to pay the license fee again.
In many cases, the HTML commands needn't be edited, but it is unlikely that a whole work of hyperfiction can be produced without any editing of the HTML commands.
Type your story text here.
In binfancy and trifancy, you'll also see:
End paragraphs with a 'p' inside angle brackets.<p>
It is this line that you'll replace with your own story text. In the fancy directories, put a <p> at the end of each paragraph. If you leave this out, all of your sentences will appear in one paragraph. In the plain directories, this is not necessary, as long as you retain the lines that contain <pre> and </pre>.
This is the first page.
possibly followed by <p>. This whole line is optional; you can delete this.
<!-- ActiPub v1999.10, www.gocek.org/actipub, copyright 1999 by Gary Gocek -->
This "comment" won't appear when viewed in the browser. This should be deleted or replaced with your own copyright notice, unless you want Gary Gocek to own the copyright to your story. This sort of editing might seem improper, but it is expressly permitted for licensed ActiPub users.
<a href=filename.htm>readable-text</a>
The piece, readable-text, is what the ultimate reader will see underlined in the browser window. This is not a file name, it's just some text that gives the user an idea of where that link leads.
<body BACKGROUND="images/bgpage1.gif">
The name in quotes can be any .gif or .jpg file. The image in that file becomes the background of the page when viewed in a browser. ActiPub users are licensed to change the default file, which is found in the images subdirectory with the name bgpage1.gif. If you need a .gif file editor, try Paint Shop Pro. You can also delete the background image; just change the line so that it reads <body>.
<img src=filename.gif>
You'll see that this type of command is followed by a link to another file. When the file is displayed, the reader sees the image followed immediately by the underlined text. There are four such lines in index.htm.
The plain files just contain the default text and links, with no title nor images.
Deleting Files, and Reducing the Size of the Default Story Tree
Holy Cow, that story tree has over 500 files in it!
You remembered to make a copy of the original directory, and you're working on that copy, right? So, you can delete anything you want, and it's still safe in the original location, or at the ActiPub home page.
<img src=../images/filename.gif>.
The link to a subsequent page looks like
<a href=filename.htm>Choice X</a>.
Delete this text completely when you've decided that the current file is an endpoint of the story. See the sample files for help.
Verifying the Links Between Files with veripub.exe
So, you've edited and/or deleted a few hundred files and you think you're close to publishing your work of hyperfiction. You've tried to test every file, but there are so many that the testing process is tedious. veripub.exe does some testing of your story tree to make sure that:
If ActiPub provides all the links from the start, what could go wrong? While ActiPub provides all the links and they've been tested, accidents can happen once the user starts hacking at all that HTML. Most errors that veripub catches will be typographical errors. Users who delete or add files may also make mistakes when entering the links or naming the files, or by forgetting to delete the files after removing the links to those files.
veripub [[directory]\filename]
If no directory name or file name are entered, the current directory is searched for .htm and .html files, and the first one (alphabetically) is used as the root file. If a directory name is entered with no file, that directory is searched for .htm and .html files, and the first one (alphabetically) is used as the root file. If a file name is entered, that file is used as the root file. If ActiPub's original file names are not changed, then the first file (alphabetically) will be the root file, so you don't need to enter its name when running veripub.
"c:\program files\actipub\veripub" a:\stuff\story\la
or
"c:\program files\actipub\veripub" a:\stuff\story\la\la110001.htm
They'll have the same effect, if the file names weren't modified from the original. It's OK to put a name in double quotes even if there are no blank spaces, but the example doesn't show that.
"c:\program files\actipub\veripub" a:\stuff\story\la
(program output not shown)
"c:\program files\actipub\veripub" a:\stuff\story\lc
(program output not shown)
"c:\program files\actipub\veripub" a:\stuff\story\rc
(program output not shown)
"c:\program files\actipub\veripub" a:\stuff\story\rt
(program output not shown)
veripub sample\la
the error reports can be observed. This was done to show users what sorts of errors can be identified.
In <filename 1>, can't find linked file <filename 2>.
<filename 1> is in the directory, but is not part of the tree.
veripub sample
veripub sample\rt
three files will be found.
<a href=http://www.abc.com/>Click here<a>
then the file is not checked for existence, nor analyzed. veripub only looks for files on the same drive and server.
Reading the Hyperfiction Work
The ActiPub user can usually read his or her own work simply by double-clicking on the index.htm file in the main directory. For example, try double-clicking on sample\index.htm. This is the first page of the sample story. This works because the web browser can display files on the local hard drive, just as it can display files on the Internet.
Uploading the Hyperfiction Work
In general, ActiPub does not provide any aids for publishing the HTML files from the hard drive, where they are edited, to the Internet, where they are viewed by the ultimate readers. The ActiPub user must already have arranged for a web site, such as through an ISP. The user will probably need an FTP program to upload the pages, but this depends on the ISP.
Support and Registration
All technical support requests and questions should be emailed to
actipub@gocek.org. No live telephone support is available at this time.
https://www.evergreennetworks.com/register/400/411a.htm
Or call 1-800-427-2770 FOR ORDERING ONLY. NOT A SUPPORT LINE!
For information on quantity discounts, send email to
actipub@gocek.org. ActiPub is distributed in its fully functional
form. After paying for a license, no activation codes or different
versions need be provided.