HyperLink 2.0 (Registered) Documentation

Copyright 1994, 1999 Cameron Kaiser and Computer Workshops, Inc. All rights reserved.

Welcome to HyperLink!

Welcome to the world of Commodore hypermedia! HyperLink is a browser-like client for reading hypertext-enabled documents, allowing you to insert graphics, hyperlinks and even dynamic content into pages. Now, your Commodore 64 can drive dynamic manuals, intelligent documentation and electronic books with its easy-to-use interface and programming language.

What's New in 2.0?

A Note on the Registered Version

Thank you very much for registering your software! Your support is very appreciated.

With the Registered version, you may access scripts by name and release scripts you've written. Please don't copy the Registered version for users who have not registered. While odds are we can't stop you, you'll be putting small companies like us that still support the 64 and 128 in the can that much faster. Please don't pirate.

Again, thank you for registering!

Starting HyperLink

System Requirements: Commodore 64 (or 128 in 64 mode), disk drive, joystick. Please plug the joystick into port #2. HyperLink has been tested compatible with CMD FD series drives, 1541/1571/1581 disk drives, and the SuperCPU. Fastloaders: HyperLink only uses Kernal routines and should be compatible with all major fastloaders. It has been tested compatible with the Epyx FastLoad and JiffyDOS. If you experience difficulty loading the program, please disable your fastloader or freezer cartridge and retry. Emulators: HyperLink has been tested compatible with C64S (2.5B), Frodo (Win32 4.1), VICE (Win32 0.16.0) and CCS64 (1.09). VICE is recommended for best performance. For C64S and Frodo, you must enable full 1541 emulation to properly read scripts. For booting this program on an emulator, please refer to your emulator's documentation.
  1. Insert your HyperLink disk into the computer and turn the computer on. 128 owners must be in 64 mode. You may use any disk drive connected to your system.
  2. At the READY. prompt, type LOAD"CWI",D,1 where D is the device number of the disk drive with the HyperLink disk.
  3. The spinning Computer Workshops logo will appear, and then HyperLink will start and load the main home script.

Getting Around in HyperLink

When HyperLink loads, you'll notice a (by default) light blue pointer which appears as an hourglass when HyperLink is formatting or loading a page, and as a regular pointer otherwise. You'll also see (by default) light blue scroll bars to the left, and at the top of the screen, a navigation bar with five icons on it.

