MAG Disk (Jan 1990) : SID / SID.ConfigDocs

                                ConfigDocs
                                **********


This file describes in detail the setup, operation, and maintenance of the
SID configuration file.  You can completely customize SID to your needs and
environment with the configuration file.  Because the configuration changes
as often as SID does, I've opted to place the instructions in this separate
file.  This file assumes you have read the SID.docs and have used SID enough
to be familiar with the terms describing the SID functions.


Why the config file is needed
-----------------------------

SID will run on its own without the configuration file, though you will be
restricted to using the defaults that are hardcoded into the program.  I must
admit that I set these up for my system, but hopefully you will find that
many of these defaults will suit you as well.  Of course, once the program is
running, any of these default settings may be changed.

In all likelihood, however, there will be some defaults that you will need to
alter.  This is where the configuration file enters the picture.  This file
should contain all SID settings which differ from the hardcoded defaults.


Name and location of the config file
------------------------------------

The SID config file must be named SID.config and placed in the s: directory.
The s: directory is automatically assigned to the 's' directory on your boot
disk, though hard disk users often assign s: to a directory in the Workbench
partition of their hard drive.  Whatever the case, be sure place the config
file there, or SID will not find it.

If you are handy with your hex file editor, however, you can change the name
and location of the config file.  Do a search on the name "s:SID.config"
(without the quotes).  I've provided up to 30 characters in which to write
the entire name (including path) of the SID config file.  SID will
automatically strip any trailing blanks.  Be sure you do not overwrite that
final NULL, or nasty things will happen.  Also, do not attempt this unless
you are handy at this kind of thing.


Loading the config file upon startup
------------------------------------

SID automatically attempts to load the config file upon startup.  No error
message is displayed if SID does not find your config file.  Entries found in
the config file will overwrite the corresponding default settings, meaning
that only entries which differ from the default settings should be included
in your config file.  That way, SID will load the fastest possible.


Editing the config file
-----------------------

You can edit the config file with any ASCII text editor.  Just load the
config file into your favorite editor and enter the keywords and values as
described below.  I'm using the text-file configuration method so that almost
anyone can create and maintain their config file.  Eventually I plan to
release an interactive configuration editor which will not only explain in
detail the meaning of each keyword inside the program, but will also
interactively prompt you for the desired values.  Registered users will be
notified when this program is available.

You may also edit the config file from within SID by selecting the "Edit"
subitem from the "Configuration" item in the "Program" menu.


Format of the config entry
--------------------------

The standard format of an entry in the config file is:

    Keyword=value

The "keyword" is name of the setting that you are changing.  This must be
specified EXACTLY as listed in the docs for SID to recognize it, meaning that
there can be no imbedded blanks and that case (upper and lower) is important.
The keyword is then immediately followed by an equal sign.  Everything from
the equal sign to the end of the line (not including the equal sign or the
end-of-line character) is considered to be part of the value.

For example, consider the following entry:

    Preferences=sys:prefs/Preferences

The keyword is "Preferences", meaning that you want to change the setting for
the Preferences command.  Note that the first letter is capitalized exactly
as listed later in this doc file.  The value is "sys:prefs/Preferences",
meaning, in this case, that SID can find the Preferences program in the
"prefs" directory on the "sys:" disk.

The best way to place comments in the config file is to begin the line with a
forward slash, followed by an equal sign and a blank, such as:

    /= this is a comment line


Entries in the config file
--------------------------

The entries in the config file are divided into four categories based on the
values they require: flags, numbers, strings, and keys.  Flags require YES
or NO values, numbers require numerical values, strings require text string
values, and keys require specific key values.  The default value for each
keyword is listed in parentheses.


Flag entries
------------

All of the flag keywords require a YES or NO value.  Note that these values
must be capitalized and should not include any preceeding, imbedded, or
trailing blanks.

AbsolutePath=
  (YES is default).  Whether the path name will be converted to its absolute
  path name.  For example, the path name "c:" may be converted to its
  absolute path name "Workbench1.3:c".  Note that even if this flag is set to
  NO, if you enter a blank directory (which will give you the current
  directory), its absolute path name will be displayed.

BeginShrunk=
  (NO is default).  Whether SID should begin iconified on the Workbench
  screen when you first run the program.  If you specify YES for this flag,
  SID will then use the configured values for WindowHeight= and ScreenType=
  when you first click on the EXPAND button.

BytesOccupied=
  (YES is default).  Whether you want the BYTES command to display the number
  of bytes the highlighted files occupy (YES) or the number of actual bytes
  in the files (NO).

