Fix many MarkDown issues in {NOTES*,README*,HACKING,LICENSE}.md files

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)

6 files changed, 162 insertions, 150 deletions

diff --git a/crypto/README-sparse_array.md b/crypto/README-sparse_array.md
index d86a48d9e1..bc2ff0cb8a 100644
--- a/crypto/README-sparse_array.md
+++ b/crypto/README-sparse_array.md
@@ -1,4 +1,7 @@
-The sparse_array.c file contains an implementation of a sparse array that
+Sparse Arrays
+=============
+
+The `sparse_array.c` file contains an implementation of a sparse array that
 attempts to be both space and time efficient.
 
 The sparse array is represented using a tree structure.  Each node in the
@@ -13,13 +16,14 @@ There are a number of parameters used to define the block size:
     SA_BLOCK_MAX_LEVELS     Indicates the maximum possible height of the tree
 
 These constants are inter-related:
+
     SA_BLOCK_MAX        = 2 ^ OPENSSL_SA_BLOCK_BITS
     SA_BLOCK_MASK       = SA_BLOCK_MAX - 1
     SA_BLOCK_MAX_LEVELS = number of bits in size_t divided by
                           OPENSSL_SA_BLOCK_BITS rounded up to the next multiple
                           of OPENSSL_SA_BLOCK_BITS
 
-OPENSSL_SA_BLOCK_BITS can be defined at compile time and this overrides the
+`OPENSSL_SA_BLOCK_BITS` can be defined at compile time and this overrides the
 built in setting.
 
 As a space and performance optimisation, the height of the tree is usually
@@ -67,7 +71,6 @@ brevity):
         +----+
     Index 0
 
-
 Inserting at element 2N+1 creates a new root node and pushes down the old root
 node.  It then creates a second second level node to hold the pointer to the
 user's new data:
@@ -102,7 +105,6 @@ user's new data:
         +----+                         +----+
     Index 0                       Index 2N+1
 
-
 The nodes themselves are allocated in a sparse manner.  Only nodes which exist
 along a path from the root of the tree to an added leaf will be allocated.
 The complexity is hidden and nodes are allocated on an as needed basis.
@@ -144,12 +146,11 @@ result in:
                                        +----+
                                   Index 2N+1
 
-
 Accesses to elements in the sparse array take O(log n) time where n is the
-largest element.  The base of the logarithm is SA_BLOCK_MAX, so for moderately
+largest element.  The base of the logarithm is `SA_BLOCK_MAX`, so for moderately
 small indices (e.g. NIDs), single level (constant time) access is achievable.
 Space usage is O(minimum(m, n log(n)) where m is the number of elements in the
 array.
 
-Note: sparse arrays only include pointers to types.  Thus, SPARSE_ARRAY_OF(char)
-can be used to store a string.
+Note: sparse arrays only include pointers to types.
+Thus, `SPARSE_ARRAY_OF(char)` can be used to store a string.
diff --git a/crypto/engine/README.md b/crypto/engine/README.md
index 0f8a8fbde4..b45115ca24 100644
--- a/crypto/engine/README.md
+++ b/crypto/engine/README.md
@@ -1,12 +1,12 @@
-Notes: 2001-09-24
------------------
+Notes on engines of 2001-09-24
+==============================
 
 This "description" (if one chooses to call it that) needed some major updating
 so here goes. This update addresses a change being made at the same time to
 OpenSSL, and it pretty much completely restructures the underlying mechanics of
 the "ENGINE" code. So it serves a double purpose of being a "ENGINE internals
 for masochists" document *and* a rather extensive commit log message. (I'd get
-lynched for sticking all this in CHANGES or the commit mails :-).
+lynched for sticking all this in CHANGES.md or the commit mails :-).
 
 ENGINE_TABLE underlies this restructuring, as described in the internal header
 "eng_local.h", implemented in eng_table.c, and used in each of the "class" files;
@@ -21,16 +21,16 @@ or can be loaded "en masse" into EVP storage so that they can be catalogued and
 searched in various ways, ie. two ways of encrypting with the "des_cbc"
 algorithm/mode pair are;
 
-(i) directly;
-     const EVP_CIPHER *cipher = EVP_des_cbc();
-     EVP_EncryptInit(&ctx, cipher, key, iv);
-     [ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...]
+    (i) directly;
+         const EVP_CIPHER *cipher = EVP_des_cbc();
+         EVP_EncryptInit(&ctx, cipher, key, iv);
+         [ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...]
 
