Doc updates

3 files changed, 47 insertions, 7 deletions

diff --git a/doc/manual/building.rst b/doc/manual/building.rst
index 34d5a4fd4..cb450974b 100644
--- a/doc/manual/building.rst
+++ b/doc/manual/building.rst
@@ -237,12 +237,20 @@ target ``docs``.
 The Amalgamation Build
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can also configure Botan to be built using only a single source
-file; this is quite convenient if you plan to embed the library into
-another application. To do so, run ``configure.py`` with whatever
-arguments you would ordinarily use, along with the option
+You can also configure Botan to be built using only a single source file; this
+is quite convenient if you plan to embed the library into another application.
+
+To generate the amalgamation, run ``configure.py`` with whatever
+options you would ordinarily use, along with the option
 ``--gen-amalgamation``. This will create two (rather large) files,
-``botan_all.h`` and ``botan_all.cpp``.
+``botan_all.h`` and ``botan_all.cpp``, plus (unless the option
+``--single-amalgmation-file`` is used) also some number of files like
+``botan_all_aesni.cpp`` and ``botan_all_sse2.cpp`` which need to be
+compiled with the appropriate compiler flags to enable that
+instruction set. The ISA specific files are only generated if there is
+code that requires them, so you can simplify your build The
+``--no-autoload`` option (described elsewhere in this documentation)
+is also quite useful with the amalgamation.
 
 Whenever you would have included a botan header, you can then include
 ``botan_all.h``, and include ``botan_all.cpp`` along with the rest of
diff --git a/doc/manual/ffi.rst b/doc/manual/ffi.rst
index bf6483295..a951c63f3 100644
--- a/doc/manual/ffi.rst
+++ b/doc/manual/ffi.rst
@@ -13,19 +13,26 @@ Versioning
 ----------------------------------------
 
 .. cpp:function:: uint32_t botan_ffi_api_version()
+
    Returns the FFI version
 
 .. cpp:function:: const char* botan_version_string()
+
     Returns a free-from version string
 
 .. cpp:function:: uint32_t botan_version_major()
+
     Returns the major version of the library
+
 .. cpp:function:: uint32_t botan_version_minor()
+
     Returns the minor version of the library
 .. cpp:function:: uint32_t botan_version_patch()
+
     Returns the patch version of the library
 
 .. cpp:function:: uint32_t botan_version_datestamp()
+
     Returns the date this version was released as an integer, or 0
     if an unreleased version
 
@@ -33,56 +40,75 @@ Hash Functions
 ----------------------------------------
 
 .. cpp:type:: typedef struct botan_hash_struct* botan_hash_t
+
     An opaque data type for a hash. Don't mess with it.
 
 .. cpp:function:: botan_hash_t botan_hash_init(const char* hash, uint32_t flags)
+
     Creates a hash of the given name. Returns null on failure. Flags should
     always be zero in this version of the API.
 
 .. cpp:function:: int botan_hash_destroy(botan_hash_t hash)
+
     Destroy the object created by botan_hash_init
 
 .. cpp:function:: int botan_hash_clear(botan_hash_t hash)
+
     Reset the state of this object back to clean, as if no input has
     been supplied
 
 .. cpp:function:: size_t botan_hash_output_length(botan_hash_t hash)
+
      Return the output length of the hash
 
 .. cpp:function:: int botan_hash_update(botan_hash_t hash, const uint8_t* input, size_t len)
+
     Add input to the hash computation
+
 .. cpp:function:: int botan_hash_final(botan_hash_t hash, uint8_t out[])
+
     Finalize the hash and place the output in out. Exactly
     botan_hash_output_length() bytes will be written.
 
 Authentication Codes
 ----------------------------------------
 .. cpp:type:: typedef struct botan_mac_struct* botan_mac_t
+
     An opaque data type for a MAC. Don't mess with it, but do remember
     to set a random key first.
 
 .. cpp:function:: botan_mac_t botan_mac_init(const char* mac, uint32_t flags)
+
 .. cpp:function:: int botan_mac_destroy(botan_mac_t mac)
+
 .. cpp:function:: int botan_mac_clear(botan_mac_t hash)
 
 .. cpp:function:: int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len)
+
 .. cpp:function:: int botan_mac_update(botan_mac_t mac, uint8_t buf[], size_t len)
-.. cpp:function:: int botan_mac_final(botan_mac_t mac, uint8_t out[], size_t* out_len)
+
+.. cpp:function:: int botan_mac_final(botan_mac_t mac, uint8_t out[], size_t* ou
+t_len)
+
 .. cpp:function:: size_t botan_mac_output_length(botan_mac_t mac)
 
 Ciphers
 ----------------------------------------
+
 .. cpp:type:: typedef struct botan_cipher_struct* botan_cipher_t
+
     An opaque data type for a MAC. Don't mess with it, but do remember
     to set a random key first. And please use an AEAD.
 
 .. cpp:function:: botan_cipher_t botan_cipher_init(const char* cipher_name, uint32_t flags)
+
     Create a cipher object from a name such as "AES-256/GCM" or "Serpent/OCB".
 
     Flags is a bitfield
     The low bit of flags specifies if encrypt or decrypt
 
 .. cpp:function:: int botan_cipher_destroy(botan_cipher_t cipher)
+
 .. cpp:function:: int botan_cipher_clear(botan_cipher_t hash)
 
 .. cpp:function:: int botan_cipher_set_key(botan_cipher_t cipher,
@@ -96,8 +122,11 @@ Ciphers
                                  const uint8_t* nonce, size_t nonce_len)
 
 .. cpp:function:: int botan_cipher_is_authenticated(botan_cipher_t cipher)
+
 .. cpp:function:: size_t botan_cipher_tag_size(botan_cipher_t cipher)
-.. cpp:function:: int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl)
+
+.. cpp:function:: int botan_cipher_valid_nonce_length(botan_cipher_t cipher, siz
+e_t nl)
 
 .. cpp:function:: size_t botan_cipher_default_nonce_length(botan_cipher_t cipher)
 
diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
index 5e1d48656..139266ce5 100644
--- a/doc/manual/tls.rst
+++ b/doc/manual/tls.rst
@@ -82,8 +82,11 @@ available:
 .. cpp:class:: TLS::Channel
 
    .. cpp:type:: std::function<void (const byte[], size_t)> output_fn
+
    .. cpp:type:: std::function<void (const byte[], size_t)> data_cb
+
    .. cpp:type:: std::function<void (Alert, const byte[], size_t)> alert_cb
+
    .. cpp:type:: std::function<bool (const Session&)> handshake_cb
 
      Typedefs used in the code for the functions described above