Simtel MSDOS 1992 June/SIMTEL_0692.cdr/msdos/hypertxt/magic15b.arc/README.DOC

Text File | 1989-11-02 | 18KB | 403 lines

Black Magic Addendum to the Manual - Version 1.2

Hardware Requirements

Black Magic will requires either an EGA graphics card, a CGA graphics card,
or a Hercules card, a hard disk, and 256K of memory for operation.  Mouse
support is included for Microsoft and compatible mice.  Black Magic may also
be used on VGA graphics systems, but it will operate the system in EGA mode.

The .INI File

Black Magic uses a initialization file generated by the install program to
define its initial configuration. This file is named MAGIC.INI and is simply
an ascii text file arranged in a certain fashion. The purpose of using an
ascii file is that it allows those with the desire to alter the .INI file to
their tastes.   This file can be altered with an ascii editor as desired.
The .INI file is updated each time the Configuration Screen is modified upon
exit from Black Magic.  Following is a listing of a complete MAGIC.INI file.

NOTE - Not all of these may be present in your .INI file,  with the
exception of the paths any may be left out; however the order in which they
appear is important.

     A Complete MAGIC.INI File

     .INI File Listing                  Comment
     System Path= C:\MAGIC              The path with MAGIC.EXE
     Document Path = C:\MAGIC\FILES     Default Document Path
     Printer Driver = EPSON.DRV         Current Printer Driver installed
     BookMark = On                      Could be On/Off/Query
     Markers = On On                    First 'On' says Link Markers are in
                                        Color.  Second 'On' says Link
                                        Markers are Shown
     Colors = 0 0 0 0                   Acceptable Values are 0 - 15 for
                                        Each.  Text Color, Background Color,
                                        Block Color, Block Background Color
                                        Note: The Text & the background
                                        color can't be equal
                                        The 0 -15 Color Scheme is that of
                                        the EGA Card
     Margins = 10 70                    Left Margin, Right Margin
                                        Values Between 1 - 79
     Tab Stops = 10                     Values Between 1 - 78
     Note Window = 40 05                Default Note Window Width, Height
                                        Values Between 10 - 78, 3 - 22

Note - As previously stated, not all of these items need be present in the
.INI file, but those that are there must be in the above order.  Also The
syntax shown here of lower case words with a capital first letter and a
space between everything is necessary.

Printouts & Files

In the manual, there are references to various files and printouts whose
location and names have since changed.  Current Information is as follows:

On page 1-4, a reference is made to the "Addendum Sheets" and a listing of
the number of disks, the disk names, and the contents of each disk.  These
addendum sheets have been replaced with a file on Disk # 1 called
README.FIL.

Command Line Options

Black Magic will automatically configure itself for your computer graphics
card; however in some situations this is not desirable.  To circumvent this,
Command Line options may now be entered to force Black Magic into certain
graphics modes.  The available command line options are:

     Command Line Option           Effect
     /EGA                          Forces Black Magic into EGA mode
     /HERC                         Forces Black Magic into Hercules mode
     /CGA                          Forces Black Magic into CGA mode
     /EGAMONO                      Forces Black Magic into EGA mode with
                                        a monochrome screen

Command Line options are used by specifying them when Black Magic is run.
To use them, you enter the following at the DOS prompt:

     MAGIC  /HERC

This example would force Black Magic into Hercules graphics mode.  Any of
the command line options can be used in this fashion.

NOMOUSE

The other command line option available is that of NOMOUSE.  This option
will disable the mouse support in Black Magic automatically.  The purpose of
this is that on certain IBM compatibles and on Genuine IBM PCs with an
expansion chassis, there is conflict with our mouse driver and Black Magic
will not execute.  Therefore if you are having trouble executing Black
Magic, you may wish to try using the NOMOUSE option This option is specified
by entering the following at the DOS prompt:

     MAGIC /NOMOUSE

The NOMOUSE option may also be used in conjunction with the other command
line options by specifying them in the following fashion:

     MAGIC /HERC /NOMOUSE

The above example  would force Black Magic into running on a Hercules board
and disable the mouse support.  Again any of the other command line options
could have been used in place of the '/HERC'.
Macros

The Define Macro command is on <Shift> <F7> as the template
says rather than <Alt> <F7> as the manual instructs.

GrabIt

The activation keystroke for GrabIt cannot be modified once
GrabIt has been loaded into memory.  It can be changed though
provided that it is done on the first time the GrabIt is
loaded into memory.

Readers

The manual states that there are three separate reader
programs called READEGA.COM, READCGA.COM, and READHGA.COM
that are in the public domain and used to read the .MAG
hypertext files.  To eliminate the inconvenience of three
separate programs, these have been combined into one called
MAGREAD.COM.  MAGREAD.COM is used in exactly the same fashion
as the previous reader programs, only it adapts automatically
to your graphics system.

The Map

The mouse may now be used to manipulate the map.  To scroll
the map with the mouse, merely move the mouse to the edge of
the screen and it will scroll automatically.  The mouse may
also be used to goto any map location by simply clicking the
mouse cursor on the node of the map that you wish to go to.

