Move reading list to the start, want people to see this

1 files changed, 46 insertions, 44 deletions

diff --git a/doc/api.tex b/doc/api.tex
index 557bdb567..d9f0f7f81 100644
--- a/doc/api.tex
+++ b/doc/api.tex
@@ -52,6 +52,27 @@ minimal fuss, but Botan also supports a modules system. This system
 exposes system dependent code to the library through portable
 interfaces, extending the set of services available to users.
 
+\subsection{Recommended Reading}
+
+It's a very good idea if you have some knowledge of cryptography prior
+to trying to use this stuff. You really should read at least one and
+ideally all of these books before seriously using the library.
+
+\setlength{\parskip}{5pt}
+
+\noindent
+\textit{Cryptography Engineering}, Niels Ferguson, Bruce Schneier, and
+Tadayoshi Kohno; Wiley
+
+\noindent
+\textit{Security Engineering -- A Guide to Building Dependable
+  Distributed Systems}, Ross Anderson; Wiley
+
+\noindent
+\textit{Handbook of Applied Cryptography}, Alfred J. Menezes,
+Paul C. Van Oorschot, and Scott A. Vanstone; CRC Press (available
+online at \url{http://www.cacr.math.uwaterloo.ca/hac/})
+
 \subsection{Targets}
 
 Botan's primary targets (system-wise) are 32 and 64-bit CPUs, with a
@@ -2197,31 +2218,33 @@ you do will be wasteful of both CPU cycles and possibly entropy.
 \pagebreak
 \section{User Interfaces}
 
-Botan has recently changed some infrastructure to better accommodate more
-complex user interfaces, in particular ones that are based on event
-loops. Primary among these was the fact that when doing something like loading
-a PKCS \#8 encoded private key, a passphrase might be needed, but then again it
-might not (a PKCS \#8 key doesn't have to be encrypted). Asking for a
-passphrase to decrypt an unencrypted key is rather pointless. Not only that,
-but the way to handle the user typing the wrong passphrase was complicated,
+Botan has recently changed some infrastructure to better accommodate
+more complex user interfaces, in particular ones that are based on
+event loops. Primary among these was the fact that when doing
+something like loading a PKCS \#8 encoded private key, a passphrase
+might be needed, but then again it might not (a PKCS \#8 key doesn't
+have to be encrypted). Asking for a passphrase to decrypt an
+unencrypted key is rather pointless. Not only that, but the way to
+handle the user typing the wrong passphrase was complicated,
 undocumented, and inefficient.
 
-So now Botan has an object called \type{UI}, which provides a simple interface
-for the aspects of user interaction the library has to be concerned
-with. Currently, this means getting a passphrase from the user, and that's it
-(\type{UI} will probably be extended in the future to support other operations
-as they are needed). The base \type{UI} class is very stupid, because the
-library can't directly assume anything about the environment that it's running
-under (for example, if there will be someone sitting at the terminal, if the
-application is even \emph{attached} to a terminal, and so on). But since you
-can subclass \type{UI} to use whatever method happens to be appropriate for
-your application, this isn't a big deal.
+So now Botan has an object called \type{UI}, which provides a simple
+interface for the aspects of user interaction the library has to be
+concerned with. Currently, this means getting a passphrase from the
+user, and that's it (\type{UI} will probably be extended in the future
+to support other operations as they are needed). The base \type{UI}
+class is very stupid, because the library can't directly assume
+anything about the environment that it's running under (for example,
+if there will be someone sitting at the terminal, if the application
+is even \emph{attached} to a terminal, and so on). But since you can
+subclass \type{UI} to use whatever method happens to be appropriate
+for your application, this isn't a big deal.
 
-\noindent
-\type{std::string} \function{get\_passphrase}(
-    \type{const std::string&} \arg{what},
-    \type{const std::string&} \arg{source},
-    \type{UI\_Result\&} \arg{result}) const;
+\begin{verbatim}
+  std::string get_passphrase(const std::string& what,
+                             const std::string& source,
+                             UI_Result& result) const;
+\end{verbatim}
 
 The \arg{what} argument specifies what the passphrase is needed for (for
 example, PKCS \#8 key loading passes \arg{what} as ``PKCS \#8 private
@@ -2824,7 +2847,7 @@ the algorithms listed here are (currently) thought to be safe.
   \item Public Key Encryption: RSA with ``EME1(SHA-256)''
 
   \item Public Key Signatures: RSA with EMSA4 and any recommended
-    hash, DSA/ECDSA with ``EMSA1(SHA-256)''
+    hash, or DSA or ECDSA with ``EMSA1(SHA-256)''
 
   \item Key Agreement: Diffie-Hellman or ECDH, with ``KDF2(SHA-256)''
 \end{list}
@@ -2901,27 +2924,6 @@ not encumbered by patents. If you have any concerns about the patent status of
 any algorithm you are considering using in an application, please discuss it
 with your attorney.
 
-\subsection{Recommended Reading}
-
-It's a very good idea if you have some knowledge of cryptography prior
-to trying to use this stuff. You really should read at least one and
-ideally all of these books before seriously using the library.
-
-\setlength{\parskip}{5pt}
-
-\noindent
-\textit{Cryptography Engineering}, Niels Ferguson, Bruce Schneier, and
-Tadayoshi Kohno; Wiley
-
-\noindent
-\textit{Security Engineering -- A Guide to Building Dependable
-  Distributed Systems}, Ross Anderson; Wiley
-
-\noindent
-\textit{Handbook of Applied Cryptography}, Alfred J. Menezes,
-Paul C. Van Oorschot, and Scott A. Vanstone; CRC Press (available
-online at \url{http://www.cacr.math.uwaterloo.ca/hac/})
-
 \subsection{Support}
 
 Questions or problems you have with Botan can be directed to the