From 3248801a925449644071671dcd85e370303071b4 Mon Sep 17 00:00:00 2001
From: Nick Wellnhofer <wellnhofer@aevum.de>
Date: Fri, 23 Jan 2015 17:04:14 +0100
Subject: Improve version information

Add version number and string as macros and symbols. Version numbers can
be easily compared, for example in the C preprocessor:

    #include <cmark.h>

    #if CMARK_VERSION < 0x020200
    #error Requires libcmark 2.2.0 or higher
    #endif

Storing the version in a global variable allows to check the library
version at runtime. For example:

    if (CMARK_VERSION != cmark_version) {
        warn("Compiled against libcmark %s, but using %s",
             CMARK_VERSION_STRING, cmark_version_string);
    }

The version should be updated whenever the public API is changed.
---
 man/man3/cmark.3 | 74 ++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 61 insertions(+), 13 deletions(-)

(limited to 'man/man3/cmark.3')

diff --git a/man/man3/cmark.3 b/man/man3/cmark.3
index f889521..f03a3ae 100644
--- a/man/man3/cmark.3
+++ b/man/man3/cmark.3
@@ -1,4 +1,4 @@
-.TH cmark 3 "January 20, 2015" "LOCAL" "Library Functions Manual"
+.TH cmark 3 "January 23, 2015" "LOCAL" "Library Functions Manual"
 .SH
 NAME
 .PP
@@ -9,18 +9,6 @@ DESCRIPTION
 .SS
 Simple Interface
 
-.PP
-.nf
-\fC
-.RS 0n
-#define CMARK_VERSION "0.1"
-.RE
-\f[]
-.fi
-
-.PP
-Current version of library.
-
 .PP
 \fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIint len\f[])
 
@@ -532,6 +520,66 @@ Render \f[C]softbreak\f[] elements as hard line breaks.
 .PP
 Normalize tree by consolidating adjacent text nodes.
 
+.SS
+Version information
+
+.PP
+.nf
+\fC
+.RS 0n
+#define CMARK_VERSION 0x000100
+.RE
+\f[]
+.fi
+
+.PP
+Macro containing the library version as integer for compile time
+checks.
+.IP \[bu] 2
+Bits 16\-23 contain the major version.
+.IP \[bu] 2
+Bits 8\-15 contain the minor version.
+.IP \[bu] 2
+Bits 0\-7 contain the patchlevel.
+.PP
+In hexadecimal format, the number 0x010203 represents version 1.2.3.
+
+.PP
+.nf
+\fC
+.RS 0n
+#define CMARK_VERSION_STRING "0.1.0"
+.RE
+\f[]
+.fi
+
+.PP
+Macro containing the library version string for compile time checks.
+
+.PP
+.nf
+\fC
+.RS 0n
+extern const int cmark_version;
+.RE
+\f[]
+.fi
+
+.PP
+The library version as integer for runtime checks.
+
+.PP
+.nf
+\fC
+.RS 0n
+extern const char cmark_version_string[];
+.RE
+\f[]
+.fi
+
+.PP
+The library version string for runtime checks.
+
 .SH
 AUTHORS
 .PP
-- 
cgit v1.2.3