Additional Commands

The following commands have been added to Black Magic:

     <Alt> H             Show/Hide Link Markers
     <Ctrl> O            Search Options

Versioning

One of the chief problems with hypertext is that of
versioning.  For example, how do you distinguish between the
latest and next to latest versions of a hypertext document if
the differences are in the link structure and can't be easily
seen ?  The answer is by doing conscious versioning with your
file saves.  For example lets say that you are working on a
hypertext document called TIME.MAG.  After making some
revisions in this, save it as TIME1.MAG.  After the next set
of revisions, save it as TIME2.MAG.  And so on.  This will
allow you to keep a coherent record of all the versions of
document.  NTERGAID cannot stress the importance of this.

Markers as History Pointers

Although markers were covered in depth in the manual, their
uses as they relate to hypertext was not.  Simply put a
marker provides a instantaneous way to jump to any particular
"node" in a document from any other node.  For example lets
say that you are writing a document, and realize that you
will want to link to your current location in the future.
Simply set a marker to that location and then from anywhere
in the document, simply activate that particular marker and
you will be able to go back to that location instantly.

UnMagic and UnUnMagic

The UnMagic feature is used to remove existing links from a
document.  When either a Note Link or a Replacement Link is
removed the text in those links is lost.  In contrast, when a
Reference Link  is UnMagic'ed it's contents may be recovered.


To recover the contents of a Reference Link that has been
UnMagic'ed and link to them it is necessary to first go into
point mode (i.e. creating a Reference Link) Now call up the
map and press the <Tab> key.  This will bring up a window
into the existing UnMagic'ed nodes.  If there is more than
one UnMagic'ed node, they can be seen by pressing the Up and
Down Arrows to scroll through them.  When the node that you
wish to UnUnMagic (i.e. join your current point mode link to)
appears on screen press <Enter>.  This will then take you to
that node.  Once inside the node, simple mark the area that
you wish to link to as a block and press <Esc>.  This will
now have reconnected the UnMagic'ed node to the document as a
whole.

File Links

With Black Magic, Reference Link to other files can be
created.  These links will simply transfer the reader to
another .MAG file when activated.  THis effectively removes
the memory limitation of RAM from hypertext documents.

To create a File Link, you must first create a point mode
reference link.  Then you must call up the Map.  With the map
on screen, press the <Tab> key twice.  The screen will then
clear and you are able to enter the filename of the file that
you wish to link to.  After the filename is entered and
<Enter> is pressed, Black Magic will then save the current
file and load the file it is to link to.  When this file
comes up on screen, go to the spot in the file that you wish
to link to and mark it as a block.  After the block is
marked, press <Esc> to complete the link.  This will take you
back to the point that you started to make the link from
automatically.

Printing

Black Magic's basic printing capabilities have been greatly
enhanced since the manual was written.  SInce then the
following capabilities have been added:

     Top Margin Control
     Lines Per Page
     Number Of Text Lines
     Double/Single Spacing
     Page Numbering
     Configurable Printer Drivers
     Header
     Footers

These functions are accessed through the Print options menu,
which is accessed by pressing <F10> P O.  This pulls a window
up on screen with a menu inside it.  This menu has a
highlighting bar inside it that is scrolled to the option
that you wish to change.  With the bar at the option that you
wish to change, enter a new value or response.  Numeric
answers are entered by pressing the new number values, and
Off/On values are entered by pressing the Right and Left
<ArrowKeys>.

To enter a header or footer, some further explanation is
needed.  First the Header or Footer must be set to "On" then
the header or footer respectively can be entered on the line
below where the header or footer is set to on.


READERS

When Black Magic was originally released, there were three separate reader
programs; one for  the CGA, one for the HGA, and one for the EGA.  These
programs were called READEGA.COM, READCGA.COM and so on.  To make things
easier for our users, we have combined the three reader programs into one.
This new program functions on EGA, CGA, and HGA systems automatically, and
is now in a file named MAGREAD.ARC.

Memory Overlays

The use of Memory Overlays has been removed from the control of the user.
Memory Overlay use is now limited only to those users with sufficient
expanded memory  to load them.  When sufficient expanded memory is present
in a system, the memory overlays are loaded automatically into it; otherwise
they are not used at all.  Your computer may require the installation of a
driver to take advantage of Expanded Memory.  See your hardware manual for
further details.

Temporary Mouse Shutdown

Occasionally people that use mice on their system want to turn them off for
one reason or another.  In Black Magic, this is implemented using the <Alt>
M key combination.  To turn off your mouse, press: <Alt> M.  To turn it on
again press: <Alt> M a second time.

Hide Markers

A new command not well detailed in the original manual is that of the <Alt>
H or Hide command.  When <Alt> H is pressed, all of the link markers are
automatically hidden from view.  Press it again and they reappear.  The
purpose of this command is to allow  you to 'zoom' in on a specific spot in
a document and not be distracted by the other links that are available to be
followed.   Note: This can also be accomplished using the Configuration
screen.

