CAB (HTML-Browser) for Atari ST/TT/Falcon/Medusa/Eagle/MagicMAC
---------------------------------------------------------------------
Version: 0.98ž (September 1995)
CAB - taxi to the information highway
CAB - Crystal Atari 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) sites requires a separate module.
Distribution
------------
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.
A glance at the version number should tell you this program is still at
an early stage of development so 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!
My address:
Alexander Clauss
Stresemannstr. 44
D-64297 Darmstadt
Germany
UK support:
Joe Connor
65 Mill Road
Colchester
CO4 5LJ
England
USA support:
Jeff Wisniewski
P.O. Box 1243
Newtown, PA 18940-0871
USA
Email contacts:
Author: Alexander Clauss: aclauss@rbg.informatik.th-darmstadt.de
UK support: Joe Connor: jconnor@cix.compulink.co.uk
USA support: Jeff Wisniewski: jeffrey.wisniewski@microserve.com
Original translation: Ben Bell: bjb@bigbox.demon.co.uk
Installation
============
The CAB distribution is supplied ready to run once unarchived onto
your working disk. To take advantage of the creature comforts offered
by CAB (HTML-Browser) follow the steps below to set up your working
environment.
CAB (HTML-Browser) can be used as either a desktop accessory or a normal
GEM application. To install as a desktop accessory rename CAB.APP to
CAB.ACC and place it and CAB.RSC in the root directory of your boot
drive.
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.
1) Install fonts (Dialog: Options/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.
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.
2) External viewers (Dialog: Options/External programs)
--------------------------------------------------------
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 'Source text...'. If no application has been assigned the
'DEFAULT' program is called instead.
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)
3) Paths (Dialog: Options/Paths...)
----------------------------------
If you have a copy of the c't ROM '94 (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, 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
4) Cache (Dialog: Options/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).
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.
5) Display (Dialog: Options/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.
Links:
Links can be displayed in underlined and/or bold text (this is
important for monochrome systems who 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-high-colour (32768/65536 colours) eg Falcon True color
mode
- 24 or 32 bit-true-colour (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.
6) Internet module
------------------
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.
Installation is now complete, now is a good time to save your setup
(Options/Save options).
Using CAB (HTML-Browser)
------------------------
All the functions of the program that are controlled by the menu bar
can also be accessed by a popup menu. This menu is brought up by
clicking the left mouse button on the viewer window (not on a link).
This is essential for desk accessories which can't install their own
menu bars.
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.
Home Page (Menu entry: Navigate/Home page)
------------------------------------------
This menu item will display the standard home page, home.html
On starting CAB (HTML-Browser) it tries to load the file 'home.html' (i.e.
'home.HTM' on TOS file system). Any HTML format file could be set up as
your home page and its contents could be set up to point at other HTML
documents as required.
Find keyword... (Menu entry: Navigate/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 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). As in the previous method, matching
documents are made into an HTML document called results.html which is
then opened.
Hotlist (Menu entry: Navigate/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. To place a page
in the hotlist, select 'Document -> Hotlist'.
Selecting 'Hotlist' displays a dialog containing the page hotlist. The
button "Add" adds the current page to the hotlist. Double click on an
entry or select it then press 'Open' opens the selected page.
'Delete' removes the page from the hotlist, and 'Change' allows the
page title to be edited and view the filename of the page it points to.
Selecting an HTML document
==========================
The 'Open HTML document' 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!
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.
Technical
=========
CAB (HTML-Browser) understands most of the HTML2 specification. Currently
the form and entry functions are not implemented.
Transparent colour images are displayed, where available.
Multi-user installation:
If the environmental variable $HOME exists the specified path is
searched for the configuration files i.e. the Hotlist and home.html.
If $HOME isn't set, or the files are not available in the $HOME path
shel_find() is used to locate the files.
CAB.OVL Module for on-line Internet access
-------------------------------------------
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 provided as commented C code and
uncommented Pascal source in the 'module' folder in this distribution.
I would be pleased if anyone who programs an on-line module would let
me have a copy for inclusion with CAB (HTML-Browser)...
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 follwoing people deserve a mention:
Ben Bell
Stephane Boisson
Joe Connor
Dieter Fiebelkorn
Tim Newsome
Fred Nicklisch
Jeff Wisniewski
Possible future updates
-----------------------
-Support for the HTML3 specification (tables, forumlae, etc.)
-Better font setup and handling of bitmap fonts
Please feel free to make further suggestions and constructive
criticisms...
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 singleTOS
-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
EOF