Merge pull request #5539

3f612cda Changed odd bullet point to low level header (Rohaq)
af9bc4ec Used subeaders to avoid slightly wonky looking formatting (Rohaq)
1873af35 Made code block usage consistent across all .md files (Rohaq)
68103075 Updated Copyright notice (Rohaq)
39bd157f Added Table of Contents to main README.md (Rohaq)

3 files changed, 138 insertions, 108 deletions

diff --git a/contrib/depends/README.md b/contrib/depends/README.md
index c9f8b0783..6a15055b4 100644
--- a/contrib/depends/README.md
+++ b/contrib/depends/README.md
@@ -2,21 +2,29 @@
 
 To build dependencies for the current arch+OS:
 
-    make
+```bash
+make
+```
 
 To build for another arch/OS:
 
-    make HOST=host-platform-triplet
+```bash
+make HOST=host-platform-triplet
+```
 
 For example:
 
-    make HOST=x86_64-w64-mingw32 -j4
+```bash
+make HOST=x86_64-w64-mingw32 -j4
+```
 
 A toolchain will be generated that's suitable for plugging into Monero's
 cmake. In the above example, a dir named x86_64-w64-mingw32 will be
 created. To use it for Monero:
 
-    cmake -DCMAKE_TOOLCHAIN=`pwd`/contrib/depends/x86_64-w64-mingw32
+```bash
+cmake -DCMAKE_TOOLCHAIN=`pwd`/contrib/depends/x86_64-w64-mingw32
+```
 
 Common `host-platform-triplets` for cross compilation are:
 
@@ -31,20 +39,24 @@ No other options are needed, the paths are automatically configured.
 Dependency Options:
 The following can be set when running make: make FOO=bar
 
-    SOURCES_PATH: downloaded sources will be placed here
-    BASE_CACHE: built packages will be placed here
-    SDK_PATH: Path where sdk's can be found (used by OSX)
-    FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up
-    DEBUG: disable some optimizations and enable more runtime checking
-    HOST_ID_SALT: Optional salt to use when generating host package ids
-    BUILD_ID_SALT: Optional salt to use when generating build package ids
+```
+SOURCES_PATH: downloaded sources will be placed here
+BASE_CACHE: built packages will be placed here
+SDK_PATH: Path where sdk's can be found (used by OSX)
+FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up
+DEBUG: disable some optimizations and enable more runtime checking
+HOST_ID_SALT: Optional salt to use when generating host package ids
+BUILD_ID_SALT: Optional salt to use when generating build package ids
+```
 
 Additional targets:
 
-    download: run 'make download' to fetch all sources without building them
-    download-osx: run 'make download-osx' to fetch all sources needed for osx builds
-    download-win: run 'make download-win' to fetch all sources needed for win builds
-    download-linux: run 'make download-linux' to fetch all sources needed for linux builds
+```
+download: run 'make download' to fetch all sources without building them
+download-osx: run 'make download-osx' to fetch all sources needed for osx builds
+download-win: run 'make download-win' to fetch all sources needed for win builds
+download-linux: run 'make download-linux' to fetch all sources needed for linux builds
+```
 
 #Darwin (macos) builds:
 
diff --git a/contrib/depends/packages.md b/contrib/depends/packages.md
index 7c8036250..ae5b47327 100644
--- a/contrib/depends/packages.md
+++ b/contrib/depends/packages.md
@@ -9,39 +9,43 @@ General tips:
 ## Identifiers
 Each package is required to define at least these variables:
 
-    $(package)_version:
-    Version of the upstream library or program. If there is no version, a
-    placeholder such as 1.0 can be used.
+```
+$(package)_version:
+Version of the upstream library or program. If there is no version, a
+placeholder such as 1.0 can be used.
 
-    $(package)_download_path:
-    Location of the upstream source, without the file-name. Usually http or
-    ftp.
+$(package)_download_path:
+Location of the upstream source, without the file-name. Usually http or
+ftp.
 
-    $(package)_file_name:
-    The upstream source filename available at the download path.
+$(package)_file_name:
+The upstream source filename available at the download path.
 
-    $(package)_sha256_hash:
-    The sha256 hash of the upstream file
+$(package)_sha256_hash:
+The sha256 hash of the upstream file
+```
 
 These variables are optional:
 