CopyOverwrite=
  (YES is default).  Whether you want to overwrite existing files in the
  destination directory when you copy files.  If YES, all highlighted files
  will be copied to the destination directory, regardless of whether they
  exist.  If NO, only the files which do not exist in the destination
  directory will be copied.  Uncopied files will remain highlighted.  You can
  toggle this flag on and off from within SID by using the "Flags" menu.

DateMDY=
  (YES is default).  Whether dates will be displayed in Month-Day-Year
  format.  If DateMDY=NO, dates will be displayed in Day-Month-Year format.
  This flag also governs the format in which dates entered for the "Select by
  Date" command are expected.

DeleteCheck=
  (YES is default).  Whether a requester will appear at the beginning of each
  delete command, asking you if you are sure you want to delete the
  highlighted files.  This is different than DirDelete because this keyword
  causes a requester to appear only once everytime you execute the DELETE
  command, whereas the DirDelete keyword causes a requester to appear for
  each directory selected for deletion.

DirDelete=
  (YES is default).  Whether a requester should appear every time you try to
  delete a non-empty directory, asking you if you are sure you want to delete
  that directory.  Though this can be annoying at times, it will save you
  from the possible catastrophic results of deleting an entire directory you
  wanted to save.

EnglishDates=
  (YES is default).  Whether file dates in the DATE and TIME entry display
  will be displayed in English for recent dates (such as "Today",
  "Yesterday", "Tuesday", etc.)  If this is NO, all dates will be displayed
  in the MM/DD/YY format.

ErrorStop=
  (YES is default).  Whether the Error requester will be displayed when SID
  encounters an error while trying to perform a command.  This allows you to
  retry the file, skip the file, or stop the command altogether.  If you
  don't wnat to be bothered each time a command fails, set this flag to NULL.
  The files for which a command fails will be left highlighted after the
  command has finished executing.

InsertMode=
  (YES is default).  Whether the input fields will be in insert or typeover
  mode.  In insert mode, characters you type are inserted at the cursor,
  and all characters under and to the right of the cursor are moved over one
  character position to the right.  In typeover mode, the character you type
  will appear in the field under the cursor, typing over any existing letter
  under the cursor.  Note that once the program is running, you can switch
  back and forth between insert and typeover mode by pressing CTRL-I and
  CTRL-T, respectively.

LoadDiskette=
  (NO is default).  Whether the root directory of a diskette inserted in any
  drive will be loaded automatically into the active list.  See the
  LoadSwitch= flag below.

LoadSwitch=
  (YES is default).  There are two ways to automatically load diskette
  directories.  You can continuously load dirs into the same list (the active
  one), or alternate lists (swap the active status after each load).  If the
  config flag LoadSwitch=YES (and LoadDiskette=YES), the directory of an
  inserted diskette will load into the active list, then the inactive list
  will be made the active list.  This means the diskette directories will be
  loaded alternating left and right.  If LoadSwitch=NO (and LoadDiskette=YES), however, the directory of an inserted diskette will
  always be loaded into the same list (the active one).  If LoadDiskette=NO,
  however, the directory of an inserted diskette will not be loaded
  (regardless of the setting of LoadSwitch=).  You can also change the status
  of the LoadDiskette= and LoadSwitch= flags with the "Diskette" item in the
  "Flags" menu.

QuitCheck=
  (NO is default).  Whether a requester will appear when you click on the
  window close gadget asking you if you are sure you want to quit.  This is
  provided for people with itchy trigger fingers.

Requester=
  (NO is default).  Whether a requester will appear for each command allowing
  you to change the command or its arguments.  You can toggle this on and off
  by clicking on the REQ gadget located in SID's window title bar.  The text
  you enter in the requester will be saved for the next time you execute that
  command.  This can be handy for temporarily changing a command without
  having to edit and reload the config file.

ScreenBehind=
  (NO is default).  Whether the SID custom screen should open behind all the
  other screens upon startup.  This is handy if you run SID from your startup
  sequence and open it on its own custom screen.  It will open out of the way
  behind the Workbench screen, but you can easily get to it if you need to.
  You must have the ScreenType= flag set to either CUSTOM or INTERLACE for
  this to work.

ShowHidden=
  (YES is default).  Whether to display hidden entries in the directory lists.
  Hidden entries are files or directories with the Hidden protection bit set.
  Even though AmigaDOS doesn't yet support this bit, SID does.  If
  ShowHidden=YES, these hidden entries will not be displayed.  This is handy
  if you don't like to be bothered with all those .info files.  Use the SET
  or PROTECT command to set their hidden bits, and they all disappear next
  time you reload the directory!  Once SID is running, you can toggle this
  flag on and off from the Flags menu.

