aboutsummaryrefslogtreecommitdiffstats
path: root/README.txt
diff options
context:
space:
mode:
authorJonathan McCrohan <jmccrohan@gmail.com>2012-10-30 21:29:30 +0000
committerJonathan McCrohan <jmccrohan@gmail.com>2012-10-30 21:29:30 +0000
commit62f81e5cafbacfb90ac0f86e52e8e3176aa5ba8f (patch)
tree8f8f6028fa880b3296b1e42bc8d87cead73aaf78 /README.txt
downloaddhex-62f81e5cafbacfb90ac0f86e52e8e3176aa5ba8f.tar.gz
Imported Upstream version 0.65upstream/0.65
Diffstat (limited to 'README.txt')
-rw-r--r--README.txt247
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