Tweaks to doc on versioning

1 files changed, 26 insertions, 18 deletions

diff --git a/doc/manual/versions.rst b/doc/manual/versions.rst
index 9b0e1d8fc..14a7dfec5 100644
--- a/doc/manual/versions.rst
+++ b/doc/manual/versions.rst
@@ -2,19 +2,16 @@
 Versioning
 ========================================
 
-As of Botan 2.0.0, Botan uses semantic versioning. So in a future
-release, if even a small feature is added, the minor number will
-increase and the next release will be 2.1.0. If an incompatible API
-change is required, the major version will be increased.
+All versions are of the tuple (major,minor,patch).
 
-The library has functions for checking compile-time and runtime
-versions.
+As of Botan 2.0.0, Botan uses semantic versioning. The minor number increases if
+any feature addition is made. The patch version is used to indicate a release
+where only bug fixes were applied. If an incompatible API change is required,
+the major version will be increased.
 
-All versions are of the tuple (major,minor,patch). Even minor versions
-indicate stable releases while odd minor versions indicate a
-development release.
+The library has functions for checking compile-time and runtime versions.
 
-The compile time version information is defined in `botan/build.h`
+The build-time version information is defined in `botan/build.h`
 
 .. c:macro:: BOTAN_VERSION_MAJOR
 
@@ -41,16 +38,16 @@ The compile time version information is defined in `botan/build.h`
    A macro expanding to a string that is set at build time using the
    ``--distribution-info`` option. It allows a packager of the library
    to specify any distribution-specific patches. If no value is given
-   at build time, the value is 'unspecified'.
+   at build time, the value is the string "unspecified".
 
 .. c:macro:: BOTAN_VERSION_VC_REVISION
 
    .. versionadded:: 1.10.1
 
    A macro expanding to a string that is set to a revision identifier
-   cooresponding to the source, or 'unknown' if this could not be
-   determined. It is set for all official releases and for builds that
-   originated from within a Monotone workspace.
+   cooresponding to the source, or "unknown" if this could not be
+   determined. It is set for all official releases, and for builds that
+   originated from within a git checkout.
 
 The runtime version information, and some helpers for compile time
 version checks, are included in `botan/version.h`
@@ -77,16 +74,27 @@ version checks, are included in `botan/version.h`
    Return the datestamp of the release (or 0 if the current version is
    not an official release).
 
+.. cpp:function:: std::string runtime_version_check(uint32_t major, uint32_t minor, uint32_t patch)
+
+   Call this function with the compile-time version being built against, eg::
+
+      Botan::runtime_version_check(BOTAN_VERSION_MAJOR, BOTAN_VERSION_MINOR, BOTAN_VERSION_PATCH)
+
+   It will return an empty string if the versions match, or otherwise
+   an error message indicating the discrepency. This only is useful in
+   dynamic libraries, where it is possible to compile and run against
+   different versions.
+
 .. c:macro:: BOTAN_VERSION_CODE_FOR(maj,min,patch)
 
    Return a value that can be used to compare versions. The current
    (compile-time) version is available as the macro
    `BOTAN_VERSION_CODE`. For instance, to choose one code path for
-   versions before 1.10 and another for 1.10 or later::
+   version 2.1.0 and later, and another code path for older releases::
 
-      #if BOTAN_VERSION_CODE >= BOTAN_VERSION_CODE_FOR(1,10,0)
-         // 1.10 code path
+      #if BOTAN_VERSION_CODE >= BOTAN_VERSION_CODE_FOR(2,1,0)
+         // 2.1+ code path
       #else
-         // pre-1.10 code path
+         // code path for older versions
       #endif