README updates

3 files changed, 68 insertions, 61 deletions

diff --git a/README.md b/README.md
index 7177ea0..c0f85a5 100644
--- a/README.md
+++ b/README.md
@@ -2,57 +2,67 @@
 
 Simple AES implementation and utilities.
 
-## Building
+## Development
 
-To build the project:
+### Prerequisites
 
-1. generate the solution aes_tools.sln using CMake,
-2. build the solution using Visual Studio.
+* Boost.Filesystem, Boost.Program_options and Boost.System
 
-Some of the [utilities] also depend on a few Boost libraries.
-In particular, Boost.Filesystem, Boost.Program\_options, and Boost.System must
-be built prior to building these utilities.
-To enable CMake to find Boost libraries, pass the path to the root Boost
-directory like this:
+### Building the utilities
 
-    > cmake -D BOOST_ROOT=C:\workspace\third-party\boost_1_58_0 ...
+Create the build files using CMake and build using your native build tools
+(Visual Studio/make/etc.).
 
-Remember that in order to link to the static Boost libraries, you also have to
-pass `-D Boost_USE_STATIC_LIBS=ON` to CMake.
+For example, using Visual Studio 2013 Update 4 for Windows Desktop (targetting
+x86 and using static Boost libraries):
+
+    > cd
+    C:\workspace\personal\build\aes-tools
+
+    > cmake -G "Visual Studio 12 2013" ^
+        -D BOOST_ROOT=C:\workspace\third-party\boost_1_58_0 ^
+        -D Boost_USE_STATIC_LIBS=ON ^
+        C:\workspace\personal\aes-tools
+    ...
+
+    > msbuild aes-tools.sln
+    ...
 
 ## Usage on older CPUs
 
-To run the executables that are using the AES-NI instruction set on a CPU w/o
-the support for these instructions, you can use [Intel Software Development
-Emulator].
+To run the executables that are using the AES-NI instruction set on a CPU
+without the support for these instructions, you can use [Intel Software
+Development Emulator].
 After you install the emulator, you can run an executable like this:
 
     > sde -- encrypt_block.exe -a aes128 -m ecb -- 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff
     69c4e0d86a7b0430d8cdb78070b4c55a
 
+[Intel Software Development Emulator]: https://software.intel.com/en-us/articles/intel-software-development-emulator
+
 ## Documentation
 
 You can generate the docs using [Doxygen].
