Docs: Rework README.md for improved readability

README

@@ -1,110 +1,103 @@
+# FUZZY HASHING API
 
-**** FUZZY HASHING API ****
-
-This file documents the fuzzy hashing API. Information on how to use the
-fuzzy hashing program ssdeep can be found in the man page. On *nix
-systems you can view this file with:
+This file documents the fuzzy hashing API. Information on how to use the fuzzy hashing program ssdeep can be found in the man page. On *nix systems you can view this file with:
 
+```console
 $ man ./ssdeep.1
+```
 
-Windows users can get the ssdeep usage information from README.TXT.
+Windows users can get the ssdeep usage information from `README.TXT`.
 
+---
 
-** Using the API in Your Own Progrms **
+## Using the API in Your Own Programs
 
-You can use the fuzzy hashing API in your own programs by doing 
-the following:
+You can use the fuzzy hashing API in your own programs by doing the following:
 
-1. Include the fuzzy hashing header
+### 1. Include the fuzzy hashing header
 
+```c
 #include <fuzzy.h>
+```
 
+### 2. Call one of the functions:
 
-2. Call one of the functions:
-
-* Fuzzy hashing a buffer of text:
+#### Fuzzy hashing a buffer of text:
 
+```c
 int fuzzy_hash_buf(const unsigned char *buf,
-		   uint32_t      buf_len,
-	           char          *result);
-
-This function computes the fuzzy hash of the buffer 'buf' and stores the
-result in result. You MUST allocate result to hold FUZZY_MAX_RESULT
-characters before calling this function. The length of the buffer should
-be passed in via buf_len. It is the user's responsibility to append the
-filename, if any, to the output. The function returns zero on success,
-one on error.
+                   uint32_t      buf_len,
+                   char          *result);
+```
 
+This function computes the fuzzy hash of the buffer `buf` and stores the result in `result`. You **MUST** allocate `result` to hold `FUZZY_MAX_RESULT` characters before calling this function. The length of the buffer should be passed in via `buf_len`. It is the user's responsibility to append the filename, if any, to the output. The function returns zero on success, one on error.
 
-* Fuzzy hashing a file:
+#### Fuzzy hashing a file:
 
-There are in fact two ways to fuzzy hash a file. If you already 
-have an open file handle you can use:
+There are in fact two ways to fuzzy hash a file. If you already have an open file handle you can use:
 
+```c
 int fuzzy_hash_file(FILE *handle,
-	            char *result);
+                    char *result);
+```
 
-This function computes the fuzzy hash of the file pointed to by handle
-and stores the result in result. You MUST allocate result to hold
-FUZZY_MAX_RESULT characters before calling this function. It is the 
-user's responsibility to append the filename to the output. 
-The function returns zero on success, one on error.
+This function computes the fuzzy hash of the file pointed to by `handle` and stores the result in `result`. You **MUST** allocate `result` to hold `FUZZY_MAX_RESULT` characters before calling this function. It is the user's responsibility to append the filename to the output. The function returns zero on success, one on error.
 
 The other function to hash a file takes a file name:
 
+```c
 int fuzzy_hash_filename(const char * filename,
-			char * result);
+                        char * result);
+```
 
-Like the function above, this function stores the fuzzy hash result
-in the parameter result. You MUST allocate result to hold 
-FUZZY_MAX_RESULT characters before calling this function.
+Like the function above, this function stores the fuzzy hash result in the parameter `result`. You **MUST** allocate `result` to hold `FUZZY_MAX_RESULT` characters before calling this function.
 
+#### Compare two fuzzy hash signatures:
 
-* Compare two fuzzy hash signatures:
-
+```c
 int fuzzy_compare(const char *sig1, const char *sig2);
+```
 
-This function returns a value from 0 to 100 indicating the match 
-score of the two signatures. A match score of zero indicates the \
-signatures did not match.
-
+This function returns a value from 0 to 100 indicating the match score of the two signatures. A match score of zero indicates the signatures did not match.
 
-3. Compile
+### 3. Compile
 
-To compile the program using gcc:
+#### To compile the program using gcc:
 
-   $ gcc -Wall -I/usr/local/include -L/usr/local/lib sample.c -lfuzzy
+```console
+$ gcc -Wall -I/usr/local/include -L/usr/local/lib sample.c -lfuzzy
+```
 
-Using mingw:
+#### Using mingw:
 
-   C:\> gcc -Wall -Ic:\path\to\includes sample.c fuzzy.dll
+```console
+C:\> gcc -Wall -Ic:\path\to\includes sample.c fuzzy.dll
+```
 
-Using Microsoft Visual C (MSVC):
+#### Using Microsoft Visual C (MSVC):
 
-To paraphrase the MinGW documentation, 
-http://www.mingw.org/mingwfaq.shtml#faq-msvcdll:
+To paraphrase the MinGW documentation, http://www.mingw.org/mingwfaq.shtml#faq-msvcdll:
 
-The Windows ssdeep package includes a Win32 DLL and a .def file. Although
-MSVC users can't use the DLL directly, they can easily create a .lib file
-using the Microsoft LIB tool:
+The Windows ssdeep package includes a Win32 DLL and a .def file. Although MSVC users can't use the DLL directly, they can easily create a .lib file using the Microsoft LIB tool:
 
-   C:\> lib /machine:i386 /def:fuzzy.def
+```console
+C:\> lib /machine:i386 /def:fuzzy.def
+```
 
 You can then compile your program using the resulting library:
 
-   C:\> cl sample.c fuzzy.lib
-
+```console
+C:\> cl sample.c fuzzy.lib
+```
 
+---
 
-** Sample Program **
-
-A sample program that uses the API is in sample.c. 
+## 💻 Sample Program
 
+A sample program that uses the API is in `sample.c`.
 
+---
 
-** See Also ** 
+## 📚 See Also
 
-- Jesse D. Kornblum, "Identifying almost identical files using context 
-triggered piecewise hashing", Digital Investigaton, 3(S):91-97, 
-September 2006, http://dx.doi.org/10.1016/j.diin.2006.06.015,
-The Proceedings of the 6th Annual Digital Forensic Research Workshop
+Jesse D. Kornblum, "Identifying almost identical files using context triggered piecewise hashing", Digital Investigation, 3(S):91-97, September 2006, http://dx.doi.org/10.1016/j.diin.2006.06.015, The Proceedings of the 6th Annual Digital Forensic Research Workshop.