home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frostbyte's 1980s DOS Shareware Collection
/
floppyshareware.zip
/
floppyshareware
/
GLEN
/
PHELP101.ZIP
/
MANUAL.DOC
< prev
next >
Wrap
Text File
|
1989-12-21
|
46KB
|
1,916 lines
THE PINNACLE HELP SYSTEM
"The Finishing Touch"
Programmer's Manual
First Edition
P I N N A C L E S O F T W A R E
P.O. Box 386, Town of Mount Royal
Montreal, Quebec, Canada H3P 3C6
(514) 345-9578
NOTICES
This software product is provided "as is" with no guarantees or warranties
express or implied. Pinnacle Software and its assigns and subcontractors
accept no liability for the use of or inability to use this product, or any
damages attributable thereto.
This software product is distributed as "shareware". You may try the program
out at no charge and distribute complete and unaltered copies for evaluation
or use by others. If you are still using it after 30 days, you must pay a
licensing fee. The HELPME program itself will provide you with details.
The Pinnacle Help System is Copyright (C) 1989 by Pinnacle Software.
This manual refers to The Pinnacle Help System as HELPME. This convention
must not be construed to lay claim to unique or exclusive use of the name
HELPME. Reference to The Pinnacle Help System in any publication must not
state or imply otherwise.
HELPME was written in Turbo Pascal Version 4, which is a marvelous language
product trademarked by Borland International, 4585 Scotts Valley Drive,
Scotts Valley, California, USA 95066. HELPME makes use of an outstanding
programming toolkit named Technojock's Turbo Toolkit Version 4.0. It is
copyrighted by TechnoJock Software Inc. and is available via shareware.
Audience
This manual is written for programmers and software developers.
Upgrades and Support
Registered users of this product will be informed of new releases, major
bugs, etc. In the past, it has been the policy of Pinnacle Software to offer
upgrades at reduced prices.
ii
TABLE OF CONTENTS
NOTICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
Audience
Upgrades and Support
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
What is HELPME?
Why HELPME was Created
Who Needs HELPME?
Installing HELPME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Sample HELPME;
Space-Saving Tip
The Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Overview
F1 Copyright
F2 Introduction
F3 User manual
F4 Setup and configuration
F5 Registration information
F6 Registration
F7 Customer comment form
F8 Changes to this version
F9 Files
The HLP File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Line 1 -- Product Name
Line 2 -- Version Number
Line 3 -- Purpose of product
Line 4 -- Command-line parameter
Line 5 -- Viewer DIR mask
Line 6 -- Start-Up
Line 7 -- Introduction
Line 8 -- Manual
Line 9 -- Configuration
Line 10 - Customer Comment Form
Line 11 - Registration Info
Line 12 - Registration Program
Line 13 - Exit
14 - 16 - Packager Data
Line 17 - Changes This Version
ii
PDC Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
What is a PDC File?
Why Use a PDC File?
Advantages for the Programmer;
Advantages for the User;
The Use of Colour
Support for Different Displays
Basic PDC Design
Control Code Format;
PDC File Format;
Sample PDC File
PDC Files for Display
The Customer Comment Form
PDC Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Next and Future Versions . . . . . . . . . . . . . . . . . . . . . . . . 20
Towards a Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Looking for Standards
A Packaging Standard?
Other Pinnacle Products . . . . . . . . . . . . . . . . . . . . . . . . . 24
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1
Introduction
What is HELPME?
The Pinnacle Help System equips the software developer with a method of
providing new users with the information they need to get started.
The Pinnacle Help System is based upon a single program, named HELPME, which
can instruct, inform and assist the user in the following general areas:
Copyright information
Product overview ("What does this program do?")
Detailed user manual or (for simpler programs) general usage guide
Hardware and software prerequisites
Configuration
Registration and warranty provisions
Program registration (for shareware programs)
Correspondance and commentary by mail
Files directory
File viewing and printing
Why HELPME was Created
In the vast majority of software products, "first glance" assistance is not
provided in a convenient manner. With standard commercial packaging, the
user may have to shuffle through several manuals, inserts, blow-ins, response
cards and diskettes to find the answers to fundamental questions. In the
case of shareware, the user is expected to have an intuitive feel for the
operating system and the file-naming conventions that have evolved around the
shareware market.
Some shareware distributors have pioneered the idea of using the power of the
computer to organize "first-timer" information. The solution has generally
involved a batch file which calls up Vernon Buerg's excellent LIST program.
Such efforts have made life easier for the user. HELPME takes the concept
further by simplifying and organizing.
HELPME is easy for the user. The user interface is uncomplicated.
HELPME is easy for the programmer. The software developer can design a
useful, attractive "front-end" to his or her product, with an extremely low
investment of effort.
2
Who Needs HELPME?
If your software product is not completely self-contained and self-
explanatory, you should consider including HELPME in the package.
If your software product is extremely complex, or has amazing capabilities
that can only be fathomed after months of use, then HELPME can prepare the
user in a friendly manner.
If you distribute your software via the shareware method, then HELPME can
make your product more dynamic and appealing, while addressing the special
needs of people who have only recently begun investigating shareware.
Companies that distribute software "in-house" should consider using HELPME as
a method of introducing their users to new programs.
3
Installing HELPME
The HELPME program is completely self-contained in the HELPME.EXE file. Its
functions are defined by the .HLP file. When including HELPME with your
software (see "NOTICES" for licensing details), all you need to include are
the EXE and HLP files, plus any relevant support files you may have written.
Sample HELPME
For an sample implementation of HELPME, create a directory named HELPME and
install the original HELPME package there. This will demonstrate most of the
techniques provided by The Pinnacle Help System.
Space-Saving Tip
To save disk space, you may also wish to put HELPME.EXE in one of your PATH
directories. (For an explanation of PATH, see your DOS manual.) This way,
all you'll need in each directory are the .HLP file and any support files
that you write. However, if you do this, make sure that your final packaging
notes remind you to include HELPME.EXE in the final disk or archive file!
4
The Main Menu
Overview
When somebody starts up your HELPME, he or she sees an introductory screen
(if you created one), followed by this menu:
F1 Copyright
F2 Introduction
F3 User manual
F4 Setup and configuration
F5 Registration information
F6 Registration
F7 Customer comment form
F8 Changes to this version
F9 Files
Apart from the F1 and F9 options -- which always appear -- the user will see
only those options that you have installed.
We will now discuss each of the menu options in detail.
F1 Copyright
This identifies the product, holder of the copyright, mailing address and
phone number.
Some protection has been built into the program to ensure that some
enterprising programmer does not remove the F1 selection or alter the name
and address.
F2 Introduction
The Introduction takes the place of the "READ.ME" file used by many shareware
products. It answers the question, "What does this product do?"
The Introduction should be very short -- perhaps only one screen in length.
Its purpose is to orient the user and give him or her a basic framework for
interpreting what will be taught in the user manual.
5
The Introduction may use a program, text or PDC file. See the chapter
entitled "The HLP File" for details.
F3 User manual
F3 enables the user to browse or print the manual-on-disk, which provides the
user with detailed instructions for using your product.
In most cases, the manual-on-disk will be a standard text file. To
accomodate the vast majority of printers, it should be 80 columns or less and
use no special control codes except for Form Feed (ASCII 12, Hex 0C). All
Word Processing programs have a provision for outputting a document to a text
file.
F3 may invoke a program, text or PDC file. See "The HLP File" for more
information about this flexible technique.
F4 Setup and configuration
This option is used to define hardware and software resources to your
program. In most cases, the F4 key will run a separate program written by
the developer. (Writing configuration programs is a dull and thankless
chore, so Pinnacle Software is now designing a product named The Pinnacle
Configurator, which will enable you to create a configuration program in
minutes.)
Just like selections F2 to F8, F4 is optional. So if your main program has
its own configuration section, you can omit it from HELPME, or have HELPME
call a text or PDC file informing the user of this.
F5 Registration information
Selection F5 covers legal and some marketing information. In this section
you can can place:
- Disclaimers and limitations of liability
- Customer support line phone numbers
- Details for registering shareware
- Product distribution provisions
- Information about discounts for customers
You may use a text or PDC file. See "The HLP File" for details.
6
F6 Registration
Selection F6 will be used only by shareware developers. It will run a
program to register a product. The registration process may stamp a serial
number, or remove an opening screen, or enable some features.
You will write the actual unlocking program, which obviously must include
some programmatic trickery to confound efforts to "crack" it by industrious
hackers.
Just like selections F2 to F8, F6 is optional. If you do not have a
registration program, it will not appear on the menu.
F7 Customer comment form
This is one of the most convenient features of HELPME. It takes the user
through a questionnaire that you design, then prints out the result, along
with a mailing envelope that can be assembled with tape or staples.
This feature encourages your users to write to you with comments. In this
age of telephones, many people strongly dislike spending the time it takes to
send a letter. HELPME makes it more likely they will write to you by greatly
reducing the effort involved.
Selection F7 can invoke a program, text or PDC file. In most cases, it's
best to use a PDC file, as this enables you to create the questionnaire in
only a few minutes. For more information, see the chapter entitled "PDC
Files".
F8 Changes to this version
This displays a list of enhancements for this version of the program.
You may decide to list the enhancements for the last few versions, instead of
simply comparing this version with the last one. Remember that some people
may not have seen the last version. Perhaps they have the version before
that, or an even older version.
If it's not too unwieldy, you should list all the enhancements right back to
Version 1. This will be helpful to everybody who has ever used your product
before, and it will trace the evolution of your product -- many people may
find this interesting.
7
F9 Files
The Files function displays the current directory and lets the user select a
file using the arrow and Enter keys. The selected file is then displayed by
the HELPME File Viewer, which provides full browsing with:
- Up-arrow and down-arrow
- PgUp and PgDn
- Find and Find Again
- Print file
- Jump-to-line-number
8
The HLP File
The HELPME.EXE program finds out what to do by inspecting the HLP file. The
HLP file is a file with a .HLP extension.
If there is more than one HLP file in a directory, the user is instructed to
select one. In most cases, this won't happen, because each product will
occupy one disk or directory and have only one HLP file. But if the user
does install several products into one directory, this won't cause any
problems. No confusion will arise if you name your HLP file according to
your product name. For example, if your product is named WHIZBANG, you
should create a WHIZBANG.HLP file.
The HLP file is a standard text file, created with a text editor such as
EDLIN, a programmer's editor, or a Word Processor in non-document mode.
Each line in the HLP file must start in column one. Any text after column 40
is ignored and may be used for comments.
The format of the HLP file is as follows:
LINE EXAMPLE DESCRIPTION
1 The WhizBang System Product Name
2 2.00 Version Number
3 Whizzing & Banging Purpose of product
4 /HELP Command-line parameter
5 *.* Viewer directory mark
6 WHIZSTRT Start-up pgm pdc txt
7 WHIZINTR Intro pgm pdc txt
8 WHIZMANU Manual pgm pdc txt
9 WHIZCONF Config pgm pdc txt
10 WHIZCCFM Comment pgm pdc txt
11 WHIZRINF Register pdc txt
12 WHIZRPGM Register pgm
13 WHIZEXIT Exit pgm pdc txt
14 Packager Data #1
15 Packager Data #2
16 Packager Data #3
17 WHIZCHG Changes pgm pdc txt
For another example, see the HELPME.HLP file included in the standard HELPME
package.
Items described as "pgm pdc txt" can invoke a program or display a PDC or
text file. (PDC stands for Pinnacle Display Codes -- see "PDC Files" for
details.) The name given in the file is used as a root name. If a file in
the current directory has the same root name, it might get used.
9
We say it "might" get used because only certain extensions are considered
valid. These are: EXE COM PDC TXT DOC ME. Thus, a file named WHIZEXIT.COM
would be used, but not a file named WHIZEXIT.DAT.
Here is another example. Line 6 of the HLP file defines what will be done
when HELPME is started. It can run a program, or display a PDC file or a
text file. Let us say that line 6 of the HLP file specified WHIZ. In such
case, HELPME would check the directory and behave in the following manner:
FILES FOUND IN THE DIRECTORY TYPE OF FILES WHAT IS DONE
WHIZ.EXE WHIZ.COM Program files The programs are run
WHIZ.PDC PDC files The files are displayed
WHIZ.TXT WHIZ.DOC WHIZ.ME Text files The files are displayed
When you specify a root name in the HLP file, it doesn't matter if the file
is a program or a PDC file or a text file; HELPME behaves appropriately. If
it can find a program, it will run it. If it can find a PDC file or a text
file, it will display it.
We will now discuss the HLP lines in detail.
Line 1 -- Product Name
This is the proper name of your product. This shouldn't be confused with the
program name of your product. For example, your product may be named "The
Chocolate Space Warp", while the program is named CSW.EXE. In such case, you
should place the full name ("Chocolate Space Warp") here.
Line 2 -- Version Number
You have up to 40 characters to specify your version number. Most version
numbers look something like this:
1.00
2.32A
Summer '89
Beta-Test 5.3
10
Line 3 -- Purpose of product
This item is not used in Version 1.00 of HELPME, but will be used in Version
2. Describe your product here, in 40 characters or less. Some samples:
Word Processing
Software Packaging
Programming Language
Shoot-'Em-Up Game
Line 4 -- Command-line parameter
When HELPME calls a pgm (COM or EXE) file, it can add a command-line
parameter. Thus, the program can find out if it was called from HELPME or
from DOS.
A command-line parameter is some additional information that is usually
passed on the DOS command line. For example, if you type the DOS command DIR
you will get a full directory listing. But if you type DIR *.TXT, you are
using a command-line parameter to specify that you only want to see files
with a TXT extension.
Thus, if you have a program which is supposed to be accessed via HELPME, such
as a configuration program, and you want to be sure that it is run only by
users who have been well-informed, your program can check for the command-
line parameter and if it is missing, advise the user to run HELPME.
In other words, the command-line parameter can be used to ensure that certain
programs can be accessed ONLY through HELPME.
The command-line parameters also report what HELPME knows about the display.
So if your HLP file specified a command-line parameter of /HELP there would
be two possible ways that the program is called:
/C /HELP This means the display can show colour
/M /HELP This means the display can't show colour (monochrome)
Line 5 -- Viewer DIR mask
This controls which files will be seen when the user presses F9 (Files) at
the main menu of HELPME.
In most cases, you can use *.* which means "display all files".
However, if you expect your users to be very inexperienced, it might be wise
to restrict their ability to view files. With a mask of *.* the user can
11
change directories and get lost, or view program files and become bewildered.
Line 6 -- Start-Up
This names the file which is used when HELPME starts up. It might be a
program that animates an attractive logo, or it might be a PDC or text file
that simply says hello to the new user. If you leave the line blank, or
specify a nonexistent file, nothing will be done.
Line 7 -- Introduction
This names the file which gives the product overview. A common choice is
READ, in which case the following files could be used:
READ.EXE READ.COM READ.PDC READ.TXT READ.DOC
and above all
READ.ME
Traditionally among shareware developers, the READ.ME file introduces the
user to the product.
Nevertheless, it is advisable to use a different file for the Introduction.
Your READ.ME file (if you decide to include one) should start off by saying
something like, "For help with this product, enter the HELPME command".
Line 8 -- Manual
This identifies the file that contains the user manual. In most cases, this
will be a text file, such as MANUAL.TXT or MANUAL.DOC. But if your product
is very easy to use, you may decide to use a PDC file. And if your product
already has a a highly sophisticated, program-driven help system, you may
decide to invoke the program itself.
In any case, this is another item that is only concerned with the root name.
It doesn't matter if it is a program or PDC or text file; HELPME will do
whatever is necessary.
Line 9 -- Configuration
This specifies the root name of the configuration program, or a PDC or text
file that describes hardware and software requirements. Just as with all
12
root names in the HLP file, if you do not have anything for this selection,
simply leave the line blank and it will not appear on the main menu.
Line 10 - Customer Comment Form
This names the program, PDC or text file for the Customer Comment Form. In
most cases, you'll use a PDC file. See the chapter entitled "PDC Files" for
details.
Line 11 - Registration Info
This will be used mainly by shareware authors. It names a PDC or text file
(thought not a program -- see Line 12) to describe to the user the benefits
of registering the product. This can include information about upgrades,
bonuses, special support and so on. Of course, shareware authors can also
use this section to extol the virtues of shareware as a means for keeping
down the price of quality software.
Line 12 - Registration Program
This will be used mainly by shareware authors. It names a program that
unlocks the product, usually in conjunction with some kind of password that
the user receives when he or she registers. This might include the removal
of restrictions or advertising screens, the enabling of advanced features, or
simply the stamping of the users' name onto the main program.
Line 13 - Exit
This names the program, PDC or text file that will be used when the user
presses Esc at the Main Menu to return to DOS. In most cases, you will use a
PDC file which will describe "What to Do Next", in order to ensure than when
the user is presented with the DOS prompt, he or she has a clear idea what
command to enter.
14 - 16 - Packager Data
These three lines are reserved for the developer. For one reason or another,
the developer may decide to use the HLP file to store configuration data.
These three lines are ignored by HELPME and may be used to store information.
13
Line 17 - Changes This Version
This names a program, PDC or text file that describes any changes to this
version. This includes bug-fixes and new features.
14
PDC Files
What is a PDC File?
A PDC file is a file with an extension of PDC. PDC stands for "Pinnacle
Display Codes". PDC files are prepared like standard text files, with DOS's
EDLIN, a programmer's editor, or a word-processor in non-document mode.
However, PDC files contain special codes which control how the text is
displayed by HELPME.
Why Use a PDC File?
Advantages for the Programmer
A PDC file can be created with about the same amount of effort as a word-
processing document. Of course, since you will be using your familiar
programmer's editor to create the file, you can learn to design PDC files in
just a few minutes. The final results are quite attractive, considering the
minimal effort required.
Advantages for the User
Rather than being presented with a drab monochrome listing of a text file,
the user controls a colourful "slide show" in which each display page is
neatly centered on the screen.
By adding a little variety to the displays, and keeping them uncluttered, the
programmer can ensure that the user remains visually stimulated. This
greatly improves comprehension and retention of the material.
The Use of Colour
First, a word about spelling. American readers have probably noticed that
this manual refers to "colour" rather than "color". We've prepared this
manual using Canadian/United Kingdom spelling. However, we've avoided
including any debateable spelling in HELPME itself. If you find that an
alternate spelling has slipped past us and appears in HELPME, please inform
us and we will remove it.
Colour is now a very important feature for software. Those of us who spend a
lot of time on monochrome screens tend to forget that virtually all software
now makes extensive use of colour. However, once you've used a colour screen
for a while, you'll become used to seeing it. Programs that don't use colour
15
will strike you as antiquated and unattractive, no matter how many pull-down
menus and fancy doo-dads it may otherwise have.
The danger is that some people may select an inferior product over yours
simply because the other one is more pleasant to look at.
Another danger, though, stems from the fact that programmers are not trained
to work with colour the way, say, a painter would be. You may have seen
programs featuring gaudy screens in which a dozen colours clash, each one
clamouring for your attention.
HELPME addresses the need for colour, and the method by which we have
implemented colour support -- a method intended to promote consistency --
also makes it difficult to overuse colour.
Support for Different Displays
HELPME (and in particular, PDC file support) supports all standard displays.
This includes CGA, EGA (25- or 43-line mode), VGA (25- or 50-line mode), HGC
and so on. HELPME is designed to work with monochrome as well as in colour.
It does all this without any extra effort by the programmer.
Basic PDC Design
Overview: This section describes the PDC controls in general terms at an
intermediate level of detail. For specific applications, refer to "PDC Files
for Display" or "The Customer Comment Form". For examples, refer to the PDC
files that accompany the HELPME package. A quick reference guide also
appears near the end of this manual.
Control Code Format
PDC controls start in column one of your PDC file. (The PDC file is created
using a standard text editor.) The general format is:
/BText
or
/B Text
or
/B
Text
16
In the first two examples, the text follows immediately after the control
code (represented by /B). In the third example, no text follows the control
on the same line, so HELPME will look on the next line. This is particularly
useful when the control refers to a block of text immediately following.
PDC File Format
The PDC file format has very few constraints. You must simply ensure that
you do not define a page (i.e. screen) that contains more than 25 lines.
While HELPME does support screens in 43- and 50-line mode, it does restrict
the number of lines per page to 25.
Sample PDC File
Here is a PDC file that displays two pages. We've placed explanitory
comments on the right side of the page, but these would not be included in
the file. You will notice that colours are specified by purpose, rather than
by name. This helps you ensure consistency in your screens.
For a summary of the display codes, refer to the Quick Reference Guide at the
end of this manual.
/H What is Shareware? <-- Heading colour
<-- Skip a line
/T <-- Text colour
Shareware is "try before you buy" software. <-- Text
It lets you see the program and use it for
a while. If you like it, you can pay for
it. If it turns out it's not appropriate
for you, you'll find that out without having
to spend any money.
<-- Skip a line
/E Shareware saves you money! <-- "Effect" colour
/P <-- Pause ("Hit spacebar")
/H What You Get <-- Heading colour
<-- Skip a line
/T <-- Text colour
If you order now, you get... <-- Text
<-- Skip a line
/B A SET OF FREE STEAK KNIVES! <-- Bold colour
<-- Skip a line
/T <-- Text colour
So don't delay! Order today! Operators are <-- Text
standing by! Call 514-555-5555!
/P <-- Final pause (optional)
17
The preceding example would display two pages, each of which are followed by
a line saying "Press spacebar to continue...". The text of each page will be
neatly centered on the screen, in appropriate colours.
HELPME does not right-justify the text. In the example above, the text was
justified manually. You may wish to create the initial text with a word-
processor, which will justify the text for you.
PDC Files for Display
PDC files are most commonly used to display succinct information. If you
have more than 10 screens worth of information, it might be better to create
a text file and advise the user to print out the manual.
Display files use all PDC codes except // and /A.
The Customer Comment Form
The customer comment form (Line 10 of the HLP file) uses the // control code,
and /A to prompt for user input. In Version 1 of HELPME, this is the only
application of these two controls.
The format of the comment form is as follows:
1. The body of letter (Pages defined by: regular PDC text followed by /A)
2. The // control word to mark the end of the questions
3. Your return address
For a sample customer comment form, refer to the HELPCCF.PDC file in the
standard HELPME package.
After the user has filled in all the questions, he or she is advised to make
the printer ready. The questionaire, along with a mailing envelope, are then
printed. If the user doesn't have a printer, HELPME will simply display the
questions without asking the user to type in any answers.
The customer comment form is a very powerful concept and has proven helpful
to Pinnacle Software. We believe that your company may also find it useful.
In-house developers can replace the return address with their Department
Number, to encourage feedback from users.
18
PDC Quick Reference
For more details, see the chapter entitled "PDC Files".
CODE DESCRIPTION
/H Heading. See Note 1.
/T Regular text.
/E "Effect" text. More emphatic than /T text.
/B "Bold" text. More emphatic than /E text but less so than /H text.
/A Accept a single line of input. See Note 1.
/An Accept "n" lines of input. See Note 1. Examples: /A5 /A 05
/P Pause. Displays the page with the notation "Press spacebar to
continue".
// End of questionnaire. Used before the return address in the
customer comment form.
NOTE 1: Text is inverse rather than colour-on-black. For monochrome
screens, colour-on-black becomes white-on-black, while inverse
becomes black-on-white.
19
Next and Future Versions
We have not yet scheduled the production of the next version of The Pinnacle
Help System, but we do have some ideas. We would also like to hear
suggestions from registered users of HELPME.
In the meantime, here are some areas of development we are considering...
1. PDC display should use a more aesthetically-oriented algorithm for
centering text on the screen. At the moment, the longest line is
centered and all others have to comply. This occasionally results in an
unattractive screen.
2. Full mouse compatibility for the Main Menu, File Viewer, and so on. A
mouse is recognized by Version 1 in a few instances, but not enough to
make it truly "mouse compatible".
3. The answer to the "Colour?" question could be saved in HELPME.SYS file
in root directory. See the chapter entitled "Towards a Standard" for a
relevant commentary.
4. Allow the programmer to assign descriptions and functions to the FKeys.
Version 1.00 of HELPME is not very flexible in this regard; your only
option is to omit options.
5. The Pinnacle Configurator. This will enable the programmer to specify
what items need to be configured, along with explanatory text. Our goal
is to make it very easy to create such a facility. For an early example
of our direction in this regard, refer to the configuration programs for
Pinnacle's Sapphire and Pyroto products. We have more sophisticated
versions in our workshop, which are more closely related to HELPME, but
these have not yet been released, and they are not yet generic.
However, considering the hundreds of man-years that could be saved by a
generic configurator, we should certainly pursue this project. The
success (i.e. number of registrations) for HELPME will determine our
schedule in this regard.
6. New PDC commands. We've already developed some extensions to the PDC
codes but these have not been implemented in Version 1.00 of HELPME.
Some ideas that might prove applicable include:
/Fx Force the next x lines to the top of the screen
The remaining lines are centered in the remaining space
/X Put a box around the screen
/Q Display text and continue (used for Exit screen)
20
7. Full 43- and 50-line compatibility for the File Viewer. At the moment,
the File Viewer acts as a sort of "top-of-the-screen window" when called
in 43- or 50-line mode. This does not take full advantage of these
modes.
8. Release some HELPME modules as Turbo Pascal toolkits. Our SHOWVIEW
(File Viewer) and PAGE (PDC Processor) units could prove helpful to
Turbo Pascal programmers. We will rely upon the comments of registered
HELPME users to guide us in making our decision in this regard.
21
Towards a Standard
This chapter is directed towards shareware authors.
Looking for Standards
Standards are hard to come by.
True, there exist organizations such as CCITT or ANSI, whose serve to
recommend the "usual" way of doing things. But in the PC world, a lot of
important development takes places informally, far beneath the notice of such
august organizations.
The shareware market is a good example.
An astonishing amount of high-quality software has been produced by the
"electronic cottage industry". Yet apart from efforts by groups such as the
Association of Shareware Professionals, aided by a few forward-looking
shareware distributors, we haven't seen much standardization in the
presentation of this kind of software.
Standardization eludes us. It taunts us, always staying just out of reach.
For example, we might think that it's now obvious that each shareware package
should contain a file named READ.ME which is the first thing somebody should
check after getting their hands on some new software.
However, some developers don't think READ.ME is the right name for such a
file. Here are some quite defensible alternate names that have appeared
recently:
README. README.EXE README.BAT README.1ST README.NOW INFORMAT.ION
Of course, two of those files aren't even text files. But aren't programs
far more convenient? Of course, in that case, the suggested name is hardly
appropriate. Perhaps they should be called "RUNFIRST"?
And even if we could decide what to call the darn thing, what would it
describe? Is it truly an introduction to the product (in which case, it
might be named README.1ST), or is it simply a last-minute bug report?
Commercial products especially use READ.ME files in this role.
22
A Packaging Standard?
This brings us to our admittedly self-serving conclusion.
We have been issuing and downloading shareware products for a few years, now.
And we've seen wide variety in the quality of packaging.
Because we wanted to improve the overall appearance of our shareware without
constantly "reinventing the wheel", we created HELPME. It enabled us to
repackage a portion of the Pinnacle Software catalog in a standard way, and
it helped make these products more "welcoming" to the user.
We have no doubt that there are programmers out there who could write faster
versions of the program, yet we'd still like to propose that some of us work
towards making this a standard method of presenting our wares.
We set the HELPME licensing fee at about two hours' worth of time for an
average computer consultant. Since the average shareware author is hardly
average in any other way, we figured that HELPME would thus be priced
reasonably.
We would welcome suggestions from anybody on the subject of shareware
standardization, and what part we can play in it. We believe that HELPME can
go a long way towards making shareware more friendly, but we're sure that it
can be improved. So we count on your feedback and your participation, which
are, after all, the very foundations of shareware.
23
Other Pinnacle Products
Here are some other Pinnacle Software products. The ones marked with an
asterisk (*) use HELPME or an early version of the product. Most of these
products are available through CompuServe, major shareware distributors and
our North American Software Distribution BBS's.
SAPPHIRE * The Original Zero-Maintenance BBS
PYROTO * The Original BBS/Gaming System
VARITALE * The multi-path, multi-authoring-by-modem system
SBD The Super Booking Database for seminars and performances
HLRB * Create Handy Little Reference Books that fit in your wallet
LOVEFIRE * An adventure game that's a parody of a romance novel
PINNTALE A compiler for writing interactive stories
LW * Label printer designed for people who've never computed before
MEGADIII A stupid game that only a true programmer could appreciate
PHONEMEM Techniques for memorizing phone and other numbers
PINNARTX Amazing PC artwork for any display -- even monochrome
PRESERVE A handy alternative to the BACKUP command
SECURE A bogus security system that just might save your valuables
SPACEINV Arcade game for monochrome displays
SV Experiment with the modes of your video card
WEED A text-file cleaner-upper -- ideal for BBS logs
DECISION Amusing executive decision-maker
SFBI * The "Star Fleet Battles" gaming assistant
All of these programs (except SBD) may be obtained as shareware for only $15
when you register your copy of HELPME.
24
INDEX
Can't find it here? Check the Table of Contents.
// 18, 19 File Viewer 20, 21
/A 18, 19 Files 2
/B 19
/E 19 Guarantees ii
/H 19
/P 19 Hackers 7
/T 19 Heading 19
43-line 16, 17, 21 HELP ii
50-line 16, 17, 21 HELPCCF.PDC 18
HGC 16
ANSI 22 HLP 4, 9
HLRB 24
Bold text 19
Borland ii Installation 4
Buerg 2 Inverse 19
Canadian 15 Justified 18
CCITT 22
Centering 20 Licensing ii
CGA 16 Limitations of liability 6
Changes This Version 14 LIST 2
Color 15 LOVEFIRE 24
Colour 15 LW 24
Command-line parameter 11
Comment Form 13, 18 Manual 2
Configuration 2, 6, 12 Mask 11
Configurator 20 MEGADIII 24
Consistency 17 Monochrome 16, 19
Control code 17 Mouse 20
Control Code Format 16
Copyright ii Non-document mode 15
Correspondance 2
Crippleware 13 Overview 2
DECISION 24
Disclaimers 6
Display Codes 15
Displays 16
Doo-dads 16
EDLIN 15
Effect text 19
EGA 16
Envelope 18
Examples 4
25
Packager Data 13
Page 17, 21 User input 18
PATH 4 User manual 2
Pause 19
Pdc 9, 15 VARITALE 24
PDC commands Versions ii, 20
New 20 VGA 16
PDC Processor 21
Pgm 9, 11 Warranties ii
PHONEMEM 24 WEED 24
Pinnacle Display Codes 15 What to Do Next 13
PINNARTX 24 Whiz 9
PINNTALE 24
PRESERVE 24
Press spacebar 18
Printer 18
PYROTO 24
Questionaire 18
Questions 18
READ.ME 5, 12
Registration 2, 13
Return address 18
Right-justify 18
Root 9
SAPPHIRE 24
SBD 24
SECURE 24
SFBI 24
Shareware ii, 22, 24
Shareware authors 13
SHOWVIEW 21
Slide show 15
Spacebar 18
SPACEINV 24
Spelling 15
Standards 22
Steak Knives 17
SV 24
TechnoJock ii
Text files 15
Txt 9
26
