diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 247 |
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 |