-    $(package)_build_subdir:
-    cd to this dir before running configure/build/stage commands.
-    
-    $(package)_download_file:
-    The file-name of the upstream source if it differs from how it should be
-    stored locally. This can be used to avoid storing file-names with strange
-    characters.
-    
-    $(package)_dependencies:
-    Names of any other packages that this one depends on.
-    
-    $(package)_patches:
-    Filenames of any patches needed to build the package
-
-    $(package)_extra_sources:
-    Any extra files that will be fetched via $(package)_fetch_cmds. These are
-    specified so that they can be fetched and verified via 'make download'.
+```
+$(package)_build_subdir:
+cd to this dir before running configure/build/stage commands.
+
+$(package)_download_file:
+The file-name of the upstream source if it differs from how it should be
+stored locally. This can be used to avoid storing file-names with strange
+characters.
+
+$(package)_dependencies:
+Names of any other packages that this one depends on.
+
+$(package)_patches:
+Filenames of any patches needed to build the package
+
+$(package)_extra_sources:
+Any extra files that will be fetched via $(package)_fetch_cmds. These are
+specified so that they can be fetched and verified via 'make download'.
+```
 
 
 ## Build Variables:
@@ -49,47 +53,55 @@ After defining the main identifiers, build variables may be added or customized
 before running the build commands. They should be added to a function called
 $(package)_set_vars. For example:
 
-    define $(package)_set_vars
-    ...
-    endef
+```
+define $(package)_set_vars
+...
+endef
+```
 
 Most variables can be prefixed with the host, architecture, or both, to make
 the modifications specific to that case. For example:
 
-    Universal:     $(package)_cc=gcc
-    Linux only:    $(package)_linux_cc=gcc
-    x86_64 only:       $(package)_x86_64_cc = gcc
-    x86_64 linux only: $(package)_x86_64_linux_cc = gcc
+```
+Universal:     $(package)_cc=gcc
+Linux only:    $(package)_linux_cc=gcc
+x86_64 only:       $(package)_x86_64_cc = gcc
+x86_64 linux only: $(package)_x86_64_linux_cc = gcc
+```
 
 These variables may be set to override or append their default values.
 
-    $(package)_cc
-    $(package)_cxx
-    $(package)_objc
-    $(package)_objcxx
-    $(package)_ar
-    $(package)_ranlib
-    $(package)_libtool
-    $(package)_nm
-    $(package)_cflags
-    $(package)_cxxflags
-    $(package)_ldflags
-    $(package)_cppflags
-    $(package)_config_env
-    $(package)_build_env
-    $(package)_stage_env
-    $(package)_build_opts
-    $(package)_config_opts
-
-The *_env variables are used to add environment variables to the respective
+```
+$(package)_cc
+$(package)_cxx
+$(package)_objc
+$(package)_objcxx
+$(package)_ar
+$(package)_ranlib
+$(package)_libtool
+$(package)_nm
+$(package)_cflags
+$(package)_cxxflags
+$(package)_ldflags
+$(package)_cppflags
+$(package)_config_env
+$(package)_build_env
+$(package)_stage_env
+$(package)_build_opts
+$(package)_config_opts
+```
+
+The `*_env` variables are used to add environment variables to the respective
 commands.
 
 Many variables respect a debug/release suffix as well, in order to use them for
 only the appropriate build config. For example:
 
-    $(package)_cflags_release = -O3
-    $(package)_cflags_i686_debug = -g
-    $(package)_config_opts_release = --disable-debug
+```
+$(package)_cflags_release = -O3
+$(package)_cflags_i686_debug = -g
+$(package)_config_opts_release = --disable-debug
+```
 
 These will be used in addition to the options that do not specify
 debug/release. All builds are considered to be release unless DEBUG=1 is set by
@@ -97,51 +109,57 @@ the user. Other variables may be defined as needed.
 
 ## Build commands:
 
-  For each build, a unique build dir and staging dir are created. For example,
-  `work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`.
+For each build, a unique build dir and staging dir are created. For example,
+`work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`.
+
+The following build commands are available for each recipe:
 
