@DATABASE "Documentation for GED-Hexedit"
@NODE MAIN "Documentation for GED-Hexedit"
@{B}
           GED-Hexedit Version 1.30 by Wolfgang Morgeneier

@{UB}

  @{" Introduction " Link 1.}

  @{" Installation " Link 2.}

  @{" Usage " Link 3.}

  @{" Operation description " Link 4.}

  @{" Description of API-Library" Link 5.}

  @{" Known bugs " Link 6.}

  @{"History" link 7.}

  @{" Copyright " Link 8.}

  @{" Author " Link 9.}
@ENDNODE

@NODE 1. "Introduction"

@{B}    Introduction:
@{UB}
For the Amiga there are not many hex-editors.  Some day I found a program
<BinHex> in the Aminet.  After seeing this, I had the idea, to write a
similar program and an environment for hexadecimal edit for the editor
GOLDED by Dietmar Eilert.  This here is the preliminary finished result of it.

@{b}This program can have bugs!@{ub}

@{b}I will not be responsible for any bugs of the program or loss of data!@{ub}

@{b}To avoid this, it is best to work only with copies of your files!@{ub}

If somebody is interested in a further development of the program by me,
he should send me an EMail with error reports or ideas for further development.

@ENDNODE

@NODE 2. "Installation"

@{B}    Installation of the program:
@{UB}
The program will be installed by the Amiga-installer.
For this, the icon <Setup> has to be clicked twice.
After this the installation goes automatic.

The following is required for the program:
- Golded 5.0.0+ by Dietmar Eilert
- the Amiga-installer in the search-path (for the installation)
- delete, copy and rename in directory c:
- Arexx
- the directory t: must exist
  as during opening a file this file will be intermediate saved at t:
- a fast Amiga computer (otherwise operation is very slow)
- RAM memory (approx. 10 times the size of the file to be edited will be needed)

@ENDNODE

@NODE 3. "Usage"

@{B}    Usage and function of the program:
@{UB}

The program installs a new icon at the end of the toolbar with inscription <HEX>.
By clicking this icon, a file-requester shows up, and you can select a file
for hexadecimal edit.
The file to be edited will then be loaded into memory, reformated and shown.


The display is separated into 3 parts:
- at the left there is the address in hex format
- in the middle are the contents of the file in hex format, 16 bytes per line,
  each long word is divided by a space
- at the right there are the contents of the file in ASCII format.  If a char
  cannot be displayed a <·> is shown.



Example:

000014B0  1F223344 44552334 55667772 22332222  ··3DDU#4Ufwr·3··
000014C0  0A112345 67890123 45677777 88890234  ··#Eg··#Egww···4



The keymap has been reconfigured to ensure, that only proper chars can be entered
at each place.

The address area and all spaces cannot be changed.
In the hex area, all digit keys, the letter keys a ... f and the cursor keys are
allowed.  The letters can be entered in capital or small spelling.  They are shown
always in capital spelling.
In the ASCII area additional all letters and most of the additional chars are allowed.

A special key is the tabulator key.
With this key you can jump between the HEX area and the ASCII area.

The mouse is used to place the cursor to the location you want.


  @{" Describtion of the menu " link Menu}


  @{" Describtion of the toolbar " link Toolbar}


@ENDNODE

@node TOOLBAR "Toolbar"


   @{b} Describtion of the toolbar@{ub}


The toolbar consists of 6 buttons.
They have the following meaning (from left to right):

- New: open new window in standard mode

- Open: open an existing file in HEX mode

- Save: save the actual file

- Undo: undo the last action

- Redo: undo the last undo action

- Help: call help for program GED_Hexedit


  @{" back " link 3.}

@endnode

@node MENU "Menu"


   @{b}Describtion of the menu@{ub}


  @{" File " link Datei}

  @{" Window " link Fenster}

  @{" Edit " link Bearbeiten}

  @{" Search " link Suchen}

  @{" Options " link Optionen}

  @{" Help " link Hilfe}



  @{" back " link 3.}