ShowOutput=
  (NO is default).  Whether a CLI window will appear for every program you
  run from SID, allowing you to view that program's output.  This can be
  toggled on and off later with the OUTPUT gadget in the SID window's title
  bar.  Note that if you are running SID from the CLI window, the output of
  programs launched from SID will be displayed in that CLI window anyway.

Wait=
  (NO is default).  Whether programs launched with the RUN command will be
  interactive (I know, "Wait" is a funny name, but you'll see my logic).  If
  Wait=NO, then a program launched with the RUN command will be run in the
  background, and SID can go on about its business (the program is launched
  asynchronously, for all you tech buffs).  The problem with this is that the
  program will not be interactive from the CLI.  If Wait=YES, then the
  program will be run in the foreground, meaning SID will wait until the
  program finishes.  The advantage of this method is that the program is
  interactive in the CLI, allowing you to enter input if it's a command-line-
  based program.  Note that this option works only when the OUTPUT window
  option is also specified.

WindowStay=
  (YES is default).  When you change the size of the SID window, if
  WindowStay=YES, SID will save the window's location in the Workbench screen
  so that if you ever return to that size window, it will be right where you
  left it last.  If WindowStay=NO, however, then the window will always be
  placed in the position according to the config values.


Value entries
-------------

All of these keywords require a numerical value.  Invalid values will be
corrected or ignored.

Color0=
Color1=
Color2=
Color3=
  (-1 is default for all of them).  These are the colors of the SID custom
  screen.  You can edit the custom screen colors by selecting "Colors" from
  the "Environment" menu (you must be in Custom or Interlace screen mode to
  see this menu item, though).  If you click on the ACCEPT button in the
  Color requester, the decimal values (between 0 and 4095) of the four colors
  you selected will be displayed in the message box.  These are the values
  you need to set here.  The four colors are:

      Color0: screen background, window title bar text
      Color1: window borders, message box text, field text
      Color2: directory list background, command button background
      Color3: show active list, command button text, cursor

  Specifying a value of -1 will give you the same color as the Workbench
  screen.

FullLeft=
  (0 is default).  This is the left edge of the Full window.

FullTop=
  (0 is default).  This is the top edge of the Full window.

HalfLeft=
  (0 is default).  This is the left edge of the Half window.  Note that on a
  standard Workbench screen, a left edge value other than zero for all but
  the Shrink window will be meaningless since both the SID window and the
  Workbench screen are the same width.  This value was placed here for future
  expansion (I'm sure we'll all have a 1024 x 1024 monitor some day) or for
  vScreen users ("BigSID").

HalfTop=
  (0 is default).  This is the top edge of the Half window.

LaceLeft=
  (0 is default).  This is the left edge of the Lace window.

LaceTop=
  (0 is default).  This is the top edge of the Lace window.

OutputHeight=
  (120 is default).  This is the height of the CLI output window.

OutputLeft=
  (0 is default).  This is the left edge of the CLI output window opened when
  programs are launched from SID and the ShowOutput flag is on.

OutputTop=
  (80 is default).  This is the top edge of the CLI output window.

OutputWidth=
  (640 is default).  This is the width of the CLI output window.

ShrinkLeft=
  (344 is default, which will place the shrink window flush right with the
  Workbench screen).  This is the LeftEdge of the Shrink window.

ShrinkTop=
  (0 is default).  This is the TopEdge of the Shrink window.

SpecifyLeft=
  (0 is default).  This is the left edge of the Specify window.

SpecifyRows=
  (10 is default).  This is the number of rows with which the specify window
  will open.  This value is only used if you specify WindowHeight=SPECIFY.

SpecifyTop=
  (0 is default).  This is the top edge of the Specify window.


String entries
--------------

These are the strings used to execute the commands.  Everything from the
equal sign after the keyword to the end of the line, including imbedded and
trailing blanks, will be recognized.

Arc=
  (c:arc a is default).  The Arc program you use for archiving files.  Notice
  that five different archival methods are supported: Arc, LHArc, Pak, Warp,
  and Zoo.  Therefore, this value should contain the command to summon the
  Arc program, not the Pak, Warp, or Zoo program.  They have their own
  separate keywords, as shown below.

AutoDir1=
AutoDir2=
  (there is no default).  The directories to be automatically loaded upon
  program startup.  AutoDir1 is loaded in the left list, AutoDir2 in the
  right.  You can override these settings by specifying directories in the
  command line when running SID from the CLI, or you can specify "-n" to load
  no directories at all.

Button1=
Button2=
Button3=
Button4=
Button5=
Button6=
Button7=
Button8=
  (The default is NOT to list them in the config file).  The eight Button
  keywords listed above correspond to the eight device buttons associated
  with the two directory lists (see the DeviceButtons= keyword).  The
  Button1= keyword corresponds to the leftmost device button, Button8= to the
  rightmost, and so on.  If a device button has a button path specified, then
  instead of appending a colon to the button name, the button path is used.
  That means you must supply any necessary colons and slashes.  That also
  means that the button name is ignored and you can name it anything you
  want.  Note that you do not have to specify a button path for each device
  button.  For example, using the DeviceButtons= keyword default, the third
  button is named DH0.  Instead, you could change the name to WKB (with the
  DeviceButtons= keyword), and set the path with Button3=Workbench1.3:

Calculator=
  (c:calculator is default).  The name and location of the calculator program
  that you like to use.

Command=
  (there is no default).  This is the AmigaDOS command executed when you
  select "Command" from the "System" menu.  If there is some command that you
  execute on a regular basis, you can set that here.

DiskEdit=
  (c:DiskX is default).  The name and location of your favorite disk
  editor.  This is not supported by the current version of SID.

Execute=
  (there is no default).  The arguments for batch files executed from SID.
  Though this will likely be blank for most users, you may find sometime that
  you are often executing the same batch file which requires a certain set of
  arguments.

FileEdit=
  (c:e is default).  The name and location of your favorite ASCII text
  editor.

FileXEdit=
  (c:newzap is default).  The name and location of your favorite hex editor
  (that allows you to edit binary files).

Hear=
  (c:hear is default).  The name and location of the program you use to play
  digitized sounds.

LHArc=
  (c:lharc a is default).  The LHArc program you use for archiving files.

ListArc=
  (c:arc l is default).  The Arc program you use for listing the contents of
  arc'd files.

ListLHArc=
  (c:lharc l is default).  The ALHrc program you use for listing the contents
  of arc'd files.

ListPak=
  (there is no default).  The command you use for listing the contents of
  pak'd files.  Even though the current version of the Pak program does not
  have the ability to display the contents of pak'd files, this was provided
  for upward compatability.

ListWarp=
  (there is no default).  The Warp program you use for listing the contents
  of warp'd files.  Note that the current version of the Warp program does
  not have a command to display the contents of a warp'd file.  This was
  provided for upward compatability.

ListZoo=
  (c:zoo l is default).  The Zoo program you use for listing the contents of
  zoo'd files.

MakeDirIcon=
  (there is no default).  This is icon that is created along with directories
  you create with the MAKEDIR command.  The default is to have no icon
  created.  I've done it this way so that you are not forced to live with the
  drawer icon image that I choose.  I suggest that you place the .info file
  you want to use somewhere safe, such as the s: directory, perhaps naming it
  "SID.icon".  Note that the new directory icon will inherit all of the
  characteristics of your MakeDir icon, such as position (if you've done a
  snapshot on it), protection bits, comment (if any), etc.

NewCLI=
  (c:NewSHELL "NEWCON:0/0/640/96/Type ENDCLI to Quit" is default).  The
  command used to create a new CLI window.  Note how I am using the Shell
  provided with Workbench 1.3 in the default.

Other=
  (c:cc is default).  This is a user-definable key which you can set to do
  anything you want.

Pak=
  (c:pak is default).  The Pak program you use for archiving files.

Pattern=
  (#?.c is default).  The first time you run the PATTERN command (which
  highlights all files in the active list based on the AmigaDOS wildcard
  pattern you specify), this pattern appears in the requester.

Preferences=
  (sys:prefs/Preferences is default).  Where to find the Preferences program.

Print=
  (run c:print is default).  The name and location of the program you use to
  print files.  A file printing program with C source is included on the disk
  of goodies sent to registered SID users.

Run=
  (there is no default).  The arguments for programs run from SID.  Though
  this will likely be blank for most users, you may find sometime that you
  are often running the same program which requires a certain set of
  arguments.

SeparateDirs=
  (NO is default).  Whether the dirs and files will be displayed separately
  in the directory lists with the directories on top and the files on the
  bottom.  The default is NO, in other words, mix the files and directories,
  sorting them alphabetically.  NOTE:  To use this feature, you cannot load
  directories which contain dir names that begin with an alternate character
  (such as ß, or any character with a value between 0x80 and 0xFF).  Such
  entries will be displayed correctly, but you will not be able to access
  them.

Set=
  (*******- is default).  The protection bit pattern used by the SET
  requester.  This string should be eight characters long, each character
  representing the bit in the corresponding protection string HSPARWED.  A
  letter indicates that the bit is to be set, a dash (-) indicates that the
  bit is to be cleared, and an asterik (or any other character) indicates
  that the bit is to be ignored.  Thus, the default setup will ignore all but
  the Delete bit which will be cleared, meaning if you execute the SET
  command without changing the bit pattern, all highlighted files will have
  their Delete bits cleared (making them Not Deletable).

UnArc=
  (c:arc x is default).  The Arc program you use for unarchiving arc'd files.

UnLHArc=
  (c:lharc x is default).  The LHArc program you use for unarchiving arc'd
  files.

UnPak=
  (there is no default).  The program you use for unarchiving pak'd files.
  For the current version of the Pak program, just typing the name of the
  pak'd file will cause it to unpak itself, therefore no command needs to be
  specified.

UnWarp=
  (c:warp write is default).  The Warp program you use for unarchiving Warp'd
  disks.  Be careful with this command.

UnZoo=
  (c:zoo x//is default).  The Zoo program you use for unarchiving zoo'd
  files.  The double slashes "//" preserves the structure of zoo'd
  directories when unzooing files by creating the directories and storing
  the zoo'd files in them.

View=
  (c:superview -c is default).  The name and location of your favorite IFF
  graphic display program.  Notice that you can attach program arguments.  In
  this case, I added a "-c" argument to surpress color cycling.

Warp=
  (c:warp read 0 79 is default).  The Warp program you use for archiving
  disks.

Zoo=
  (c:zoo a is default).  The Zoo program you use for archiving files.


Special entries
---------------

These keywords require one of the special flags listed.

ArchiveMethod=
  (ARC is default).  This flag allows you to specify which archive method you
  want to use when archiving files.  You can specify one of the following
  flags:
      ARC ..... to use Arc
      LHARC ... to use LHArc
      PAK ..... to use Pak
      WARP .... to use Warp
      ZOO ..... to use Zoo
  Of course, you can change this at any time with the "Archival Method" item
  in the "Flags" menu.  Also, this flag has nothing to do with unarchiving or
  listing the contents of archived files.  SID automatically determines which
  archival method to use in those cases.

ArrowDirection=
  (FLOW is default).  The direction in which the arrow (in the center of the
  SID window) will point.  If ArrowDirection=FLOW, the arrow will point in
  the direction of file flow, i.e. from the active side to the inactive side.
  If ArrowDirection=ACTIVE, the arrow will point to the currently active
  side.  Requires one of the following:
    FLOW
    ACTIVE

DeviceButtons=
  (DF0DF1RAMRADDH0DH1DH2DH3 is default).  These are the names of the eight
  device buttons which appear under each window.  Notice how they are
  listed in succession with no imbedded blanks.  The colons are implied and
  will be added by SID.  Each button name must be exactly three characters
  long, and you must specify all eight button names or strange things will
  happen.  You can override the directories loaded when clicking on the
  device buttons by specifying alternate path names with the Button1=,
  Button2=, etc. entries.  See those keyword definitions below for more
  information.

EntryType=
  (SIZE is default).  The manner in which the entries will be displayed.
  Requires one of the following:
      SIZE ... <--------- File Name --------->9999999
      DATE ... <--------- File Name ------> MM/DD/YY
      TIME ... <--------- File Name -----> HH:MM:SSam
      BITS ... <--------- File Name -------> HSPARWED
      NOTE ... <-- File Name --> <---- Comment ----->
      DESC ... <-- File Name --> <-- Description --->

ScreenType=
  (WORKBENCH is default).  The screen on which the SID window will open when
  the program begins.  Requires one of the following:
    CUSTOM ...... SID will open on its own non-interlaced custom screen
    INTERLACE ... SID will open on its own interlaced custom screen
    WORKBENCH ... SID will open on the Workbench screen

WindowHeight=
  (FULL is default).  The size at which SID's window will open when the
  program begins.  Requires one of the following:
    FULL ..... SID will open with a 640x200 pixel window, if possible
    HALF ..... SID will open with a 640x100 pixel window
    LACE ..... SID will open with a 640x400 pixel window, if possible
    SPECIFY .. SID will open with the number of rows you specified with the
               SpecifyRows keyword


ConfigDocs v1.06 12/02/89
© Copyright 1989 Timm Martin
All Rights Reserved Worldwide

/*-- END --*/