-(ii) indirectly;
-     OpenSSL_add_all_ciphers();
-     cipher = EVP_get_cipherbyname("des_cbc");
-     EVP_EncryptInit(&ctx, cipher, key, iv);
-     [ ... etc ... ]
+    (ii) indirectly;
+         OpenSSL_add_all_ciphers();
+         cipher = EVP_get_cipherbyname("des_cbc");
+         EVP_EncryptInit(&ctx, cipher, key, iv);
+         [ ... etc ... ]
 
 The latter is more generally used because it also allows ciphers/digests to be
 looked up based on other identifiers which can be useful for automatic cipher
@@ -177,7 +177,7 @@ is deliberately a distinct step. Moreover, registration and unregistration has
 nothing to do with whether an ENGINE is *functional* or not (ie. you can even
 register an ENGINE and its implementations without it being operational, you may
 not even have the drivers to make it operate). What actually happens with
-respect to cleanup is managed inside eng_lib.c with the "engine_cleanup_***"
+respect to cleanup is managed inside eng_lib.c with the `engine_cleanup_***`
 functions. These functions are internal-only and each part of ENGINE code that
 could require cleanup will, upon performing its first allocation, register a
 callback with the "engine_cleanup" code. The other part of this that makes it
@@ -208,4 +208,3 @@ hooking of ENGINE is now automatic (and passive, it can internally use a NULL
 ENGINE pointer to simply ignore ENGINE from then on).
 
 Hell, that should be enough for now ... comments welcome.
-
diff --git a/crypto/err/README.md b/crypto/err/README.md
index 6d2ce0cd0e..78085b3779 100644
--- a/crypto/err/README.md
+++ b/crypto/err/README.md
@@ -1,17 +1,17 @@
 Adding new libraries
---------------------
+====================
 
 When adding a new sub-library to OpenSSL, assign it a library number
-ERR_LIB_XXX, define a macro XXXerr() (both in err.h), add its
-name to ERR_str_libraries[] (in crypto/err/err.c), and add
-ERR_load_XXX_strings() to the ERR_load_crypto_strings() function
-(in crypto/err/err_all.c). Finally, add an entry:
+`ERR_LIB_XXX`, define a macro `XXXerr()` (both in `err.h`), add its
+name to `ERR_str_libraries[]` (in `crypto/err/err.c`), and add
+`ERR_load_XXX_strings()` to the `ERR_load_crypto_strings()` function
+(in `crypto/err/err_all.c`). Finally, add an entry:
 
     L      XXX     xxx.h   xxx_err.c
 
-to crypto/err/openssl.ec, and add xxx_err.c to the Makefile.
-Running make errors will then generate a file xxx_err.c, and
-add all error codes used in the library to xxx.h.
+to `crypto/err/openssl.ec`, and add `xxx_err.c` to the `Makefile`.
+Running make errors will then generate a file `xxx_err.c`, and
+add all error codes used in the library to `xxx.h`.
 
 Additionally the library include file must have a certain form.
 Typically it will initially look like this:
@@ -33,12 +33,12 @@ Typically it will initially look like this:
 
     /* BEGIN ERROR CODES */
 
-The BEGIN ERROR CODES sequence is used by the error code
+The `BEGIN ERROR CODES` sequence is used by the error code
 generation script as the point to place new error codes, any text
 after this point will be overwritten when make errors is run.
-The closing #endif etc will be automatically added by the script.
+The closing `#endif` etc will be automatically added by the script.
 
-The generated C error code file xxx_err.c will load the header
-files stdio.h, openssl/err.h and openssl/xxx.h so the
+The generated C error code file `xxx_err.c` will load the header
+files `stdio.h`, `openssl/err.h` and `openssl/xxx.h` so the
 header file must load any additional header files containing any
 definitions it uses.
diff --git a/crypto/objects/README.md b/crypto/objects/README.md
index 700f9c5e54..49c749887d 100644
--- a/crypto/objects/README.md
+++ b/crypto/objects/README.md
@@ -1,44 +1,43 @@
 objects.txt syntax
-------------------
+==================
 
-To cover all the naming hacks that were previously in objects.h needed some
-kind of hacks in objects.txt.
+To cover all the naming hacks that were previously in `objects.h` needed some
+kind of hacks in `objects.txt`.
 
 The basic syntax for adding an object is as follows:
 
