Imported Upstream version 0.65upstream/0.65

1 files changed, 247 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..4c61f21
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,247 @@
+-----------------------------------------------------------------[ 0. Welcome ]-
+
+Thank you for downloading dhex 0.63. It is a hex editor with a diff mode.
+Since it is based on ncurses, it runs in any console.
+It makes heavy use of colors, but it is themeable to run on monochrome-displays
+as well.
+
+If you have any questions, or found any bugs, please do not hesitate to contact
+me under dettus@dettus.net. Be sure to include "DHEX" somewhere in the subject.
+
+
+Thomas Dettbarn, 30-Dec-2010
+
+0.60: Initial release
+0.61: Some code cleanup, rudementary manual correlation is possible through 
+      commandline parameters
+0.62: Code cleanup, bug fixes, and as new features: bookmarks and ascii-search.
+0.63: Man pages were written, searching is possible from the command line.
+0.64: Naive correlation, a new default theme
+0.65: dhex 0.64 crashed at startup on some systems.
+
+---------------------------------------------------------[ 1. Getting started ]-
+
+Download the latest version from http://www.dettus.net/dhex/dhex_latest.tar.gz.
+Unpack it,
+
+% tar xvfz dhex_latest.tar.gz
+
+then compile it
+
+% make
+
+This should produce an executable. It requires a file as a paramter to start
+
+% ./dhex gpl.txt
+
+When starting for the first time, dhex will attempt to create a .dhexrc file 
+in your $HOME-directory. If you already have a .dhexrc from an older version of
+dhex, it will convert it. 
+
+
+The first screen you'll see will be the keyboard setup. (I was not satisfied 
+with the way ncurses handled the function keys, so i created something new)
+The keyboard setup will be written into the .dhexrc file.
+
+
+You can edit the file, search for short strings in it, and scroll through it.
+After pressing F10 (or whichever key you pressed instead of F10 during the 
+keyboard setup), dhex will ask you whether or not to save the changes.
+
+
+To invode the keyboard setup manually, just start dhex with the parameter -k
+
+% ./dhex -k gpl.txt
+
+
+
+---------------------------------------------------------------[ 2. Diff mode ]-
+
+
+When you run dhex with two files, 
+
+% ./dhex gpl.txt dhex
+
+it will start in the diff mode. This is useful for file comparison. Any 
+difference in the files will be highlighted. To jump from one difference to 
+the next, press F3. To go to the previous one, press F4.
+
+
+--------------------------------------------------------------------[ 3. Goto ]-
+
+Pressing F1 will open up the "Goto" dialog. Here you have three possibilities:
+Pressing = will set the cursor to the absolute address you're about to type in,
+Pressing + will advance the cursors those many bytes,
+Pressing - will go back those many bytes.
+
+Press "Go" to set the cursor, or "Cancel" to quit the dialog.
+
+
+Moreover, you can set up to ten bookmarks here. And save them for later use.
+
+
+
+---------------------------------------------------------------[ 4. Searching ]-
+
+When not in diff mode, pressing F2 will invoke the "Search" dialog. You can
+search forward or backward. When selecting the "Writelog" option, you'll have
+to provide a filename to write the search results to. 
+Later, when you select the "Readlog" option, it'll read the cursor positions 
+where to search from this file. Otherwise dhex will search the whole file.
+
+When not selecting the "Writelog" option, the search dialog will immediately
+close upon finding the first occuracnce, and set the cursor there.
+
+Press F3 to go to the next occurace, or F4 to the previous one.
+
+Searching is also possible from the command line: Simply apply the -sa, -sab, 
+-sh, -shb parameters. To write into a searchlog, -w is the parameter to go. To 
+read from it, -r can be used. For example
+
+% ./dhex -oh affe -shb d00f dhex
+
+sets the cursor to 0xaffe, and searches for the hex string "d0 0f" backwards 
+from there.
+
+% ./dhex -oh affe -shb d00f -w occurances.log dhex 
+
+writes the results into a logfile called "occurances.log" and exits.
+
+-----------------------------------------------------------------[ 5. Hexcalc ]-
+
+Pressing F5 will open up the hexcalc dialog. This is a small 64-bit calculator.
+Simply type in a value in one of the formats "decimal", "hexadecimal" or
+"binary", chose an operation, press ENTER and see the results.
+You can select any former result by going up a few lines with the cursor keys.
+
+
+
+------------------------------------------------------------[ 6. config-files ]-
+
+The default config file is $HOME/.dhexrc. Another config file can be chosen
+with the -f option:
+
+% ./dhex -f /etc/globaldhexrc gpl.txt
+
+Basically, a config file is broken down into two sections: Colors and keyboard
+conversion tab. The default config file on a MacBook looks like this:
+
+DHEXCOLORSCHEME
+#VERSION 0
+#possible colors are: BLACK,GREEN,GREEN,YELLOW,BLUE,MAGENTA,CYAN,BLACK
+#possible extra flags are: UNDERLINE,REVERSE,BLINK,DIM,BOLD
+
+BRACKETS:       FG=BLACK,BG=BLACK,BOLD
+HEXFIELD:       FG=WHITE,BG=BLACK
+INPUT:          FG=BLACK,BG=WHITE
+CURSOR:         FG=WHITE,BG=BLACK
+TEXT:           FG=WHITE,BG=BLACK,BOLD
+MENU_NORMAL:    FG=CYAN,BG=BLACK
+MENU_HIGHLIGHT: FG=BLACK,BG=CYAN
+MENU_HOTKEY:    FG=YELLOW,BG=BLACK,BOLD
+MENU_HOTKEY_HI: FG=YELLOW,BG=CYAN,BOLD
+FRAME:          FG=BLUE,BG=BLACK,BOLD
+NORMAL_DIFF:    FG=YELLOW,BG=BLACK
+CURSOR_DIFF:    FG=YELLOW,BG=WHITE,BOLD
+HEADLINE:       FG=BLUE,BG=BLACK,BOLD
+	
+KEYF1:c2 a1 
+KEYF2:e2 84 a2 
+KEYF3:c2 a3 
+KEYF4:c2 a2 
+KEYF5:e2 88 9e 
+KEYF6:c2 a7 
+KEYF7:c2 b6 
+KEYF8:e2 80 a2 
+KEYF9:c2 aa 
+KEYF10:c2 ba 
+KEYESC:1b 
+KEYBACKSPACE:08 
+KEYDEL:1b 
+KEYENTER:0a 
+KEYTAB:09 
+KEYUP:1b 5b 41 
+KEYDOWN:1b 5b 42 
+KEYRIGHT:1b 5b 43 
+KEYLEFT:1b 5b 44 
+KEYPGUP:02 
+KEYPGDOWN:06 
+KEYHOME:5e 
+KEYEND:24 
+
+(Actually, in this example ALT+1, ALT+2, ALT+3,... ALT+0 were used instead of 
+F1..F10) You can edit it with any texteditor you like.
+
+
+
+--------------------------------------[ 7. Correlating two files in diff mode ]-
+
+Lets assume you would like to compare two files. One of those files starts with
+garbage at the beginning:
+
+  file1: GARBAGE0123456789ABCDEF
+  file2:        0123456789ABCDEF
+
+GARBAGE has 7 letters, so to skip over the first 7 bytes in the first file, just
+apply the following paramters:
+
+% dhex -o1d 7 file1 file2
+
+-o sets the cursor offset. -o1 means that the first buffer is affected. -o1d 
+gives the radix for the offset. it can either be -o1d for decimal, -o1b for
+binary, -o1h for hexadecimal or -o1o for octal.
+
+If the garbage is in the second file, just use
+
+% dhex -o2d 7 file1 file2
+
+Since version 0.64 there is also a way of doing this automatically: Pressing
+F6 in the GUI will open up a dialog where you can select one of three
+correlation algorithms. They are painfully slow, but they'll do the job.
+Those three algorithms are:
+
+- best match
+  move the two files in such a way that as many bytes match as possible
+- longest match
+  move the two files in such a way that as many consecutive bytes match as
+  possible
+- minimum diff
+  move the two files in such a way that as little bytes differ as possible. This
+  algorithm requires an upper limit to improve its speed.
+
+To invoke correlation from the command line, use one of these
+
+% dhex -cb file1 file2  # best match
+% dhex -cl file1 file2  # longest match
+% dhex -cd 1000 file1 file2 # minimum difference, with the upper limit of 1000.
+  
+
+
+--------------------------------------------------------------[ 8. Disclaimer ]-
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+--------------------------------------------------------------[ 9. Known bugs ]-
+
+- Searching has not been thourughly tested.
+- Code is not clean (yet)
+- Searching is only possible in normal mode, not diff mode
+- Searching ignores unsaved changes.
+- Some features are missing
+- -k expects a file to be opened
+- -f might overwrite ANY file.
+- GOTO can jump way behind the end of the file
+- some ways of exiting won't free all the allocated buffers