@endnode
@node DATEI "File"

   @{b}Menu File@{ub}


- new text:
  opens a new text without name in standard mode

- open new normal:
  opens an existing file in normal mode.  The file can be selected at a file
  requester.

-open new hex:
  opens an existing file in hex mode.  The file can be selected at a file requester.

- save:
  saves the file with its existing file name.

- save as:
  shows up a file requester, where you can change the file name and saves the file.

- file properties:
  with this you can change the file name, the file comment, the protection bits
  and the file type.  The file type of files, which are edited by GED_Hexedit,
  is always <HEX>.
  Note: if the display of the file is corrupted by a unforeseen event or a bug,
  you can repair it by deleting the file type, normal changing of the file and,
  after this, changing the file type again to <HEX>.

- close:
  the actual file will be closed.  If it was changed a safety requester will
  appear before.

- quit:
  all windows will be closed and the program will quit.
  When  files have been changed, a safety requester will appear before.

- open files:
  here all open files show up and can be selected for editing.


  @{" Back " link Menu}


@endnode
@node FENSTER "Window"

   @{b}Menu Window@{ub}


- window:
  with this menu item and its subitems you can change the size and view of the
  windows (see manual for GoldED).

- window next:
  the next open window becomes the actual text window.

- window previous:
  the previous open window becomes the actual text window.

- hidden texts:
  with this menu item and its subitems you can change the size and view of the
  windows (see manual for GoldED).


  @{" Back " link Menu}

@endnode
@node BEARBEITEN "Edit"

   @{b}Menu Edit@{ub}

- undo:
  undos the last action.

- redo:
  undos the last undo-action.

- save position:
  up to 5 positions can be stored.  You can jump to this positions by activating
  the next menu item.

- goto position:
  jumps to up to 5 saved text positions

- goto byte:
  with this you can jump to a specified byte in the hex or ascii area.  You have to
  enter the address in a requester.
  This can be done in different ways:
  - by entering the $ sign first, you can enter the address in hexadecimal format
  - otherwise you enter the address in decimal format
  - entering a + or - before you can jump relative to the actual byte

- insert byte:
  in front of the actual byte a new byte will be inserted.  Therefore the cursor
  must be in the hex area.
  ATTENTION: doing this with programs they normally cannot be started anymore.
  Therefore a safety requester appears before the action will be done.

- delete byte:
  the actual byte will be deleted.  Therefore the cursor must be in the hex area.
  ATTENTION: doing this with programs they normally cannot be started anymore.
  Therefore a safety requester appears before the action will be done.

- Convert Hex-Dec:
  With this, numbers can be converted from one format to another.  There are the
  following possibilities:
  - enter a single char: this will be considered as an ASCII char.  The decimal
    value, hexadecimal value and the char equivalent will be displayed.
  - enter two or more digits (e.g. 02): this will be considered as a decimal number.
    The decimal value, hexadecimal value and the char equivalent will be displayed.
  - enter $ followed by hex digits: this will be considered as a hexadecimal number.
    The decimal value, hexadecimal value and the char equivalent will be displayed.


  @{" Back " link Menu}

@endnode
@node SUCHEN "Search"

   @{b}Menu Search@{ub}


- search file:
  you can search for a file (see manual for GoldED)

- search hex bytes:
  a sequence of hex bytes will be searched for.  You have to enter the search
  string in a requester.  All digits and the letters a ... f in small or capital
  letters are allowed.  If search wildcards is on also the question mark can be
  entered.  As a maximum 16 bytes (= 32 chars) can be entered each byte-wise.
  After confirmation with <OK> the hex area will be searched in downward direction
  for the byte sequence.  If a byte sequence is found, the cursor will be put to
  the start point of it.  The entered search string will be saved and used as
  default value for the next search action.

- search again hex bytes:
  a sequence of hex bytes will be searched also.  But this cannot be entered here,
  because the last entered string will be used as search string.  This will only
  function the correct way, when the last search was a hex search.