-	1 2 3 4		: shortName	: Long Name
+        1 2 3 4         : shortName     : Long Name
 
-		If Long Name contains only word characters and hyphen-minus
-		(0x2D) or full stop (0x2E) then Long Name is used as basis
-		for the base name in C. Otherwise, the shortName is used.
+                If Long Name contains only word characters and hyphen-minus
+                (0x2D) or full stop (0x2E) then Long Name is used as basis
+                for the base name in C. Otherwise, the shortName is used.
 
-		The base name (let's call it 'base') will then be used to
-		create the C macros SN_base, LN_base, NID_base and OBJ_base.
+                The base name (let's call it 'base') will then be used to
+                create the C macros SN_base, LN_base, NID_base and OBJ_base.
 
-		Note that if the base name contains spaces, dashes or periods,
-		those will be converted to underscore.
+                Note that if the base name contains spaces, dashes or periods,
+                those will be converted to underscore.
 
 Then there are some extra commands:
 
-	!Alias foo 1 2 3 4
+        !Alias foo 1 2 3 4
 
-		This just makes a name foo for an OID.  The C macro
-		OBJ_foo will be created as a result.
+                This just makes a name foo for an OID.  The C macro
+                OBJ_foo will be created as a result.
 
-	!Cname foo
+        !Cname foo
 
-		This makes sure that the name foo will be used as base name
-		in C.
+                This makes sure that the name foo will be used as base name
+                in C.
 
-	!module foo
-	1 2 3 4		: shortName	: Long Name
-	!global
+        !module foo
+        1 2 3 4         : shortName     : Long Name
+        !global
 
-		The !module command was meant to define a kind of modularity.
-		What it does is to make sure the module name is prepended
-		to the base name.  !global turns this off.  This construction
-		is not recursive.
+                The !module command was meant to define a kind of modularity.
+                What it does is to make sure the module name is prepended
+                to the base name.  !global turns this off.  This construction
+                is not recursive.
 
-Lines starting with # are treated as comments, as well as any line starting
+Lines starting with `#` are treated as comments, as well as any line starting
 with ! and not matching the commands above.
-
diff --git a/crypto/perlasm/README.md b/crypto/perlasm/README.md
index 59f2c95515..912dac7f07 100644
--- a/crypto/perlasm/README.md
+++ b/crypto/perlasm/README.md
@@ -1,124 +1,130 @@
+Perl scripts for assembler sources
+==================================
+
 The perl scripts in this directory are my 'hack' to generate
 multiple different assembler formats via the one original script.
 
 The way to use this library is to start with adding the path to this directory
 and then include it.
 
-push(@INC,"perlasm","../../perlasm");
-require "x86asm.pl";
+    push(@INC,"perlasm","../../perlasm");
+    require "x86asm.pl";
 
 The first thing we do is setup the file and type of assembler
 
-&asm_init($ARGV[0]);
+    &asm_init($ARGV[0]);
 
 The first argument is the 'type'.  Currently
-'cpp', 'sol', 'a.out', 'elf' or 'win32'.
-Argument 2 is the file name.
+`cpp`, `sol`, `a.out`, `elf` or `win32`.
+The second argument is the file name.
 
 The reciprocal function is
-&asm_finish() which should be called at the end.
+`&asm_finish()` which should be called at the end.
 
-There are 2 main 'packages'. x86ms.pl, which is the Microsoft assembler,
-and x86unix.pl which is the unix (gas) version.
+There are two main 'packages'. `x86ms.pl`, which is the Microsoft assembler,
+and `x86unix.pl` which is the unix (gas) version.
 
 Functions of interest are:
-&external_label("des_SPtrans");	declare and external variable
-&LB(reg);			Low byte for a register
-&HB(reg);			High byte for a register
-&BP(off,base,index,scale)	Byte pointer addressing
-&DWP(off,base,index,scale)	Word pointer addressing
-&stack_push(num)		Basically a 'sub esp, num*4' with extra
-&stack_pop(num)			inverse of stack_push
-&function_begin(name,extra)	Start a function with pushing of
-				edi, esi, ebx and ebp.  extra is extra win32
-				external info that may be required.
-&function_begin_B(name,extra)	Same as normal function_begin but no pushing.
-&function_end(name)		Call at end of function.
-&function_end_A(name)		Standard pop and ret, for use inside functions
-&function_end_B(name)		Call at end but with pop or ret.
-&swtmp(num)			Address on stack temp word.
-&wparam(num)			Parameter number num, that was push
-				in C convention.  This all works over pushes
-				and pops.
-&comment("hello there")		Put in a comment.
-&label("loop")			Refer to a label, normally a jmp target.
-&set_label("loop")		Set a label at this point.
-&data_word(word)		Put in a word of data.
+
+    &external_label("des_SPtrans");  declare and external variable
+    &LB(reg);                        Low byte for a register
+    &HB(reg);                        High byte for a register
+    &BP(off,base,index,scale)        Byte pointer addressing
+    &DWP(off,base,index,scale)       Word pointer addressing
+    &stack_push(num)                 Basically a 'sub esp, num*4' with extra
+    &stack_pop(num)                  inverse of stack_push
+    &function_begin(name,extra)      Start a function with pushing of
+                                     edi, esi, ebx and ebp. extra is extra win32
+                                     external info that may be required.
+    &function_begin_B(name,extra)    Same as normal function_begin but no
+                                     pushing.
+    &function_end(name)              Call at end of function.
+    &function_end_A(name)            Standard pop and ret, for use inside
+                                     functions.
+    &function_end_B(name)            Call at end but with pop or ret.
+    &swtmp(num)                      Address on stack temp word.
+    &wparam(num)                     Parameter number num, that was push in
+                                     C convention.  This all works over pushes
+                                     and pops.
+    &comment("hello there")          Put in a comment.
+    &label("loop")                   Refer to a label, normally a jmp target.
+    &set_label("loop")               Set a label at this point.
+    &data_word(word)                 Put in a word of data.
 
 So how does this all hold together?  Given
 
-int calc(int len, int *data)
-	{
-	int i,j=0;
+    int calc(int len, int *data)
+    {
+        int i,j=0;
 
-	for (i=0; i<len; i++)
-		{
-		j+=other(data[i]);
-		}
-	}
+        for (i=0; i<len; i++)
+        {
+            j+=other(data[i]);
+        }
+    }
 
 So a very simple version of this function could be coded as
 
-	push(@INC,"perlasm","../../perlasm");
-	require "x86asm.pl";
-	
-	&asm_init($ARGV[0]);
+    push(@INC,"perlasm","../../perlasm");
+    require "x86asm.pl";
+
+    &asm_init($ARGV[0]);
 
-	&external_label("other");
+    &external_label("other");
 
-	$tmp1=	"eax";
-	$j=	"edi";
-	$data=	"esi";
-	$i=	"ebp";
+    $tmp1=   "eax";
+    $j=      "edi";
+    $data=   "esi";
+    $i=      "ebp";
 
-	&comment("a simple function");
-	&function_begin("calc");
-	&mov(	$data,		&wparam(1)); # data
-	&xor(	$j,		$j);
-	&xor(	$i,		$i);
+    &comment("a simple function");
+    &function_begin("calc");
+    &mov(    $data,     &wparam(1)); # data
+    &xor(    $j,        $j);
+    &xor(    $i,        $i);
 
-	&set_label("loop");
-	&cmp(	$i,		&wparam(0));
-	&jge(	&label("end"));
+    &set_label("loop");
+    &cmp(    $i,        &wparam(0));
+    &jge(    &label("end"));
 
-	&mov(	$tmp1,		&DWP(0,$data,$i,4));
-	&push(	$tmp1);
-	&call(	"other");
-	&add(	$j,		"eax");
-	&pop(	$tmp1);
-	&inc(	$i);
-	&jmp(	&label("loop"));
+    &mov(    $tmp1,     &DWP(0,$data,$i,4));
+    &push(   $tmp1);
+    &call(   "other");
+    &add(    $j,        "eax");
+    &pop(    $tmp1);
+    &inc(    $i);
+    &jmp(    &label("loop"));
 
-	&set_label("end");
-	&mov(	"eax",		$j);
+    &set_label("end");
+    &mov(    "eax",     $j);
 
-	&function_end("calc");
+    &function_end("calc");
 
-	&asm_finish();
+    &asm_finish();
 
 The above example is very very unoptimised but gives an idea of how
 things work.
 
 There is also a cbc mode function generator in cbc.pl
 
-&cbc(	$name,
-	$encrypt_function_name,
-	$decrypt_function_name,
-	$true_if_byte_swap_needed,
-	$parameter_number_for_iv,
-	$parameter_number_for_encrypt_flag,
-	$first_parameter_to_pass,
-	$second_parameter_to_pass,
-	$third_parameter_to_pass);
+    &cbc($name,
+         $encrypt_function_name,
+         $decrypt_function_name,
+         $true_if_byte_swap_needed,
+         $parameter_number_for_iv,
+         $parameter_number_for_encrypt_flag,
+         $first_parameter_to_pass,
+         $second_parameter_to_pass,
+         $third_parameter_to_pass);
 
 So for example, given
-void BF_encrypt(BF_LONG *data,BF_KEY *key);
-void BF_decrypt(BF_LONG *data,BF_KEY *key);
-void BF_cbc_encrypt(unsigned char *in, unsigned char *out, long length,
-        BF_KEY *ks, unsigned char *iv, int enc);
 
-&cbc("BF_cbc_encrypt","BF_encrypt","BF_encrypt",1,4,5,3,-1,-1);
+    void BF_encrypt(BF_LONG *data,BF_KEY *key);
+    void BF_decrypt(BF_LONG *data,BF_KEY *key);
+    void BF_cbc_encrypt(unsigned char *in, unsigned char *out, long length,
+                        BF_KEY *ks, unsigned char *iv, int enc);
 
-&cbc("des_ncbc_encrypt","des_encrypt","des_encrypt",0,4,5,3,5,-1);
-&cbc("des_ede3_cbc_encrypt","des_encrypt3","des_decrypt3",0,6,7,3,4,5);
+    &cbc("BF_cbc_encrypt","BF_encrypt","BF_encrypt",1,4,5,3,-1,-1);
 
+    &cbc("des_ncbc_encrypt","des_encrypt","des_encrypt",0,4,5,3,5,-1);
+    &cbc("des_ede3_cbc_encrypt","des_encrypt3","des_decrypt3",0,6,7,3,4,5);
diff --git a/crypto/property/README.md b/crypto/property/README.md
index b3f56cfa2f..9d97a69873 100644
--- a/crypto/property/README.md
+++ b/crypto/property/README.md
@@ -1,4 +1,8 @@
-Properties are associated with algorithms and are used to select between different implementations dynamically.
+Selecting algorithm implementations by properties
+=================================================
+
+Properties are associated with algorithms and are used to select between
+different implementations dynamically.
 
 This implementation is based on a number of assumptions:
 
@@ -23,7 +27,6 @@ This implementation is based on a number of assumptions:
 
 * Property queries can never add new property definitions.
 
-
 Some consequences of these assumptions are:
 
 * That definition is uncommon and queries are very common, we can treat
@@ -52,14 +55,15 @@ Some consequences of these assumptions are:
   properties are changed as doing so removes the need to index on both the
   global and requested property strings.
 
-
 The implementation:
 
-* property_lock.c contains some wrapper functions to handle the global
+* [property_lock.c](property_lock.c)
+  contains some wrapper functions to handle the global
   lock more easily.  The global lock is held for short periods of time with
   per algorithm locking being used for longer intervals.
 
-* property_string.c contains the string cache which converts property
+* [property_string.c](property_string.c)
+  contains the string cache which converts property
   names and values to small integer indices.  Names and values are stored in
   separate hash tables.  The two Boolean values, the strings "yes" and "no",
   are populated as the first two members of the value table.  All property
@@ -67,13 +71,15 @@ The implementation:
   provided to convert from an index back to the original string (this can be
   done by maintaining parallel stacks of strings if required).
 
-* property_parse.c contains the property definition and query parsers.
+* [property_parse.c](property_parse.c)
+  contains the property definition and query parsers.
   These convert ASCII strings into lists of properties.  The resulting
   lists are sorted by the name index.  Some additional utility functions
   for dealing with property lists are also included: comparison of a query
   against a definition and merging two queries into a single larger query.
 
-* property.c contains the main APIs for defining and using properties.
+* [property.c](property.c)
+  contains the main APIs for defining and using properties.
   Algorithms are discovered from their NID and a query string.
   The results are cached.
 
@@ -82,6 +88,7 @@ The implementation:
   without bounds and must garbage collect under-used entries.  The garbage
   collection does not have to be exact.
 
-* defn_cache.c contains a cache that maps property definition strings to
+* [defn_cache.c](defn_cache.c)
+  contains a cache that maps property definition strings to
   parsed properties.  It is used by property.c to improve performance when
   the same definition appears multiple times.