Place Holders

Another feature whose documentation could use amplification is that of
PlaceHolders. In a paper book, you can have multiple pieces of paper holding
your place.  This allows you a tremendous amount of flexibility in 'jumping'
from spot to spot. Black Magic has this sort of flexibility also. Black
Magic supports up to 9 (1 - 9) electronic placeholders.  A Placeholder in
Black Magic allows you to assign a key combination of the form <alt>
<NumberKey> to a place in a document, then by pressing the <Alt> <NumberKey>
combination again, you can instantly leap to that spot in the document.  The
placeholders work across hypertext links also so this gives even more added
flexibility.

Placeholders are extremely useful when creating a large hypertext document.
By assigning them to the major links in the document, places can be reached
almost instantly, this makes the various editing operations that one goes
through in document revision very easy to accomplish.
To assign a placeholder to a spot in a document, position the cursor where
you wish the placeholder to be assigned to and press:

     <Alt> -
     <NumberKey> <Enter>

Where '-' is the minus key on the keyboard and <Numberkey> is any of the
number keys from 1 to 9.  As you can see a dialog box comes up when the
<Alt> - combination is pressed, and then the <NumberKey> for the placeholder
is entered and <Enter> is pressed.

To jump to a placeholder that has previously been defined, press <Alt>
<Numberkey> (for the placeholder), and you will be there instantly.

To eliminate a placeholder that already exists, simply define a new
placeholder with the same number key. Placeholders will also be eliminated
when the text that they point to has been deleted.

Justification

Justification has now been implemented in this version of Black Magic, but
its implementation is inconsistent with what is described in the manual.
The default for justification in Black Magic is that of left justified text.
This is what is always shown on screen in editing mode.  The other options
for justification are Right Justify (<Ctrl> <F8>) and Full Justification
(<Alt> <F8>).  To change a window's justification, press one of the below
control keys:

     Key                                Effect
     <Shift> <F8>                       Left Justified
     <Alt> <F8>                         Full Justified
     <Ctrl> <F8>                        Right Justified

When one of the above keys is pressed, a dialog box  will come up and query
you as to whether or not the window's justification should be changed.  By
answering 'Y',  the window will be justified as per the key combination that
you pressed.

Note: The effects of a justification command are not apparent on screen, the
justification only appears in reader mode (<Alt> <F2>).

Margins

The Margin commands in Black Magic have now been enhanced and changed from
what is stated in the manual.  There are three ways to change the margins in
Black Magic:  <Alt> L, <Alt> R, and The Configuration Screen.
<ALT> L and <Alt> R are both used to change the margins in the current
window.  The current window is simply the active area that you are typing a
document in.  The advantage to being able to set margins on an individual
window basis is that in a large hypertext document, you may wish to use
various different ways of formatting the document.  The ability to change
margins on a per window basis allows you this flexibility.

To change the margins for an individual window, press either <Alt> L or
<Alt> R.  A dialog box will then come up for you to enter the new margin
into.  After entering the new values and pressing <Enter>, the current
window will be reformatted to the new margins.

The other method of changing margins is through the use of the Configuration
screen.  When the margins are adjusted on the configuration screen, they are
adjusted for all windows yet to be created.  What this means is that when
you change a margin setting on the Configuration screen, it does not
reformat the entire document to those new margins; instead any new reference
links that you make will have the new margins automatically.

The Convert Program

For people who have upgraded from previous versions of Black Magic, a note
about the CONVERT utility is necessary.

NOTE  - ONLY those who have used previous versions of Black Magic and have
files with graphics in them need worry about the CONVERT utility.  Black
Magic version 1.20's screen grabber (GRABIT) automatically saves files in
the new format.

Black Magic version 1.20 features a compressed graphics file format for
faster file loading of graphics files and more importantly for smaller
files.  However despite the use of this new file format, all old graphics
files are compatible with Black Magic.
If you wish to get the speed and size benefits of the 1.20 format on your

old files, it is necessary to use the convert utility on the graphics files.
Convert is a small program run at the DOS level that simply converts a
graphics file from the old format to the new format.  Typically a savings of
35 - 50 % is witnessed in file size.

Using Convert

     Purpose:  Change a file from the Version 1.0 graphics file format to
                    the 1.20 file format.
     Format :  CONVERT [d:] [path] filename
     Switches: None; wildcards may be used however.
     Remarks:

When the CONVERT command is entered, it takes the specified filename and
automatically converts it from the 1.0 file format to the 1.20 file format.
Both path statements and wildcards may be used in the command parameter.
This allows you to convert for than one graphics file at once, and also
specify its location remotely (I.e. CONVERT.COM need not be in the same
directory as the files).

Examples of CONVERT Syntax:

     CONVERT PICTURE.MGR
     CONVERT C:\MAGIC\FILES\PICTURE.MGR
     CONVERT  \MAGIC\FILES\*.MGR