\documentclass[12pt]{article}
\title{Using Heck\\or Heckin' to the Oldies}
\author{Jason Killen\\killen@lssi.net}
\begin{document}
\maketitle

Heck stands for Hex Editor Care of Killen.  Heck allows the user to display 
and edit a file in a number of different formats.  Heck also allows editing of 
two different files at once and placing these files into ``lockstep'' allowing 
the user to move through both files at once.

\section{In The Beginning}
The first time starting Heck you will be asked a series of questions.  
Answering these questions allows you to associate the functions with keys
on the keyboard and tailor how Heck acts to your own personal preferences.

The first question you will be asked is if you want the default keymap.  The
suggestion here is to answer ``yes'' and read up on the default key map, see 
section \ref{Default Keymap}.  If you answer no you will be
prompted with a function description.  Once you have decided which key to
map this function to just press that key.  This goes on for a while.  After 
you have configured the keymap will be given the description
of a Heck option.  When you pick how you want Heck to behave just press the
corresponding number.  After answering a few of these type questions Heck will
startup with the file you defined.

\section{Command Line Options}
Heck understands a very small but very useful set of command line options.

\subsection{Keytest}
\label{Keytest}
If you are editing your config file by hand and are not sure what hex code 
some key maps to then say \verb#heck -kt#.  Heck will print out the hex code
of the next key pressed in a format ready for your config file.

Heck also accepts \verb#-keytest#, \verb#--keytest#, and \verb#--kt#.

\subsection{Line Drawing}
When Heck is run it decides if it should allow curses to pick the character
which is used when drawing borders around the window or if Heck should use 
something safe.  (The decision is made depending on the os you are running.) 
If you do not like what Heck has decided you can run Heck with either
\verb#-ll# or \verb#-cl#.  The \verb#-ll# option tells Heck to choose the 
safe characters to draw the lines.  The \verb#-cl# option tells Heck to let 
curses pick the characters.  The option \verb#-ll# can also be typed 
\verb#-locallines# \verb#--ll#, or \verb#--locallines#.  The option \verb#-cl# 
can also be typed \verb#-curseslines#, \verb#--cl#, or \verb#--curseslines#.

\section{The Config File}
One of the greatest things about Heck is the fact that almost everything is
configurable.  The format of the config file may seem odd at first but with
a little instruction things should fall into place.  The config file is kept 
in \verb#~/.heckrc#. There are basically two types of things that can
be configured when using Heck.  One is the keymap the second are a set of
options.  By defining the keymap the user can assign any of Hecks many 
functions to any key they wish.  The setting of options allows a user to
control how Heck acts in certain circumstances.

\subsection{Defining Keys}
The syntax for defining keys is pretty simple.  Here it is:
\begin{verbatim}
    key keycode function
\end{verbatim}

The only keyword in this statement is \verb#key#.  The variable \verb#keycode# 
can be defined in a few different ways.  One way is just by using the printable
character. For example:
\begin{verbatim}
    key k line_up 
\end{verbatim}

A second way is by putting in the hex code generated by the key pressed.  
(It should be noted that defining keys in this fashion is os dependent.)
If you need some help in finding the hex code for a key on your keyboard
see section \ref{Keytest}.
An example:
\begin{verbatim}
    key 0c lockstep 
\end{verbatim}

The third way of defining keys in the keymap allows defining of control keys
without needing to know the hex code.  When defining a control key the user
can simply use \verb#^# and the letter.  For example:
\begin{verbatim}
    key ^v goto_eof 
\end{verbatim}

\subsection{Setting Options}
The syntax for defining an option in Heck looks like this:
\begin{verbatim}
    optionclass option value
\end{verbatim}

These words probably do not make sense right now so I will try to explain them.

The variable \verb#optionclass# is used to tell Heck what area of the program
this options has to do with. Here is a list of the valid values for 
\verb#optionclass#. 
\begin{verbatim}
    lockstep
    edit
    help
    display
    format
\end{verbatim}

The variable \verb#option# defines which option you are setting.  (This means 
that more than one \verb#option# can be defined for an \verb#optionclass#.) 

The variable \verb#value# is the value which you wish to set the \verb#option#
to.  

Here are a few examples to help:
\begin{verbatim}
    lockstep scroll tight
    edit modal on
    help help_type jason
    help line off
    display byte_count hex
    format irf H E
\end{verbatim}

An in depth explanation of the configurable options can be found in section \ref{Options}.

\subsection{Notes On The Config File}
\begin{list}{-}{}
\item The keymap may also be changed through the help menu, see \ref{Changing The Keymap Through Help}.

\item The variable \verb#function# in the original example is any of the 
functions supported by Heck, see \ref{List Of Kable Key Functions}.

\item An in depth explanation of the configurable options can be found in section \ref{Options}.
\end{list}

\subsection{An Example Config File}
\begin{verbatim}
lockstep scroll tight
edit modal on
help help_type jason
key 0c lockstep
key n search_next
key s search
key 0a next_file
key 09 next_win
key k line_up
key j line_down
key h one_left
key l one_right
key q quit
key 12 redraw
key g goto
key f format
key d lockstep_diff
key i begin_modal_edit
key 1b stop_modal_edit
key x count_match
key 109 help
key 09 next_win
key k line_up
key j line_down
key h one_left
key l one_right
key q quit
key 12 redraw
key g goto
key f format
key d lockstep_diff
key i begin_modal_edit
key 1b stop_modal_edit
key x count_match
key 109 help
key 16 goto_eof
key 02 goto_bof
key 107 backspace
key 1b cancel
key 09 change_selection
key . load_format
\end{verbatim}

\section{Getting Help With Your Problem}
\label{Changing The Keymap Through Help}
If you have a question or run into a problem the first place you should go is
to the help menu.  To get there just press the key mapped to the function
\verb#help#.  This will bring up a list of functions supported by Heck.  
To navigate downward through the list use either the key mapped to 
\verb#line_down# or \verb#change_selection#.  To navigate upward press the key 
mapped to \verb#line_up#.  When you find the function you want to learn more 
about press enter.  This will bring up a window which describes the function, 
tells you which key this function is mapped to, and allows you to change the
key this function is mapped to (the \it{}change key\rm{}).  To quit the 
description window just press any key other than the \it{}change key\rm{}.
If the \it{}change key\rm{} is pressed the next key pressed will become 
mapped the the given function.  Changes made to the keymap while using Heck 
are saved when the editor is exited from.

\subsection{Using The Help Line}
\label{Using The Help Line}
Defining a help line allows the user to define a number of lines at the bottom
of the screen to be used for displaying some part of the keymap.  The default
help line displays the keys used to change the format of the current window, 
search for a string, and quit.  To use the default keymap just add \verb#help line on# to your config file.  If you would like to configure the help line to
display more or less of the keymap use this format \verb#help line on numlines formatstring#.  Where \verb#numlines# is some integer greater than 0.  The \verb#formatstring# is basically a list of which functions you want the key displayed for with \verb#\n# appearing when you would like to move to the next line down. If more lines are defined in \verb#numlines# than are used in 
\verb#formatstring# then blank lines are left after the displayed help line.  
If more lines are defined in \verb#formatstring# than are defined in 
\verb#numlines# the extra parts of \verb#formatstring# are ignored. Here is an
example:
\begin{verbatim}
help line on 3 LS S \n Q G \n F
\end{verbatim}
As you probably can figure out this defines three lines at the bottom of the
screen the first line displaying the key mapped to \verb#lockstep# and 
\verb#search#, the second line \verb#quit# and \verb#goto#, the last line 
\verb#format#.

Here is what it looks like:
\begin{verbatim}
  Enter/Exit Lockstep: ^L  Search: s
  Quit: q  Goto: g
  Format: f
\end{verbatim}

To find out what belongs in \verb#formatstring# for the function you want either
look at the help for that function or reference section \ref{Help Line Function Definitions}.

\subsection{Notes On Getting Help}
\begin{list}{-}{}
\item Changing the key mapped to \verb#help# will change the \it{}change 
key\rm{}.
\end{list}


\section{Option Descriptions}
\label{Options}
\subsection{Option Class format}
Using the \verb#display# option allows you to tell Heck that when it is run
on a file with a certain extension display that file in the format you specify.
For example if you wanted Heck to always open files with \verb#.txt# at the 
end of the filename in hex and ASCII then you would add:
\verb#format txt H A# to your config file.  (You can always change the format
of the file you are looking at using the \verb#format# function.)

The characters which define each format are as follows:
\begin{verbatim}
    A - ASCII
    C - ASCII
    H - hex
    D - decimal
    E - EBCDIC
    O - octal
\end{verbatim}

\subsection{Option Class lockstep}
The currently supported options for optionclass \verb#lockstep# are: 
\begin{verbatim}
    scroll
\end{verbatim}

The valid values for \verb#scroll# are \verb#tight# and \verb#sloppy#.  Using 
\verb#tight# means that when operating in lockstep mode (see \ref{Lockstep}) 
if the beginning or end of either file is reached then scrolling in that 
direction is not allowed.  Using \verb#sloppy# means that when operating in 
lockstep mode (see \ref{Lockstep}) if the beginning or end of either file is 
reached scrolling for the file which is not at the end continues leaving the 
other file at the end (or beginning).

\subsection{Option Class edit}
The currently supported options for optionclass \verb#edit# are:
\begin{verbatim}
    modal
\end{verbatim}

The valid values for \verb#modal# are \verb#on# and \verb#off#.  If you are not
familiar with the long running \verb#vi# \it{}vs.\rm{} \verb#emacs# war then
this option may not make much sense to you.  When \verb#modal# is \verb#on#
editing is done apart from movement, formatting, and the like. Editing mode 
must be entered into and out of.  When \verb#modal# is \verb#off# editing is
done without pressing keys to bring the editor into and out of editing mode.
Both ways of working have their advantages.  When \verb#modal# is \verb#off#
all functions must be mapped to special keys (control, function, etc.).  When
\verb#modal# is \verb#on# functions may be mapped to regular keys but to 
edit a special key must be pressed then you must go back to ``function mode''
before performing any functions.  (The creator of this article would like to
take this moment to put in a plug for vi.)

\subsection{Option Class help}
The currently supported options for optionclass \verb#help# are:
\begin{verbatim}
    help_type
    line
\end{verbatim}

The valid values for \verb#help_type# are \verb#jason# and \verb#dave#.  I'll
spare you the story explaining the need for this option and just explain the 
differences.  In \verb#jason# mode a single line is highlighted.  Using the 
functions \verb#line_up#, \verb#line_down#, or \verb#change_selection# move 
the list of help items around the highlighted line.  In \verb#dave# mode the 
hi-light moves through the list.

The valid values for \verb#line# are \verb#on# and \verb#off#.  Having 
\verb#line# on means that at the bottom of the screen a list of most used
functions and the key they are mapped to will be displayed.  The user can
change the help line to meet their preferences, see section \ref{Using The Help Line}.

\subsection{Option Class display}
The currently supported options for optionclass \verb#display# are:
\begin{verbatim}
    byte_count
\end{verbatim}

The valid values for \verb#byte_count# are \verb#hex#, \verb#oct#, and
\verb#dec#.  The option \verb#byte_count# allows the user to define how the
byte counter in the lower left of the file window is displayed.  The count is
displayed in hexadecimal when option \verb#hex# is used, octal when option 
\verb#oct#, and decimal when option \verb#dec# is used.

\section{Using Lockstep}
\label{Lockstep}
When Heck is run with two files on the command line
you will notice that each file is opened in its own window (you can switch
windows using the \verb#next_file# function).  Placing the two files into 
lockstep, using the  \verb#lockstep# function, means that each movement
of the cursor (up, down, right, or left) will be reflected in both files.
You will also notice when lockstep is entered into two lines will appear
in the middle of the screen.  These two lines allow you to watch the ``active''
byte of each file without having to move your eyes very much.  As you move 
through the files the bytes in the middle of the screen change to reflect
the movement.  When lockstep is entered into the matching movements begin
at the ``active'' byte of each file.  This allows you to compare a different
part of each file using lockstep.

\subsection{Notes on using lockstep}
\begin{list}{-}{}
\item Not all functions are avalible while in lockstep, in particular editing
\item Searching in lockstep is for the current file only
\item The function \verb#lockstep_diff# finds the first difference between the two files
\end{list}

\section{List Of Kable Key Functions}
\label{List Of Kable Key Functions}

\subsection{lockstep}
Lockstep is explained in section \ref{Lockstep}.

\subsection{search\_next}
Find the next occurrence of the string searched for.

\subsection{search}
Search for some string.  The search string is expected to be formatted using the
same format as the current window.  For example if the current window is 
displaying the file in hex then the search string is expected to be entered as
hex.  The current format can be seen in the search window between square 
brackets.

\subsection{next\_file}
When Heck was started with two files on the command line using this function
moves to the next file.

\subsection{next\_win}
Using this function moves to the other display of the current file.

\subsection{line\_up}
Moves the cursor one line up.

\subsection{line\_down}
Moves the cursor one line down.

\subsection{one\_left}
Moves the cursor one byte to the left.

\subsection{one\_right}
Moves the cursor one byte to the right.

\subsection{quit}
Exits Heck.

\subsection{redraw}
Re-draws the screen

\subsection{goto}
Allows you to move to a certain byte in the file.  When \verb#Byte 0# is 
selected Heck moves to the byte entered.  When \verb#Here# is selected Heck
moves to the current byte plus the number entered.

The entered number is handled as hex if it starts with \verb#0x#, as octal if
it starts with \verb#0#, and decimal otherwise.

\subsection{format}
Allows you to change the format which the data is displayed in.  You can move 
through the list of formats by pressing the \verb#change_selection# key or you
can pick a format by pressing the key corresponding to the first letter of
the display type you desire.

\subsection{lockstep\_diff}
Finds the first difference between two files when in lockstep.

\subsection{begin\_modal\_edit}
Begin editing the current file.

\subsection{stop\_modal\_edit}
Stop editing the current file.

\subsection{count\_match}
Count the number of matches to the current search string.

\subsection{help}
Displays a list of help items.  Move through the list using the \verb#line_up#, 
\verb#line_down#, or \verb#change_selection#. 

\subsection{goto\_eof}
Move to the end of the file.

\subsection{goto\_bof}
Move to the beginning of the file.

\subsection{backspace}
Backup over a character you have typed.  This is used in places like the 
\verb#search# and \verb#goto# windows.

\subsection{cancel}
Stop doing what you are doing.  Use this to cancel out of functions like 
\verb#search# and \verb#goto#.

\subsection{change\_selection}
Pressing this allows you to change a hi-lighted item.  This function is mainly
used in \verb#help#, \verb#format#, and \verb#goto#.

\subsection{load\_format}
This is unused right now but could do great things in the future.

\section{Default Keymap}
\label{Default Keymap}
\begin{verbatim}
lockstep = ^L
search_next = n
search = s
next_file = return key
next_win = tab key
line_up = up arrow key
line_down = down arrow key
one_left = left arrow key
one_right = right arrow key
quit = q
redraw = ^R
goto = g
format = f
lockstep_diff = d
begin_modal_edit = i
stop_modal_edit = esc key
count_match = x
help = F1 key
goto_eof = ^B
goto_bof = ^V
backspace = backspace key
cancel = esc key
change_selection = tab key
load_format = .
page_up = page up key
page_down = page down key
\end{verbatim}

\section{Help Line Function Definitions}
\label{Help Line Function Definitions}
\begin{verbatim}
lockstep = LS
search_next = SN
search = S
next_file = NF
next_win = NW
line_up = U
line_down = D
one_left = L
one_right = R
quit = Q
redraw = R
goto = G
format = F
lockstep_diff = LD
begin_modal_edit = BME
stop_modal_edit = EME
count_match = CM
help = H
goto_eof = EOF
goto_bof = BOF
backspace = BSP
cancel = C
change_selection = CS
load_format = LF
page_up = PGU
page_down = PGD
\end{verbatim}

\section{The End}
Heck was written mostly from the need for a hex editor that understands EBCDIC.
It has grown into what I hope is a useful program.
I would like to thank everyone who helped including Scot C., Dave, and Brook.

\end{document}