You can move the pointer around with a joystick in port 2, point to things, and click on them, just like in a regular Web browser. Clicking on the scroll icons moves you down the document, or back to the beginning. (For technical reasons, you can't scroll back up.)

Like a web page, hyperlinks may be embedded in the document you're reading. The pointer and scroll bars always reflect the colour of hyperlinked text that you can click on. Clicking on it takes you to the linked page, just like in a Web browser.

The navigation bar has five options. The light green arrow icon is the Back icon, taking you back to the previous page you linked from. HyperLink stores a stack of twenty pages, so you can use the Back arrow up to twenty times. The light blue file folder icon is the Open icon, which allows you to access scripts by name directly. Simply click on it and enter the filename (you don't need the lnk prefix). The light grey house icon is the Home icon, which finds the home script on the disk in the drive, resets HyperLink, and loads and displays it. The white Computer Workshops logo icon finds the about script on the current disk, and displays it as if you clicked on it as a link. You can use the Back icon to back up from it. Finally, the pink question mark icon is the Help icon, which finds the help script on the current disk and displays it as if you clicked on it as a link. You can use the Back icon to back up from it.

You can also press F1 for help, F3 to open a script by name, F5 for the home script, and F7 to back up, as in previous versions of HyperLink.

Using Other HyperLink Applications

You can boot any HyperLink-powered application by simply inserting its disk into the drive and pressing F5 or clicking the home icon. The application will automatically start. Proper applications will also include their own help and about scripts. You can run any application in the Free client that you can run in the Registered client, and vice versa.

To go back to the original HyperLink scripts, insert your HyperLink disk and press F5 or click the home icon.

Programming in HyperLink

HyperLink scripts are programmed in LinkScript, a special text markup language that uses dot commands to indicate how text should be formatted. There are two versions of LinkScript; version A was used in the original HyperLink 1.0, and version B is used in this version 2.0. LinkScript version B is completely backwards compatible with version A meaning you can continue to view all your old HyperLink 1.0 scripts in HyperLink 2.0.

All LinkScript files are regular text files that you can type up in any wordprocessor (as long as it has an option to save in plain PETSCII, such as to a SEQ file), and always start with the prefix lnk. LinkScript directives always start with a period (.). Anything that the LinkScript parser does not understand or see as a command is printed, until there is no more room on the screen and the page must be turned. For example, this sample script

Big type
Little type
Blue type
Regular type
prints Big type in oversize letters, Little type in regular characters, Blue type in blue and Regular type in the default screen colour (usually black). All the tags used here are described below.

All lines must be 37 characters or less.

There are three special HyperLink scripts that must be on each HyperLink disk: lnk.home, which is the home script; lnk.help, which is the online help; and lnk.info, which describes the application you're running. When you press F5, you access the home script (which you can also do by pressing F3 and entering home); F1, the help script (or press F3 and enter help); and when you click the CWI icon, you get the about script (or F3 and enter about). Disk errors result otherwise. These are most important when developing your own applications for distribution.

Each directive below is keyed by which version of LinkScript they work in. Many tags only work in HyperLink 2.0, so if you are intending to wite scripts for LinkScript 1.0 users, be sure to use only the tags that version understands.

@ [comment] (LinkScript A, B)
The @ sign simply treats the rest of the line as a comment, effectively skipping it. Comments are good programming practise, but slow down execution and loading, so use them parsimoniously. This is the only LinkScript command that does not start with a dot.

.rv[version] (LinkScript A, B)
The .rv tag tells the interpreter what version of LinkScript is required to view the script. .rvb says that LinkScript B is required; .rva says LinkScript A. With this tag properly set, instead of garbled tags a user with a version of LinkScript too old to view your script will get an error message explaining the problem. If this tag is not declared, the interpreter assumes A. You should only use this tag once, at the beginning of your script.

.fc[colour] (LinkScript B)
This specifies the text colour (0-15) for following text; .fc2, for example, starts displaying text in red. .fc alone goes back to the default colour, usually black, and turns off the colour. This replaces the .co tag in LinkScript A, which is now deprecated.

.fs[size] (B)
This specifies the text size for following text. .fs alone goes back to the default size, usually 1x character size. Only .fs2 and .fs1 are currently supported (2x and 1x size). This replaces the .h2 and .h1 tags in LinkScript A, which are now deprecated.

.il[width],[image] or .il[image] (B)
This inserts an inline image in I3 format. The image must be no wider than 37 cells in width (or it will be truncated on the right edge), but it can be as vertically long as desired. The optional width parameter allows you to truncate the image further to the left (so that formatting like centreing and right justification will work more effectively); for example, .il20,picture trims I3 image picture to 20 cells width while .ilpicture does not. The iii prefix is automatically added to the filename for you.

The I3 image format (Interleaved Inline Image) is a special format designed for quickly referencing parts of an image for applications such as inline display. If the image is corrupt, the interpreter will instead show the text "Corrupt image" (like a broken image icon in Netscape Navigator). You can convert Doodle pictures to I3 format with the freeware Doodle->I3 converter, available from Computer Workshops.

.ps (B)
This tag "pops the stack" as if you had pressed F7 to back out of a script. It does not pause.

.cs[byte] (A, B)
This tag clears the background to the colour byte requested; the byte equals the colour of text times 16 plus the colour of the background. These colours then become the default colours. One useless example might be .cs17, which sets both background and text to white. Since the tag clears the screen, text will now start from the top of the screen again.

.pw[location] (A, B)
This tag goes with .pk, and tells where the value specified in .pk should be stored. Do not attempt to bank RAM/ROM or alter system vectors with this or the following instruction, as it will trigger a system crash due to the method in which it is implemented.

.pk[value] (A, B)
This tag stores its value in the location specified by .pw (so something like POKE 53280, 0 would be represented by

). A .pk without a preceding .pw either goes to the last location specified, or gets an error.

.lc[colour] (A, B)
This tag specifies the current link colour. If you change this mid-screen, all previous links displayed to this point are invalidated. The pointer and scrollbars always reflect what this tag sets.

.tc (A, B)
This tag toggles centred text on or off. When off, text is left-justified (default). Right-justification takes precedence over centreing. This also affects inline images.

.tr (A, B)
This tag toggles right-justified text on or off. When off, text is left-justified (default). Right-justification takes precedence over centreing. This also affects inline images.

.ws[timeout] (A, B)
This sets the wait timeout for the .wa tag in jiffies (1/60th of a second). If the timeout is zero, then the interpreter will wait for the firebutton to be pressed before continuing (default).

.wa (A, B)
This waits according to the settings in the .ws tag.

.ln[filename] (A, B)
.li[filename] (B)
These synonymous tags make the line immediately following into a hyperlink and highlight it in the current link colour. When the link is clicked on, the user will go to the script indicated by filename. For example,

Why don't you click here?
It's groovy.
will allow the user to click on the line "Why don't you click here?" and be transported to script script2. The lnk prefix is added for you. Note that "It's groovy." does not become a link; if you wanted it to be, you must insert another .li tag above that line.

.dp[filename] (A, B)
This tag tries to load a Doodle-format picture (include the dd prefix if necessary) and then displays it according to the wait settings specified by the .ws tag. This is useful for slide shows. The screen clears before and after the picture is displayed.

.ch[filename] (A, B)
This tag immediately "chains" to script filename. Unlike the related .lh tag, it doesn't put anything on the stack; i.e., the new script will be treated as a continuation of the first, and pressing F7 to backup will go to the script before the one that started the chain. This tag does not pause.

.lh[filename] (B)
This tag immediately "links" to script filename, as if the user had clicked on it. Unlike the .ch tag, pressing F7 will go back through the "chain" of .lhs, though each script will start over. This tag, thus, can cause infinite loops under uncontrolled circumstances, but with .ps, you can implement primitive subroutines. This tag does not pause.

.xl[filename] (A, B)
This tag loads a file into memory. It does no memory-bounds checking: you must make sure that your program does not enter memory used by HyperLink. You can use this tag to load custom machine language subroutines, pass them parameters with the .pw/.pk tags, and call them with the .xs tag.

The 8K memory range between $8000 (32768) and $9FFF (40959) is available for your ML programs and data. If your program wishes to manipulate the HyperLink screen, it is at $6000 to $7FFF (24576 to 32767), with colour memory between $4400 and $47FF (17408 to 18431). All other locations are reserved and must not be disturbed. If your routine changes memory configurations, it must bank I/O, BASIC ROM and Kernal ROM back in upon return.

As an example, the music in the Baroque Age demonstration is implemented with the .xl and .xs tags. Part of the routine lives at $7D00, right in the hi-res screen, so the .cs tag is used to hide the machine language data from showing up onscreen.

.xs[address] (A, B)
This tag calls the machine-language subroutine at location address. The return value is currently not used in HyperLink.

.bk (B)
This tag causes an execution break, as if the interpreter had reached the end of the screen and were waiting for the screen to be scrolled down to continue. You can use this tag to delay instruction execution.

Style Tips

Distributing Your Scripts

As a Registered user, you are fully licensed to create, distribute and disseminate your applications written in HyperLink freely to your users by including the Free version right on the disk.

To make your scripts distributable, you will need to copy certain files from your HyperLink disk. You may use the HyperLink help and about scripts, if you like, but you must use your own home script and not the script on your HyperLink disk.

Include the following files:

Your users will simply load and run "hello" to start the interpreter. They can also, if they already have HyperLink, insert your disk and press F5 while in HyperLink. You may distribute as many copies as you like without royalties as long as you follow the terms as described above, and do not disseminate the registered version of the program or any other files from the HyperLink system disk not described above.

Legal and Warranty Information

This legal and warranty information only covers the Registered client.

HyperLink Registered is (C) 1994, 1999 Cameron Kaiser and Computer Workshops, Inc. All rights reserved. The Registered edition may not be distributed in any way, shape or form, nor may it be distributed with scripts written by users of the Registered edition.

Violation of these terms constitutes piracy and is punishable under U.S. and international copyright law, making violators liable for criminal and civil damages. Please, don't pirate.

This program is distributed strictly "AS IS". No warranties, express or implied, have been issued concerning the functionality of the program, accuracy of documentation or any other facet of program function and distribution. While the Author and Computer Workshops shall endeavour to ensure the proper operation of the program, you may not assign to the Author, nor to Computer Workshops, liability for any damages, real, intentional, or otherwise, incurred from the use of this program. Your use of this program constitutes your binding acceptance of all terms listed within, and your binding acceptance of punitive legal action should you fail to comply.