-The docs will be put to the `doc/` directory under the project's root.
+The docs will be generated in the "doc/" directory under the project's root.
+
+[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
 
 ## Utilities
 
 See [Utilities].
 
+[Utilities]: utils/README.md
+
 ## Testing
 
 See [Testing].
 
+[Testing]: test/README.md
+
 ## License
 
 This project, including all of the files and their contents, is licensed under
 the terms of the MIT License.
 See [LICENSE.txt] for details.
 
-
-
 [LICENSE.txt]: LICENSE.txt
-[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
-[Intel Software Development Emulator]: https://software.intel.com/en-us/articles/intel-software-development-emulator
-[testing]: test/README.md
-[utilities]: utils/README.md
diff --git a/test/README.md b/test/README.md
index 6d7cc8b..db7a418 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,16 +1,21 @@
 # Testing
 
 Using the [utilities], you can validate the implementation either by providing
-an arbitrary set of inputs (see [manual testing]) or by using the test vectors
+an arbitrary set of inputs (see [Manual testing]) or by using the test vectors
 provided by various AES [validation programs].
 
 You can also test that [file encryption] works (at least to some extent).
 
+[utilities]: ../utils/README.md
+[Manual testing]: #manual-testing
+[Validation programs]: #validation-programs
+[File encryption]: #file-encryption
+
 ## Manual testing
 
 You can validate the implementation manually using the block
 encryption/decryption utilities `encrypt_block.exe` and `decrypt_block.exe`.
-Pass the `--help` parameter to examine the utility's usage info.
+Pass the `--help` flag to examine the utility's usage info.
 
     > encrypt_block.exe -a aes128 -m ecb -- 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff
     69c4e0d86a7b0430d8cdb78070b4c55a
@@ -26,7 +31,7 @@ Pass the `--help` parameter to examine the utility's usage info.
 A number of test vectors have been collected from various AES validation
 programs/reference implementations.
 
-The test scripts are written in Python 3 and are used in similar fashion:
+The test scripts are used in similar fashion:
 
 * they accept the path to the directory with the block encryption/decryption
   utilities,
@@ -46,6 +51,10 @@ To allow the utilities to be executed on older CPUs, pass the `--sde`
 parameter.
 Pass the `--help` parameter to see examine the script's usage info.
 
+### Prerequisites
+
+* Python (3.4 or higher)
+
 ### NIST Special Publication 800-38A
 
 To validate the implementation using the inputs from [NIST SP 800-38A], use
@@ -53,13 +62,17 @@ To validate the implementation using the inputs from [NIST SP 800-38A], use
 
     > nist-sp-800-38a.py -p C:\workspace\personal\build\aes-tools\utils\Debug
 
+[NIST SP 800-38A]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+
 ### Cryptographic Algorithm Validation Program
 
 To validate the implementation using the inputs from [CAVP], use `cavp.py`.
 
     > cavp.py -p C:\workspace\personal\build\aes-tools\utils\Debug
 
-The AES Known Answer Test (KAT) Vectors are used and read from `KAT_AES.zip`.
+The AES Known Answer Test (KAT) Vectors are used and read from "KAT_AES.zip".
+
+[CAVP]: http://csrc.nist.gov/groups/STM/cavp/
 
 ## File encryption
 
@@ -67,22 +80,14 @@ You can also test file encryption using `file.py`.
 Its interface and output is similar to the [validation programs] test scripts.
 The expected ciphertexts (for encryption) and plaintexts (for decryption),
 along with the keys and initialization vectors, are stored in the files under
-a separate directory (`file/` by default).
+a separate directory ("file/" by default).
 
 ## See also
 
-* [Building]
+* [Building the utilities]
 * [Usage on older CPUs]
 * [License]
 
-
-
-[building]: ../README.md#building
-[license]: ../README.md#license
-[usage on older cpus]: ../README.md#usage-on-older-cpus
-[utilities]: ../utils/README.md
-[manual testing]: #manual-testing
-[validation programs]: #validation-programs
-[file encryption]: #file-encryption
-[NIST SP 800-38A]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
-[CAVP]: http://csrc.nist.gov/groups/STM/cavp/
+[Building the utilities]: ../README.md#building-the-utilities
+[Usage on older CPUs]: ../README.md#usage-on-older-cpus
+[License]: ../README.md#license
diff --git a/utils/README.md b/utils/README.md
index 312c754..6bf52f6 100644
--- a/utils/README.md
+++ b/utils/README.md
@@ -1,21 +1,15 @@
 # Utilities
 
-A couple of useful utilities built on top of the library.
+A couple of useful utilities are built on top of the library.
 Each of the utilities accepts the `--help` flag, which can be used to examine
 the utility's usage info.
 
-The included utilities are:
-
-* [block encryption] utilities,
-* [file encryption] utilities,
-* and [bitmap encryption] utilities.
-
 ## Block encryption
 
 Block encryption utilities can produce verbose human-readable output, including
 round keys, intermediate initialization vector values, etc.
-Those are primarily intended for debugging purposes.
-Enable verbose output by passing the `--verbose` flag to a utilities.
+They are primarily intended for debugging purposes.
+Enable verbose output by passing the `--verbose` flag.
 Please note that verbose output can only be produced when *not* using the
 "boxes" interface (the `--use-boxes` flag).
 
@@ -136,30 +130,28 @@ Plaintext BMP    | Encrypted in ECB mode | Encrypted in CBC mode
 ---------------- | --------------------- | ---------------------
 ![butterfly.bmp] | ![cipherfly_ecb.bmp]  | ![cipherfly_cbc.bmp]
 
+[butterfly.bmp]: bmp/butterfly.bmp?raw=true
+[cipherfly_ecb.bmp]: bmp/cipherfly_ecb.bmp?raw=true
+[cipherfly_cbc.bmp]: bmp/cipherfly_cbc.bmp?raw=true
+
 ### encrypt_bmp.exe
 
 Encrypts the pixels in a BMP image file, preserving the header.
 The usage is the same as for [encrypt_file.exe].
 
+[encrypt_file.exe]: #encrypt_fileexe
+
 ### decrypt_bmp.exe
 
 Decrypts the pixels in a BMP image file, preserving the header.
 The usage is the same as for [decrypt_file.exe].
 
+[decrypt_file.exe]: #decrypt_fileexe
+
 ## See also
 
-* [Building]
+* [Building the utilities]
 * [License]
 
-
-
-[building]: ../README.md#building
-[license]: ../README.md#license
-[block encryption]: #block-encryption
-[file encryption]: #file-encryption
-[bitmap encryption]: #bitmap-encryption
-[encrypt_file.exe]: #encrypt_fileexe
-[decrypt_file.exe]: #decrypt_fileexe
-[butterfly.bmp]: bmp/butterfly.bmp?raw=true
-[cipherfly_ecb.bmp]: bmp/cipherfly_ecb.bmp?raw=true
-[cipherfly_cbc.bmp]: bmp/cipherfly_cbc.bmp?raw=true
+[Building the utilities]: ../README.md#building-the-utilities
+[License]: ../README.md#license