Move deprecated and ABI notices to the handbook

Probably easier to find for most users since the handbook is packaged
but the other stuff in doc isn't.

4 files changed, 28 insertions, 19 deletions

diff --git a/doc/abi.rst b/doc/abi.rst
deleted file mode 100644
index 0fa26d21b..000000000
--- a/doc/abi.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-
-API/ABI Stability
-====================
-
-API of release branches is stable; that is to say code that compiles and works
-against 2.0.0 should also compile with all later 2.x.x versions. The API on
-master is completely fair game and may change at any time.
-
-Maintaining a consistent ABI while evolving a complex C++ API is exceedingly
-expensive in development time. It is likely ABI breakage will occur at least
-occasionally even in release branches. In these cases, the soname revision will
-increase to prevent applications from linking against a potentially incompatible
-version at runtime.
-
-You can review a report on ABI changes to Botan at
-https://abi-laboratory.pro/tracker/timeline/botan/
diff --git a/doc/manual/abi.rst b/doc/manual/abi.rst
new file mode 100644
index 000000000..888f0c33a
--- /dev/null
+++ b/doc/manual/abi.rst
@@ -0,0 +1,21 @@
+
+ABI Stability
+====================
+
+Botan uses semantic versioning for the API; if API features are added the minor
+version increases, whereas if API compatability breaks occur the major version
+is increased.
+
+However no guarantees about ABI are made between releases. Maintaining an ABI
+compatible release in a complex C++ API is exceedingly expensive in development
+time; just adding a single member variable or virtual function is enough to
+cause ABI issues.
+
+If ABI changes, the soname revision will increase to prevent applications from
+linking against a potentially incompatible version at runtime.
+
+If you are concerned about long-term ABI issues, considering using the C API
+instead; this subset *is* ABI stable.
+
+You can review a report on ABI changes to Botan at
+https://abi-laboratory.pro/tracker/timeline/botan/
diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst
index 941bf014e..e33876b9e 100644
--- a/doc/manual/contents.rst
+++ b/doc/manual/contents.rst
@@ -42,4 +42,5 @@ Contents
    side_channels
    packaging
    fuzzing
-
+   deprecated
+   abi
diff --git a/doc/deprecated.txt b/doc/manual/deprecated.rst
index cbb48c797..8cfe7e590 100644
--- a/doc/deprecated.txt
+++ b/doc/manual/deprecated.rst
@@ -1,3 +1,6 @@
+Deprecated Features
+========================
+
 The following functionality is currently deprecated, and will likely
 be removed in a future release. If you think you have a good reason to
 be using one of the following, contact the developers to explain your
@@ -6,9 +9,9 @@ use case if you want to make sure your code continues to work.
 This is in addition to specific API calls marked with BOTAN_DEPRECATED
 in the source.
 
-- The headers botan.h, init.h, lookup.h
+- The headers ``botan.h``, ``init.h``, ``lookup.h``
 
-- All or nothing package transform
+- All or nothing package transform (``package.h``)
 
 - The TLS constructors taking `std::function` for callbacks. Instead
   use the TLS::Callbacks interface.