fix: make manual page more standard conformant and nicer to man2html

16 files changed, 535 insertions, 490 deletions

diff --git a/man/man3/mt_assert.3 b/man/man3/mt_assert.3
deleted file mode 100644
index e04ea20..0000000
--- a/man/man3/mt_assert.3
+++ /dev/null
@@ -1,47 +0,0 @@
-.TH "MT_ASSERT" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH NAME
-
-mt_assert, mt_fail - test checks macros
-
-.SH SYNOPSIS
-
-c/c++
-
-.B #include <mtest.h>
-.sp
-.BI "mt_assert(" expression ")"
-.br
-.BI "mt_fail(" expression ")"
-.sp
-
-shell
-
-.BI "mt_fail <" expression ">"
-
-.SH DESCRIPTION
-
-Macro \fBmt_assert\fR(3) evaluates \fIexpression\fR and if it evaluates to false,
-test will be marked as failed and information about assert will be printed.
-Information contains \fIfunction_name\fR, line where assert occured, and
-\fIexpression\fR that caused test to fail. Also macro forces function it was
-called in to immediately return.
-
-\fBmt_fail\fR(3) works just as \fBmt_assert\fR(3) but function is not forced to
-exit and can continue execution. This is good when test allocates some memory
-and we need to clean up before returning.
-
-.SH EXAMPLE
-
-Proper example can be found in \fBmtest_overview\fR(7).
-
-.SH "SEE ALSO"
-
-.BR mt_defs (3),
-.BR mt_defs_ext (3),
-.BR mt_run (3),
-.BR mt_run_named (3),
-.BR mt_fok (3),
-.BR mt_ferr (3),
-.BR mt_return (3),
-.BR mtest_overview (7)
diff --git a/man/man3/mt_defs.3 b/man/man3/mt_defs.3
deleted file mode 100644
index 10d6b02..0000000
--- a/man/man3/mt_defs.3
+++ /dev/null
@@ -1,111 +0,0 @@
-.TH "MT_DEFS" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH NAME
-
-mt_defs, mt_defs_ext - defines variables for test framework
-
-.SH SYNOPSIS
-
-.B #include <mtest.h>
-.sp
-.B mt_defs()
-.br
-.B mt_defs_ext()
-.sp
-
-.SH DESCRIPTION
-
-\fBmt_defs\fR(3) defines all variables needed by the test framework. This must
-be called exactly once in a global scope, before calling any of the
-\fBmtest\fR function. Calling this macro in two places will lead to 'double
-definition' linker error. As a rule of thumb, it is good to call this macro in
-test-main.c file after #includes.
-
-If all tests are in a single file (like test-main.c) calling \fBmt_defs\fR(3)
-is sufficient, but if tests are splitted into more .c files, you should also
-call \fBmt_defs_ext\fR(3) in all .c files that uses \fBmtest\fR functions. As
-with \fBmt_defs\fR(3), it should be called before any call to \fBmtest\fR
-function.
-
-Note, don't call \fBmt_defs_ext\fR(3) if \fBmt_defs\fR(3) has already been
-called in a single file.
-
-.SH EXAMPLE
-
-.nf
-/* test-main.c */
-
-#include <mtest.h>
-
-#include "t1.h"
-#include "t2.h"
-#include "library-under-test.h"
-
-mt_defs();
-
-static void test_zero(void)
-{
-    mt_assert(foo() == 0);
-}
-
-int main(void)
-{
-    mt_run(test_zero);
-    mt_run(test_one);
-    test_group();
-
-    mt_return();
-}
-
-
-/* t1.c */
-
-#include <mtest.h>
-
-#include "t1.h"
-#include "library-under-test.h"
-
-mt_defs_ext();
-
-void test_one(void)
-{
-    mt_assert(bar() == 0);
-}
-
-
-/* t2.c */
-
-#include <mtest.h>
-
-#include "t2.h"
-#include "library-under-test.h"
-
-mt_defs_ext();
-
-static void test_two(void)
-{
-    mt_assert(baz() == 0);
-}
-
-static void test_three(void)
-{
-    mt_assert(qux() == 0);
-}
-
-void test_group(void)
-{
-    mt_run(test_two);
-    mt_run(test_three);
-}
-.fi
-
-.SH "SEE ALSO"
-
-.BR mt_run (3),
-.BR mt_run_named (3),
-.BR mt_assert (3),
-.BR mt_fail (3),
-.BR mt_fok (3),
-.BR mt_ferr (3),
-.BR mt_return (3)
-.BR mtest_overview (7)
diff --git a/man/man3/mt_fok.3 b/man/man3/mt_fok.3
deleted file mode 100644
index 99d4f88..0000000
--- a/man/man3/mt_fok.3
+++ /dev/null
@@ -1,71 +0,0 @@
-.TH "MT_FOK" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH NAME
-
-mt_fok, mt_ferr - shortcut macro to test if function executed as expected.
-
-.SH SYNOPSIS
-
-.B #include <mtest.h>
-.sp
-.BI "mt_fok(" function_call ")"
-.br
-.BI "mt_ferr(" function_call ", " errno_value ")"
-.sp
-
-.SH DESCRIPTION
-
-Macros are a simple shortcuts to perform test on functions that return either
--1 or 0. By convention 0 means success and -1 means error and error reason is
-stored in \fBerrno\fR variable. If function returns different values than 0
-or -1, ordinary \fBmt_fail\fR(3) should be used instead.
-
-\fBmt_fok\fR(3) simply expects that function returns 0.
-
-\fBmt_ferr\fR(3) expects function to return -1, and sets \fBerrno\fR value to
-\fIerrno_value\fR.
-
-Both functions uses \fBmt_fail\fR(3) under the hood.
-
-.SH EXAMPLE
-
-.nf
-#include <mtest.h>
-#include <errno.h>
-
-mt_defs();
-
-static int f1(void)
-{
-    return 0;
-}
-
-static int f2(void)
-{
-    errno = ENOSYS;
-    return -1;
-}
-
-static void t1(void)
-{
-    mt_fok(f1());
-    mt_ferr(f2(), ENOSYS);
-}
-
-int main(void)
-{
-    mt_run(t1);
-    mt_return();
-}
-.fi
-
-.SH "SEE ALSO"
-
-.BR mt_defs (3),
-.BR mt_defs_ext (3),
-.BR mt_run (3),
-.BR mt_run_named (3),
-.BR mt_assert (3),
-.BR mt_fail (3),
-.BR mt_return (3)
-.BR mtest_overview (7),
diff --git a/man/man3/mt_return.3 b/man/man3/mt_return.3
deleted file mode 100644
index ff442b6..0000000
--- a/man/man3/mt_return.3
+++ /dev/null
@@ -1,45 +0,0 @@
-.TH "MT_RETURN" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH NAME
-
-mt_return - finishes test execution
-
-.SH SYNOPSIS
-
-c/c++
-
-.B #include <mtest.h>
-.sp
-.BI mt_return()
-.sp
-
-shell
-
-.BI mt_return
-
-.SH DESCRIPTION
-
-\fBmt_return\fR(3) should be called once at the very end of \fBmain\fR()
-function. In other words, this macro should be called in \fBmain\fR() instead of
-normal return.  Function will print number of tests executed and will exit test
-program.  Returned value is number of tests that have failed, so if return code
-of application is 0, that means all tests have finished with success. If there
-is more than 254 tests failed, macro will return 254.
-
-In shell call this function at the very end of shell script.
-
-.SH EXAMPLE
-
-Proper example can be found in \fBmtest_overview\fR(7).
-
-.SH "SEE ALSO"
-
-.BR mt_defs (3),
-.BR mt_defs_ext (3),
-.BR mt_run (3),
-.BR mt_run (3),
-.BR mt_assert (3),
-.BR mt_fail (3),
-.BR mt_fok (3),
-.BR mt_ferr (3),
-.BR mtest_overview (7)
diff --git a/man/man3/mt_run.3 b/man/man3/mt_run.3
deleted file mode 100644
index 49fc321..0000000
--- a/man/man3/mt_run.3
+++ /dev/null
@@ -1,101 +0,0 @@
-.TH "MT_RUN" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH NAME
-
-mt_run - runs specific test
-
-c/c++
-
-.SH SYNOPSIS
-
-.B #include <mtest.h>
-.sp
-.BI "void (*" function_name ")(void)
-.br
-.BI "mt_run(" function_name ")"
-.br
-.BI "mt_run_named(" function_name ", " test_name ")"
-.br
-.br
-.BI "static void (*" mt_prepare_test ")(void)"
-.br
-.BI "static void (*" mt_cleanup_test ")(void)"
-.sp
-
-shell
-
-.BI "mt_run <" function_name ">"
-
-.SH DESCRIPTION
-
-\fBmt_run\fR(#) runs a single test specified in \fIfunction_name\fR. Inside
-function you can call \fBmt_assert\fR(3) and \fBmt_fail\fR(3). If none if these
-functions is called inside test function, \fBmtest\fR will mark test as
-successful. After function finishes its work, \fBmt_run\fR(3) will print test
-status and a \fIfunction_name\fR to know which test passed or failed.
-
-\fBmt_run_named\fR(3) works similar, but also takes \fItest_name\fR, that will
-be printed instead of \fIfunction_name\fR when reporting test results.
-\fItest_name\fR should be simple \fBconst char *\fR.
-
-Optionally user can also set two function pointers \fImt_prepare_test\fR and
-\fImt_cleanup_test\fR that take no argument and return nothing. These functions
-will be called before and after calling test \fIfunction_name\fR.
-
-When testing from shell, it is only neccessary to define functions
-\fImt_prepare_test\fR and \fImt_cleanup_test\fR and \fBmtest\fR will use
-then automatically
-
-.SH EXAMPLE
-
-c/c++
-
-.nf
-#include <mtest.h>
-#include "foo.h"
-
-mt_defs();
-
-static void test(void)
-{
-    mt_assert(foo() == 0);
-}
-
-int main(void)
-{
-    mt_run(test);
-    mt_run_named(test, "test param 1");
-    mt_run_named(test, "test_param 2");
-
-    mt_return();
-}
-.fi
-
-shell
-
-.nf
-#!/bin/sh
-
-\$. ./mtest.sh
-
-test_one()
-{
-    a=1
-    a=$((a + 1))
-    mt_fail "[ $a -eq 2 ]"
-}
-
-mt_run test_one
-mt_return
-.fi
-
-.SH "SEE ALSO"
-
-.BR mt_defs (3),
-.BR mt_defs_ext (3),
-.BR mt_assert (3),
-.BR mt_fail (3),
-.BR mt_fok (3),
-.BR mt_ferr (3),
-.BR mt_return (3)
-.BR mtest_overview (7),
diff --git a/man/man7/mtest_overview.7 b/man/man7/mtest_overview.7
deleted file mode 100644
index 6705c2a..0000000
--- a/man/man7/mtest_overview.7
+++ /dev/null
@@ -1,115 +0,0 @@
-.TH "MTEST" "7" "17 January 2018 (v1.1.0)" "bofc.pl"
-
-.SH "NAME"
-
-\fBmtest_overview\fR - overview of \fBmtest\fR testing framework
-
-.SH "DESCRIPTION"
-
-\fBmtest\fR - very simple test framework for testing anything. mtest currently
-supports following languages:
-
-For c/c++
-
-.sp
-.BI "mt_defs()"
-.br
-.BI "mt_defs_ext()"
-.br
-.BI "mt_run(" function_name ")"
-.br
-.BI "mt_run_named(" function_name ", " test_name ")"
-.br
-.BI "mt_assert(" expression ")"
-.br
-.BI "mt_fail(" expression ")"
-.br
-.BI "mt_fok(" function_call ")"
-.br
-.BI "mt_ferr(" function_call ", " errno_value ")"
-.br
-.BI "mt_return()"
-.sp
-
-For shell
-
-.sp
-.BI "mt_run <" function_name ">"
-.br
-.BI "mt_fail <" expression ">"
-.br
-.BR "mt_return"
-.sp
-
-Test output is compatible with \fBTAP\fR (which stands for Test Anything
-Protocol), so its output can be piped to another tool (like Jenkins or
-automake tests) for nice output.
-
-Each test binary (written in c/c++) should contain call to \fBmt_defs\fR(3)
-anywhere in a global scope and \fBmt_return\fR(3) at the end of tests.
-
-Tests in shell only requires \fBmt_return\fR(3) at the end of tests
-
-.SH "EXAMPLE"
-
-.nf
-#include <mtest.h>
-#include <stdlib.h>
-#include "file_to_test.h"
-
-mt_defs(); /* defines necessary variables for mtest */
-
-static void test_one(void)
-{
-    mt_assert(foo() == 0);
-    mt_assert(bar() == 0);
-}
-
-static void test_two(void)
-{
-    unsigned char *mem;
-
-    mt_assert((mem = malloc(100)) != NULL);
-    mt_fok(baz(mem));
-    mt_ferr(qux(mem), ENOSYS);
-
-    free(mem);
-}
-
-int main(void)
-{
-    mt_run(test_one);
-    mt_run(test_two);
-
-    mt_return();
-}
-.fi
-
-Example of using mt in posix shell
-
-.nf
-#!/bin/sh
-
-\&. ./mtest.sh
-
-test_one()
-{
-    a=1
-    a=$((a + 1))
-    mt_fail "[ $a -eq 2 ]"
-}
-
-mt_run test_one
-mt_return
-.fi
-
-.SH "SEE ALSO"
-
-.BR mt_defs (3),
-.BR mt_defs_ext (3),
-.BR mt_run (3),
-.BR mt_assert (3),
-.BR mt_fail (3),
-.BR mt_fok (3),
-.BR mt_ferr (3),
-.BR mt_return (3)
diff --git a/man/mt_assert.3 b/man/mt_assert.3
new file mode 100644
index 0000000..e14d479
--- /dev/null
+++ b/man/mt_assert.3
@@ -0,0 +1,54 @@
+.TH "MT_ASSERT" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH NAME
+.PP
+.BR mt_assert ,
+.B mt_fail
+- test checks macros
+.SH SYNOPSIS
+.PP
+c/c++
+.PP
+.B #include <mtest.h>
+.PP
+.BI "mt_assert(" expression ")"
+.br
+.BI "mt_fail(" expression ")"
+.PP
+shell
+.PP
+.BI "mt_fail <" expression ">"
+.SH DESCRIPTION
+.PP
+Macro
+.BR mt_assert (3)
+evaluates
+.I expression
+and if it evaluates to false, test will be marked as failed and information
+about assert will be printed.
+Information contains
+.BR function_name ,
+line where assert occured, and
+.I expression
+that caused test to fail.
+Also macro forces function it was called in to immediately return.
+.PP
+.BR mt_fail (3)
+works just as
+.BR mt_assert (3)
+but function is not forced to exit and can continue execution.
+This is good when test allocates some memory and we need to clean up before
+returning.
+.SH EXAMPLE
+.PP
+Proper example can be found in
+.BR mtest_overview (7).
+.SH "SEE ALSO"
+.PP
+.BR mt_defs (3),
+.BR mt_defs_ext (3),
+.BR mt_run (3),
+.BR mt_run_named (3),
+.BR mt_fok (3),
+.BR mt_ferr (3),
+.BR mt_return (3),
+.BR mtest_overview (7)
diff --git a/man/mt_defs.3 b/man/mt_defs.3
new file mode 100644
index 0000000..a219aad
--- /dev/null
+++ b/man/mt_defs.3
@@ -0,0 +1,121 @@
+.TH "MT_DEFS" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH NAME
+.PP
+.BR mt_defs ,
+.B mt_defs_ext
+- defines variables for test framework
+.SH SYNOPSIS
+.PP
+.B #include <mtest.h>
+.PP
+.B mt_defs()
+.br
+.B mt_defs_ext()
+.SH DESCRIPTION
+.PP
+.BR mt_defs (3)
+defines all variables needed by the test framework.
+This must be called exactly once in a global scope, before calling any of the
+.B mtest
+function.
+Calling this macro in two places will lead to 'double definition' linker error.
+As a rule of thumb, it is good to call this macro in test-main.c file after
+#include.
+.PP
+If all tests are in a single file (like test-main.c) calling
+.BR mt_defs (3)
+is sufficient, but if tests are splitted into more .c files, you should also
+call
+.BR mt_defs_ext (3)
+in all .c files that uses
+.B mtest
+functions.
+As with
+.BR mt_defs (3),
+it should be called before any call to
+.B mtest
+function.
+.PP
+Note, don't call
+.BR mt_defs_ext (3)
+if
+.B mt_defs (3)
+has already been called in a single file.
+.SH EXAMPLE
+.PP
+.EX
+    /* test-main.c */
+
+    #include <mtest.h>
+
+    #include "t1.h"
+    #include "t2.h"
+    #include "library-under-test.h"
+
+    mt_defs();
+
+    static void test_zero(void)
+    {
+        mt_assert(foo() == 0);
+    }
+
+    int main(void)
+    {
+        mt_run(test_zero);
+        mt_run(test_one);
+        test_group();
+
+        mt_return();
+    }
+
+
+    /* t1.c */
+
+    #include <mtest.h>
+
+    #include "t1.h"
+    #include "library-under-test.h"
+
+    mt_defs_ext();
+
+    void test_one(void)
+    {
+        mt_assert(bar() == 0);
+    }
+
+
+    /* t2.c */
+
+    #include <mtest.h>
+
+    #include "t2.h"
+    #include "library-under-test.h"
+
+    mt_defs_ext();
+
+    static void test_two(void)
+    {
+        mt_assert(baz() == 0);
+    }
+
+    static void test_three(void)
+    {
+        mt_assert(qux() == 0);
+    }
+
+    void test_group(void)
+    {
+        mt_run(test_two);
+        mt_run(test_three);
+    }
+.EE
+.SH "SEE ALSO"
+.PP
+.BR mt_run (3),
+.BR mt_run_named (3),
+.BR mt_assert (3),
+.BR mt_fail (3),
+.BR mt_fok (3),
+.BR mt_ferr (3),
+.BR mt_return (3)
+.BR mtest_overview (7)
diff --git a/man/man3/mt_defs_ext.3 b/man/mt_defs_ext.3
index 2a574c6..2a574c6 100644
--- a/man/man3/mt_defs_ext.3
+++ b/man/mt_defs_ext.3
diff --git a/man/man3/mt_fail.3 b/man/mt_fail.3
index 9be3e5e..9be3e5e 100644
--- a/man/man3/mt_fail.3
+++ b/man/mt_fail.3
diff --git a/man/man3/mt_ferr.3 b/man/mt_ferr.3
index d2ba116..d2ba116 100644
--- a/man/man3/mt_ferr.3
+++ b/man/mt_ferr.3
diff --git a/man/mt_fok.3 b/man/mt_fok.3
new file mode 100644
index 0000000..0898c7c
--- /dev/null
+++ b/man/mt_fok.3
@@ -0,0 +1,78 @@
+.TH "MT_FOK" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH NAME
+.PP
+.BR mt_fok ,
+.B mt_ferr
+- shortcut macro to test if function executed as expected.
+.SH SYNOPSIS
+.PP
+.B #include <mtest.h>
+.PP
+.BI "mt_fok(" function_call ")"
+.br
+.BI "mt_ferr(" function_call ", " errno_value ")"
+.SH DESCRIPTION
+.PP
+Macros are a simple shortcuts to perform test on functions that return either
+-1 or 0.
+By convention 0 means success and -1 means error and error reason is
+stored in
+.B errno
+variable.
+If function returns different values than 0 or -1, ordinary
+.BR mt_fail (3)
+should be used instead.
+.PP
+.RB mt_fok (3)
+simply expects that function returns 0.
+.PP
+.BR mt_ferr (3)
+expects function to return -1, and sets
+.B errno
+value to
+.IR errno_value .
+.PP
+Both functions uses
+.BR mt_fail (3)
+under the hood.
+.SH EXAMPLE
+.PP
+.EX
+    #include <mtest.h>
+    #include <errno.h>
+
+    mt_defs();
+
+    static int f1(void)
+    {
+        return 0;
+    }
+
+    static int f2(void)
+    {
+        errno = ENOSYS;
+        return -1;
+    }
+
+    static void t1(void)
+    {
+        mt_fok(f1());
+        mt_ferr(f2(), ENOSYS);
+    }
+
+    int main(void)
+    {
+        mt_run(t1);
+        mt_return();
+    }
+.EE
+.SH "SEE ALSO"
+.PP
+.BR mt_defs (3),
+.BR mt_defs_ext (3),
+.BR mt_run (3),
+.BR mt_run_named (3),
+.BR mt_assert (3),
+.BR mt_fail (3),
+.BR mt_return (3)
+.BR mtest_overview (7),
diff --git a/man/mt_return.3 b/man/mt_return.3
new file mode 100644
index 0000000..3c3428c
--- /dev/null
+++ b/man/mt_return.3
@@ -0,0 +1,46 @@
+.TH "MT_RETURN" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH NAME
+.PP
+.B mt_return
+- finishes test execution
+.SH SYNOPSIS
+.PP
+c/c++
+.PP
+.B #include <mtest.h>
+.PP
+.BI mt_return()
+.PP
+shell
+.PP
+.BI mt_return
+.SH DESCRIPTION
+.PP
+.BR mt_return (3)
+should be called once at the very end of
+.B main()
+function.
+In other words, this macro should be called in
+.B main()
+instead of normal return.
+Function will print number of tests executed and will exit test program.
+Returned value is number of tests that have failed, so if return code
+of application is 0, that means all tests have finished with success.
+If there is more than 254 tests failed, macro will return 254.
+.PP
+In shell call this function at the very end of shell script.
+.SH EXAMPLE
+.PP
+Proper example can be found in
+.BR mtest_overview (7).
+.SH "SEE ALSO"
+.PP
+.BR mt_defs (3),
+.BR mt_defs_ext (3),
+.BR mt_run (3),
+.BR mt_run (3),
+.BR mt_assert (3),
+.BR mt_fail (3),
+.BR mt_fok (3),
+.BR mt_ferr (3),
+.BR mtest_overview (7)
diff --git a/man/mt_run.3 b/man/mt_run.3
new file mode 100644
index 0000000..84ee686
--- /dev/null
+++ b/man/mt_run.3
@@ -0,0 +1,119 @@
+.TH "MT_RUN" "3" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH NAME
+.PP
+.B mt_run
+- runs specific test
+.SH SYNOPSIS
+.PP
+c/c++
+.PP
+.B #include <mtest.h>
+.PP
+.BI "void (*" function_name ")(void)
+.br
+.BI "mt_run(" function_name ")"
+.br
+.BI "mt_run_named(" function_name ", " test_name ")"
+.PP
+.BI "static void (*" mt_prepare_test ")(void)"
+.br
+.BI "static void (*" mt_cleanup_test ")(void)"
+.PP
+shell
+.PP
+.BI "mt_run <" function_name ">"
+.SH DESCRIPTION
+.PP
+.BR mt_run (3)
+runs a single test specified in
+.IR function_name .
+Inside function you can call
+.BR mt_assert (3)
+and
+.BR mt_fail (3).
+If none if these functions are called inside test function,
+.B mtest
+will mark test as successful.
+After function finishes its work,
+.BR mt_run (3)
+will print test status and a
+.I function_name
+to know which test passed or failed.
+.PP
+.BR mt_run_named (3)
+works similar, but also takes
+.IR test_name ,
+that will be printed instead of
+.I function_name
+when reporting test results.
+.I test_name
+should be simple
+. Bconst char *.
+.PP
+Optionally user can also set two function pointers
+.I mt_prepare_test
+and
+.I mt_cleanup_test
+that take no argument and return nothing.
+These functions will be called before and after calling test
+.IR function_name .
+.PP
+When testing from shell, it is only neccessary to define functions
+.I mt_prepare_test
+and
+.I mt_cleanup_test
+and
+.B mtest
+will use then automatically
+.SH EXAMPLE
+.PP
+c/c++
+.PP
+.EX
+    #include <mtest.h>
+    #include "foo.h"
+
+    mt_defs();
+
+    static void test(void)
+    {
+        mt_assert(foo() == 0);
+    }
+
+    int main(void)
+    {
+        mt_run(test);
+        mt_run_named(test, "test param 1");
+        mt_run_named(test, "test_param 2");
+
+        mt_return();
+    }
+.EX
+.PP
+shell
+.PP
+.EX
+    #!/bin/sh
+
+    . ./mtest.sh
+
+    test_one()
+    {
+        a=1
+        a=$((a + 1))
+        mt_fail "[ $a -eq 2 ]"
+    }
+
+    mt_run test_one
+    mt_return
+.EE
+.SH "SEE ALSO"
+.PP
+.BR mt_defs (3),
+.BR mt_defs_ext (3),
+.BR mt_assert (3),
+.BR mt_fail (3),
+.BR mt_fok (3),
+.BR mt_ferr (3),
+.BR mt_return (3)
+.BR mtest_overview (7),
diff --git a/man/man3/mt_run_named.3 b/man/mt_run_named.3
index 7c9fe17..7c9fe17 100644
--- a/man/man3/mt_run_named.3
+++ b/man/mt_run_named.3
diff --git a/man/mtest_overview.7 b/man/mtest_overview.7
new file mode 100644
index 0000000..89bdc3d
--- /dev/null
+++ b/man/mtest_overview.7
@@ -0,0 +1,117 @@
+.TH "MTEST" "7" "17 January 2018 (v1.1.0)" "bofc.pl"
+.SH "NAME"
+.PP
+.B mtest_overview
+- overview of
+.B mtest
+testing framework
+.SH "DESCRIPTION"
+.PP
+.B mtest
+- very simple test framework for testing anything. mtest currently
+supports following languages:
+.PP
+For c/c++
+.PP
+.BI "mt_defs()"
+.br
+.BI "mt_defs_ext()"
+.br
+.BI "mt_run(" function_name ")"
+.br
+.BI "mt_run_named(" function_name ", " test_name ")"
+.br
+.BI "mt_assert(" expression ")"
+.br
+.BI "mt_fail(" expression ")"
+.br
+.BI "mt_fok(" function_call ")"
+.br
+.BI "mt_ferr(" function_call ", " errno_value ")"
+.br
+.BI "mt_return()"
+.PP
+For shell
+.PP
+.BI "mt_run <" function_name ">"
+.br
+.BI "mt_fail <" expression ">"
+.br
+.BR "mt_return"
+.PP
+Test output is compatible with
+.B TAP
+(which stands for Test Anything Protocol), so its output can be piped to another
+tool (like Jenkins or automake tests) for nice output.
+.PP
+Each test binary (written in c/c++) should contain call to
+.BR mt_defs (3)
+anywhere in a global scope and
+.RB mt_return (3)
+at the end of tests.
+.PP
+Tests in shell only requires
+.RB mt_return (3)
+at the end of tests
+.SH "EXAMPLE"
+.PP
+.EX
+    #include <mtest.h>
+    #include <stdlib.h>
+    #include "file_to_test.h"
+
+    mt_defs(); /* defines necessary variables for mtest */
+
+    static void test_one(void)
+    {
+        mt_assert(foo() == 0);
+        mt_assert(bar() == 0);
+    }
+
+    static void test_two(void)
+    {
+        unsigned char *mem;
+
+        mt_assert((mem = malloc(100)) != NULL);
+        mt_fok(baz(mem));
+        mt_ferr(qux(mem), ENOSYS);
+
+        free(mem);
+    }
+
+    int main(void)
+    {
+        mt_run(test_one);
+        mt_run(test_two);
+
+        mt_return();
+    }
+.EE
+.PP
+Example of using mt in posix shell
+.PP
+.EX
+    #!/bin/sh
+
+    . ./mtest.sh
+
+    test_one()
+    {
+        a=1
+        a=$((a + 1))
+        mt_fail "[ $a -eq 2 ]"
+    }
+
+    mt_run test_one
+    mt_return
+.EE
+.SH "SEE ALSO"
+.PP
+.BR mt_defs (3),
+.BR mt_defs_ext (3),
+.BR mt_run (3),
+.BR mt_assert (3),
+.BR mt_fail (3),
+.BR mt_fok (3),
+.BR mt_ferr (3),
+.BR mt_return (3)