- search ASCII:
  a sequence of ASCII chars will be searched for.  You have to enter the search
  string in a requester.  All digits, all small or capital letters, space and most
  of the special chars are allowed.  If search wildcards is on the question mark
  has the special function of a wildcard.  As a maximum 16 chars can be entered.
  After confirmation with <OK> the ASCII area will be searched in downward direction
  for the char sequence.  If a char sequence is found, the cursor will be put to
  the start point of it.  The entered search string will be saved and used as
  default value for the next search action.

- search again ASCII:
  a sequence of chars will be searched also.  But this cannot be entered here,
  because the last entered string will be used as search string.  This will only
  function the correct way, when the last search was an ASCII search.

- replace hex bytes:
  This is an extension for the function search hex bytes.  When a sequence of hex
  bytes was found, a replacing sequence of hex bytes can be entered.  With this
  the original byte sequence will be replaced.  The replacing sequence of hex
  bytes must be the same length as the searched sequence of hex bytes.  The
  question mark may not be entered as a wildcard for the replacing sequence.  The
  sequences entered for searching and replacing will be stored and used as default
  value for the next action.
  After replacing a requester appeares, where you can decide to replace all search
  sequences by the replace sequence in the remaining file or to stop the action.
  During the replace action will be done in the remaining file, pushing the <CTRL> key
  will stop the action.

- replace ASCII:
  This is an extension for the function search ASCII.  When a sequence of chars
  was found, a replacing sequence of chars can be entered.  With this the original
  char sequence will be replaced.  The replacing sequence of chars must be the
  same length as the searched sequence of chars.  The question mark may not be
  entered as a wildcard.  The sequences entered for searching and replacing will
  be stored and used as default value for the next action.
  After replacing a requester appeares, where you can decide to replace all search
  sequences by the replace sequence in the remaining file or to stop the action.
  During the replace action will be done in the remaining file, pushing the <CTRL> key
  will stop the action.

- different capital/small case:
  if this menu item is marked searching for capital letters is not the same as
  searching for small letters ASCII area and in the Hex area.

- with wildcard:
  if this menu item is marked, you can enter wildcards for searching.  This means
  you can enter the char <?> instead of any char. The first char and/or byte may
  not be a wildcard.


  @{" Back " link Menu}

@endnode
@node OPTIONEN "Options"

   @{b}Menu Options@{ub}


- Toolbar:
  switches the toolbar on or off

- change options:
  change global and local options (see manual for GoldED)


  @{" Back " link Menu}

@endnode
@node HILFE "Help"

   @{b}Menu Help@{ub}


- Statistics:
  shows a requester with informations about the text statistics (see manual for GoldED)

- GED_Hexedit:
  shows this help file

- about this program:
  shows a requester with informations about GoldED


  @{" Back " link Menu}

@endnode
@node 4. "Function describtion"

   @{b}Describtion of the program functions@{ub}

This part deals with the internas of the progam.  Reading this part is not
absolutely necessary for operating the program.

The program is based on the editor GoldED by Dietmar Eilert.  This editor will be
changed by a new keyboard, menu, toolbar and syntax registry to work with
hexadecimal datas.  Furthermore most actions will be done by ARexx programs.
The necessary files will be copied during installation process to the directory
GOLDED:add-ons/hex and its sub directories.
Furthermore, the commands of the programm GOLDED will be extended by an
API-Library of name <hexfunc.api>.

During loading a file the ARexx-Program <OpenAsHex.rexx> will be called.  This
program first makes a safety copy of the original file (original + extension .bak.hex).
This file will be saved in backup directory.  If this doesn't exist, the file will be
save in the directory of the original file.  After this the program <hexbin> is called
which prepares a temporary hex-coded file with name <t:gedhex> based on the original
file.  To ensure, that there are no texts displayed in a wrong way, the space in the
ASCII area will be displayed as code 160.  The prepared file will be loaded by the
editor.  Now the top display of the editor will be changed to show the correct file
name.  After this the temporary file will be deleted.