-  The following build commands are available for each recipe:
+```
+$(package)_fetch_cmds:
+Runs from: build dir
+Fetch the source file. If undefined, it will be fetched and verified
+against its hash.
 
-    $(package)_fetch_cmds:
-    Runs from: build dir
-    Fetch the source file. If undefined, it will be fetched and verified
-    against its hash.
+$(package)_extract_cmds:
+Runs from: build dir
+Verify the source file against its hash and extract it. If undefined, the
+source is assumed to be a tarball.
 
-    $(package)_extract_cmds:
-    Runs from: build dir
-    Verify the source file against its hash and extract it. If undefined, the
-    source is assumed to be a tarball.
+$(package)_preprocess_cmds:
+Runs from: build dir/$(package)_build_subdir
+Preprocess the source as necessary. If undefined, does nothing.
 
-    $(package)_preprocess_cmds:
-    Runs from: build dir/$(package)_build_subdir
-    Preprocess the source as necessary. If undefined, does nothing.
+$(package)_config_cmds:
+Runs from: build dir/$(package)_build_subdir
+Configure the source. If undefined, does nothing.
 
-    $(package)_config_cmds:
-    Runs from: build dir/$(package)_build_subdir
-    Configure the source. If undefined, does nothing.
+$(package)_build_cmds:
+Runs from: build dir/$(package)_build_subdir
+Build the source. If undefined, does nothing.
 
-    $(package)_build_cmds:
-    Runs from: build dir/$(package)_build_subdir
-    Build the source. If undefined, does nothing.
+$(package)_stage_cmds:
+Runs from: build dir/$(package)_build_subdir
+Stage the build results. If undefined, does nothing.
+```
 
-    $(package)_stage_cmds:
-    Runs from: build dir/$(package)_build_subdir
-    Stage the build results. If undefined, does nothing.
+The following variables are available for each recipe:
 
-  The following variables are available for each recipe:
-    
-    $(1)_staging_dir: package's destination sysroot path
-    $(1)_staging_prefix_dir: prefix path inside of the package's staging dir
-    $(1)_extract_dir: path to the package's extracted sources
-    $(1)_build_dir: path where configure/build/stage commands will be run
-    $(1)_patch_dir: path where the package's patches (if any) are found
+```    
+$(1)_staging_dir: package's destination sysroot path
+$(1)_staging_prefix_dir: prefix path inside of the package's staging dir
+$(1)_extract_dir: path to the package's extracted sources
+$(1)_build_dir: path where configure/build/stage commands will be run
+$(1)_patch_dir: path where the package's patches (if any) are found
+```
 
 Notes on build commands:
 
-For packages built with autotools, $($(package)_autoconf) can be used in the
+For packages built with autotools, `$($(package)_autoconf)` can be used in the
 configure step to (usually) correctly configure automatically. Any
-$($(package)_config_opts) will be appended.
+`$($(package)_config_opts`) will be appended.
 
 Most autotools projects can be properly staged using:
 
-    $(MAKE) DESTDIR=$($(package)_staging_dir) install
+```bash
+$(MAKE) DESTDIR=$($(package)_staging_dir) install
+```
diff --git a/contrib/gitian/README.md b/contrib/gitian/README.md
index b869bde87..1efc87e0a 100644
--- a/contrib/gitian/README.md
+++ b/contrib/gitian/README.md
@@ -119,7 +119,7 @@ In order to sign gitian builds on your host machine, which has your PGP key,
 fork the gitian.sigs repository and clone it on your host machine, 
 or pass the signed assert file back to your build machine.
 
-```
+```bash
 git clone git@github.com:monero-project/gitian.sigs.git
 git remote add fluffypony git@github.com:fluffypony/gitian.sigs.git
 ```
@@ -156,9 +156,9 @@ git push --set-upstream $NAME v0.14.0
 ```
 
 ```bash
-    gpg --detach-sign ${VERSION}-linux/${SIGNER}/monero-linux-*-build.assert
-    gpg --detach-sign ${VERSION}-win-unsigned/${SIGNER}/monero-win-*-build.assert
-    gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert
+gpg --detach-sign ${VERSION}-linux/${SIGNER}/monero-linux-*-build.assert
+gpg --detach-sign ${VERSION}-win-unsigned/${SIGNER}/monero-win-*-build.assert
+gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert
 ```
 
 More Build Options