Ares is a hypertext authoring system, distributed by UserWare. After reviewing this how-to guide, you might want to print out the quick reference card. Just enter QCARD from any DOS command prompt (C>). 4
Authoring an Ares hypertext is a two-step process: g
(1) Create a hypertext script using any text
editor. The script must be in Borland's HelpFile format. 1
(2) Compile your script with the Help
Compiler. >
You can then launch Ares and view your hypertext by entering
ARES myfile
from any DOS command prompt (C>).
If you are a registered user, your hypertext is then ready to distribute. By registering with UserWare, you will be granted an unlimited license to distribute ARES.EXE and ARES.RCS with your hypertexts.
Hypertext
A hypertext allows automatic access to cross-referenced material, usually by selection of a highlighted word or phrase.
Text Editors
If your word processing program doesn't save text to ASCII easily, and you don't already have a text editor, here are some packages worth your consideration. Note that the Microstar package is included as part of your Ares registration.
Galaxy. (nka Nova) A fast, RAM-based text editor distributed by OmniVerse, PO Box 2974, Renton WA 98056-0961, 206 228-7627; 24 Hour BBS: (206) 235-8760. Available as shareware thru most major libraries.
PC-Write. A very popular, mostly ASCII, word processor distributed by Quicksoft, 219 First Ave N #224, Seattle WA 98109. Available as shareware thru most major libraries.
Microstar. Microstar is a simple but powerful text editor bundled with the registered version of Ares. Microstar was created by Borland International, and licensed for use by UserWare.
QEdit. QEdit is a powerful text editor distributed by SemWare of 730 Elk Cove Ct, Kennesa GA 30144, 404 428-6416. Available as shareware thru most major libraries.
WP Editor. The text editor of choice for anyone used to the WordPerfect keyset. Available separately or as part of the WP Office package. WordPerfect Corporation, 1555 N Technology Way, Orem Utah 85057-9971.
See Also
HelpFile
UserWare Help Compiler
The script for your hypertext can be written with any text
editor. Many word processing programs support saving or exporting a document as a plain ASCII (or DOS) text file. U
Once you have installed Ares and UWHC, you can then launch the compiler by entering
UWHC myfile.txt
at any DOS command prompt (C>). Of course, you should substitute the name of your script for "myfile.txt". j
UWHC will then produce a hypertext, and give it the same name as your script, but with a .HLP extension.
Currently, UWHC supports the Borland HelpFile format. Support for other formats, like setext and Dart WYSIWYG, is under development.
See Also
Distribution
Registration
ASCII
American Standard Code for Information Interchange: the linga franca of computerdom.
Press (BackSpace) to return.
HelpFile Format
Borland International is a leading software vendor that distributes a number of popular programming tools. Borland's HelpFile format was designed for programs that support context-sensitive help. Once written, the HelpFile script is processed by a compiler, like UWHC. The format for the script very simple.
Each topic is given a name (i.e. HelpFile). The text following the topic name is put into the help file. Since some of the lines may contain cross-references, the script will need to be wrapped to fit nicely in the text window. If a line of text is flush left with no preceding white space, the line will be wrapped. All adjacent wrappable lines are wrapped as a paragraph. If a line begins with a space it will not be wrapped. For example, the following is the help script for the beginning of this topic: t
|.TOPIC HelpFile
| HelpFile Format
|Borland International is a leading software vendor that
The "HelpFile Format" will not be wrapped with the "
" line since they both begin with a space, but the "Borland International .." line will be wrapped. $
The syntax for a ".TOPIC" line is:
.TOPIC name[, name][..]
This just means that you can have one or more topic names, separated by commas. Also, the names cannot contain spaces.
Cross-references can be placed within the text so that the reader can quickly flip to related topics. There are two ways of formatting a cross-reference:
{HelpFile}
If the cross-reference is the same as the topic's name, or
{help script:Helpfile}
if you want to display something other than the topic's name.
If you need to use braces in your text, you can insert a pair of opening braces, like this: {{put this text in braces}. This is how we were able to display these instructions without making the examples cross references. i
If you would like to insert comment lines in your script, simply begin each line with a semi-colon (;).
See Also
Help
Compiler
Registration
If you have the complete Ares test
drive, you will find a file called REGISTER.FRM. If so, use the REGISTER.BAT file to print it, and mail the completed form to UserWare with your payment. 5
Otherwise, send $30 with your name and address to UserWare, Attn Ares Registration, 4 Falcon Ln E, Fairport NY 14450-3312. (New York State residents: include the name of your county and local sales tax. International orders: add $4 for shipping; Travelers checks or US funds drawn on a US bank only please.)
In return, you will be entitled to distribute ARES.EXE and ARES.RCS with your hypertexts. There are -no- additional royalties or runtime fees beyond the $30 registration; regardless of the number of copies you distribute or the price you charge. z
Distribution licenses are assigned to individual or joint copyright holders. You may not use your license to distribute Ares with another person's hypertext: YOU must own the copyright. Persons distributing hypertexts both under individual and joint copyrights should obtain additional licenses. A license is not required to distribute Ares with "public-domain" hypertexts.
Please note, that Ares may be used to distribute shareware hypertexts. Do not confuse registering a hypertext distributed with Ares with registering Ares itself.
See Also
Distribution
Distribution
This topic deals with preparing your hypertext for distribution. For information on your distribution rights, see Registration.
We want you to use Ares to distribute your hypertext, so there are no hard-and-fast packaging requirements. If it works, you're doing it right. V
But to be helpful, here are some hints and guidelines that you might want to follow. ?
Files needed for distribution
When distributing your text with Ares, it is necessary to include only the Ares.EXE and Ares.RCS files. If you are packaging your text for mass distribution, you might also want to include a FILE_ID.DIZ, GO.BAT, PACKING.LST, and REGISTER.FRM file with your text. These are "convenience" files, though, and not required by the Ares system.
FILE_ID.DIZ
This is a specially formatted text file that can be used by many bulletin board systems to provide a description of your text. It can be up to ten lines long, with up to 45 characters on each line. It should simply be a short, catalog-type description of your hypertext.
REGISTER.FRM
If your text is shareware, you will of course want to include a registration form. Feel free to crib our "mailer" format, if you like.
GO.BAT
Generally, it's a good idea to include a "MYTEXT.BAT" or "GO.BAT" file with your text, which would load the Ares program together with your hypertext. For example:
REM MYTEXT -- COPYRIGHT 1994 IMA AUTHOR
ECHO "LOADING VIEWING SOFTWARE .."
ARES MYTEXT
ECHO "THANK YOU FOR VIEWING MYTEXT"
Or, if your readers will be using DOS 3.0 or better, you can rename Ares.EXE and Ares.RCS to MyText.EXE and MyText.RCS. This will cause Ares to automatically load MyText.HLP when launched. Of course, you can use any name you want in place of "MyText".
PACKING.LST
It is also a good idea to provide a directory of the files that are supposed to be on your distribution disk. For example, a file named PACKING.LST might read:
FILE_ID.DIZ -- program description.
PACKING.LST -- this file.
ARES.EXE -- program file used to view text.
ARES.RCS -- program utility file.
MYTEXT.HLP -- hypertext file.
REGISTER.FRM -- registration information.
GO.BAT -- run to launch hypertext.
An easy way to do this is to "pipe" the DOS DIR list to a file, and then edit the output with a text
editor:
DIR *.*>PACKING.LST
Note the use of the (>) character, which tells DOS to send the output of the DIR command to a disk file.
See Also
Registration
Shareware
Shareware is a marketing arrangement whereby people write software that can be freely copied and "shared" among interested parties. People who choose to use the software regularly may then register directly with the author. Shareware authors offer various benefits for registration, including telephone support, program updates, printed manuals, and newsletters.
The Association of Shareware Professionals (ASP) is an organization serving shareware authors, users, and libraries. ASP provides guidelines for authors and libraries, and support intervention should a user have difficulty dealing with an author. X
The documentation of all ASP members must include the following "Ombudsman statement": C
"(Member's Name) is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send a Compuserve message via Compuserve Mail to ASP Ombudsman 70007,3536"
UserWare, the creator of Ares, is not, at this time, a member of ASP, but we do consider ourselves ASP compliant. To receive a complimentary Ares test drive, contact UserWare. C
The hypertexts distributed with Ares may or may not be shareware.
Questions
?> How does Ares find the "Contents" page?
-> Ares considers the first topic in a hypertext to be the Table of Contents. You can format this page any way you please. Ares will display this page first, and readers will always return here when they press (Alt)+(C). ?
?> Does Ares let me search topics for a given word or phrase?
-> A number of features, including Search, Print, and View History, and under development for a future release. Your support will help make future releases possible. ;
?> How did you put those graphic lines into your scripts?
-> Most editors will let you type any character from the IBM character set by holding down the (Alt) key, entering the character's number using the numeric keypad, and releasing the (Alt) key.
The horizontal line is #196. To input this into your text, hold down the (Alt) key, press 1 9 6 on your numeric keypad, and release the (Alt) key.
Note that you -must- use the keypad on the right side of your keyboard. This will not work with the number keys along the top of your keyboard. W
?> How do I use a brace in my file without it being mistaken for a cross-reference. ,
-> Type two braces together, like this {{. Q
?> The compiler keeps telling me that a topic is undefined, but it is defined. 4
-> The HelpFile format was designed for use with programming languages, and so only allows a limited set of characters in topic names. Your topic name must only use alphanumeric characters, with no spaces or symbols. This, and typographic errors, are the most common reason for the "undefined" warning. l
?> My script used a different line length than the text window, and the compiler rewrapped all the lines.
-> Ares uses a standard 65-character text window. The Borland HelpFile format is wrappable, and Ares wraps the text to fit into this window. To keep a line from wrapping, type a space as the first character. m
?> My text editor can only handle shorter files, but I would like to use Ares to distribute a larger file. d
-> The DOS COPY command can be used to concatenate (paste) several files together. The syntax is ,
COPY source1+source2[..][+source#] target
This will take several small "source" files and paste them into one large file. If you name your source files something like mytext.001, mytext.002, et cetera, you can also use the copy command this way:
COPY mytext.*,, mybook.txt
The trick is the double-commas. Also, it works better if you use a different filename for your script. Here, we used myBOOK instead of myTEXT. Of course, you can use any names you choose. D
?> The highlighting doesn't work well on my (my reader's) monitor.
-> Some "greyscale" monitors operate in "color" mode, which causes Ares to mis-detect the monitor type. To correct this, execute the command
MODE BW80
from any DOS command prompt (C>).
?> I want to distribute my hypertext (to retail stores, over a large network, on a CD). Will I need to make special arrangements?
-> No. The single registration fee is good for as many hypertexts as a copyright holder cares to distribute. The number of copies, or the price charged, is not material. k
The only proviso is that each copyright holder, or copyright partnership, should have their own license.
Warranty
Users of Ares must accept this disclaimer of warranty: B
"The Ares software program is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of this software."
UserWare is not responsible for the content of any files viewed with Ares, except those authored by UserWare received directly by you from UserWare. }
Hypertexts distributed with Ares are subject to the terms, conditions, and warranties provided by their respective authors.
UserWare
UserWare was founded in 1988 by its proprietor, Ted Husted. Ted spends 8 to 12 hours a week on UserWare activities, including order fulfillment, bookkeeping, end-user support, research, development, and, of course, debugging.
The rest of Ted's busy work-week is spent as System Administrator for a Rochester NY law firm specializing in commercial collections. t
Ted, who turns 35 this year, is also blessed with a lovely wife, Barbara, and an aggressive three year-old, Jacob.
Ares is UserWare's third shareware program, of what may be a suite of (at least) four, each designed to fill the needs of a different brand of user.
Prior to 1992, UserWare sold over 300 copies of its Iris/Prism software, and another 400 copies in 1992. By the end of 1994, we hope to have a thousand registered users. B
For more information, contact UserWare via any of these methods:
Service Address
CompuServe 71540,3660
Facsimile 716 262-5185
Genie T.HUSTED
Internet 71540.3660@cis.com
Telephone 716 425-3463
Mail 4 FALCON LN E, FAIRPORT NY 14450-3312 USA
If you did not receive the complete Ares test drive, feel free to request a complimentary copy. Please specify preferred disk size.
(.txt)