The documentation to
CAB
Version 1.0a
12.12.1995
by
Alexander Clauss
Stresemannstraže 44
D-64297 Darmstadt
aclauss@rbg.informatik.th-darmstadt.de
Contents
========
1 A short introduction
2 Legal
3 Address
4 System requirements
5 Installation
6 Navigating HTML Documents
7 Module for on-line Internet access
8 Description of menu items
8.1 Open URL...
8.2 Open local...
8.3 Reload
8.4 Print
8.5 New window
8.6 Close window
8.7 View source
8.8 Quit
8.9 Home page
8.10 Back
8.11 Find keyword
8.12 Hotlist
8.13 Document -> Hotlist
8.14 General options
8.15 Display
8.16 Font selection
8.17 External viewers
8.18 Paths...
8.19 Cache
8.20 Save options
9 Button bar
10 Thanks
11 Possible future updates
12 History
1 A short introduction
======================
*CAB* - The Taxi to the information highway!
*CAB* - Crystal Atari Browser
Formerly called HTML-Browser
This browser is capable of reading HTML format documents. The HTML
documents could be on disk or CD. Reading pages on-line to an
Internet World Wide Web (WWW) site requires a separate module.
2 Legal
=======
CAB (HTML-Browser) is FREEWARE. It may be copied and used freely.
Distribution by BBSs and PD libraries is allowed. However, CAB (HTML-
Browser) may NOT under ANY circumstances be included in CD-ROM
collections or on magazine cover disks without my prior written
permission. CAB (HTML-Browser) and its documentation must always
remain together and complete with all its files and documentation.
Changes to the program and/or documentation is forbidden.
If you like CAB (HTML-Browser) and you use it regularly, please
register your copy, any currency is welcome.
If you would like to see this program developed please send some
feedback and register your copy. UK, USA users can take advantage of
local support, refer to SUPPORT.TXT for more details. No feedback
means no development, it's that simple!
3 Address
=========
*My address:*
Alexander Clauss
Stresemannstr. 44
D-64297 Darmstadt
Germany
email: aclauss@rbg.informatik.th-darmstadt.de
WWW: http://www.student.informatik.th-darmstadt.de/~aclauss/
*Banking arrangements:*
Sparkasse Darmstadt
BLZ: 508 501 50
Kontonr: 0115032143
*UK support:*
Joe Connor
65 Mill Road
Colchester
CO4 5LJ
England
email: jconnor@cix.compulink.co.uk
*USA, Canada support:*
Jeff Wisniewski
P.O. Box 1243
Newtown, PA 18940-0871
email: jeffrey.wisniewski@microserve.com
*France support:*
Jouffrey Romuald
1 chemin de l'‚glise
38100 GRENOBLE
email: rom38@gen4.pressimage.fr
4 System requirements
=====================
The program runs on any computer using the (Atari-) TOS operating
system with 1Mb or more memory. The memory requirements for images
depends on the colour depth. The greater the colour depth the more
memory required. Using a True colour graphic card (24 or 32 bit)
gobbles up memory and you're likely to need considerably more than
1Mb.
CAB is resolution independent with two limitations: At 320x200 (ST-
low) not all of the dialogs fit entirely on screen, at 640x200 (ST-
Medium) the screen display is distorted (half height). Consequently
we recommend using CAB at resolutions of 640x400 (ST-high) or higher
with any number of colours, a multitasking environment (e.g MagiC,
Geneva etc) is also desirable.
Although not absolutely necessary the use of vector fonts via NVDI
v3.x or SpeedoGDOS is recommended. The system font or bitmap GDOS
fonts can however be used if required.
5 Installation
==============
*Attention:*
Since v1.0 the program can no longer be installed as a desktop
accessory.
Configuration files from older versions of CAB (CAB.INF) cannot
be used. Unfortunately you'll have to reset your settings
manually.
The format of the Hotlist file has also been altered but unless a
file in the new format is available the old Hotlist file
(CAB.HOT) is loaded. The new Hotlist file is called hotlist.html.
As soon as the Hotlist has been saved in the new format the old
file (CAB.HOT) can safely be deleted.
HTML files downloaded from WWW sites often include long filenames
which can easily result in duplication of filenames using the basic
TOS 8+3 character file system. It's well worth setting up a Minix
hard disk partition or other file system which supports long
filenames to handle HTML files.
The CAB distribution is supplied ready to run once unarchived onto
your working disk but you should still review the settings in the
Options menu and configure the options to suit your needs.
6 Navigating HTML Documents
===========================
Click on any underlined keyword to branch to the new page. Press the
[Undo] key to step to return to the previous page. Clicking on a link
using the right mouse button will display the address of the page it
links to.
7 Module for on-line Internet access
====================================
To browse WWW pages on-line to the Internet a further module
(CAB.OVL) is needed. This module should be copied to the same
directory as CAB.APP. This file contains the additional routines
needed to access the Internet.
On Minix partitions the x-flag of the CAB.OVL file must be set
otherwise the modul can not be started.
I'm not able to test an Internet module but have built an interface
into CAB (HTML-Browser) to enable anyone capable of programming these
routines to create an on-line module. The description of this
interface is available on request and is available as commented C or
Pascal source. I'd like to hear from anyone who programs an on-line
module and would like a copy to distribute with CAB (HTML-Browser)...
8 Description of menu items
===========================
8.1 Open URL...
---------------
The *Open URL...* option in the *File* menu displays the URL dialog
containing any URL (Universal Resource Locator) addresses you have
set up to access the WWW.
8.2 Open local...
-----------------
The *Open local* option in the *File* menu calls the file selector which
can be used to open any HTML document from hard disk or CD-ROM.
Any file types can be selected. HTML, XBM and GIF files are normally
displayed by CAB (HTML-Browser) with other file types handled by
external programs. Refer to *External programs* for more details.
If a folder is selected the contents of the folder and sub
directories are displayed graphically as an HTML page and any files
and folders can be selected using the mouse!
8.3 Reload
----------
Reloads the HTML page again. This function is useful (in a
multitasking environment) for editing HTML pages in an editor with
CAB running parallel to display the pages.
If the page originated from the WWW using *Reload* will fetch the page
from the WWW again -even if a copy is available in the cache.
8.4 Print
---------
If GDOS is available the document in the topped window can be output
as text. Bitmap fonts require matching screen and printer fonts
whereas vector fonts under NVDI 3.x or SpeedoGDOS are automatically
scaled as required.
In the dialog the margins can be set. These are in addition to any
offsets or margins attributable to either the printer or GDOS driver.
A popdown menu offers selection between any installed GDOS driver
including, so long as a suitable GDOS driver is available, GEM
Metafile (*.GEM) or bit image (*.IMG).
8.5 New window
--------------
Opens a new window displaying the contents of the previously topped
window.
8.6 Close window
----------------
Closes the window.
8.7 View source
---------------
Displays the source text of the displayed HTML document. Also refer
to the *External programs* menu option.
8.8 Quit
--------
Exits the program.
8.9 Home page
-------------
This menu option displays the home page, if available.
CAB tries to load the home page directly. Anyone who understands HTML
syntax can easily set any page as the home page and create a page to
reference other HTML documents. The file used as the home page can be
set in the *General options* dialog.
8.10 Back
---------
Displays the previous document.
8.11 Find keyword
-----------------
This allows the user to perform a search for keywords in HTML files,
and can optionally be case sensitive. The search can be conducted
over one of the following ranges of documents:
1. Current document only. The text is searched for in the current
document (the top window). If the text is found the window is
scrolled so the text is displayed at the top of the window.
2. Local HTML Documents. The text is searched for in all local HTML
documents contained in the paths specified in the *Paths* dialog
box (and their subdirectories). The files that contain the text
is made into a list of links in an HTML file called result.html.
At the moment the HTML files searched by method two are searched
purely as text, so hidden text such as comments, HTML commands,
links and so are also found. Processing the files to ignore
hidden text would be very time costly. This also means that
special characters such as accents and so on which are written
into HTML code using commands like ä are not found. This
shortcoming may be addressed in a future version.
Another tip: If you're searching for something which is often
used in HTML code as a command or URL-address placing a space
before it may make it less likely to turn up in commands or URL
addresses..
For example: Searching for the text 'WWW' often matches
subdirectories and addresses for pages in the form
'.../WWW/foo.html...'. Placing a space before it in the search
string, ' WWW' removes these occurences resulting in a better
targetted search. These don't apply to methods 1) and 3)!
3. In the c't-CDROM Database. This option is only useful for people
with the c't-CDROM (the 1994 (or 92/93) c't magazines in HTML
format)!
In this case the HTML files themselves aren't searched, but the
index file on the CD is accessed instead. So that HTML-Browser
knows where the files for this CD are kept are, you need to fill
in the appropriate section of the *Paths* dialog box - the HTML
documents (in \HTML which also contains the file DEFAULT.HTML)
and the index database (\UNIX\CT94.DAT or \UNIX\CT9293.DAT). As
in the previous method, matching documents are made into an HTML
document called results.html which is then opened.
8.12 Hotlist
------------
The hotlist is a list of your most used HTML documents. This list
enables you to get quickly to you favourite pages, without having to
navigate through a long series of pages to get there.
The hotlist is divided into themed areas. Using the popup at the top
of the dialog it's easy to switch between different themes.
*The 'Theme...' popup:*
*Change theme:* Changes the name of the current theme area. The
/Miscellaneous/ area cannot be renamed.
*New theme:* Creates a new theme area.
*Delete theme:* Delete the current theme area. The /Miscellaneous/ area
cannot be deleted. All remaining entries in a deleted theme area
are moved to the /Miscellaneous/ theme area.
*The 'New theme...' popup:*
Using this option a selected entry can be moved to another theme
area.
*The 'Document...' popup:*
*Delete entry:* Deletes the selected entry.
*Change entry:* Changes the selected entry. Annotations to the page
can also be made.
*Open document:* Opens a document.
*Add current doc:* Copies the current document to the Hotlist.
Double clicking on an entry opens the document.
The Hotlist is saved to disk as a normal HTML document which provides
an easy way for anyone not familiar with HTML syntax to create their
own home page.
8.13 Document -> Hotlist
------------------------
The current document is inserted in the Hotlist provided it's not
already listed. It will be filed away in the /Miscellaneous/ theme
area.
8.14 General options
--------------------
*Home page:* After launching CAB or by selecting the *Home page* menu
entry the specified HTML file will be displayed. Often it's
useful to create a home page containing references to frequently
used HTML pages. By default CAB attempts to load home.html as the
home page although any page can be set to be the home page
-simply enter the URL address. If the file is located in the
specified start directory for CAB.APP you can select the *Start
folder* button and using the *Search* button select the desired file
using the file selector.
*Popup menus:* CAB provides a row of popup menus to relieve the tedium
of navigating through HTML pages. Basic principle:
ù Left click on a reference to branch to the corresponding
page.
ù Right click on a reference to display the destination of the
reference.
ù Click on the window background (not on a reference) to
display further popup menus.
You can set which menu will be displayed using the left and right
mouse clicks (with and without holding down the [Shift] key). The
following popup menus are available:
*History:* Lists the previously displayed documents.
*References:* Lists the references in the current document.
*Menu:* Lists some menu items.
*Miscellaneous:* During loading, formatting and data transfer from the
Internet CAB displays a series of reports in a windowed dialog
(if the option *Dialog for Status messages* is active) otherwise
the window info line is used instead. The display in the window
info line has a couple of disadvantages. First a window may not
be open to display the information and secondly the dialog
displays the information more clearly. On the other hand using
the window info line allows a document in the window can be read
and scrolled while the text is still being formatted.
The *load index.html automatically* only has an affect on local
references (ie to files/directories on your drive) If the
reference points to a directory on a drive the contents will be
displayed unless a file index.html exists in which case this is
loaded instead. On use for index.html is to set up a page
containing an index of all your favourite documents.
8.15 Display
------------
In this dialog you can configure various display options for HTML
documents.
*Colours:* This section allows you to configure the display colours,
for the foreground text, the background colour and link colour.
If you're using less than 16 colours, the window background will
always be white regardless of the settings here. In 16 colour
mode, only the first nine colours should be used as the last 7
may be changed for pictures etc. In more than 16 colours, any of
the first 16 can be used as they will not be changed.
Some HTML documents include information about which colours
should be used for text, references and the window background.
The option *Use guidelines in document* tells CAB to use this
information (if available).
*Links:* Links can be displayed in underlined and/or bold text (this
is important for monochrome systems which can't distinguish links
by colour).
*Images:* Controls image display.
*Don't show* Prevents images being loaded and displayed which
speeds up page loading.
*Monochrome* Images are displayed in monochrome using dithering.
It's the quickest method but this obviously the quality
suffers.
*Greyscale* Images are displayed as greyscales. Higher quality
display at the expense of speed.
*Colour* Images are displayed in colour depending on the hardware
available:
ù 4-8 bitplanes (16-256 colours). Images are dithered if the
number of colours available is less than the number of
colours contained in the image. In 16 colour modes
greyscale display is often more suitable.
ù 15/16 bit Highcolor (32768/65536 colours) eg Falcon
Truecolor mode
ù 24 or 32 bit Truecolor (16.7 million colours)
*Text instead of images* The HTML language provides for text only
systems by allowing images to be accompanied by some text
which is displayed instead of the image. This enables WWW
Browsers which cannot display images to display text output
instead. If this option is active (crossed) only images for
which no alternative text is available are displayed as
images.
*Text width:* Text can either be formatted at a fixed width or
justified to fit the window width. Text justified to fit the
window width looks better but takes longer to display as the text
must be reformatted.
8.16 Font selection
-------------------
Wherever possible CAB (HTML-Browser) uses different fonts and point
sizes to display HTML files. Optimal output quality is provided using
vector fonts for which you'll need to install either NVDI v3.x or
SpeedoGDOS. Normal bitmap fonts can be used but they're not nearly as
nice.
Next you need to tell CAB (HTML-Browser) which (GDOS) fonts to use
for each corresponding style in an HTML document. Vector fonts as
provided by SpeedoGDOS or NVDI 3.x are recommended. You must specify
three fonts (sans-serif, serif and monospaced) in four different
styles (normal, bold, italic and bold and italic) making twelve
selections altogether.
For the bold and italic settings you should use a 'real' bold or
italic font wherever possible. If you don't have one available you'll
have to simulate these text effects using the corresponding buttons
adjacent to the font selection popup. If you're using vector fonts
then use the appropriate font from the font family, if available.
Some commands such as ...
, etc will cause
display format problems with /proportional/ fonts. To avoid these
problems only use *non-proportional* fonts for *preformatted* text.
The supplied INF file has the following presets (for NVDI 3.x):
*Headings:* Swiss 721 (normal, bold, italic, bold+italic)
*Normal text:* Dutch 801 (normal, bold, italic, bold+italic)
*Formatted:* Letter Gothic 12 Pitch (normal, bold, italic,
bold+italic)
If you don't like or haven't got these fonts, you'll have to select
alternatives.
The size of the body text can also be altered. Don't make this too
large or too small! Somewhere between 10 and 13 point is sensible (I
use 12 point).
If you haven't got access to vector fonts (i.e. you don't own a copy
of NVDI 3.x or SpeedoGDOS) then the point size won't change, but the
text can still be viewed using the system font, usually 10 point.
8.17 External viewers
---------------------
If a link in an HTML document points to a file which is not in HTML
format, an external viewer can be called. These programs can be
called in one of two ways and are configurable via the *External
programs...* dialog via the *Options* menu.
Individual file types can be assigned to different programs. File
extensions are entered into the *Files* field. Several extensions can
be entered using a comma to separate each entry.
Programs are selected by clicking on the selection box to the right
of the *Files* field which displays the file selector to select the
desired viewer.
Finally each entry includes a *Supports VA_START* checkbox which should
be crossed if the viewer understands the VA_START message so CAB can
send a VA_START message to the viewer so the file can be viewed with
re-launching the viewer.
The *Default* program (*.*) is called to display any files for which no
program has been assigned.
If one of more extensions have been defined without a program
assigned CAB attempts to display the file. This is only sensible for
*.gif, *.xbm, *.htm and ASCII files (for example: *.txt, *.doc, *.c,
*.pas, *.tex etc...) for which CAB (HTML-Browser) includes built-in
display routines. Using CAB (HTML-Browser) for these file types does
keep the number of external viewers needed to the minimum.
The current HTML page can be displayed as source text by selecting an
application in the *Source* entry. This application is called via the
menu entry *View source...*. If no application has been assigned the
*Default* program is called instead.
Double clicking on the *program path* boxes opens a further dialog with
an option to clear the current path.
Some suggested external programs:
*.text,txt: ST-Guide, 1st-Guide (or none, then HTML.APP is used)
*.mpeg,mpg,mpe: 1st-Guide (on a Falcon under Single TOS the fast DSP
MPEG player is recommeded)
*.jpeg,jpg,jpe: 1st-Guide, GEMview
*.tiff,tif: GEMview, Imagecopy
*.gif,xbm: GEMview, Imagecopy (or none, then HTML.APP is used)
*.dvi: DVI display included in TeX archives
*.* (Default): GEMview (or other program which handles as many
formats as possible)
*.html,htm: ST-Guide, 1st-Guide, (or and editor so the HTML
source can be edited)
8.18 Paths...
-------------
If you have a copy of the c't ROM '94 (or 92/93) (CD containing the
contents of the German magazine c't) then set the path for the field
c't CDROM.
In the *HTML folder* field set the directory which contains the file
DEFAULT.HTM on the CD (eg ?:\HTML\, where ? is replaced with the
drive letter of your CD-ROM drive). In the *Database* field set the
path to the contents of the CD (?:\UNIX\CT94.DAT (or
?:\UNIX\CT9293.DAT), again ? is the CD-ROM drive letter).
If you want to use CAB online to an Internet WWW site you should set
the *Cache folder* where all files downloaded from the Internet can be
stored. Ideally this folder should be on a Minix hard disk partition,
or other file system which supports long filenames to handle HTML
files because HTML files downloaded from WWW sites often include long
filenames which can easily result in duplication of filenames using
the basic TOS 8+3 character file system -and make sure the partition
has plenty of room!
In *HTML folders* you can enter the paths CAB (HTML-Browser) looks to
find HTML files.
HTML files contain absolute local paths (eg /path/file.html) which
can soon turn the root directory of your partition into choas. The
HTML folders help avoid this by telling HTML-Browser to look for HTML
files in the folders specified.
Here's an example:
*Entered HTML folders:*
ù F:\HTML.DOC\
ù G:\VARIOUS\
*Current drive:* F:\
*Path in HTML file:*
ù /example/text/index.html
*Where CAB looks:*
1. F:\example\text\index.html
2. F:\HTML.DOC\example\text\index.html
3. G:\VARIOUS\example\text\index.html
Double clicking on the *program path* boxes opens a further dialog with
an option to clear the current path.
8.19 Cache
----------
CAB (HTML-Browser) uses two caches to maximise the display of files.
The *Image cache* is used to avoid repeated unpacking and dithering
which both take a great deal of processing time. Images no longer
displayed are held in memory (RAM) in case they are needed again.
Naturally this takes memory so the maximum size of the cache can be
set in the *Maximum size* field. If the cache becomes full the least
used image is purged from the cache to free up more space. Using the
*Keep free* option it's also possible to set the minimim amount of
memory free for other applications. The cache can also be manually
purged using the *Free cache* button which can be useful to quickly
free up more memory for another application under a multitasking OS.
The cache remains empty until further images are displayed in CAB
(HTML-Browser).
*Attention*
The actual memory consumption for the Cache can be higher than
entered in the dialog.
The *Internet Cache* is used to store files downloaded from the
Internet on your disk to avoid repeatedly downloading the same files
from the Internet if they're viewed more than once. See also *Paths*
The *Maximum size* and *Keep free* options limit the amount of disk space
used by the cache and CAB (HTML-Browser) will purge the oldest files
from the cache to maintain the cache within the defined limits.
If the *Delete after 'quit'* option is active (crossed) the files in
the cache will be deleted on exiting CAB (HTML-Browser). Naturally
unless disk space is limited or you're sure you'll never need the
files again it's best to keep the files.
The *Free cache* button is for emergency use in case you need extra
disk space fast! Only files placed in the the cache directory placed
there by CAB (HTML-Browser) will be deleted.
8.20 Save options
-----------------
Save the current settings
9 Button bar
============
Each CAB window contains a button bar which provides an easy way to
access some of the more important functions:
*Back* Displays the previous document
*Home* Displays the home page
*URL* Select a document from a URL address
*File* Select a file using the file selector
*Source* Displays the source text of the currently displayed document
*New* Reloads the current document again
*Hotlist* Displays the hotlist dialog
If a 'sad' smiley appears to the right of the buttons it means the
displayed document is faulty in some way. Click on to the smiley to
display detailed error information. This is a particularly useful
option for anyone using CAB to author HTML pages. Only errors which
CAB can determine without wasting disk space or processing time will
be reported.
Faulty documents are not neccessarily displayed incorrectly in CAB
but may well exhibit display problems in other browsers (e.g. Mosaic,
Netscape, WebExplorer etc) may not display the document as you
intended.
10 Thanks
=========
I'd like to thank everyone who through their praise, criticism,
suggestions and bug reports have helped in the development of CAB
(HTML-Browser). In particular the following people deserve a mention:
ù Stefan Becker
ù Ben Bell
ù Stephane Boisson
ù Joe Connor
ù Dieter Fiebelkorn
ù Stefan Haake
ù Romuald Jouffrey
ù Ulrich Kaiser
ù Tim Newsome
ù Fred Nicklisch
ù Jeff Wisniewski
ù Manfred Ssykor
11 Possible future updates
==========================
ù Further implementation of HTML3 commands
ù Image loading (Double click on [IMG] text)
ù ...
Please feel free to make further suggestions and constructive
criticisms...
12 History
==========
*V0.8ž (20.04.1995)*
ù First release version
*V0.9ž (15.05.1995)*
ù Reduced memory requirements
ù MTOS Drag&Drop (ARGS) supported
ù External programs will now run under single TOS
ù Error reports are now more descriptive
ù Bugfix: when running as an accessory no longer tries to
invert (non-existant) menu items
ù The .INF file is now found even if HTML is not started in it
own directory
ù Is now a lot more tolerant of buggy HTML file syntax.
ù home.html is now loaded on startup if possible
ù Hotlist
ù Configuration of window and text colours etc.
ù Search (including searching c't CDROM)
ù In-line images can be displayed as greyscales
*V0.93ž (07.06.1995)*
ù Preparation for on-line operation implemented (although not
activated in this version)
ù Bugfix: Problem with line spacing fixed
ù Bugfix: Endless loop with defective gifs fixed
ù Bugfix: fclose() for Hotlist was forgotton :-(
ù A few other minor bugfixes
*V0.94ž (07.07.1995)*
ù Bugfix: Deleting the last Hotlist entry caused a crash :-(
ù Bugfix: CR/LF inside tags led to problems
ù Bugfix: Last word in an HTML file gobbled
ù Documents access using absolute path information, including
directories listed in the 'Paths...' dialog
ù Contents of a drive can be displayed as an HTML document
(including launching programs and viewing files)!
ù Support for the special Netscape tags
*V0.95ž (04.08.1995)*
ù Inline colour images
ù Configurable image cache (in RAM)
ù Configurable WWW cache (on disk)
ù Option to automatically format text to the window width
ù ASCII, xbm and gif files can now be viewed directly in HTML-
Browser. Calling external programs is no longer required (but
naturally still available as an option)
ù Interface for 'Internet module' implemented Using a suitable
module HTML-Browser could be used to display WWW pages on-
line to the Internet, naturally you'd need an Internet
account to do this!
ù Support for xbm images
*V0.96ž (22.08.1995)*
ù Lots of minor bugfixes
*V0.98ž (03.10.1995)*
ù In colour resolutions with fewer than 16 colours the colour
palette is no longer altered
ù Zero length files should no longer cause problems
ù The program is now called:
CAB - The Taxi to the information highway!
CAB = Crystal Atari Browser
*V1.0 (01.11.1995)*
ù Minor adjustments to accomodate the 3D look under Geneva
release 4 (unfortunately Geneva is not entirely MultiTOS
compatible)
ù Multiple open windows may be opened
ù Each window may individually configured with its own colour
and font
ù Support for the following Netscape tags (commands):
-
-
-
-
-
ù Support for the