During a save process the file first will be saved in the normal displayed format.
After this, the file will be overwritten by an own save routine in the API-Library.
During this conversion from the hex display of the file into normal binary format
only the hex area will be considered.
If for any reason overwriting of the file by the save routine will be interrupted
there are two possibilities to reprovide the right file.

1. Open the wrong file in standard mode after restart of the editor.  Now enter
   the file type <HEX> in the requester <file properties>. After this it should
   be possible to save the file in the right format.

2. Direct way with the program <hexbin>:
   golded:add-ons/hex/hexbin h <wrong input file> <right output file>

When inserting a byte with the program <InsertByte.rexx> the actual line will be
splitted and a byte will be inserted.  Each last byte of a line will be inserted
as start of the next line, and so on.  This means, inserting a byte is slower the
more lines have to be worked with after the byte in the file.

When deleting a byte with the program <DeleteByte.rexx> the first byte from the
last line will be cut.  This will be added to the line before, from which again
the first byte will be cut.  This will be done up to the actual line.  This means,
deleting a byte is slower the more lines have to be worked with after the byte in
the file.

@ENDNODE

@node 5. "Description of API-Library"

   @{b}Description of API-Library@{ub}

The API-Library <hexfunc.api> has two functions:
- own save routing
- extension of the commands of the program GOLDED

The following commands will be added:

@{" HEXKEY " link Hexkey}

@{" HEXSEARCHASCII " link HexSearchAscii}

@{" HEXSEARCHHEX " link HexSearchHex}

@endnode

@node Hexkey "HEXKEY"

   @{b}Command HEXKEY@{ub}

With this command key input will be done.
If the command will be used without option, the cursor will be
moved to ensure, that it is in an allowed area.

Option KEYH/K: char for hex area
Option KEYA/K: char for ASCII area
Option KEYL/K: line with 32 chars for hex area
Option KEYC/K: control char
The following values are allowed for KEYC:
  TAB:   Change Hex-ASCII
  RIGHT: cursor 1 char right
  LEFT:  cursor 1 char left
  NEXT:  cursor 8 chars right
  PREV:  cursor 8 chars left

only the options KEYH and KEYA may be used together

  @{" Back " link 5.}

@endnode

@node HexSearchAscii "HEXSEARCHASCII"

   @{b}Command HEXSEARCHASCII@{ub}

With this command a char sequence in ASCII area will be searched for.

Option SEARCH/K:   search string
Option USECASE/S:  different capital and lower case
Option WILDCARD/S: ? is a wildcard for searching
Option NEXT/S:     before seaching the cursor will be move for 1 char
                   to the right


  @{" Back " link 5.}

@endnode

@node HexSearchHex "HEXSEARCHHEX"

   @{b}Command HEXSEARCHHEX@{ub}

With this command a byte sequence in hex area will be searched for.

Option SEARCH/K:   search string
Option USECASE/S:  different capital and lower case
Option WILDCARD/S: ? is a wildcard for searching
Option NEXT/S:     before seaching the cursor will be move for 1 byte
                   to the right

  @{" Back " link 5.}

@endnode

@NODE 6. "Known bugs"

@{B}    Known bugs and disadvantages:
@{UB}
As the pograms is based on Arexx-macros, the operation speed is slow, especially
at Amigas with no turbo cards.
This mainly is the case at insert and delete of bytes operations.

The own save routine gets a signal at every save of a file.
Then it compares, wheather the full filename of the respective hex file is the same
as the full filename of the file saved.  If this is the case, the save routine will
be started.
This means when the same file is open in hex mode and in normal mode, and you save the
file in normal mode this file will be replaced by the file in hex mode.

The program always uses overwrite mode, even if this is not shown in the
title bar.

After undo and redo the cursor is not always at the right location in the text.

In the AREXX macros not all possible errors are catched.

@ENDNODE


@node 7. "History"

@{B}    History:
@{UB}

Version 0.8: (07/12/97) first version, upload to Aminet

Version 0.9: (11/13/97) second version, upload to Aminet
The following has been changed:
- now there can be spaces in the filename
- for a better overview in the hex area, spaces between long words were added
- search in hex and ASCII area was added
- the Arexx scripts were packed with the program Rexxopt of Ulrich Sibiller
- small changes
Thank you very much to Mario Kemper for his bug reports!

Version 1.0: (01/02/98) third version, upload to Aminet
The following things have been changed:
- the macro hexchar.ged for processing the key inputs will be copied to t:,
  for a faster access time (t: normally is in RAM)
- removed a bug in the macro hexchar.ged at displaying in the ASCII area
- changed and extended menu
- all keys used and/or not usefull keys blocked (hopefully)
- the hex-file is write-protected now.  Therefore when pushing the close gadget
  you are not requested to save (tip by Dietmar Eilert)
- syntay parser added (received from Dietmar Eilert)
  (thanks to Dietmar Eilert for his support)
- new functions added (save as, goto byte, seach with wildcard, replace, insert
  and delete Byte)
- extended the guide

Version 1.1: (07/12/99) forth version, upload to Aminet
The following things have been changed:
- syntax parser suitable for GOLDED 5+ written
- ARexx scripts added in unpacked form, because they are not much slower
- program changed to suit to GOLDED 5+
- small changes

Version 1.2: (10/01/99) fifth version, upload to Aminet
The following things have been changed:
- API-Library with some commands and a save routine written
  - this means a faster text input, as no AREXX macros are needed
  - seaching for char sequences is included in the API-Library, resulting
    in a much faster search operation
  - by using the own save routine (thanks to Dietmar Eilert for his help)
    the special operations during closing the file and quitting the editor
    are not more necessary
- changed the program <hexbin>, to ensure that also small files (<=16 bytes)
  can be read without errors (thanks to Christian Sauer for his bug report)
- extended the mouse operation, so that only allowed position can be clicked
- changed the macro <GotoByte> to allow the operation also in the ASCII area.
  Furthermore, by preceiding the value with a + or - it will jump relative
  to the actual byte.
- changed the macros <SearchByte> and <SearchASCII> to allow replacing in the
  whole file.
- changed the macros <DeleteByte> and <InsertByte> to get a faster operation
  by using the new command HEXKEY.
- AREXX macro <TransHexDez.rexx> added, for conversion of numbers in different
  formats.
- change the AREXX macros, so that the same macros can be used for german and
  english
- The chars <"> and <'> are now shown in the ASCII area and you can enter them.
  Replacing with these chars is not possible.
- New syntax parser written, suitable for Golded  version 6.2.0 and above. Starting
  with version 6.2.0 the new parser will be installed, otherwise the old parser
  will be installed.
- extended the guide
- small changes

Version 1.3: (12/11/99) sixth version, upload to Aminet
The following things have been changed:
- changed the macro <OpenAsHex.rexx> to save the backup file into backup directory
  (if it exists)
- removed bugs and changed macro <TransHexDez.rexx>
- removed bugs and changed macro <SearchAscii.rexx>.  As replacement string you
  can now enter all chars.
- adapted the guide
- small changes

Future:
the following is planned for the future:
- small extensions
- eventually an ASCII table in an own window
- solve errors in the program (if possible)
  things mentioned under <known bugs> normally will stay
- suit GED-Hexedit to new versions of GOLDED

@endnode

@NODE 8. "Copyright"

@{B}    Copyright:
@{UB}
This program is freeware.  It may be distributed free, as long as all files
are included without changes.  Distribution of the program at shareware CDs
and shareware discs is allowed.  A further commercial use of the program
without my allowance is not permitted.

You use the program at your own risc.  As the author of the program I am
not responsible for any damage caused by use of the program. Consider,
that bugs in the program are always possible.

If you want any improvements or have bug reports you are encouraged to
sent it to me.

@ENDNODE

@NODE 9. "Author"

@{B}    Name and address of the author:
@{UB}
   Wolfgang Morgeneier
   Kurfuerstenstr. 22
   D-92637 Weiden
   Germany

   EMail: Wolfgang.Morgeneier@t-online.de

@ENDNODE