diff --git a/ChangeLog b/ChangeLog
index 07660d2..be48475 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -7,7 +7,13 @@ Mark Overmeer.
 TODO:
 	. connect to Message::Passing framework
 
-version 1.28:
+version 1.29:
+
+	Improvements:
+	- skip tests with error messages for Haiku, because they are quite
+	  different. [cpantesters]
+
+version 1.28: Tue 14 May 09:27:50 CEST 2019
 
 	Fixes:
 	- Dancer2 version 0.166001 is too old as well. [cpantesters]
diff --git a/MANIFEST b/MANIFEST
index 2b93770..cab6ae9 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,52 +1,31 @@
 ChangeLog
 MANIFEST
 Makefile.PL
-README
 README.md
 examples/dancer/dancer1.pl
 lib/Dancer/Logger/LogReport.pm
-lib/Dancer/Logger/LogReport.pod
 lib/Dancer2/Logger/LogReport.pm
-lib/Dancer2/Logger/LogReport.pod
 lib/Dancer2/Plugin/LogReport.pm
-lib/Dancer2/Plugin/LogReport.pod
 lib/Dancer2/Plugin/LogReport/Message.pm
-lib/Dancer2/Plugin/LogReport/Message.pod
 lib/Log/Report.pm
-lib/Log/Report.pod
 lib/Log/Report/DBIC/Profiler.pm
-lib/Log/Report/DBIC/Profiler.pod
 lib/Log/Report/Die.pm
-lib/Log/Report/Die.pod
 lib/Log/Report/Dispatcher.pm
-lib/Log/Report/Dispatcher.pod
 lib/Log/Report/Dispatcher/Callback.pm
-lib/Log/Report/Dispatcher/Callback.pod
 lib/Log/Report/Dispatcher/File.pm
-lib/Log/Report/Dispatcher/File.pod
 lib/Log/Report/Dispatcher/Log4perl.pm
-lib/Log/Report/Dispatcher/Log4perl.pod
 lib/Log/Report/Dispatcher/LogDispatch.pm
-lib/Log/Report/Dispatcher/LogDispatch.pod
 lib/Log/Report/Dispatcher/Perl.pm
-lib/Log/Report/Dispatcher/Perl.pod
 lib/Log/Report/Dispatcher/Syslog.pm
-lib/Log/Report/Dispatcher/Syslog.pod
 lib/Log/Report/Dispatcher/Try.pm
-lib/Log/Report/Dispatcher/Try.pod
 lib/Log/Report/Domain.pm
-lib/Log/Report/Domain.pod
 lib/Log/Report/Exception.pm
-lib/Log/Report/Exception.pod
 lib/Log/Report/Message.pm
-lib/Log/Report/Message.pod
 lib/Log/Report/Translator.pm
-lib/Log/Report/Translator.pod
 lib/Log/Report/messages/first-domain.utf-8.po
 lib/Log/Report/messages/log-report.utf-8.po
 lib/Log/Report/messages/log-report/nl_NL.po
 lib/MojoX/Log/Report.pm
-lib/MojoX/Log/Report.pod
 t/00use.t
 t/09message.t
 t/10interp.t
@@ -66,5 +45,3 @@ t/60mojo.t
 t/70dancer2.t
 t/DieTests.pm
 xt/99pod.t
-META.yml                                 Module YAML meta-data (added by MakeMaker)
-META.json                                Module JSON meta-data (added by MakeMaker)
diff --git a/MANIFEST.extra b/MANIFEST.extra
new file mode 100644
index 0000000..1936cc1
--- /dev/null
+++ b/MANIFEST.extra
@@ -0,0 +1 @@
+html
diff --git a/META.json b/META.json
deleted file mode 100644
index 7ed05c9..0000000
--- a/META.json
+++ /dev/null
@@ -1,59 +0,0 @@
-{
-   "abstract" : "report a problem, pluggable handlers and language support",
-   "author" : [
-      "Mark Overmeer <markov@cpan.org>"
-   ],
-   "dynamic_config" : 1,
-   "generated_by" : "ExtUtils::MakeMaker version 7.3, CPAN::Meta::Converter version 2.150010",
-   "license" : [
-      "perl_5"
-   ],
-   "meta-spec" : {
-      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
-      "version" : 2
-   },
-   "name" : "Log-Report",
-   "no_index" : {
-      "directory" : [
-         "t",
-         "inc"
-      ]
-   },
-   "prereqs" : {
-      "build" : {
-         "requires" : {
-            "ExtUtils::MakeMaker" : "0"
-         }
-      },
-      "configure" : {
-         "requires" : {
-            "ExtUtils::MakeMaker" : "0"
-         }
-      },
-      "runtime" : {
-         "requires" : {
-            "Devel::GlobalDestruction" : "0.09",
-            "Encode" : "2.00",
-            "Log::Report::Optional" : "1.03",
-            "Scalar::Util" : "0",
-            "String::Print" : "0.91",
-            "Sys::Syslog" : "0.27",
-            "Test::More" : "0.86"
-         }
-      }
-   },
-   "release_status" : "stable",
-   "resources" : {
-      "homepage" : "http://perl.overmeer.net/CPAN/",
-      "license" : [
-         "http://dev.perl.org/licenses/"
-      ],
-      "repository" : {
-         "type" : "git",
-         "url" : "https://github.com/markov2/perl5-Log-Report.git",
-         "web" : "https://github.com/markov2/perl5-Log-Report"
-      }
-   },
-   "version" : "1.28",
-   "x_serialization_backend" : "JSON::PP version 2.94"
-}
diff --git a/META.yml b/META.yml
deleted file mode 100644
index d6c9c04..0000000
--- a/META.yml
+++ /dev/null
@@ -1,33 +0,0 @@
----
-abstract: 'report a problem, pluggable handlers and language support'
-author:
-  - 'Mark Overmeer <markov@cpan.org>'
-build_requires:
-  ExtUtils::MakeMaker: '0'
-configure_requires:
-  ExtUtils::MakeMaker: '0'
-dynamic_config: 1
-generated_by: 'ExtUtils::MakeMaker version 7.3, CPAN::Meta::Converter version 2.150010'
-license: perl
-meta-spec:
-  url: http://module-build.sourceforge.net/META-spec-v1.4.html
-  version: '1.4'
-name: Log-Report
-no_index:
-  directory:
-    - t
-    - inc
-requires:
-  Devel::GlobalDestruction: '0.09'
-  Encode: '2.00'
-  Log::Report::Optional: '1.03'
-  Scalar::Util: '0'
-  String::Print: '0.91'
-  Sys::Syslog: '0.27'
-  Test::More: '0.86'
-resources:
-  homepage: http://perl.overmeer.net/CPAN/
-  license: http://dev.perl.org/licenses/
-  repository: https://github.com/markov2/perl5-Log-Report.git
-version: '1.28'
-x_serialization_backend: 'CPAN::Meta::YAML version 0.011'
diff --git a/Makefile.PL b/Makefile.PL
index 12b9845..8315ae5 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -2,7 +2,7 @@ use ExtUtils::MakeMaker;
 
 use 5.010;
 
-my $version = '1.28';
+my $version = '1.29';
 
 my %prereq  =
   ( Test::More               => '0.86'
diff --git a/README b/README
deleted file mode 100644
index 320ac73..0000000
--- a/README
+++ /dev/null
@@ -1,25 +0,0 @@
-=== README for Log-Report version 1.28
-=   Generated on Tue May 14 09:25:07 2019 by OODoc 2.02
-
-There are various ways to install this module:
-
- (1) if you have a command-line, you can do:
-       perl -MCPAN -e 'install <any package from this distribution>'
-
- (2) if you use Windows, have a look at http://ppm.activestate.com/
-
- (3) if you have downloaded this module manually (as root/administrator)
-       gzip -d Log-Report-1.28.tar.gz
-       tar -xf Log-Report-1.28.tar
-       cd Log-Report-1.28
-       perl Makefile.PL
-       make          # optional
-       make test     # optional
-       make install
-
-For usage, see the included manual-pages or
-    http://search.cpan.org/dist/Log-Report-1.28/
-
-Please report problems to
-    http://rt.cpan.org/Dist/Display.html?Queue=Log-Report
-
diff --git a/debian/changelog b/debian/changelog
index 91ec409..152fd92 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+liblog-report-perl (1.28+git20190516.ec277f3-1) UNRELEASED; urgency=medium
+
+  * New upstream snapshot.
+
+ -- Debian Janitor <janitor@jelmer.uk>  Tue, 01 Oct 2019 04:24:08 +0000
+
 liblog-report-perl (1.28-1) unstable; urgency=medium
 
   * Import upstream version 1.28.
diff --git a/examples/dancer/dancer1.pl b/examples/dancer/dancer1.pl
old mode 100644
new mode 100755
diff --git a/html/manual/doclist.html b/html/manual/doclist.html
new file mode 100644
index 0000000..7fb958d
--- /dev/null
+++ b/html/manual/doclist.html
@@ -0,0 +1,23 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<b>Show</b>
+<ul>
+<li>class <a href="relations.html">relations</a></li>
+<li>methods <a href="grouped.html">grouped</a></li>
+<li>methods <a href="sorted.html">alphabeticly</a></li>
+<li><b>documentation overview</b></li>
+</ul>
+<!--{list SYNOPSIS    }-->
+<!--{list DESCRIPTION }-->
+<!--{list OVERLOADED show_subroutines => COUNT }-->
+<!--{list METHODS    show_subroutines => COUNT }-->
+<!--{list DETAILS     }-->
+
+</body>
+</html>
diff --git a/html/manual/grouped.html b/html/manual/grouped.html
new file mode 100644
index 0000000..40df2b4
--- /dev/null
+++ b/html/manual/grouped.html
@@ -0,0 +1,20 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<b>Show</b> 
+<ul>
+<li>class <a href="relations.html">relations</a></li>
+<li><b>methods grouped</b></li>
+<li>methods <a href="sorted.html">alphabeticly</a></li>
+<li>documentation <a href="doclist.html">overview</a></li>
+</ul>
+<!--{list OVERLOADED show_sections => NAME}-->
+<!--{list METHODS    show_sections => NAME}-->
+
+</body>
+</html>
diff --git a/html/manual/head.html b/html/manual/head.html
new file mode 100644
index 0000000..69d0789
--- /dev/null
+++ b/html/manual/head.html
@@ -0,0 +1,25 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table width="100%">
+<tr><td valign="top">
+       <b><!--{project}--></b> <!--{a front}-->documentation</a><br />
+       <!--{distribution}--> <!--{version}--><br />
+       produced <!--{date}-->
+    </td><td align="center" valign="bottom">
+       <h1><!--{manual}--><br /><font size="5"><!--{name}--></font></h1>
+    </td><td valign="top">
+       <!--{a manuals}-->all manuals</a><br />
+       <!--{a methods}-->all methods</a><br />
+       <!--{a diagnostics}-->all&nbsp;diagnostics</a><br />
+       <!--{a details}-->all details</a><br />
+    </td></tr>
+</table>
+
+</body>
+</html>
diff --git a/html/manual/index.html b/html/manual/index.html
new file mode 100644
index 0000000..abf91e1
--- /dev/null
+++ b/html/manual/index.html
@@ -0,0 +1,22 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+
+<frameset rows="130,*" frameborder="NO">
+   <frame src="head.html" name="head">
+   <frameset cols="*,350" frameborder="NO">
+      <frame src="main.html"    name="main">
+      <frame src="relations.html" name="grouped">
+   </frameset>
+<frameset>
+   
+<noframes>
+  <body>
+  Sorry, you need frames for this documentation.
+  </body>
+</noframes>
+
+</html>
diff --git a/html/manual/main.html b/html/manual/main.html
new file mode 100644
index 0000000..ee18424
--- /dev/null
+++ b/html/manual/main.html
@@ -0,0 +1,14 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<!--{chapter SYNOPSIS   }-->
+<!--{chapter DESCRIPTION}-->
+<!--{chapter DETAILS   }-->
+
+</body>
+</html>
diff --git a/html/manual/methods.html b/html/manual/methods.html
new file mode 100644
index 0000000..a0bc872
--- /dev/null
+++ b/html/manual/methods.html
@@ -0,0 +1,20 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<!--{chapter OVERLOADED show_examples         => EXPAND,
+                        show_diagnostics      => EXPAND,
+                        show_sub_descriptions => ALL
+    }-->
+
+<!--{chapter METHODS    show_examples         => EXPAND,
+                        show_diagnostics      => EXPAND,
+                        show_sub_descriptions => ALL
+    }-->
+
+</body>
+</html>
diff --git a/html/manual/relations.html b/html/manual/relations.html
new file mode 100644
index 0000000..041a373
--- /dev/null
+++ b/html/manual/relations.html
@@ -0,0 +1,20 @@
+
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<b>Show</b> 
+<ul>
+<li><b>class relations</b></li>
+<li>methods <a href="grouped.html">grouped</a></li>
+<li>methods <a href="sorted.html">alphabeticly</a></li>
+<li>documentation <a href="doclist.html">overview</a></li>
+</ul>
+
+<!--{inheritance}-->
+
+</body>
+</html>
diff --git a/html/manual/sorted.html b/html/manual/sorted.html
new file mode 100644
index 0000000..35a2f42
--- /dev/null
+++ b/html/manual/sorted.html
@@ -0,0 +1,24 @@
+<html>
+<head>
+  <title><!--{title}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<b>Show</b>
+<ul>
+<li>class <a href="relations.html">relations</a></li>
+<li>methods <a href="grouped.html">grouped</a></li>
+<li><b>methods alphabeticly</b></li>
+<li>documentation <a href="doclist.html">overview</a></li>
+</ul>
+<!--{list METHODS show_subroutines => COUNT}-->
+
+Overloaded:
+<!--{list ALL subroutine_types => overload}--><br />
+
+Methods:
+<!--{list ALL subroutine_types => method|tie}--><br />
+
+</body>
+</html>
diff --git a/html/other/README.install b/html/other/README.install
new file mode 100644
index 0000000..0b51adc
--- /dev/null
+++ b/html/other/README.install
@@ -0,0 +1,44 @@
+
+Mail::Box documentation on HTML
+===============================
+
+An installed version of the manual pages of Mail::Box in HTML can be found
+at http://perl.overmeer.net/mailbox/html/
+
+All installation rules may change in future releases.  Please read this
+installation file carefully, each time.
+
+== Requirements
+
+ - To install this documentation set, you must to be able to run CGI
+   scripts on your web-server.
+ - About 6MB disk-space
+ - absolute location /mailbox/html to the top of your domain
+
+== Installation
+
+1) Unpack all files in $web/mailbox/html/
+
+2) Be sure that mailbox/html/jump.cgi has execute rights
+
+3) Be sure that web-server's configuration permit jump.cgi to run:
+
+     Options +ExecCGI
+     AddHandler cgi-script .cgi
+
+== Other location
+
+If you need to install the documentation on a different location than
+you need to change some absolute paths in the html files. On Unix/Linux,
+you can simply do:
+
+  for f in $(find . -type f);
+  do
+     sed <$f >x 's!/mailbox/html!/new/location!g' && mv x $f
+  done
+
+== Cannot run CGI
+
+Now you have a problem.  You *CAN NOT* point the cgi link to the public
+CGI script, because used numbers will change for each (pre-)release.  So
+you have to use the public installation of these pages.
diff --git a/html/other/details/index.html b/html/other/details/index.html
new file mode 100644
index 0000000..959a646
--- /dev/null
+++ b/html/other/details/index.html
@@ -0,0 +1,29 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Details</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table width="100%">
+<tr><td valign="top">
+       <b>Log::Report</b> <!--{a front}-->documentation</a><br />
+       <!--{distribution}--> <!--{version}--><br />
+       produced <!--{date}-->
+    </td><td align="center" valign="bottom">
+       <h1><font size="4"><!--{project}--></font><br /> All details</h1>
+    </td><td valign="top">
+       <!--{a manuals}-->all manuals</a><br />
+       <!--{a methods}-->all methods</a><br />
+       <!--{a diagnostics}-->all&nbsp;diagnostics</a><br />
+       <b>all details</b><br />
+    </td></tr>
+</table>
+
+<table cellspacing="10">
+<!--{index DETAILS table_columns => 3}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/diagnostics/errors.html b/html/other/diagnostics/errors.html
new file mode 100644
index 0000000..f851b42
--- /dev/null
+++ b/html/other/diagnostics/errors.html
@@ -0,0 +1,14 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Errors</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table>
+<!--{index DIAGNOSTICS type => error}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/diagnostics/head.html b/html/other/diagnostics/head.html
new file mode 100644
index 0000000..6f279f7
--- /dev/null
+++ b/html/other/diagnostics/head.html
@@ -0,0 +1,35 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Diagnostics</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table width="100%">
+<tr><td valign="top">
+       <b>Log::Report</b> <!--{a front}-->Documentation</a><br />
+       <!--{distribution}--> <!--{version}--><br />
+       produced <!--{date}-->
+    </td><td align="center" valign="bottom">
+       <h1><font size="4"><!--{project}--></font><br /> All Diagnostics</h1>
+    </td><td valign="top">
+       <!--{a manuals}-->all manuals</a><br />
+       <!--{a methods}-->all methods</a><br />
+       <b>all&nbsp;diagnostics</b><br />
+       <!--{a details}-->all details</a><br />
+    </td></tr>
+
+<tr><td>&nbsp;</td>
+    <td align="center">
+<font color="red">These pages are very incomplete on the moment</font><br />
+       <a href="errors.html" target="diag">Errors</a>&nbsp;&nbsp;--
+       <a href="warnings.html" target="diag">Warnings</a>&nbsp;&nbsp;--
+       <a href="notices.html" target="diag">Notices</a></td>
+    <td>&nbsp;</td>
+    </tr>
+
+</table>
+
+</body>
+</html>
diff --git a/html/other/diagnostics/index.html b/html/other/diagnostics/index.html
new file mode 100644
index 0000000..6af6cb4
--- /dev/null
+++ b/html/other/diagnostics/index.html
@@ -0,0 +1,19 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Diagnostics</title>
+  <!--{meta}-->
+</head>
+
+<frameset rows="150,*" frameborder="NO">
+   <frame src="head.html" name="head">
+   <frame src="errors.html" name="diag">
+<frameset>
+   
+<noframes>
+  <body>
+  Sorry, you need frames for this documentation.
+  </body>
+</noframes>
+
+</html>
diff --git a/html/other/diagnostics/notices.html b/html/other/diagnostics/notices.html
new file mode 100644
index 0000000..6686095
--- /dev/null
+++ b/html/other/diagnostics/notices.html
@@ -0,0 +1,14 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Notices</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table>
+<!--{index DIAGNOSTICS type => notice}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/diagnostics/warnings.html b/html/other/diagnostics/warnings.html
new file mode 100644
index 0000000..e6048ac
--- /dev/null
+++ b/html/other/diagnostics/warnings.html
@@ -0,0 +1,14 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Warnings</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table>
+<!--{index DIAGNOSTICS type => warning}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/index.html b/html/other/index.html
new file mode 100644
index 0000000..9543976
--- /dev/null
+++ b/html/other/index.html
@@ -0,0 +1,40 @@
+
+<html>
+<head>
+  <title><!--{project}--> <!--{version}--></title>
+  <!--{meta}-->
+</head>
+<body>
+
+<center>
+<table width="80%">
+<tr><td>
+  <h1><!--{project}--></h1>
+
+  <dl>
+  <dt><b><!--{a manuals}-->All packages&nbsp;&gt;&gt;</a></b></dt>
+  <dd><p>Lists all packages which are currently included in this
+      documentation system by name.</p></dd>
+
+  <dt><b><!--{a methods}-->All methods&nbsp;&gt;&gt;</a></b><dt>
+  <dd><p>The methods which are described, sorted alphabetically.  Sometimes
+      you have a feeling about the name of a method, but no idea where to
+      find it.</p></dd>
+
+  <dt><b><!--{a diagnostics}-->All diagnostics&nbsp;&gt;&gt;</a></b></dt>
+  <dd><p>Explanation of the meaning of error and warning messages, produced
+      by the library.  You can also find-out which method produces the
+      complaint, which may help resolving it.<br />
+      This page is far from complete, on the moment.</p>
+
+  <dt><b><!--{a details}-->All details&nbsp;&gt;&gt;</a></b></dt>
+  <dd><p>Many manual pages contain detailed explanations on how to use
+      the objects, with background information, examples, FAQ, etc.
+      This page provides an overview on all these manual page sections.<br />
+  </dl>
+
+</table>
+</center>
+
+</body>
+</html>
diff --git a/html/other/jump.cgi b/html/other/jump.cgi
new file mode 100755
index 0000000..ebb1aa7
--- /dev/null
+++ b/html/other/jump.cgi
@@ -0,0 +1,69 @@
+#!/usr/bin/perl -T
+
+use strict;
+use warnings;
+
+print "Content-Type: text/html\r\n\r\n";
+
+# Get the question
+
+my $to = $ENV{QUERY_STRING} || '';
+my ($manual, $unique) = $to =~ m/([\w:%]+)\&(\d+)/;
+$manual =~ s/\%[a-fA-F0-9]{2}/chr hex $1/ge;
+
+# Contact the database
+
+my $DB = $0;
+$DB    =~ s/[\w\.]+$/markers/;
+
+open DB, '<', $DB or die "Cannot read markers from $DB: $!\n";
+my $root = <DB>;
+chomp $root;
+
+# Lookup location of item in the manual page
+
+my ($nr, $in, $page);
+while( <DB> )
+{   ($nr, $in, $page) = split " ", $_, 3;
+    last if $nr eq $unique && $in eq $manual;
+}
+
+die "Cannot find id $to for $manual in $DB.\n"
+   unless $nr eq $unique;
+
+chomp $page;
+
+# Keep same index on the right, if possible
+
+my $show = "relations.html";
+if(my $refer = $ENV{HTTP_REFERER})
+{   $show = "$1.html"
+        if $refer =~ m/(doclist|sorted|grouped|relations)\.html/;
+}
+
+# Produce page, which is compible to the normal html/manual/index.html
+# This cgi script is processed by the template system too.
+
+print <<PAGE;
+<html>
+<head>
+  <title>$manual</title>
+  <!--{meta}-->
+</head>
+
+<frameset rows="130,*" frameborder="NO">
+   <frame src="$root/$manual/head.html" name="head">
+   <frameset cols="*,350" frameborder="NO">
+      <frame src="$root/$manual/$page#$unique" name="main">
+      <frame src="$root/$manual/$show" name="grouped">
+   </frameset>
+</frameset>
+   
+<noframes>
+  <body>
+  Sorry, you need frames for this documentation.
+  </body>
+</noframes>
+
+</html>
+PAGE
diff --git a/html/other/manuals/head.html b/html/other/manuals/head.html
new file mode 100644
index 0000000..192ff08
--- /dev/null
+++ b/html/other/manuals/head.html
@@ -0,0 +1,25 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Manuals</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table width="100%">
+<tr><td valign="top">
+       <b>Log::Report</b> <!--{a front}-->Documentation</a><br />
+       <!--{distribution}--> <!--{version}--><br />
+       produced <!--{date}-->
+    </td><td align="center" valign="bottom">
+       <h1><font size="4"><!--{project}--></font><br /> All Manuals</h1>
+    </td><td valign="top">
+       <b>all manuals</b><br />
+       <!--{a methods}-->all methods</a><br />
+       <!--{a diagnostics}-->all&nbsp;diagnostics</a><br />
+       <!--{a details}-->all details</a><br />
+    </td></tr>
+</table>
+
+</body>
+</html>
diff --git a/html/other/manuals/index.html b/html/other/manuals/index.html
new file mode 100644
index 0000000..cdb62d7
--- /dev/null
+++ b/html/other/manuals/index.html
@@ -0,0 +1,19 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Manuals</title>
+  <!--{meta}-->
+</head>
+
+<frameset rows="150,*" frameborder="NO">
+   <frame src="head.html" name="head">
+   <frame src="list.html" name="list">
+<frameset>
+   
+<noframes>
+  <body>
+  Sorry, you need frames for this documentation.
+  </body>
+</noframes>
+
+</html>
diff --git a/html/other/manuals/list.html b/html/other/manuals/list.html
new file mode 100644
index 0000000..7b0c4c0
--- /dev/null
+++ b/html/other/manuals/list.html
@@ -0,0 +1,20 @@
+<html>
+<head>
+  <title><!--{project}--> Manuals</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<center>
+<table width="80%" cellspacing="10">
+<!--{index MANUALS table_columns => 3}-->
+</table>
+</center>
+
+<hr noshade="noshade" />
+<a href="mailto:mark@overmeer.net">Mark Overmeer</a>.
+Documentation of <!--{version}-->,
+produced with OODoc on <!--{date}-->.
+
+</body>
+</html>
diff --git a/html/other/methods/A.html b/html/other/methods/A.html
new file mode 100644
index 0000000..e630ac7
--- /dev/null
+++ b/html/other/methods/A.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with A</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>A</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => A}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/B.html b/html/other/methods/B.html
new file mode 100644
index 0000000..7dbb7e0
--- /dev/null
+++ b/html/other/methods/B.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with B</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>B</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => B}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/C.html b/html/other/methods/C.html
new file mode 100644
index 0000000..6a7383e
--- /dev/null
+++ b/html/other/methods/C.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with C</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>C</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => C}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/D.html b/html/other/methods/D.html
new file mode 100644
index 0000000..531be77
--- /dev/null
+++ b/html/other/methods/D.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with D</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>D</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => D}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/E.html b/html/other/methods/E.html
new file mode 100644
index 0000000..a335066
--- /dev/null
+++ b/html/other/methods/E.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with E</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>E</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => E}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/F.html b/html/other/methods/F.html
new file mode 100644
index 0000000..794ab27
--- /dev/null
+++ b/html/other/methods/F.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with F</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>F</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => F}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/G.html b/html/other/methods/G.html
new file mode 100644
index 0000000..6f84c70
--- /dev/null
+++ b/html/other/methods/G.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with G</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>G</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => G}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/H.html b/html/other/methods/H.html
new file mode 100644
index 0000000..6dd63f0
--- /dev/null
+++ b/html/other/methods/H.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with H</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>H</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => H}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/I.html b/html/other/methods/I.html
new file mode 100644
index 0000000..d24891c
--- /dev/null
+++ b/html/other/methods/I.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with I</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>I</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => I}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/J.html b/html/other/methods/J.html
new file mode 100644
index 0000000..5b4b558
--- /dev/null
+++ b/html/other/methods/J.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with J</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>J</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => J}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/K.html b/html/other/methods/K.html
new file mode 100644
index 0000000..bd7bd30
--- /dev/null
+++ b/html/other/methods/K.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with K</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>K</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => K}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/L.html b/html/other/methods/L.html
new file mode 100644
index 0000000..8a56b84
--- /dev/null
+++ b/html/other/methods/L.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with L</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>L</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => L}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/M.html b/html/other/methods/M.html
new file mode 100644
index 0000000..26d8c9f
--- /dev/null
+++ b/html/other/methods/M.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with M</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>M</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => M}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/N.html b/html/other/methods/N.html
new file mode 100644
index 0000000..adf598f
--- /dev/null
+++ b/html/other/methods/N.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with N</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>N</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => N}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/O.html b/html/other/methods/O.html
new file mode 100644
index 0000000..fc747ee
--- /dev/null
+++ b/html/other/methods/O.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with O</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>O</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => O}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/P.html b/html/other/methods/P.html
new file mode 100644
index 0000000..12c6b2b
--- /dev/null
+++ b/html/other/methods/P.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with P</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>P</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => P}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/Q.html b/html/other/methods/Q.html
new file mode 100644
index 0000000..56789b1
--- /dev/null
+++ b/html/other/methods/Q.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with Q</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>Q</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => Q}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/R.html b/html/other/methods/R.html
new file mode 100644
index 0000000..204cebb
--- /dev/null
+++ b/html/other/methods/R.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with R</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>R</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => R}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/S.html b/html/other/methods/S.html
new file mode 100644
index 0000000..d5c73e4
--- /dev/null
+++ b/html/other/methods/S.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with S</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>S</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => S}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/T.html b/html/other/methods/T.html
new file mode 100644
index 0000000..5481772
--- /dev/null
+++ b/html/other/methods/T.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with T</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>T</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => T}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/U.html b/html/other/methods/U.html
new file mode 100644
index 0000000..1855cdd
--- /dev/null
+++ b/html/other/methods/U.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with U</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>U</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => U}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/V.html b/html/other/methods/V.html
new file mode 100644
index 0000000..3345d2f
--- /dev/null
+++ b/html/other/methods/V.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with V</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>V</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => V}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/W.html b/html/other/methods/W.html
new file mode 100644
index 0000000..0670d1d
--- /dev/null
+++ b/html/other/methods/W.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with W</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>W</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => W}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/X.html b/html/other/methods/X.html
new file mode 100644
index 0000000..b072912
--- /dev/null
+++ b/html/other/methods/X.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with X</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>X</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => X}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/Y.html b/html/other/methods/Y.html
new file mode 100644
index 0000000..d2c681f
--- /dev/null
+++ b/html/other/methods/Y.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with Y</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>Y</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => Y}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/Z.html b/html/other/methods/Z.html
new file mode 100644
index 0000000..ad16761
--- /dev/null
+++ b/html/other/methods/Z.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Methods with Z</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>Z</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => Z}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/_.html b/html/other/methods/_.html
new file mode 100644
index 0000000..f396ae6
--- /dev/null
+++ b/html/other/methods/_.html
@@ -0,0 +1,16 @@
+
+<html>
+<head>
+  <title><!--{project}-->; Other methods</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<h1>Other methods</h1>
+
+<table>
+<!--{index SUBROUTINES starting_with => _}-->
+</table>
+
+</body>
+</html>
diff --git a/html/other/methods/head.html b/html/other/methods/head.html
new file mode 100644
index 0000000..8416860
--- /dev/null
+++ b/html/other/methods/head.html
@@ -0,0 +1,55 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Methods</title>
+  <!--{meta}-->
+</head>
+<body>
+
+<table width="100%">
+<tr><td valign="top">
+       <b>Log::Report</b> <!--{a front}-->Documentation</a><br />
+       <!--{distribution}--> <!--{version}--><br />
+       produced <!--{date}-->
+    </td><td align="center" valign="bottom">
+       <h1><font size="4"><!--{project}--></font><br /> All Methods</h1>
+    </td><td valign="top">
+       <!--{a manuals}-->all manuals</a><br />
+       <b>all methods</b><br />
+       <!--{a diagnostics}-->all&nbsp;diagnostics</a><br />
+       <!--{a details}-->all details</a><br />
+    </td></tr>
+</table>
+
+<center>
+<a href="A.html" target="char">A</A>&nbsp;&nbsp;
+<a href="B.html" target="char">B</A>&nbsp;&nbsp;
+<a href="C.html" target="char">C</A>&nbsp;&nbsp;
+<a href="D.html" target="char">D</A>&nbsp;&nbsp;
+<a href="E.html" target="char">E</A>&nbsp;&nbsp;
+<a href="F.html" target="char">F</A>&nbsp;&nbsp;
+<a href="G.html" target="char">G</A>&nbsp;&nbsp;
+<a href="H.html" target="char">H</A>&nbsp;&nbsp;
+<a href="I.html" target="char">I</A>&nbsp;&nbsp;
+<a href="J.html" target="char">J</A>&nbsp;&nbsp;
+<a href="K.html" target="char">K</A>&nbsp;&nbsp;
+<a href="L.html" target="char">L</A>&nbsp;&nbsp;
+<a href="M.html" target="char">M</A>&nbsp;&nbsp;
+<a href="N.html" target="char">N</A>&nbsp;&nbsp;
+<a href="O.html" target="char">O</A>&nbsp;&nbsp;
+<a href="P.html" target="char">P</A>&nbsp;&nbsp;
+<a href="Q.html" target="char">Q</A>&nbsp;&nbsp;
+<a href="R.html" target="char">R</A>&nbsp;&nbsp;
+<a href="S.html" target="char">S</A>&nbsp;&nbsp;
+<a href="T.html" target="char">T</A>&nbsp;&nbsp;
+<a href="U.html" target="char">U</A>&nbsp;&nbsp;
+<a href="V.html" target="char">V</A>&nbsp;&nbsp;
+<a href="W.html" target="char">W</A>&nbsp;&nbsp;
+<a href="X.html" target="char">X</A>&nbsp;&nbsp;
+<a href="Y.html" target="char">Y</A>&nbsp;&nbsp;
+<a href="Z.html" target="char">Z</A>&nbsp;&nbsp;
+<a href="_.html" target="char">Other</A>
+</center>
+
+</body>
+</html>
diff --git a/html/other/methods/index.html b/html/other/methods/index.html
new file mode 100644
index 0000000..c9be478
--- /dev/null
+++ b/html/other/methods/index.html
@@ -0,0 +1,19 @@
+
+<html>
+<head>
+  <title><!--{project}-->; All Methods</title>
+  <!--{meta}-->
+</head>
+
+<frameset rows="150,*" frameborder="NO">
+   <frame src="head.html" name="head">
+   <frame src="A.html" name="char">
+<frameset>
+   
+<noframes>
+  <body>
+  Sorry, you need frames for this documentation.
+  </body>
+</noframes>
+
+</html>
diff --git a/html/other/oodoc.css b/html/other/oodoc.css
new file mode 100644
index 0000000..d8ebe27
--- /dev/null
+++ b/html/other/oodoc.css
@@ -0,0 +1,26 @@
+
+BODY {
+   font-family: Arial, Herlvetica, sans-serif
+}
+
+H2 {
+   font-variant: small-caps;
+}
+
+A:link {
+   color: green;
+   text-decoration: none;
+}
+
+A:visited {
+   color: blue;
+   text-decoration: none;
+}
+
+UL {
+   margin-top: 0;
+}
+
+DL {
+   margin-top: 1ex;
+}
diff --git a/lib/Dancer/Logger/LogReport.pm b/lib/Dancer/Logger/LogReport.pm
index 01d747b..cf9dfa1 100644
--- a/lib/Dancer/Logger/LogReport.pm
+++ b/lib/Dancer/Logger/LogReport.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Dancer::Logger::LogReport;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Dancer::Logger::Abstract', 'Exporter';
 
 use strict;
@@ -34,6 +27,58 @@ my %level_dancer2lr =
   , debug => 'TRACE'
   );
 
+=chapter NAME
+
+Dancer::Logger::LogReport - reroute Dancer logs into Log::Report
+
+=chapter SYNOPSIS
+
+  # When your main program is not a Dancer object
+  use My::Dancer::App;
+  use Log::Report;
+  ... start dispatcher ...
+  error "something is wrong";   # Log::Report::error()
+
+  # When your main program is a Dancer object
+  use Dancer;
+  use Dancer::Logger::LogReport;
+  use Log::Report import => 'dispatcher';
+  ... start dispatcher ...
+  error "something is wrong";   # Dancer::error()
+
+  # In any case, your main program needs to start log dispatcers
+  # Both Dancer and other Log::Report based modules will send
+  # their messages here:
+  dispatcher FILE => 'default', ...;
+
+  # In your config
+  logger: log_report
+  logger_format: %i%m   # keep it simple
+  log: debug            # filtered by dispatchers
+
+=chapter DESCRIPTION
+
+The M<Log::Report> exception/translation framework defines a large
+number of logging back-ends.  The same log messages can be sent to 
+multiple destinations at the same time via flexible dispatchers.
+When you use this logger in your Dancer application, it will nicely
+integrate with non-Dancer modules which need logging.
+
+Many log back-ends, like syslog, have more levels of system messages.
+Modules who explicitly load this module can use the missing C<assert>,
+C<notice>, C<panic>, and C<alert> log levels.  The C<trace> name is
+provided as well: when you are debugging, you add a 'trace' to your
+program... its just a better name than 'debug'.
+
+You probably want to set a very simple C<logger_format>, because the
+dispatchers do already add some of the fields that the default
+C<simple> format adds.  For instance, to get the filename/line-number 
+in messages depends on the dispatcher 'mode' (f.i. 'DEBUG').
+
+You also want to set the log level to C<debug>, because level filtering
+is controlled per dispatcher (as well)
+
+=cut
 
 # Add some extra 'levels'
 sub trace   { goto &Dancer::Logger::debug  }
diff --git a/lib/Dancer/Logger/LogReport.pod b/lib/Dancer/Logger/LogReport.pod
deleted file mode 100644
index 932219f..0000000
--- a/lib/Dancer/Logger/LogReport.pod
+++ /dev/null
@@ -1,74 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Dancer::Logger::LogReport - reroute Dancer logs into Log::Report
-
-=head1 INHERITANCE
-
- Dancer::Logger::LogReport
-   is a Dancer::Logger::Abstract
-
- Dancer::Logger::LogReport
-   is a Exporter
-
-=head1 SYNOPSIS
-
-  # When your main program is not a Dancer object
-  use My::Dancer::App;
-  use Log::Report;
-  ... start dispatcher ...
-  error "something is wrong";   # Log::Report::error()
-
-  # When your main program is a Dancer object
-  use Dancer;
-  use Dancer::Logger::LogReport;
-  use Log::Report import => 'dispatcher';
-  ... start dispatcher ...
-  error "something is wrong";   # Dancer::error()
-
-  # In any case, your main program needs to start log dispatcers
-  # Both Dancer and other Log::Report based modules will send
-  # their messages here:
-  dispatcher FILE => 'default', ...;
-
-  # In your config
-  logger: log_report
-  logger_format: %i%m   # keep it simple
-  log: debug            # filtered by dispatchers
-
-=head1 DESCRIPTION
-
-The L<Log::Report|Log::Report> exception/translation framework defines a large
-number of logging back-ends.  The same log messages can be sent to 
-multiple destinations at the same time via flexible dispatchers.
-When you use this logger in your Dancer application, it will nicely
-integrate with non-Dancer modules which need logging.
-
-Many log back-ends, like syslog, have more levels of system messages.
-Modules who explicitly load this module can use the missing C<assert>,
-C<notice>, C<panic>, and C<alert> log levels.  The C<trace> name is
-provided as well: when you are debugging, you add a 'trace' to your
-program... its just a better name than 'debug'.
-
-You probably want to set a very simple C<logger_format>, because the
-dispatchers do already add some of the fields that the default
-C<simple> format adds.  For instance, to get the filename/line-number 
-in messages depends on the dispatcher 'mode' (f.i. 'DEBUG').
-
-You also want to set the log level to C<debug>, because level filtering
-is controlled per dispatcher (as well)
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Dancer2/Logger/LogReport.pm b/lib/Dancer2/Logger/LogReport.pm
index 88653f5..de13f5f 100644
--- a/lib/Dancer2/Logger/LogReport.pm
+++ b/lib/Dancer2/Logger/LogReport.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Dancer2::Logger::LogReport;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 # ABSTRACT: Dancer2 logger engine for Log::Report
 
 use strict;
@@ -66,6 +59,67 @@ around 'error' => sub {
     $self->log(error => @_);
 };
 
+=chapter NAME
+
+Dancer2::Logger::LogReport - reroute Dancer2 logs into Log::Report
+
+=chapter SYNOPSIS
+
+  # This module is loaded when configured.  It does not provide
+  # end-user functions or methods.
+
+  # See L<Dancer2::Plugin::LogReport/"DETAILS">
+  
+=chapter DESCRIPTION
+
+[The Dancer2 plugin was contributed by Andrew Beverley]
+
+This logger allows the use of the many logging backends available
+in M<Log::Report>.  It will process all of the Dancer2 log messages,
+and also allow any other module to use the same logging facilities. The
+same log messages can be sent to multiple destinations at the same time
+via flexible dispatchers.
+
+If using this logger, you may also want to use
+M<Dancer2::Plugin::LogReport>
+
+Many log back-ends, like syslog, have more levels of system messages.
+Modules who explicitly load this module can use the missing C<assert>,
+C<notice>, C<panic>, and C<alert> log levels.  The C<trace> name is
+provided as well: when you are debugging, you add a 'trace' to your
+program... it's just a better name than 'debug'. You will need to load
+Log::Report in order to use the additional levels; if doing so directly within
+a Dancer2 application (not a sub-module), then you will either need to load
+Log::Report with C<syntax, 'LONG'> or use M<Dancer2::Plugin::LogReport> to
+prevent namespace clashes.
+
+=head2 Log Format
+
+If using this module on its own (such as a drop-in replacement for
+M<Dancer2::Logger::Syslog>), then the logging format is configured as with any
+other Dancer logger. If using this module with M<Dancer2::Plugin::LogReport>,
+then log_format is ignored and messages are not formatted, in order to keep the
+message format consistent regardless of where the message was generated (be it
+another module using Log::Report, the plugin, or Dancer itself). In this case,
+the log format should be configured using the applicable dispatcher (such as
+M<Log::Report::Dispatcher::Syslog::new(format)>).
+    
+If also using with the L<Log::Report> logging functions, then you probably want
+to set a very simple C<logger_format>, because the dispatchers do already add
+some of the fields that the default C<simple> format adds.  For instance, to
+get the filename/line-number in messages depends on the dispatcher 'mode' (f.i.
+'DEBUG').
+
+You also want to set the Dancer2 log level to C<debug>, because level filtering
+is controlled per dispatcher (as well).
+
+See L<Dancer2::Plugin::LogReport/"DETAILS"> for examples.
+
+=chapter METHODS
+
+=method log $level, $params
+
+=cut
 
 sub log   # no protoypes in Dancer2
 {   my ($self, $level, $msg) = @_;
diff --git a/lib/Dancer2/Logger/LogReport.pod b/lib/Dancer2/Logger/LogReport.pod
deleted file mode 100644
index 6db5190..0000000
--- a/lib/Dancer2/Logger/LogReport.pod
+++ /dev/null
@@ -1,84 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Dancer2::Logger::LogReport - reroute Dancer2 logs into Log::Report
-
-=head1 INHERITANCE
-
- Dancer2::Logger::LogReport
-   is a Moo::Object
-
-=head1 SYNOPSIS
-
-  # This module is loaded when configured.  It does not provide
-  # end-user functions or methods.
-
-  # See DETAILS
-
-=head1 DESCRIPTION
-
-[The Dancer2 plugin was contributed by Andrew Beverley]
-
-This logger allows the use of the many logging backends available
-in L<Log::Report|Log::Report>.  It will process all of the Dancer2 log messages,
-and also allow any other module to use the same logging facilities. The
-same log messages can be sent to multiple destinations at the same time
-via flexible dispatchers.
-
-If using this logger, you may also want to use
-L<Dancer2::Plugin::LogReport|Dancer2::Plugin::LogReport>
-
-Many log back-ends, like syslog, have more levels of system messages.
-Modules who explicitly load this module can use the missing C<assert>,
-C<notice>, C<panic>, and C<alert> log levels.  The C<trace> name is
-provided as well: when you are debugging, you add a 'trace' to your
-program... it's just a better name than 'debug'. You will need to load
-Log::Report in order to use the additional levels; if doing so directly within
-a Dancer2 application (not a sub-module), then you will either need to load
-Log::Report with C<syntax, 'LONG'> or use L<Dancer2::Plugin::LogReport|Dancer2::Plugin::LogReport> to
-prevent namespace clashes.
-
-=head2 Log Format
-
-If using this module on its own (such as a drop-in replacement for
-Dancer2::Logger::Syslog), then the logging format is configured as with any
-other Dancer logger. If using this module with L<Dancer2::Plugin::LogReport|Dancer2::Plugin::LogReport>,
-then log_format is ignored and messages are not formatted, in order to keep the
-message format consistent regardless of where the message was generated (be it
-another module using Log::Report, the plugin, or Dancer itself). In this case,
-the log format should be configured using the applicable dispatcher (such as
-L<Log::Report::Dispatcher::Syslog::new(format)|Log::Report::Dispatcher::Syslog/"Constructors">).
-    
-If also using with the L<Log::Report> logging functions, then you probably want
-to set a very simple C<logger_format>, because the dispatchers do already add
-some of the fields that the default C<simple> format adds.  For instance, to
-get the filename/line-number in messages depends on the dispatcher 'mode' (f.i.
-'DEBUG').
-
-You also want to set the Dancer2 log level to C<debug>, because level filtering
-is controlled per dispatcher (as well).
-
-See L<Dancer2::Plugin::LogReport/"DETAILS"> for examples.
-
-=head1 METHODS
-
-=over 4
-
-=item $obj-E<gt>B<log>($level, $params)
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Dancer2/Plugin/LogReport.pm b/lib/Dancer2/Plugin/LogReport.pm
index 7f195fb..ffd244a 100644
--- a/lib/Dancer2/Plugin/LogReport.pm
+++ b/lib/Dancer2/Plugin/LogReport.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Dancer2::Plugin::LogReport;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 
 use warnings;
 use strict;
@@ -26,6 +19,67 @@ use Scalar::Util qw/blessed refaddr/;
 my %_all_dsls;  # The DSLs for each app within the Dancer application
 my $_settings;
 
+=chapter NAME
+
+Dancer2::Plugin::LogReport - logging and exceptions via Log::Report
+
+=chapter SYNOPSIS
+
+  # Load the plugin into Dancer2
+  # see Log::Report::import() for %options
+  use Dancer2::Plugin::LogReport %options;
+
+  # Stop execution, redirect, and display an error to the user
+  $name or error "Please enter a name";
+
+  # Add debug information to logger
+  trace "We're here";
+
+  # Handling user errors cleanly
+  if (process( sub {MyApp::Model->create_user} )) {
+      # Success, redirect user elsewhere
+  } else {
+      # Failed, continue as if submit hadn't been made.
+      # Error message will be in session for display later.
+  }
+
+  # Send errors to template for display
+  hook before_template => sub {
+      my $tokens = shift;
+      $tokens->{messages} = session 'messages';
+      session 'messages' => [];
+  }
+
+=chapter DESCRIPTION
+
+[The Dancer2 plugin was contributed by Andrew Beverley]
+
+This module provides easy access to the extensive logging facilities
+provided by M<Log::Report>. Along with M<Dancer2::Logger::LogReport>,
+this brings together all the internal Dancer2 logging, handling for
+expected and unexpected exceptions, translations and application logging.
+
+Logging is extremely flexible using many of the available
+L<dispatchers|Log::Report::Dispatcher/DETAILS>.  Multiple dispatchers can be
+used, each configured separately to display different messages in different
+formats.  By default, messages are logged to a session variable for display on
+a webpage, and to STDERR.
+
+Messages within this plugin use the extended
+L<Dancer2::Logger::LogReport::Message> class rather than the standard
+L<Log::Report::Message> class.
+
+Note that it is currently recommended to use the plugin in all apps within
+a Dancer2 program, not only some. Therefore, wherever you C<use Dancer2>
+you should also C<use Dancer2::Plugin::LogReport>. This does not apply if
+using the same app name (C<use Dancer2 appname, 'Already::Exists'>). In
+all other modules, you can just C<use Log::Report>.
+
+Read the L</DETAILS> in below in this manual-page.
+
+=chapter METHODS
+
+=cut
 
 # "use" import
 sub import
@@ -146,6 +200,26 @@ on_plugin_import
 
 };    # ";" required!
 
+=method process
+
+C<process()> is an eval, but one which expects and understands exceptions
+generated by M<Log::Report>. Any messages will be logged as normal in
+accordance with the dispatchers, but any fatal exceptions will be caught
+and handled gracefully.  This allows much simpler error handling, rather
+than needing to test for lots of different scenarios.
+
+In a module, it is enough to simply use the C<error> keyword in the event
+of a fatal error.
+
+The return value will be 1 for success or 0 if a fatal exception occurred.
+
+See the L</DETAILS> for an example of how this is expected to be used.
+
+This module is configured only once in your application. The other modules
+which make your website do not need to require this plugin, instead they
+can C<use Log::Report> to get useful functions like error and fault.
+
+=cut
 
 sub process($$)
 {   my ($dsl, $coderef) = @_;
@@ -158,6 +232,50 @@ sub process($$)
 register process => \&process;
 
 
+=method fatal_handler
+
+C<fatal_handler()> allows alternative handlers to be defined in place of (or in
+addition to) the default redirect handler that is called on a fatal error.
+
+Calls should be made with 1 parameter: the subroutine to call in the case of a
+fatal error. The subroutine is passed 3 parameters: the DSL, the message in
+question, and the reason. The subroutine should return true or false depending
+on whether it handled the error. If it returns false, the next fatal handler is
+called, and if there are no others then the default redirect fatal handler is
+called.
+
+=example Error handler based on URL (e.g. API)
+
+  fatal_handler sub {
+    my ($dsl, $msg, $reason) = @_;
+    return if $dsl->app->request->uri !~ m!^/api/!;
+    status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';
+    $dsl->send_as(JSON => {
+        error             => 1,
+        error_description => $msg->toString,
+    }, {
+        content_type => 'application/json; charset=UTF-8',
+    });
+  };
+
+=example Return JSON responses for requests with content-type of application/json
+
+fatal_handler sub {
+    my ($dsl, $msg, $reason, $default) = @_;
+
+    (my $ctype = $dsl->request->header('content-type')) =~ s/;.*//;
+    return if $ctype ne 'application/json';
+    status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';
+    $dsl->send_as(JSON => {
+        error       => 1,
+        description => $msg->toString,
+    }, {
+        content_type => 'application/json; charset=UTF-8',
+    });
+  };
+
+
+=cut
 
 my @user_fatal_handlers;
 
@@ -229,6 +347,36 @@ sub _message_add($)
 }
 
 #------
+=section Handlers
+
+All the standard M<Log::Report> functions are available to use. Please see the
+L<Log::Report/"The Reason for the report"> for details
+of when each one should be used.
+
+L<Log::Report class functionality|Log::Report::Message.pod#class-STRING-ARRAY>
+to class messages (which can then be tested later):
+
+  notice __x"Class me up", _class => 'label';
+  ...
+  if ($msg->inClass('label')) ...
+
+M<Dancer2::Plugin::LogReport> has a special message class, C<no_session>,
+which prevents the message from being saved to the messages session
+variable. This is useful, for example, if you are writing messages within
+the session hooks, in which case recursive loops can be experienced.
+
+=method trace
+=method assert
+=method info
+=method notice
+=method warning
+=method mistake
+=method error
+=method fault
+=method alert
+=method failure
+=method panic
+=cut
 
 sub _forward_home($)
 {   my $dsl = _message_add(shift) || _get_dsl();
@@ -317,12 +465,346 @@ register alert   => sub { _report(ALERT => @_) };
 register fault   => sub { _report(FAULT => @_) };
 register failure => sub { _report(FAILURE => @_) };
 
+=method success
+This is a special additional type, equivalent to C<notice>.  The difference is
+that messages using this keyword will have the class C<success> added, which
+can be used to color the messages differently to the end user. For example,
+L<Dancer2::Plugin::LogReport::Message#bootstrap_color> uses this to display the
+message in green.
+=cut
 register success => sub { _report(SUCCESS => @_) };
 
 register_plugin for_versions => ['2'];
 
 #----------
 
+=chapter CONFIGURATION
+
+All configuration is optional. The example configuration file below shows the
+configuration options and defaults.
+
+    plugins:
+      LogReport:
+        # Whether to handle Dancer HTTP errors such as 404s. Currently has
+        # no effect due to unresolved issues saving messages to the session
+        # and accessing the DSL at that time.
+        handle_http_errors: 1
+        # Where to forward users in the event of an uncaught fatal
+        # error within a GET request
+        forward_url: /
+        # Or you can specify a template instead [1.13]
+        forward_template: error_template_file   # Defaults to empty
+        # For a production server (show_errors: 0), this is the text that
+        # will be displayed instead of unexpected exception errors
+        fatal_error_message: An unexpected error has occurred
+        # The levels of messages that will be saved to the session, and
+        # thus displayed to the end user
+        session_messages: [ NOTICE, WARNING, MISTAKE, ERROR, FAULT, ALERT, FAILURE, PANIC ]
+
+
+=chapter DETAILS
+
+This chapter will guide you through the myriad of ways that you can use
+M<Log::Report> in your Dancer2 application.
+
+We will set up our application to do the following:
+
+=over 4
+
+=item Messages to the user
+We'll look at an easy way to output messages to the user's web page, whether
+they be informational messages, warnings or errors.
+
+=item Debug information
+We'll look at an easy way to log debug information, at different levels.
+
+=item Manage unexpected exceptions
+We'll handle unexpected exceptions cleanly, in the unfortunate event that
+they happen in your production application.
+
+=item Email alerts of significant errors
+If we do get unexpected errors then we want to be notified them.
+
+=item Log DBIC information and errors
+We'll specifically look at nice ways to log SQL queries and errors when
+using DBIx::Class.
+
+=back
+
+=section Larger example
+
+In its simplest form, this module can be used for more flexible logging
+
+  get '/route' => sub {
+      # Stop execution, redirect, and display an error to the user
+      $name or error "Please enter a name";
+ 
+      # The same but translated
+      $name or error __"Please enter a name";
+  
+      # The same but translated and with variables
+      $name or error __x"{name} is not valid", name => $name;
+ 
+      # Show the user a warning, but continue execution
+      mistake "Not sure that's what you wanted";
+ 
+      # Add debug information, can be caught in syslog by adding
+      # the (for instance) syslog dispatcher
+      trace "Hello world";
+   };
+
+=section Setup and Configuration
+
+To make full use of L<Log::Report>, you'll need to use both
+L<Dancer2::Logger::LogReport> and L<Dancer2::Plugin::LogReport>.
+
+=subsection Dancer2::Logger::LogReport
+
+Set up L<Dancer2::Logger::LogReport> by adding it to your Dancer2
+application configuration (see L<Dancer2::Config>). By default,
+all messages will go to STDERR.
+
+To get all message out "the Perl way" (using print, warn and die) just use
+
+  logger: "LogReport"
+
+At start, these are handled by a M<Log::Report::Dispatcher::Perl> object,
+named 'default'.  If you open a new dispatcher with the name 'default',
+the output via the perl mechanisms will be stopped.
+
+To also send messages to your syslog:
+
+  logger: "LogReport"
+
+  engines:
+    logger:
+      LogReport:
+        log_format: %a%i%m      # See Dancer2::Logger::LogReport
+        app_name: MyApp
+        dispatchers:
+          default:              # Name
+            type: SYSLOG        # Log::Reporter::dispatcher() options
+            identity: myapp
+            facility: local0
+            flags: "pid ndelay nowait"
+            mode: DEBUG
+
+To send messages to a file:
+
+  logger: "LogReport"
+
+  engines:
+    logger:
+      LogReport:
+        log_format: %a%i%m      # See Dancer2::Logger::LogReport
+        app_name: MyApp
+        dispatchers:
+          logfile:              # "default" dispatcher stays open as well
+            type: FILE
+            to: /var/log/myapp.log
+            charset: utf-8
+            mode: DEBUG
+
+See L<Log::Report::Dispatcher> for full details of options.
+
+Finally: a Dancer2 script may run many applications.  Each application
+can have its own logger configuration.  However, Log::Report dispatchers
+are global, so will be shared between Dancer2 applications.  Any attempt
+to create a new Log::Report dispatcher by the same name (as will happen
+when a new Dancer2 application is started with the same configuration)
+will be ignored.
+
+=subsection Dancer2::Plugin::LogReport
+
+To use the plugin, you simply use it in your application:
+
+  package MyApp;
+  use Log::Report ();  # use early and minimal once
+  use Dancer2;
+  use Dancer2::Plugin::LogReport %config;
+
+Dancer2::Plugin::LogReport takes the same C<%config> options as
+L<Log::Report> itself (see M<Log::Report::import()>).
+
+If you want to send messages from your modules/models, there is
+no need to use this specific plugin. Instead, you should simply
+C<use Log::Report> to negate the need of loading all the Dancer2
+specific code.
+
+=section In use
+
+=subsection Logging debug information
+
+In its simplest form, you can now use all the
+L<Log::Report logging functions|Log::Report#The-Reason-for-the-report>
+to send messages to your dispatchers (as configured in the Logger
+configuration):
+
+  trace "I'm here";
+
+  warning "Something dodgy happened";
+
+  panic "I'm bailing out";
+
+  # Additional, special Dancer2 keyword
+  success "Settings saved successfully";
+
+=subsection Exceptions
+
+Log::Report is a combination of a logger and an exception system.  Messages
+to be logged are I<thrown> to all listening dispatchers to be handled.
+
+This module will also catch any unexpected exceptions:
+
+  # This will be caught, the error will be logged (full stacktrace to STDOUT,
+  # short message to the session messages), and the user will be forwarded
+  # (default to /). This would also be sent to syslog with the appropriate
+  # dispatcher.
+  get 'route' => sub {
+      my $foo = 1;
+      my $bar = $foo->{x}; # whoops
+  }
+
+For a production application (C<show_errors: 1>), the message saved in the
+session will be the generic text "An unexpected error has occurred". This
+can be customised in the configuration file, and will be translated.
+
+=subsection Sending messages to the user
+
+To make it easier to send messages to your users, messages at the following
+levels are also stored in the user's session: C<notice>, C<warning>, C<mistake>,
+C<error>, C<fault>, C<alert>, C<failure> and C<panic>.
+
+You can pass these to your template and display them at each page render:
+
+  hook before_template => sub {
+    my $tokens = shift;
+    $tokens->{messages} = session 'messages';
+    session 'messages' => []; # Clear the message queue
+  }
+
+Then in your template (for example the main layout):
+
+  [% FOR message IN messages %]
+    <div class="alert alert-[% message.bootstrap_color %]">
+      [% message.toString | html_entity %]
+    </div>
+  [% END %]
+
+The C<bootstrap_color> of the message is compatible with Bootstrap contextual
+colors: C<success>, C<info>, C<warning> or C<danger>.
+
+Now, anywhere in your application that you have used Log::Report, you can
+
+  warning "Hey user, you should now about this";
+
+and the message will be sent to the next page the user sees.
+
+=subsection Handling user errors
+
+Sometimes we write a function in a model, and it would be nice to have a
+nice easy way to return from the function with an error message. One
+way of doing this is with a separate error message variable, but that
+can be messy code. An alternative is to use exceptions, but these
+can be a pain to deal with in terms of catching them.
+Here's how to do it with Log::Report.
+
+In this example, we do use exceptions, but in a neat, easier to use manner.
+
+First, your module/model:
+
+  package MyApp::CD;
+
+  sub update {
+    my ($self, %values) = @_;
+    $values{title} or error "Please enter a title";
+    $values{description} or warning "No description entered";
+  }
+
+Then, in your controller:
+
+  package MyApp;
+  use Dancer2;
+
+  post '/cd' => sub {
+    my %values = (
+      title       => param('title');
+      description => param('description');
+    );
+    if (process sub { MyApp::CD->update(%values) } ) {
+      success "CD updated successfully";
+      redirect '/cd';
+    }
+
+    template 'cd' => { values => \%values };
+  }
+
+Now, when update() is called, any exceptions are caught. However, there is
+no need to worry about any error messages. Both the error and warning
+messages in the above code will have been stored in the messages session
+variable, where they can be displayed using the code in the previous section.
+The C<error> will have caused the code to stop running, and process()
+will have returned false. C<warning> will have simply logged the warning
+and not caused the function to stop running.
+
+=subsection Logging DBIC database queries and errors
+
+If you use L<DBIx::Class> in your application, you can easily integrate
+its logging and exceptions. To log SQL queries:
+
+  # Log all queries and execution time
+  $schema->storage->debugobj(new Log::Report::DBIC::Profiler);
+  $schema->storage->debug(1);
+
+By default, exceptions from DBIC are classified at the level "error". This
+is normally a user level error, and thus may be filtered as normal program
+operation. If you do not expect to receive any DBIC exceptions, then it
+is better to class them at the level "panic":
+
+  # panic() DBIC errors
+  $schema->exception_action(sub { panic @_ });
+  # Optionally get a stracktrace too
+  $schema->stacktrace(1);
+
+If you are occasionally running queries where you expect to naturally
+get exceptions (such as not inserting multiple values on a unique constraint),
+then you can catch these separately:
+
+  try { $self->schema->resultset('Unique')->create() };
+  # Log any messages from try block, but only as trace
+  $@->reportAll(reason => 'TRACE');
+
+=subsection Email alerts of exceptions
+
+If you have an unexpected exception in your production application,
+then you probably want to be notified about it. One way to do so is
+configure rsyslog to send emails of messages at the panic level. Use
+the following configuration to do so:
+
+  # Normal logging from LOCAL0
+  local0.*                        -/var/log/myapp.log
+
+  # Load the mail module
+  $ModLoad ommail
+  # Configure sender, receiver and mail server
+  $ActionMailSMTPServer localhost
+  $ActionMailFrom root
+  $ActionMailTo root
+  # Set up an email template
+  $template mailSubject,"Critical error on %hostname%"
+  $template mailBody,"RSYSLOG Alert\r\nmsg='%msg%'\r\nseverity='%syslogseverity-text%'"
+  $ActionMailSubject mailSubject
+  # Send an email no more frequently than every minute
+  $ActionExecOnlyOnceEveryInterval 60
+  # Configure the level of message to notify via email
+  if $syslogfacility-text == 'local0' and $syslogseverity < 3 then :ommail:;mailBody
+  $ActionExecOnlyOnceEveryInterval 0
+
+With the above configuration, you will only be emailed of severe errors, but can
+view the full log information in /var/log/myapp.log
+
+
+=cut
 
 1;
 
diff --git a/lib/Dancer2/Plugin/LogReport.pod b/lib/Dancer2/Plugin/LogReport.pod
deleted file mode 100644
index 4679af2..0000000
--- a/lib/Dancer2/Plugin/LogReport.pod
+++ /dev/null
@@ -1,526 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Dancer2::Plugin::LogReport - logging and exceptions via Log::Report
-
-=head1 INHERITANCE
-
- Dancer2::Plugin::LogReport
-   is a Dancer2::Plugin
-
-=head1 SYNOPSIS
-
-  # Load the plugin into Dancer2
-  # see Log::Report::import() for %options
-  use Dancer2::Plugin::LogReport %options;
-
-  # Stop execution, redirect, and display an error to the user
-  $name or error "Please enter a name";
-
-  # Add debug information to logger
-  trace "We're here";
-
-  # Handling user errors cleanly
-  if (process( sub {MyApp::Model->create_user} )) {
-      # Success, redirect user elsewhere
-  } else {
-      # Failed, continue as if submit hadn't been made.
-      # Error message will be in session for display later.
-  }
-
-  # Send errors to template for display
-  hook before_template => sub {
-      my $tokens = shift;
-      $tokens->{messages} = session 'messages';
-      session 'messages' => [];
-  }
-
-=head1 DESCRIPTION
-
-[The Dancer2 plugin was contributed by Andrew Beverley]
-
-This module provides easy access to the extensive logging facilities
-provided by L<Log::Report|Log::Report>. Along with L<Dancer2::Logger::LogReport|Dancer2::Logger::LogReport>,
-this brings together all the internal Dancer2 logging, handling for
-expected and unexpected exceptions, translations and application logging.
-
-Logging is extremely flexible using many of the available
-L<dispatchers|Log::Report::Dispatcher/DETAILS>.  Multiple dispatchers can be
-used, each configured separately to display different messages in different
-formats.  By default, messages are logged to a session variable for display on
-a webpage, and to STDERR.
-
-Messages within this plugin use the extended
-L<Dancer2::Logger::LogReport::Message> class rather than the standard
-L<Log::Report::Message> class.
-
-Note that it is currently recommended to use the plugin in all apps within
-a Dancer2 program, not only some. Therefore, wherever you C<use Dancer2>
-you should also C<use Dancer2::Plugin::LogReport>. This does not apply if
-using the same app name (C<use Dancer2 appname, 'Already::Exists'>). In
-all other modules, you can just C<use Log::Report>.
-
-Read the L</DETAILS> in below in this manual-page.
-
-=head1 METHODS
-
-=over 4
-
-=item $obj-E<gt>B<fatal_handler>()
-
-C<fatal_handler()> allows alternative handlers to be defined in place of (or in
-addition to) the default redirect handler that is called on a fatal error.
-
-Calls should be made with 1 parameter: the subroutine to call in the case of a
-fatal error. The subroutine is passed 3 parameters: the DSL, the message in
-question, and the reason. The subroutine should return true or false depending
-on whether it handled the error. If it returns false, the next fatal handler is
-called, and if there are no others then the default redirect fatal handler is
-called.
-
-example: Error handler based on URL (e.g. API)
-
-  fatal_handler sub {
-    my ($dsl, $msg, $reason) = @_;
-    return if $dsl->app->request->uri !~ m!^/api/!;
-    status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';
-    $dsl->send_as(JSON => {
-        error             => 1,
-        error_description => $msg->toString,
-    }, {
-        content_type => 'application/json; charset=UTF-8',
-    });
-  };
-
-example: Return JSON responses for requests with content-type of application/json
-
-fatal_handler sub {
-    my ($dsl, $msg, $reason, $default) = @_;
-
-    (my $ctype = $dsl->request->header('content-type')) =~ s/;.*//;
-    return if $ctype ne 'application/json';
-    status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';
-    $dsl->send_as(JSON => {
-        error       => 1,
-        description => $msg->toString,
-    }, {
-        content_type => 'application/json; charset=UTF-8',
-    });
-  };
-
-=item $obj-E<gt>B<process>()
-
-C<process()> is an eval, but one which expects and understands exceptions
-generated by L<Log::Report|Log::Report>. Any messages will be logged as normal in
-accordance with the dispatchers, but any fatal exceptions will be caught
-and handled gracefully.  This allows much simpler error handling, rather
-than needing to test for lots of different scenarios.
-
-In a module, it is enough to simply use the C<error> keyword in the event
-of a fatal error.
-
-The return value will be 1 for success or 0 if a fatal exception occurred.
-
-See the L</DETAILS> for an example of how this is expected to be used.
-
-This module is configured only once in your application. The other modules
-which make your website do not need to require this plugin, instead they
-can C<use Log::Report> to get useful functions like error and fault.
-
-=back
-
-=head2 Handlers
-
-All the standard L<Log::Report|Log::Report> functions are available to use. Please see the
-L<Log::Report/"The Reason for the report"> for details
-of when each one should be used.
-
-L<Log::Report class functionality|Log::Report::Message.pod#class-STRING-ARRAY>
-to class messages (which can then be tested later):
-
-  notice __x"Class me up", _class => 'label';
-  ...
-  if ($msg->inClass('label')) ...
-
-L<Dancer2::Plugin::LogReport|Dancer2::Plugin::LogReport> has a special message class, C<no_session>,
-which prevents the message from being saved to the messages session
-variable. This is useful, for example, if you are writing messages within
-the session hooks, in which case recursive loops can be experienced.
-
-=over 4
-
-=item $obj-E<gt>B<alert>()
-
-=item $obj-E<gt>B<assert>()
-
-=item $obj-E<gt>B<error>()
-
-=item $obj-E<gt>B<failure>()
-
-=item $obj-E<gt>B<fault>()
-
-=item $obj-E<gt>B<info>()
-
-=item $obj-E<gt>B<mistake>()
-
-=item $obj-E<gt>B<notice>()
-
-=item $obj-E<gt>B<panic>()
-
-=item $obj-E<gt>B<success>()
-
-This is a special additional type, equivalent to C<notice>.  The difference is
-that messages using this keyword will have the class C<success> added, which
-can be used to color the messages differently to the end user. For example,
-L<Dancer2::Plugin::LogReport::Message#bootstrap_color> uses this to display the
-message in green.
-
-=item $obj-E<gt>B<trace>()
-
-=item $obj-E<gt>B<warning>()
-
-=back
-
-=head1 DETAILS
-
-This chapter will guide you through the myriad of ways that you can use
-L<Log::Report|Log::Report> in your Dancer2 application.
-
-We will set up our application to do the following:
-
-=over 4
-
-=item Messages to the user
-
-We'll look at an easy way to output messages to the user's web page, whether
-they be informational messages, warnings or errors.
-
-=item Debug information
-
-We'll look at an easy way to log debug information, at different levels.
-
-=item Manage unexpected exceptions
-
-We'll handle unexpected exceptions cleanly, in the unfortunate event that
-they happen in your production application.
-
-=item Email alerts of significant errors
-
-If we do get unexpected errors then we want to be notified them.
-
-=item Log DBIC information and errors
-
-We'll specifically look at nice ways to log SQL queries and errors when
-using DBIx::Class.
-
-=back
-
-=head2 Larger example
-
-In its simplest form, this module can be used for more flexible logging
-
-  get '/route' => sub {
-      # Stop execution, redirect, and display an error to the user
-      $name or error "Please enter a name";
- 
-      # The same but translated
-      $name or error __"Please enter a name";
-  
-      # The same but translated and with variables
-      $name or error __x"{name} is not valid", name => $name;
- 
-      # Show the user a warning, but continue execution
-      mistake "Not sure that's what you wanted";
- 
-      # Add debug information, can be caught in syslog by adding
-      # the (for instance) syslog dispatcher
-      trace "Hello world";
-   };
-
-=head2 Setup and Configuration
-
-To make full use of L<Log::Report>, you'll need to use both
-L<Dancer2::Logger::LogReport> and L<Dancer2::Plugin::LogReport>.
-
-=head3 Dancer2::Logger::LogReport
-
-Set up L<Dancer2::Logger::LogReport> by adding it to your Dancer2
-application configuration (see L<Dancer2::Config>). By default,
-all messages will go to STDERR.
-
-To get all message out "the Perl way" (using print, warn and die) just use
-
-  logger: "LogReport"
-
-At start, these are handled by a L<Log::Report::Dispatcher::Perl|Log::Report::Dispatcher::Perl> object,
-named 'default'.  If you open a new dispatcher with the name 'default',
-the output via the perl mechanisms will be stopped.
-
-To also send messages to your syslog:
-
-  logger: "LogReport"
-
-  engines:
-    logger:
-      LogReport:
-        log_format: %a%i%m      # See Dancer2::Logger::LogReport
-        app_name: MyApp
-        dispatchers:
-          default:              # Name
-            type: SYSLOG        # Log::Reporter::dispatcher() options
-            identity: myapp
-            facility: local0
-            flags: "pid ndelay nowait"
-            mode: DEBUG
-
-To send messages to a file:
-
-  logger: "LogReport"
-
-  engines:
-    logger:
-      LogReport:
-        log_format: %a%i%m      # See Dancer2::Logger::LogReport
-        app_name: MyApp
-        dispatchers:
-          logfile:              # "default" dispatcher stays open as well
-            type: FILE
-            to: /var/log/myapp.log
-            charset: utf-8
-            mode: DEBUG
-
-See L<Log::Report::Dispatcher> for full details of options.
-
-Finally: a Dancer2 script may run many applications.  Each application
-can have its own logger configuration.  However, Log::Report dispatchers
-are global, so will be shared between Dancer2 applications.  Any attempt
-to create a new Log::Report dispatcher by the same name (as will happen
-when a new Dancer2 application is started with the same configuration)
-will be ignored.
-
-=head3 Dancer2::Plugin::LogReport
-
-To use the plugin, you simply use it in your application:
-
-  package MyApp;
-  use Log::Report ();  # use early and minimal once
-  use Dancer2;
-  use Dancer2::Plugin::LogReport %config;
-
-Dancer2::Plugin::LogReport takes the same C<%config> options as
-L<Log::Report> itself (see L<Log::Report::import()|Log::Report/"Configuration">).
-
-If you want to send messages from your modules/models, there is
-no need to use this specific plugin. Instead, you should simply
-C<use Log::Report> to negate the need of loading all the Dancer2
-specific code.
-
-=head2 In use
-
-=head3 Logging debug information
-
-In its simplest form, you can now use all the
-L<Log::Report logging functions|Log::Report#The-Reason-for-the-report>
-to send messages to your dispatchers (as configured in the Logger
-configuration):
-
-  trace "I'm here";
-
-  warning "Something dodgy happened";
-
-  panic "I'm bailing out";
-
-  # Additional, special Dancer2 keyword
-  success "Settings saved successfully";
-
-=head3 Exceptions
-
-Log::Report is a combination of a logger and an exception system.  Messages
-to be logged are I<thrown> to all listening dispatchers to be handled.
-
-This module will also catch any unexpected exceptions:
-
-  # This will be caught, the error will be logged (full stacktrace to STDOUT,
-  # short message to the session messages), and the user will be forwarded
-  # (default to /). This would also be sent to syslog with the appropriate
-  # dispatcher.
-  get 'route' => sub {
-      my $foo = 1;
-      my $bar = $foo->{x}; # whoops
-  }
-
-For a production application (C<show_errors: 1>), the message saved in the
-session will be the generic text "An unexpected error has occurred". This
-can be customised in the configuration file, and will be translated.
-
-=head3 Sending messages to the user
-
-To make it easier to send messages to your users, messages at the following
-levels are also stored in the user's session: C<notice>, C<warning>, C<mistake>,
-C<error>, C<fault>, C<alert>, C<failure> and C<panic>.
-
-You can pass these to your template and display them at each page render:
-
-  hook before_template => sub {
-    my $tokens = shift;
-    $tokens->{messages} = session 'messages';
-    session 'messages' => []; # Clear the message queue
-  }
-
-Then in your template (for example the main layout):
-
-  [% FOR message IN messages %]
-    <div class="alert alert-[% message.bootstrap_color %]">
-      [% message.toString | html_entity %]
-    </div>
-  [% END %]
-
-The C<bootstrap_color> of the message is compatible with Bootstrap contextual
-colors: C<success>, C<info>, C<warning> or C<danger>.
-
-Now, anywhere in your application that you have used Log::Report, you can
-
-  warning "Hey user, you should now about this";
-
-and the message will be sent to the next page the user sees.
-
-=head3 Handling user errors
-
-Sometimes we write a function in a model, and it would be nice to have a
-nice easy way to return from the function with an error message. One
-way of doing this is with a separate error message variable, but that
-can be messy code. An alternative is to use exceptions, but these
-can be a pain to deal with in terms of catching them.
-Here's how to do it with Log::Report.
-
-In this example, we do use exceptions, but in a neat, easier to use manner.
-
-First, your module/model:
-
-  package MyApp::CD;
-
-  sub update {
-    my ($self, %values) = @_;
-    $values{title} or error "Please enter a title";
-    $values{description} or warning "No description entered";
-  }
-
-Then, in your controller:
-
-  package MyApp;
-  use Dancer2;
-
-  post '/cd' => sub {
-    my %values = (
-      title       => param('title');
-      description => param('description');
-    );
-    if (process sub { MyApp::CD->update(%values) } ) {
-      success "CD updated successfully";
-      redirect '/cd';
-    }
-
-    template 'cd' => { values => \%values };
-  }
-
-Now, when update() is called, any exceptions are caught. However, there is
-no need to worry about any error messages. Both the error and warning
-messages in the above code will have been stored in the messages session
-variable, where they can be displayed using the code in the previous section.
-The C<error> will have caused the code to stop running, and process()
-will have returned false. C<warning> will have simply logged the warning
-and not caused the function to stop running.
-
-=head3 Logging DBIC database queries and errors
-
-If you use L<DBIx::Class> in your application, you can easily integrate
-its logging and exceptions. To log SQL queries:
-
-  # Log all queries and execution time
-  $schema->storage->debugobj(new Log::Report::DBIC::Profiler);
-  $schema->storage->debug(1);
-
-By default, exceptions from DBIC are classified at the level "error". This
-is normally a user level error, and thus may be filtered as normal program
-operation. If you do not expect to receive any DBIC exceptions, then it
-is better to class them at the level "panic":
-
-  # panic() DBIC errors
-  $schema->exception_action(sub { panic @_ });
-  # Optionally get a stracktrace too
-  $schema->stacktrace(1);
-
-If you are occasionally running queries where you expect to naturally
-get exceptions (such as not inserting multiple values on a unique constraint),
-then you can catch these separately:
-
-  try { $self->schema->resultset('Unique')->create() };
-  # Log any messages from try block, but only as trace
-  $@->reportAll(reason => 'TRACE');
-
-=head3 Email alerts of exceptions
-
-If you have an unexpected exception in your production application,
-then you probably want to be notified about it. One way to do so is
-configure rsyslog to send emails of messages at the panic level. Use
-the following configuration to do so:
-
-  # Normal logging from LOCAL0
-  local0.*                        -/var/log/myapp.log
-
-  # Load the mail module
-  $ModLoad ommail
-  # Configure sender, receiver and mail server
-  $ActionMailSMTPServer localhost
-  $ActionMailFrom root
-  $ActionMailTo root
-  # Set up an email template
-  $template mailSubject,"Critical error on %hostname%"
-  $template mailBody,"RSYSLOG Alert\r\nmsg='%msg%'\r\nseverity='%syslogseverity-text%'"
-  $ActionMailSubject mailSubject
-  # Send an email no more frequently than every minute
-  $ActionExecOnlyOnceEveryInterval 60
-  # Configure the level of message to notify via email
-  if $syslogfacility-text == 'local0' and $syslogseverity < 3 then :ommail:;mailBody
-  $ActionExecOnlyOnceEveryInterval 0
-
-With the above configuration, you will only be emailed of severe errors, but can
-view the full log information in /var/log/myapp.log
-
-=head1 CONFIGURATION
-
-All configuration is optional. The example configuration file below shows the
-configuration options and defaults.
-
-    plugins:
-      LogReport:
-        # Whether to handle Dancer HTTP errors such as 404s. Currently has
-        # no effect due to unresolved issues saving messages to the session
-        # and accessing the DSL at that time.
-        handle_http_errors: 1
-        # Where to forward users in the event of an uncaught fatal
-        # error within a GET request
-        forward_url: /
-        # Or you can specify a template instead [1.13]
-        forward_template: error_template_file   # Defaults to empty
-        # For a production server (show_errors: 0), this is the text that
-        # will be displayed instead of unexpected exception errors
-        fatal_error_message: An unexpected error has occurred
-        # The levels of messages that will be saved to the session, and
-        # thus displayed to the end user
-        session_messages: [ NOTICE, WARNING, MISTAKE, ERROR, FAULT, ALERT, FAILURE, PANIC ]
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Dancer2/Plugin/LogReport/Message.pm b/lib/Dancer2/Plugin/LogReport/Message.pm
index 0bd7ce0..27f2f49 100644
--- a/lib/Dancer2/Plugin/LogReport/Message.pm
+++ b/lib/Dancer2/Plugin/LogReport/Message.pm
@@ -1,20 +1,38 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Dancer2::Plugin::LogReport::Message;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use parent 'Log::Report::Message';
 
 use strict;
 use warnings;
 
+=chapter NAME
+
+Dancer2::Plugin::LogReport::Message - extended Log::Report message class
+
+=chapter SYNOPSIS
+
+  In your template:
+
+  [% FOR message IN messages %]
+    <div class="alert alert-[% message.bootstrap_color %]">
+      [% message.toString | html_entity %]
+    </div>
+  [% END %]
+
+=chapter DESCRIPTION
+
+[The Dancer2 plugin was contributed by Andrew Beverley]
+
+This class is an extension of L<Log::Report::Message>, with functions
+specifically designed for Dancer applications. Minimal functions are
+provided (currently only aimed at Bootstrap), but ideas for new ones are
+welcome.
+
+=chapter METHODS
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -22,6 +40,10 @@ sub init($)
     $self;
 }
 
+=method reason
+
+Get or set the reason of a message
+=cut
 
 sub reason
 {   my $self = shift;
@@ -38,6 +60,15 @@ my %reason2color =
     , MISTAKE => 'warning'
     );
 
+=method bootstrap_color
+
+Get a suitable bootstrap context color for the message. This can be
+used as per the SYNOPSIS.
+
+C<success> is used for M<Dancer2::Plugin::LogReport::success()> messages,
+C<info> colors are used for messages C<notice> and below, C<warning> is used
+for C<warning> and C<mistake>, C<danger> is used for all other messages
+=cut
 
 sub bootstrap_color
 {  my $self = shift;
diff --git a/lib/Dancer2/Plugin/LogReport/Message.pod b/lib/Dancer2/Plugin/LogReport/Message.pod
deleted file mode 100644
index 7202c7f..0000000
--- a/lib/Dancer2/Plugin/LogReport/Message.pod
+++ /dev/null
@@ -1,90 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Dancer2::Plugin::LogReport::Message - extended Log::Report message class
-
-=head1 INHERITANCE
-
- Dancer2::Plugin::LogReport::Message
-   is a Log::Report::Message
-
-=head1 SYNOPSIS
-
-  In your template:
-
-  [% FOR message IN messages %]
-    <div class="alert alert-[% message.bootstrap_color %]">
-      [% message.toString | html_entity %]
-    </div>
-  [% END %]
-
-=head1 DESCRIPTION
-
-[The Dancer2 plugin was contributed by Andrew Beverley]
-
-This class is an extension of L<Log::Report::Message>, with functions
-specifically designed for Dancer applications. Minimal functions are
-provided (currently only aimed at Bootstrap), but ideas for new ones are
-welcome.
-
-Extends L<"DESCRIPTION" in Log::Report::Message|Log::Report::Message/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Message|Log::Report::Message/"METHODS">.
- 
-=over 4
-
-=item $obj-E<gt>B<bootstrap_color>()
-
-Get a suitable bootstrap context color for the message. This can be
-used as per the SYNOPSIS.
-
-C<success> is used for L<Dancer2::Plugin::LogReport::success()|Dancer2::Plugin::LogReport/"Handlers"> messages,
-C<info> colors are used for messages C<notice> and below, C<warning> is used
-for C<warning> and C<mistake>, C<danger> is used for all other messages
-
-=item $obj-E<gt>B<reason>()
-
-Get or set the reason of a message
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Message|Log::Report::Message/"DETAILS">.
- 
-=head1 OVERLOADING
-
-Extends L<"OVERLOADING" in Log::Report::Message|Log::Report::Message/"OVERLOADING">.
- 
-=over 4
-
-=item overload: B<as $function>
-
-Inherited, see L<Log::Report::Message/"OVERLOADING">
-
-=item overload: B<concatenation>
-
-Inherited, see L<Log::Report::Message/"OVERLOADING">
-
-=item overload: B<stringification>
-
-Inherited, see L<Log::Report::Message/"OVERLOADING">
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report.pm b/lib/Log/Report.pm
index 36de3bf..c8d6401 100644
--- a/lib/Log/Report.pm
+++ b/lib/Log/Report.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Exporter';
 
 use warnings;
@@ -59,6 +52,172 @@ textdomain 'log-report';
 
 my $default_dispatcher = dispatcher PERL => 'default', accept => 'NOTICE-';
 
+=chapter NAME
+Log::Report - report a problem, with exceptions and translation support
+
+=chapter SYNOPSIS
+ # Invocation with 'mode' to get trace and verbose messages
+ use Log::Report mode => 'DEBUG';
+
+ # Usually invoked with a domain, which groups packages for translation
+ use Log::Report 'my-domain', %options;
+
+ # Interpolation syntax via String::Print
+ # First step to translations, once you need it.
+ print __x"my name is {name}", name => $n;  # print, so no exception
+ print __"Hello World\n";     # no interpolation, optional translation
+ print __x'Hello World';      # SYNTAX ERROR!!  ' is alternative for ::
+
+ # Functions replacing die/warn/carp, casting exceptions.
+ error "oops";                # exception like die(), no translation
+ -f $config or panic "Help!"; # alert/error/fault/info/...more
+
+ # Combined exception, interpolation, and optional translation
+ error __x"Help!";            # __x() creates ::Message object
+ error __x('gettext msgid', param => $value, ...)
+     if $condition;
+
+ # Also non fatal "exceptions" find their way to dispatchers
+ info __x"started {pid}", pid => $$;   # translatable
+ debug "$i was here!";        # you probably do not want to translate debug
+ panic "arrghhh";             # like Carp::Confess
+
+ # Many destinations for an exception message (may exist in parallel)
+ dispatcher PERL => 'default' # see Log::Report::Dispatcher: use die/warn
+   , reasons => 'NOTICE-';    # this dispatcher is already present at start
+
+ dispatcher SYSLOG => 'syslog'# also send to syslog
+   , charset => 'iso-8859-1'  # explicit character conversions
+   , locale => 'en_US';       # overrule user's locale
+
+ dispatcher close => 'default';  # stop default die/warn dispatcher
+
+ # Fill-in values, like Locale::TextDomain and gettext
+ # See Log::Report::Message section DETAILS
+ fault __x"cannot allocate {size} bytes", size => $size;
+ fault "cannot allocate $size bytes";     # no translation, ok
+ fault __x"cannot allocate $size bytes";  # not translatable, wrong
+
+ # Translation depending on count
+ # Leading and trailing whitespace stay magically outside translation
+ # tables.  @files in scalar context.  Special parameter with _
+ print __xn"found one file\n", "found {_count} files", @files;
+
+ # Borrow from an other text-domain (see M<Log::Report::Message>)
+ print __x(+"errors in {line}", _domain => 'global', line => $line);
+
+ # catch errors (implements hidden eval/die)
+ try { error };
+ if($@) {...}      # $@ isa Log::Report::Dispatcher::Try
+ if(my $exception = $@->wasFatal)         # ::Exception object
+
+ # Language translations at the output component
+ # Translation management via Log::Report::Lexicon
+ use POSIX::1003::Locale qw/setlocale LC_ALL/;
+ setlocale(LC_ALL, 'nl_NL');
+ info __"Hello World!";      # in Dutch, if translation table found
+
+ # Exception classes, see Log::Report::Exception
+ try { error __x"something", _class => 'parsing,schema' };
+ if($@->wasFatal->inClass('parsing')) ...
+
+=chapter DESCRIPTION 
+Get messages to users and logs.  C<Log::Report> combines three tasks
+which are closely related in one:
+=over 4
+=item . logging (like L<Log::Log4Perl> and syslog), and
+=item . exceptions (like error and info), with
+=item . translations (like C<gettext> and L<Locale::TextDomain>)
+=back
+You B<do not need> to use this module for all three reasons: pick what
+you need now, maybe extend the usage later.  Read more about how and
+why in the L</DETAILS> section, below.  Especially, you should B<read
+about the REASON parameter>.
+
+Also, you can study this module swiftly via the article published in
+the German Perl C<$foo-magazine>.  English version:
+F<http://perl.overmeer.net/log-report/papers/201306-PerlMagazine-article-en.html>
+
+=chapter FUNCTIONS
+
+=section Report Production and Configuration
+
+=function report [%options], $reason, $message|<STRING,$params>, 
+
+The C<report> function is sending (for some $reason) a $message to be
+displayed or logged (by a `dispatcher').  This function is the core
+for M<error()>, M<info()> etc functions, which are nicer names for this
+exception throwing: better use those short names.
+
+The $reason is a string like 'ERROR' (for function C<error()>).
+The $message is a M<Log::Report::Message> object (which are created with
+the special translation syntax like M<__x()>).  The $message may also
+be a plain string, or an M<Log::Report::Exception> object. The optional
+first parameter is a HASH which can be used to influence the dispatchers.
+
+The optional %options are listed below.  Quite differently from other
+functions and methods, they have to be passed in a HASH as first parameter.
+
+This function returns the LIST of dispatchers which accepted the $message.
+When empty, no back-end has accepted it so the $message was "lost".
+Even when no back-end needs the message, the program will still exit
+when there is a $reason to C<die()>.
+
+=option  to NAME|ARRAY-of-NAMEs
+=default to C<undef>
+Sent the $message only to the NAMEd dispatchers.  Ignore unknown NAMEs.
+Still, the dispatcher needs to be enabled and accept the REASONs.
+
+=option  errno INTEGER
+=default errno C<$!> or C<1>
+When the $reason includes the error text (See L</Run modes>), you can
+overrule the error code kept in C<$!>.  In other cases, the return code
+defaults to C<1> (historical UNIX behavior). When the message $reason
+(combined with the run-mode) is severe enough to stop the program,
+this value as return code of the program.  The use of this option itself
+will not trigger an C<die()>.
+
+=option  stack ARRAY
+=default stack C<undef>
+When defined, that data is used to display the call stack.  Otherwise,
+it is collected via C<caller()> if needed.
+
+=option  location STRING
+=default location C<undef>
+When defined, this location is used in the display.  Otherwise, it
+is determined automatically if needed.  An empty string will disable
+any attempt to display this line.
+
+=option  locale LOCALE
+=default locale C<undef>
+Use this specific locale, in stead of the user's preference.
+
+=option  is_fatal BOOLEAN
+=default is_fatal <depends on reason>
+Some logged exceptions are fatal, other aren't.  The default usually
+is correct. However, you may want an error to be caught (usually with
+M<try()>), redispatch it to syslog, but without it killing the main
+program.
+
+=examples for use of M<report()>
+ # long syntax example
+ report TRACE => "start processing now";
+ report INFO  => '500: ' . __'Internal Server Error';
+
+ # explicit dispatcher, no translation
+ report {to => 'syslog'}, NOTICE => "started process $$";
+ notice "started process $$", _to => 'syslog';   # same
+
+ # short syntax examples
+ trace "start processing now";
+ warning  __x'Disk {percent%.2f}% full', percent => $p
+     if $p > 97;
+
+ # error message, overruled to be printed in Brazilian
+ report {locale => 'pt_BR'}
+    , WARNING => "do this at home!";
+ 
+=cut
 
 sub report($@)
 {   my $opts = ref $_[0] eq 'HASH' ? +{ %{ (shift) } } : {};
@@ -164,6 +323,78 @@ sub report($@)
     @disp;
 }
 
+=function dispatcher <$type, $name, %options>|<$command, @names>
+
+The C<dispatcher> function controls access to dispatchers: the back-ends
+which process messages, do the logging.  Dispatchers are global entities,
+addressed by a symbolic $name.  Please read M<Log::Report::Dispatcher> as
+well.
+
+The C<Log::Report> suite has its own dispatcher @types, but also connects
+to external dispatching frameworks.  Each need some (minor) conversions,
+especially with respect to translation of REASONS of the reports
+into log-levels as the back-end understands.
+
+[1.10] When you open a dispatcher with a $name which is already in use,
+that existing dispatcher gets closed.  Except when you have given an
+'dispatcher "do-not-reopen"' earlier, in which case the first object
+stays alive, and the second attempt ignored. [1.11] The automatically
+created default dispatcher will get replaced, even when this option
+is given, by another dispatcher which is named 'default'.
+
+The %options are a mixture of parameters needed for the
+Log::Report dispatcher wrapper and the settings of the back-end.
+See M<Log::Report::Dispatcher>, the documentation for the back-end
+specific wrappers, and the back-ends for more details.
+
+Implemented COMMANDs are C<close>, C<find>, C<list>, C<disable>,
+C<enable>, C<mode>, C<filter>, C<needs>, C<active-try>, and C<do-not-reopen>.
+
+Most commands are followed by a LIST of dispatcher @names to be addressed.
+For C<mode> see section L</Run modes>; it requires a MODE argument
+before the LIST of NAMEs.  Non-existing names will be ignored. When
+C<ALL> is specified, then all existing dispatchers will get addressed.
+For C<filter> see L<Log::Report::Dispatcher/Filters>; it requires a CODE
+reference before the @names of the dispatchers which will have the it
+applied (defaults to all).
+
+With C<needs>, you only provide a REASON: it will return the list of
+dispatchers which need to be called in case of a message with the REASON
+is triggered.  The C<active-try> [1.09] returns the closest surrounding
+exception catcher, a M<Log::Report::Dispatcher::Try> object.
+
+For both the creation as COMMANDs version of this method, all objects
+involved are returned as LIST, non-existing ones skipped.  In SCALAR
+context with only one name, the one object is returned.
+
+=examples play with dispatchers
+ dispatcher Log::Dispatcher::File => mylog =>
+   , accept   => 'MISTAKE-'              # for wrapper
+   , locale   => 'pt_BR'                 # other language
+   , filename => 'logfile';              # for back-end
+
+ dispatcher close => 'mylog';            # cleanup
+ my $obj = dispatcher find => 'mylog'; 
+ my @obj = dispatcher 'list';
+ dispatcher disable => 'syslog';
+ dispatcher enable => 'mylog', 'syslog'; # more at a time
+ dispatcher mode => 'DEBUG', 'mylog';
+ dispatcher mode => 'DEBUG', 'ALL';
+ my $catcher = dispatcher 'active-try';
+ dispatcher 'do-not-reopen';
+
+ my @need_info = dispatcher needs => 'INFO';
+ if(dispatcher needs => 'INFO') ...      # anyone needs INFO
+
+ # Getopt::Long integration: see Log::Report::Dispatcher::mode()
+ dispatcher PERL => 'default', mode => 'DEBUG', accept => 'ALL'
+     if $debug;
+
+=error in SCALAR context, only one dispatcher name accepted
+The M<dispatcher()> method returns the M<Log::Report::Dispatcher>
+objects which it has accessed.  When multiple names where given, it
+wishes to return a LIST of objects, not the count of them.
+=cut
 
 my %disp_actions = map +($_ => 1), qw/
   close find list disable enable mode needs filter active-try do-not-reopen
@@ -280,6 +511,50 @@ sub _whats_needed()
     $reporter->{needs} = \%needs;
 }
 
+=function try CODE, %options
+
+Execute the CODE while blocking all dispatchers as long as it is running.
+The exceptions which occur while running the CODE are caught until it
+has finished.  When there where no fatal errors, the result of the CODE
+execution is returned.
+
+After the CODE was tried, the C<$@> will contain a
+M<Log::Report::Dispatcher::Try> object, which contains the collected
+messages.
+
+Run-time errors from Perl and die's, croak's and confess's within the
+program (which shouldn't appear, but you never know) are collected into an
+M<Log::Report::Message> object, using M<Log::Report::Die>.
+
+The %options are passed to the constructor of the try-dispatcher, see
+M<Log::Report::Dispatcher::Try::new()>.  For instance, you may like to
+add C<< mode => 'DEBUG' >>, or C<< accept => 'ERROR-' >>.
+
+B<Be warned> that the parameter to C<try> is a CODE reference.  This means
+that you shall not use a comma after the block when there are %options
+specified.  On the other hand, you shall use a semi-colon after the
+block if there are no arguments.
+
+B<Be warned> that the {} are interpreted as subroutine, which means that,
+for instance, it has its own C<@_>.  The manual-page of M<Try::Tiny>
+lists a few more side-effects of this.
+
+=examples
+ my $x = try { 3/$x };  # mind the ';' !!
+ if($@) {               # signals something went wrong
+
+ if(try {...}) {        # block ended normally, returns bool
+
+ try { ... }            # no comma!!
+    mode => 'DEBUG', accept => 'ERROR-';
+
+ try sub { ... },       # with comma, also \&function
+    mode => 'DEBUG', accept => 'ALL';
+
+ my $response = try { $ua->request($request) };
+ if(my $e = $@->wasFatal) ...
+
+=cut
 
 sub try(&@)
 {   my $code = shift;
@@ -324,6 +599,36 @@ sub try(&@)
 }
 
 #------------
+=section Abbreviations for report()
+
+The following functions are all wrappers for calls to M<report()>,
+and available when "syntax is SHORT" (by default, see M<import()>).
+You cannot specify additional options to influence the behavior of
+C<report()>, which are usually not needed anyway.
+
+=function trace $message
+Short for C<< report TRACE => $message >>
+=function assert $message
+Short for C<< report ASSERT => $message >>
+=function info $message
+Short for C<< report INFO => $message >>
+=function notice $message
+Short for C<< report NOTICE => $message >>
+=function warning $message
+Short for C<< report WARNING => $message >>
+=function mistake $message
+Short for C<< report MISTAKE => $message >>
+=function error $message
+Short for C<< report ERROR => $message >>
+=function fault $message
+Short for C<< report FAULT => $message >>
+=function alert $message
+Short for C<< report ALERT => $message >>
+=function failure $message
+Short for C<< report FAILURE => $message >>
+=function panic $message
+Short for C<< report PANIC => $message >>
+=cut
 
 sub trace(@)   {report TRACE   => @_}
 sub assert(@)  {report ASSERT  => @_}
@@ -338,6 +643,65 @@ sub failure(@) {report FAILURE => @_}
 sub panic(@)   {report PANIC   => @_}
 
 #-------------
+=section Messages (optionally translatable)
+
+Even when you do not support translations (yet) you may want to use
+message objects to improve the logging feature. For instance,
+you get very powerful interpolation from M<String::Print>.
+
+The language translations are initiate by limited set of functions
+which contain B<two under-scores> (C<__>) in their name.  Most
+of them return a M<Log::Report::Message> object.
+
+B<Be warned(1)> that -in general- its considered very bad practice to
+combine multiple translations into one message: translating may also
+affect the order of the translated components. Besides, when the person
+which translates only sees smaller parts of the text, his (or her) job
+becomes more complex.  So:
+
+ print __"Hello" . ', ' . __"World!";  # works, but to be avoided
+ print __"Hello, World!";              # preferred, complete sentence
+
+The the former case, tricks with overloading used by the
+M<Log::Report::Message> objects will still make delayed translations
+work.
+
+In normal situations, it is not a problem to translate interpolated
+values:
+
+ print __"the color is {c}", c => __"red";
+
+B<Be warned(2)> that using C<< __'Hello' >> will produce a syntax error like
+"String found where operator expected at .... Can't find string terminator
+"'" anywhere before EOF".  The first quote is the cause of the complaint,
+but the second generates the error.  In the early days of Perl, the single
+quote was used to separate package name from function name, a role which
+was later replaced by a double-colon.  So C<< __'Hello' >> gets interpreted
+as C<< __::Hello ' >>.  Then, there is a trailing single quote which has
+no counterpart.
+
+=function __ $msgid
+This function (name is B<two> under-score characters) will cause the $msgid
+to be replaced by the translations when doing the actual output.  Returned
+is a M<Log::Report::Message> object, which will be used in translation
+later.  Translating is invoked when the object gets stringified.  When
+you have no translation tables, the $msgid will be shown untranslated.
+
+If you need options for M<Log::Report::Message::new()> then use M<__x()>;
+the prototype of this function does not permit parameters: it is a
+prefix operator!
+
+=examples how to use __()
+ print __"Hello World";      # translated into user's language
+ print __'Hello World';      # syntax error!
+ print __('Hello World');    # ok, translated
+ print __"Hello", " World";  # World not translated
+
+ my $s = __"Hello World";    # creates object, not yet translated
+ print ref $s;               # Log::Report::Message
+ print $s;                   # ok, translated
+ print $s->toString('fr');   # ok, forced into French
+=cut
 
 
 sub __($)
@@ -349,6 +713,14 @@ sub __($)
       );
 } 
 
+=function __x $msgid, PAIRS
+Translate the $msgid and then interpolate the VARIABLES in that string.
+Of course, translation and interpolation is delayed as long as possible.
+Both OPTIONS and VARIABLES are key-value pairs.
+
+The PAIRS are options for M<Log::Report::Message::new()> and variables
+to be filled in.
+=cut
 
 # label "msgid" added before first argument
 sub __x($@)
@@ -366,6 +738,30 @@ sub __x($@)
       );
 } 
 
+=function __n $msgid, $plural_msgid, $count, PAIRS
+It depends on the value of $count (and the selected language) which
+text will be displayed.  When translations can not be performed, then
+$msgid will be used when $count is 1, and PLURAL_MSGSID in other cases.
+However, some languages have more complex schemes than English.
+
+The PAIRS are options for M<Log::Report::Message::new()> and variables
+to be filled in.
+
+=examples how to use __n()
+ print __n "one", "more", $a;
+ print __n("one", "more", $a), "\n";
+ print +(__n "one", "more", $a), "\n";
+
+ # new-lines are ignore at lookup, but printed.
+ print __n "one\n", "more\n", $a;
+
+ # count is in scalar context
+ # the value is also available as _count
+ print __n "found one\n", "found {_count}\n", @r;
+
+ # ARRAYs and HASHes are counted
+ print __n "one", "more", \@r;
+=cut
 
 sub __n($$$@)
 {   my ($single, $plural, $count) = (shift, shift, shift);
@@ -380,6 +776,21 @@ sub __n($$$@)
      );
 }
 
+=function __nx $msgid, $plural_msgid, $count, PAIRS
+It depends on the value of $count (and the selected language) which
+text will be displayed.  See details in M<__n()>.  After translation,
+the VARIABLES will be filled-in.
+
+The PAIRS are options for M<Log::Report::Message::new()> and variables
+to be filled in.
+
+=examples how to use __nx()
+ print __nx "one file", "{_count} files", $nr_files;
+ print __nx "one file", "{_count} files", @files;
+
+ local $" = ', ';
+ print __nx "one file: {f}", "{_count} files: {f}", @files, f => \@files;
+=cut
 
 sub __nx($$$@)
 {   my ($single, $plural, $count) = (shift, shift, shift);
@@ -395,6 +806,9 @@ sub __nx($$$@)
      );
 }
 
+=function __xn $single_msgid, $plural_msgid, $count, $paurs
+Same as M<__nx()>, because we have no preferred order for 'x' and 'n'.
+=cut
 
 sub __xn($$$@)   # repeated for prototype
 {   my ($single, $plural, $count) = (shift, shift, shift);
@@ -410,17 +824,85 @@ sub __xn($$$@)   # repeated for prototype
      );
 }
 
+=function N__ $msgid
+Label to indicate that the string is a text which will be translated
+later.  The function itself does nothing.  See also M<N__w()>.
+
+This no-op function is used as label to the xgettext program to build the
+translation tables.
+
+=example how to use N__()
+ # add three msgids to the translation table
+ my @colors = (N__"red", N__"green", N__"blue");
+ my @colors = N__w "red green blue";   # same
+ print __ $colors[1];                  # translate green
+
+ # using M<__()>, would work as well
+ my @colors = (__"red", __"green", __"blue");
+ print $colors[1];
+ # however: this will always create all M<Log::Report::Message> objects,
+ # where maybe only one is used.
+=cut
 
 sub N__($) { $_[0] }
 
+=function N__n $single_msgid, $plural_msgid
+Label to indicate that the two MSGIDs are related, the first as
+single, the seconds as its plural.  Only used to find the text
+fragments to be translated.  The function itself does nothing.
+=examples how to use M<N__n()>
+ my @save = N__n "save file", "save files";
+ my @save = (N__n "save file", "save files");
+ my @save = N__n("save file", "save files");
+
+ # be warned about SCALARs in prototype!
+ print __n @save, $nr_files;  # wrong!
+ print __n $save[0], $save[1], @files, %vars;
+=cut
 
 sub N__n($$) {@_}
 
+=function N__w STRING
+This extension to the M<Locale::TextDomain> syntax, is a combined
+C<qw> (list of quoted words) and M<N__()> into a list of translatable
+words.
+
+=example of M<N__w()>
+  my @colors = (N__"red", N__"green", N__"blue");
+  my @colors = N__w"red green blue";  # same
+  print __ $colors[1];
+=cut
 
 sub N__w(@) {split " ", $_[0]}
 
 
 #-------------
+=subsection Messages with msgctxt
+
+In Log::Report, the message context (mgsctxt in the PO-files --in the
+translation tables) can be used in a very powerful way.  Read all about
+it in M<Log::Report::Translator::Context>
+
+The msgctxt versions of the tranditional gettext infrastructure are far
+less useful for Log::Report, because we can easily work with different
+text domains within the same program.  That should avoid most of the
+accidental translation conflicts between components of the code.
+
+Just for compatibility with M<Locale::TextDomain> and completeness, the
+'p' versions of above methods are supported.  See examples for these
+functions in M<Locale::TextDomain>.
+
+B<Warnings:> Functions C<N__p()> and C<N__np()> seem not to be usable in
+reality, hence not implemented.  The script xgettext-perl and
+M<Log::Report::Extract::PerlPPI> (both in the M<Log::Report::Lexicon>
+distribution) do not yet support these functions.
+
+=function __p $msgctxt, $msgid
+=function __px $msgctxt, $msgid, PAIRS
+=function __np $msgctxt, $msgid, $plural, count
+=function __npx $msgctxt, $msgid, $plural, count, PAIRS
+
+=cut
 
 sub __p($$) { __($_[0])->_msgctxt($_[1]) }
 sub __px($$@)
@@ -439,6 +921,76 @@ sub __npx($$$$@)
 }
 
 #-------------
+=section Configuration
+
+=method import [$level,][$domain,] %options
+The import is automatically called when the package is compiled.  For all
+packages but one in your distribution, it will only contain the name of
+the $domain.
+
+For one package, the import list may additionally contain textdomain
+configuration %options.  These %options are used for all packages which
+use the same $domain.  These are alternatives:
+
+  # Do not use variables in the %*config!  They are not yet initialized
+  # when Log::Report->import is run!!!
+  use Log::Report 'my-domain', %config, %domain_config;
+
+  use Log::Report 'my-domain', %config;
+  textdomain 'my-domain', %domain_config;   # vars allowed
+
+The latter syntax has major advantages, when the configuration of the
+domain is determined at run-time.  It is probably also easier to understand.
+
+See M<Log::Report::Domain::configure()>, for the B<list of %options>
+for the domain configuration.  Here, we only list the options which are
+related to the normal import behavior.
+
+The export $level is a plus (+) followed by a number, for instance C<+1>,
+to indicate to on which caller level we need to work.  This is used
+in M<Log::Report::Optional>.  It defaults to '0': my direct caller.
+
+=option  syntax 'REPORT'|'SHORT'|'LONG'
+=default syntax 'SHORT'
+The SHORT syntax will add the report abbreviations (like function
+M<error()>) to your name-space.  Otherwise, each message must be produced
+with M<report()>. C<LONG> is an alternative to C<REPORT>: both do not
+pollute your namespace with the useful abbrev functions.
+
+=option  mode LEVEL
+=default mode 'NORMAL'
+This sets the default mode for all created dispatchers.  You can
+also selectively change the output mode, like
+ dispatcher PERL => 'default', mode => 3
+
+=option  import FUNCTION|ARRAY
+=default import C<undef>
+[0.998] When not specified, the C<syntax> option determines the list
+of functions which are being exported.  With this option, the C<syntax>
+option is ignored and only the specified FUNCTION(s) are imported.
+
+=option  message_class CLASS
+=default message_class C<Log::Report::Message>
+[1.08] Use a more powerful message object class, for instance because
+your messages need extra attributes.  The provided CLASS must extend
+M<Log::Report::Message>
+
+=examples of import
+ use Log::Report mode => 3;     # '3' or 'DEBUG'
+
+ use Log::Report 'my-domain';   # in each package producing messages
+
+ use Log::Report 'my-domain'    # in one package, top of distr
+  , mode            => 'VERBOSE'
+  , syntax          => 'REPORT' # report ERROR, not error()
+  , translator      => Log::Report::Translator::POT->new
+     ( lexicon => '/home/mine/locale'  # translation tables
+     )
+  , native_language => 'nl_NL'; # untranslated msgs are Dutch
+
+ use Log::Report import => 'try';      # or ARRAY of functions
+
+=cut
 
 sub import(@)
 {   my $class = shift;
@@ -532,6 +1084,17 @@ sub translator($;$$$$)
     $domain->configure(translator => $translator, where => [$pkg, $fn, $line]);
 }
 
+=function textdomain <[$name],$config>|<$name, 'DELETE'|'EXISTS'>|$domain
+[1.00] Without CONFIGuration, this returns the M<Log::Report::Domain> object
+which administers the $domain, by default the domain effective in the scope
+of the package.
+
+A very special case is "DELETE", which will remove the domain
+configuration. [1.20] "EXISTS" will check for existence: when it exists,
+it will be returned, but a domain will not be automagically created.
+
+[1.20] You may also pass a pre-configured domain.
+=cut
 
 sub textdomain(@)
 {   if(@_==1 && blessed $_[0])
@@ -555,6 +1118,20 @@ sub textdomain(@)
 }
 
 #--------------
+=section Reasons
+
+=c_method needs $reason, [$reasons]
+Returns true when the reporter needs any of the $reasons, when any of
+the active dispatchers is collecting messages in the specified level.
+This is useful when the processing of data for the message is relatively
+expensive, but for instance only required in debug mode.
+
+=example
+  if(Log::Report->needs('TRACE'))
+  {   my @args = ...expensive calculation...;
+      trace "your options are: @args";
+  }
+=cut
 
 sub needs(@)
 {   my $thing = shift;
@@ -562,5 +1139,441 @@ sub needs(@)
     first {$self->{needs}{$_}} @_;
 }
 
+=chapter DETAILS
+
+=section Introduction
+
+Getting messages to users and logs. The distincting concept of this module,
+is that three tasks which are strongly related are merged into one simple
+syntax.  The three tasks:
+
+=over 4
+=item produce some text on a certain condition,
+=item translate it to the proper language, and
+=item deliver it in some way to a user.
+=back
+
+Text messages in Perl are produced by commands like C<print>, C<die>,
+C<warn>, C<carp>, or C<croak>.  But where is that output directed to?
+Translations is hard.  There is no clean exception mechanism.
+
+Besides, the C<print>/C<warn>/C<die> together produce only three different
+output "levels" with a message.  Think of the variation syslog offers:
+more than 7 levels.  Many people manually implement their own tricks to
+get additional levels, like verbose and debug flags.  Log::Report offers
+that variety.
+
+The (optional) translations use the beautiful syntax defined by
+M<Locale::TextDomain>, with some own extensions (of course).  A very
+important difference is that translations are delayed till the delivery
+step: until a dispatcher actually writes your message into a file, sends
+it to syslog, or shows it on the screen.  This means that the pop-up in
+the graphical interface of the user may show the text in the language
+of the user --say Chinese in utf8--, but at the same time syslog may
+write the latin1 English version of the same message.
+
+=section Background ideas
+
+The following ideas are the base of this implementation:
+
+=over 4
+
+=item . simplification
+Handling errors and warnings is probably the most labor-intensive
+task for a programmer: when programs are written correctly, up-to
+three-quarters of the code is related to testing, reporting, and
+handling (problem) conditions.  Simplifying the way to create reports,
+simplifies programming and maintenance.
+
+=item . multiple dispatchers
+It is not the location where the (for instance) error occurs which
+determines what will happen with the text, but the main application which
+uses the the complaining module has control.  Messages have a reason.
+Based on the `reason' classification, they can get ignored, send to one
+or multiple dispatchers, like M<Log::Dispatch>, M<Log::Log4perl>,
+or UNIX syslog.
+
+=item . delayed translations
+The background ideas are that of M<Locale::TextDomain>, based
+on C<gettext()>.  However, in the C<Log::Report> infrastructure,
+translations are postponed until the text is dispatched to a screen
+or log-file; the same report can be sent to syslog in (for instance)
+English and to the user interface in Dutch.
+
+=item . context sensitive
+Using contexts, you can set-up how to translate or rewrite messages,
+to improve messages.  A typical problem is whether to use gender in
+text (use 'his' or 'her'): you can set a gender in a context, and the
+use translation tables to pick the right one.
+=back
+
+=section Error handling models
+
+There are two approaches to handling errors and warnings.  In the first
+approach, as produced by C<die>, C<warn> and the C<carp> family of
+commands, the program handles the problem immediately on the location
+where the problem appears.  In the second approach, an I<exception>
+is thrown on the spot where the problem is created, and then somewhere
+else in the program the condition is handled.
+
+The implementation of exceptions in Perl5 is done with a eval-die pair:
+on the spot where the problem occurs, C<die> is called.  But, because of
+the execution of that routine is placed within an C<eval>, the program
+as a whole will not die, just the execution of a part of the program
+will seize.  However, what if the condition which caused the routine to die
+is solvable on a higher level?  Or what if the user of the code doesn't
+bother that a part fails, because it has implemented alternatives for
+that situation?  Exception handling is quite clumsy in Perl5.
+
+The C<Log::Report> set of distributions let modules concentrate on the
+program flow, and let the main program decide on the report handling
+model.  The infrastructure to translate messages into multiple languages,
+whether to create exceptions or carp/die, to collect longer explanations
+with the messages, to log to mail or syslog, and so on, is decided in
+pluggable back-ends.
+
+=subsection The Reason for the report
+
+Traditionally, perl has a very simple view on error reports: you
+either have a warning or an error.  However, it would be much clearer
+for user's and module-using applications, when a distinction is made
+between various causes.  For instance, a configuration error is quite
+different from a disk-full situation.  In C<Log::Report>, the produced
+reports in the code tell I<what> is wrong.  The main application defines
+loggers, which interpret the cause into (syslog) levels.
+
+Defined by C<Log::Report> are
+
+=over 4
+=item . trace (debug, program)
+The message will be used when some logger has debugging enabled.  The
+messages show steps taken by the program, which are of interest by the
+developers and maintainers of the code, but not for end-users.
+
+=item . assert (program)
+Shows an unexpected condition, but continues to run.  When you want the
+program to abort in such situation, that use C<panic>.
+
+=item . info (verbose, program)
+These messages show larger steps in the execution of the program.
+Experienced users of the program usually do not want to see all these
+intermediate steps.  Most programs will display info messages (and
+higher) when some C<verbose> flag is given on the command-line.
+
+=item . notice (program)
+An user may need to be aware of the program's accidental smart behavior,
+for instance, that it initializes a lasting C<Desktop> directory in your
+home directory.  Notices should be sparse.
+
+=item . warning (program)
+The program encountered some problems, but was able to work around it
+by smart behavior.  For instance, the program does not understand a
+line from a log-file, but simply skips the line.
+
+=item . mistake (user)
+When a user does something wrong, but what is correctable by smart
+behavior of the program.  For instance, in some configuration file,
+you can fill-in "yes" or "no", but the user wrote "yeah".  The program
+interprets this as "yes", producing a mistake message as warning.
+
+It is much nicer to tell someone that he/she made a mistake, than
+to call that an error.
+
+=item . error (user)
+The user did something wrong, which is not automatically correctable
+or the program is not willing to correct it automatically for reasons
+of code quality.  For instance, an unknown option flag is given on the
+command-line.  These are configuration issues, and have no useful
+value in C<$!>.  The program will be stopped, usually before taken off.
+
+=item . fault (system)
+The program encountered a situation where it has no work-around.  For
+instance, a file cannot be opened to be written.  The cause of that
+problem can be some user error (i.e. wrong filename), or external
+(you accidentally removed a directory yesterday).  In any case, the
+C<$!> (C<$ERRNO>) variable is set here.
+
+=item . alert (system)
+Some external cause disturbs the execution of the program, but the
+program stays alive and will try to continue operation.  For instance,
+the connection to the database is lost.  After a few attempts, the
+database can be reached and the program continues as if nothing happened.
+The cause is external, so C<$!> is set.  Usually, a system administrator
+needs to be informed about the problem.
+
+=item . failure (system)
+Some external cause makes it impossible for this program to continue.
+C<$!> is set, and usually the system administrator wants to be
+informed.  The program will die.
+
+The difference with C<fault> is subtile and not always clear.  A fault
+reports an error returned by an operating system call, where the failure
+would report an operational problem, like a failing mount.
+
+=item . panic (program)
+All above report classes are expected: some predictable situation
+is encountered, and therefore a message is produced.  However, programs
+often do some internal checking.  Of course, these conditions should
+never be triggered, but if they do... then we can only stop.
+
+For instance, in an OO perl module, the base class requires all
+sub-classes to implement a certain method.  The base class will produce
+a stub method with triggers a panic when called.  The non-dieing version
+of this test C<assert>.
+=back
+
+I<Debugging> or being C<verbose> are run-time behaviors, and have nothing
+directly to do with the type of message which is produced.  These two
+are B<modes> which can be set on the dispatchers: one dispatcher may
+be more verbose that some other.
+
+On purpose, we do not use the terms C<die> or C<fatal>, because the
+dispatcher can be configured what to do in cause of which condition.
+For instance, it may decide to stop execution on warnings as well.
+
+The terms C<carp> and C<croak> are avoided, because the program cause
+versus user cause distinction (warn vs carp) is reflected in the use
+of different reasons.  There is no need for C<confess> and C<croak>
+either, because the dispatcher can be configured to produce stack-trace
+information (for a limited sub-set of dispatchers)
+
+=subsection Report levels
+Various frameworks used with perl programs define different labels
+to indicate the reason for the message to be produced.
+
+ Perl5 Log::Dispatch Syslog Log4Perl Log::Report
+ print   0,debug     debug  debug    trace
+ print   0,debug     debug  debug    assert
+ print   1,info      info   info     info
+ warn\n  2,notice    notice info     notice
+ warn    3,warning   warn   warn     mistake
+ carp    3,warning   warn   warn     warning
+ die\n   4,error     err    error    error
+ die     5,critical  crit   fatal    fault
+ croak   6,alert     alert  fatal    alert  
+ croak   7,emergency emerg  fatal    failure
+ confess 7,emergency emerg  fatal    panic
+
+=subsection Run modes
+The run-mode change which messages are passed to a dispatcher, but
+from a different angle than the dispatch filters; the mode changes
+behavioral aspects of the messages, which are described in detail in
+L<Log::Report::Dispatcher/Processing the message>.  However, it should
+behave as you expect: the DEBUG mode shows more than the VERBOSE mode,
+and both show more than the NORMAL mode.
+
+=example extract run mode from Getopt::Long
+The C<GetOptions()> function will count the number of C<v> options
+on the command-line when a C<+> is after the option name.
+
+ use Log::Report;
+ use Getopt::Long qw(:config no_ignore_case bundling);
+
+ my $mode;    # defaults to NORMAL
+ GetOptions 'v+'        => \$mode
+          , 'verbose=i' => \$mode
+          , 'mode=s'    => \$mode
+     or exit 1;
+
+ dispatcher 'PERL', 'default', mode => $mode;
+
+Now, C<-vv> will set C<$mode> to C<2>, as will C<--verbose 2> and
+C<--verbose=2> and C<--mode=ASSERT>.  Of course, you do not need to
+provide all these options to the user: make a choice.
+
+=example the mode of a dispatcher
+ my $mode = dispatcher(find => 'myname')->mode;
+
+=example run-time change mode of a dispatcher
+To change the running mode of the dispatcher, you can do
+  dispatcher mode => DEBUG => 'myname';
+
+However, be warned that this does not change the types of messages
+accepted by the dispatcher!  So: probably you will not receive
+the trace, assert, and info messages after all.  So, probably you
+need to replace the dispatcher with a new one with the same name:
+  dispatcher FILE => 'myname', to => ..., mode => 'DEBUG';
+
+This may reopen connections (depends on the actual dispatcher), which
+might be not what you wish to happened.  In that case, you must take
+the following approach:
+
+  # at the start of your program
+  dispatcher FILE => 'myname', to => ...
+     , accept => 'ALL';    # overrule the default 'NOTICE-' !!
+
+  # now it works
+  dispatcher mode => DEBUG => 'myname';    # debugging on
+  ...
+  dispatcher mode => NORMAL => 'myname';   # debugging off
+
+Of course, this comes with a small overall performance penalty.
+
+=subsection Exceptions
+
+The simple view on live says: you 're dead when you die.  However,
+more complex situations try to revive the dead.  Typically, the "die"
+is considered a terminating exception, but not terminating the whole
+program, but only some logical block.  Of course, a wrapper round
+that block must decide what to do with these emerging problems.
+
+Java-like languages do not "die" but throw exceptions which contain the
+information about what went wrong.  Perl modules like C<Exception::Class>
+simulate this.  It's a hassle to create exception class objects for each
+emerging problem, and the same amount of work to walk through all the
+options.
+
+Log::Report follows a simpler scheme.  Fatal messages will "die", which is
+caught with "eval", just the Perl way (used invisible to you).  However,
+the wrapper gets its hands on the message as the user has specified it:
+untranslated, with all unprocessed parameters still at hand.
+
+ try { fault __x "cannot open file {file}", file => $fn };
+ if($@)                         # is Log::Report::Dispatcher::Try
+ {   my $cause = $@->wasFatal;  # is Log::Report::Exception
+     $cause->throw if $cause->message->msgid =~ m/ open /;
+     # all other problems ignored
+ }
+
+See M<Log::Report::Dispatcher::Try> and M<Log::Report::Exception>.
+
+=section Comparison
+
+Some notes on differences between the Log::Report approach and other
+Perl concepts.
+
+=subsection die/warn/Carp
+
+Perl's built-in exception system is very primitive: "die" and "warn".
+Most programming languages provide a much more detailed exception
+mechanism.
+
+A typical perl program can look like this:
+
+ my $dir = '/etc';
+
+ File::Spec->file_name is_absolute($dir)
+     or die "ERROR: directory name must be absolute.\n";
+
+ -d $dir
+     or die "ERROR: what platform are you on?";
+
+ until(opendir DIR, $dir)
+ {   warn "ERROR: cannot read system directory $dir: $!";
+     sleep 60;
+ }
+
+ print "Processing directory $dir\n"
+     if $verbose;
+
+ while(defined(my $file = readdir DIR))
+ {   if($file =~ m/\.bak$/)
+     {   warn "WARNING: found backup file $dir/$f\n";
+         next;
+     }
+
+     die "ERROR: file $dir/$file is binary"
+         if $debug && -B "$dir/$file";
+
+     print "DEBUG: processing file $dir/$file\n"
+         if $debug;
+
+     open FILE, "<", "$dir/$file"
+         or die "ERROR: cannot read from $dir/$f: $!";
+
+     close FILE
+         or croak "ERROR: read errors in $dir/$file: $!";
+ }
+
+Where C<die>, C<warn>, and C<print> are used for various tasks.  With
+C<Log::Report>, you would write
+
+ use Log::Report;
+
+ # can be left-out when there is no debug/verbose
+ dispatcher PERL => 'default', mode => 'DEBUG';
+
+ my $dir = '/etc';
+
+ File::Spec->file_name is_absolute($dir)
+     or mistake "directory name must be absolute";
+
+ -d $dir
+     or panic "what platform are you on?";
+
+ until(opendir DIR, $dir)
+ {   alert "cannot read system directory $dir";
+     sleep 60;
+ }
+
+ info "Processing directory $dir";
+
+ while(defined(my $file = readdir DIR))
+ {   if($file =~ m/\.bak$/)
+     {   notice "found backup file $dir/$f";
+         next;
+     }
+
+     assert "file $dir/$file is binary"
+         if -B "$dir/$file";
+
+     trace "processing file $dir/$file";
+
+     unless(open FILE, "<", "$dir/$file")
+     {   error "no permission to read from $dir/$f"
+             if $!==ENOPERM;
+         fault "unable to read from $dir/$f";
+     }
+
+     close FILE
+         or failure "read errors in $dir/$file";
+ }
+
+A lot of things are quite visibly different, and there are a few smaller
+changes.  There is no need for a new-line after the text of the message.
+When applicable (error about system problem), then the C<$!> is added
+automatically.
+
+=subsection Log::Dispatch and Log::Log4perl
+The two major logging frameworks for Perl are M<Log::Dispatch> and
+M<Log::Log4perl>; both provide a pluggable logging interface.
+
+Both frameworks do not have (gettext or maketext) language translation
+support, which has various consequences.  When you wish for to report
+in some other language, it must be translated before the logging
+function is called.   This may mean that an error message is produced
+in Chinese, and therefore also ends-up in the syslog file in Chinese.
+When this is not your language, you have a problem.
+
+Log::Report translates only in the back-end, which means that the user may
+get the message in Chinese, but you get your report in your beloved Dutch.
+When no dispatcher needs to report the message, then no time is lost in
+translating.
+
+With both logging frameworks, you use terminology comparable to
+syslog: the module programmer determines the seriousness of the
+error message, not the application which integrates multiple modules.
+This is the way perl programs usually work, but often the cause for
+inconsequent user interaction.
+
+=subsection Locale::gettext and Locate::TextDomain
+
+Both on GNU gettext based implementations can be used as translation
+frameworks.  M<Locale::TextDomain> syntax is supported, with quite some
+extensions. Read the excellent documentation of Locale::Textdomain.
+Only the tried access via C<$__> and C<%__> are not supported.
+
+The main difference with these modules is the moment when the translation
+takes place.  In M<Locale::TextDomain>, an C<__x()> will result in an
+immediate translation request via C<gettext()>.  C<Log::Report>'s version
+of C<__x()> will only capture what needs to be translated in an object.
+When the object is used in a print statement, only then the translation
+will take place.  This is needed to offer ways to send different
+translations of the message to different destinations.
+
+To be able to postpone translation, objects are returned which stringify
+into the translated text.
+
+=cut
 
 1;
diff --git a/lib/Log/Report.pod b/lib/Log/Report.pod
deleted file mode 100644
index 3c3a180..0000000
--- a/lib/Log/Report.pod
+++ /dev/null
@@ -1,1172 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report - report a problem, with exceptions and translation support
-
-=head1 INHERITANCE
-
- Log::Report
-   is a Exporter
-
-=head1 SYNOPSIS
-
- # Invocation with 'mode' to get trace and verbose messages
- use Log::Report mode => 'DEBUG';
-
- # Usually invoked with a domain, which groups packages for translation
- use Log::Report 'my-domain', %options;
-
- # Interpolation syntax via String::Print
- # First step to translations, once you need it.
- print __x"my name is {name}", name => $n;  # print, so no exception
- print __"Hello World\n";     # no interpolation, optional translation
- print __x'Hello World';      # SYNTAX ERROR!!  ' is alternative for ::
-
- # Functions replacing die/warn/carp, casting exceptions.
- error "oops";                # exception like die(), no translation
- -f $config or panic "Help!"; # alert/error/fault/info/...more
-
- # Combined exception, interpolation, and optional translation
- error __x"Help!";            # __x() creates ::Message object
- error __x('gettext msgid', param => $value, ...)
-     if $condition;
-
- # Also non fatal "exceptions" find their way to dispatchers
- info __x"started {pid}", pid => $$;   # translatable
- debug "$i was here!";        # you probably do not want to translate debug
- panic "arrghhh";             # like Carp::Confess
-
- # Many destinations for an exception message (may exist in parallel)
- dispatcher PERL => 'default' # see Log::Report::Dispatcher: use die/warn
-   , reasons => 'NOTICE-';    # this dispatcher is already present at start
-
- dispatcher SYSLOG => 'syslog'# also send to syslog
-   , charset => 'iso-8859-1'  # explicit character conversions
-   , locale => 'en_US';       # overrule user's locale
-
- dispatcher close => 'default';  # stop default die/warn dispatcher
-
- # Fill-in values, like Locale::TextDomain and gettext
- # See Log::Report::Message section DETAILS
- fault __x"cannot allocate {size} bytes", size => $size;
- fault "cannot allocate $size bytes";     # no translation, ok
- fault __x"cannot allocate $size bytes";  # not translatable, wrong
-
- # Translation depending on count
- # Leading and trailing whitespace stay magically outside translation
- # tables.  @files in scalar context.  Special parameter with _
- print __xn"found one file\n", "found {_count} files", @files;
-
- # Borrow from an other text-domain (see Log::Report::Message)
- print __x(+"errors in {line}", _domain => 'global', line => $line);
-
- # catch errors (implements hidden eval/die)
- try { error };
- if($@) {...}      # $@ isa Log::Report::Dispatcher::Try
- if(my $exception = $@->wasFatal)         # ::Exception object
-
- # Language translations at the output component
- # Translation management via Log::Report::Lexicon
- use POSIX::1003::Locale qw/setlocale LC_ALL/;
- setlocale(LC_ALL, 'nl_NL');
- info __"Hello World!";      # in Dutch, if translation table found
-
- # Exception classes, see Log::Report::Exception
- try { error __x"something", _class => 'parsing,schema' };
- if($@->wasFatal->inClass('parsing')) ...
-
-=head1 DESCRIPTION
-
-Get messages to users and logs.  C<Log::Report> combines three tasks
-which are closely related in one:
-
-=over 4
-
-=item . logging (like L<Log::Log4Perl> and syslog), and
-
-=item . exceptions (like error and info), with
-
-=item . translations (like C<gettext> and L<Locale::TextDomain>)
-
-=back
-
-You B<do not need> to use this module for all three reasons: pick what
-you need now, maybe extend the usage later.  Read more about how and
-why in the L</DETAILS> section, below.  Especially, you should B<read
-about the REASON parameter>.
-
-Also, you can study this module swiftly via the article published in
-the German Perl C<$foo-magazine>.  English version:
-F<http://perl.overmeer.net/log-report/papers/201306-PerlMagazine-article-en.html>
-
-=head1 FUNCTIONS
-
-=head2 Report Production and Configuration
-
-=over 4
-
-=item B<dispatcher>( <$type, $name, %options>|<$command, @names> )
-
-The C<dispatcher> function controls access to dispatchers: the back-ends
-which process messages, do the logging.  Dispatchers are global entities,
-addressed by a symbolic $name.  Please read L<Log::Report::Dispatcher|Log::Report::Dispatcher> as
-well.
-
-The C<Log::Report> suite has its own dispatcher @types, but also connects
-to external dispatching frameworks.  Each need some (minor) conversions,
-especially with respect to translation of REASONS of the reports
-into log-levels as the back-end understands.
-
-[1.10] When you open a dispatcher with a $name which is already in use,
-that existing dispatcher gets closed.  Except when you have given an
-'dispatcher "do-not-reopen"' earlier, in which case the first object
-stays alive, and the second attempt ignored. [1.11] The automatically
-created default dispatcher will get replaced, even when this option
-is given, by another dispatcher which is named 'default'.
-
-The %options are a mixture of parameters needed for the
-Log::Report dispatcher wrapper and the settings of the back-end.
-See L<Log::Report::Dispatcher|Log::Report::Dispatcher>, the documentation for the back-end
-specific wrappers, and the back-ends for more details.
-
-Implemented COMMANDs are C<close>, C<find>, C<list>, C<disable>,
-C<enable>, C<mode>, C<filter>, C<needs>, C<active-try>, and C<do-not-reopen>.
-
-Most commands are followed by a LIST of dispatcher @names to be addressed.
-For C<mode> see section L</Run modes>; it requires a MODE argument
-before the LIST of NAMEs.  Non-existing names will be ignored. When
-C<ALL> is specified, then all existing dispatchers will get addressed.
-For C<filter> see L<Log::Report::Dispatcher/Filters>; it requires a CODE
-reference before the @names of the dispatchers which will have the it
-applied (defaults to all).
-
-With C<needs>, you only provide a REASON: it will return the list of
-dispatchers which need to be called in case of a message with the REASON
-is triggered.  The C<active-try> [1.09] returns the closest surrounding
-exception catcher, a L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> object.
-
-For both the creation as COMMANDs version of this method, all objects
-involved are returned as LIST, non-existing ones skipped.  In SCALAR
-context with only one name, the one object is returned.
-
-example: play with dispatchers
-
- dispatcher Log::Dispatcher::File => mylog =>
-   , accept   => 'MISTAKE-'              # for wrapper
-   , locale   => 'pt_BR'                 # other language
-   , filename => 'logfile';              # for back-end
-
- dispatcher close => 'mylog';            # cleanup
- my $obj = dispatcher find => 'mylog'; 
- my @obj = dispatcher 'list';
- dispatcher disable => 'syslog';
- dispatcher enable => 'mylog', 'syslog'; # more at a time
- dispatcher mode => 'DEBUG', 'mylog';
- dispatcher mode => 'DEBUG', 'ALL';
- my $catcher = dispatcher 'active-try';
- dispatcher 'do-not-reopen';
-
- my @need_info = dispatcher needs => 'INFO';
- if(dispatcher needs => 'INFO') ...      # anyone needs INFO
-
- # Getopt::Long integration: see Log::Report::Dispatcher::mode()
- dispatcher PERL => 'default', mode => 'DEBUG', accept => 'ALL'
-     if $debug;
-
-=item B<report>( [%options], $reason, $message|<STRING,$params>, )
-
-The C<report> function is sending (for some $reason) a $message to be
-displayed or logged (by a `dispatcher').  This function is the core
-for L<error()|Log::Report/"Abbreviations for report()">, L<info()|Log::Report/"Abbreviations for report()"> etc functions, which are nicer names for this
-exception throwing: better use those short names.
-
-The $reason is a string like 'ERROR' (for function C<error()>).
-The $message is a L<Log::Report::Message|Log::Report::Message> object (which are created with
-the special translation syntax like L<__x()|Log::Report/"Messages (optionally translatable)">).  The $message may also
-be a plain string, or an L<Log::Report::Exception|Log::Report::Exception> object. The optional
-first parameter is a HASH which can be used to influence the dispatchers.
-
-The optional %options are listed below.  Quite differently from other
-functions and methods, they have to be passed in a HASH as first parameter.
-
-This function returns the LIST of dispatchers which accepted the $message.
-When empty, no back-end has accepted it so the $message was "lost".
-Even when no back-end needs the message, the program will still exit
-when there is a $reason to C<die()>.
-
- -Option  --Default
-  errno     $! or 1
-  is_fatal  <depends on reason>
-  locale    undef
-  location  undef
-  stack     undef
-  to        undef
-
-=over 2
-
-=item errno => INTEGER
-
-When the $reason includes the error text (See L</Run modes>), you can
-overrule the error code kept in C<$!>.  In other cases, the return code
-defaults to C<1> (historical UNIX behavior). When the message $reason
-(combined with the run-mode) is severe enough to stop the program,
-this value as return code of the program.  The use of this option itself
-will not trigger an C<die()>.
-
-=item is_fatal => BOOLEAN
-
-Some logged exceptions are fatal, other aren't.  The default usually
-is correct. However, you may want an error to be caught (usually with
-L<try()|Log::Report/"Report Production and Configuration">), redispatch it to syslog, but without it killing the main
-program.
-
-=item locale => LOCALE
-
-Use this specific locale, in stead of the user's preference.
-
-=item location => STRING
-
-When defined, this location is used in the display.  Otherwise, it
-is determined automatically if needed.  An empty string will disable
-any attempt to display this line.
-
-=item stack => ARRAY
-
-When defined, that data is used to display the call stack.  Otherwise,
-it is collected via C<caller()> if needed.
-
-=item to => NAME|ARRAY-of-NAMEs
-
-Sent the $message only to the NAMEd dispatchers.  Ignore unknown NAMEs.
-Still, the dispatcher needs to be enabled and accept the REASONs.
-
-=back
-
-example: for use of L<report()|Log::Report/"Report Production and Configuration">
-
- # long syntax example
- report TRACE => "start processing now";
- report INFO  => '500: ' . __'Internal Server Error';
-
- # explicit dispatcher, no translation
- report {to => 'syslog'}, NOTICE => "started process $$";
- notice "started process $$", _to => 'syslog';   # same
-
- # short syntax examples
- trace "start processing now";
- warning  __x'Disk {percent%.2f}% full', percent => $p
-     if $p > 97;
-
- # error message, overruled to be printed in Brazilian
- report {locale => 'pt_BR'}
-    , WARNING => "do this at home!";
-
-=item B<try>(CODE, %options)
-
-Execute the CODE while blocking all dispatchers as long as it is running.
-The exceptions which occur while running the CODE are caught until it
-has finished.  When there where no fatal errors, the result of the CODE
-execution is returned.
-
-After the CODE was tried, the C<$@> will contain a
-L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> object, which contains the collected
-messages.
-
-Run-time errors from Perl and die's, croak's and confess's within the
-program (which shouldn't appear, but you never know) are collected into an
-L<Log::Report::Message|Log::Report::Message> object, using L<Log::Report::Die|Log::Report::Die>.
-
-The %options are passed to the constructor of the try-dispatcher, see
-L<Log::Report::Dispatcher::Try::new()|Log::Report::Dispatcher::Try/"Constructors">.  For instance, you may like to
-add C<< mode => 'DEBUG' >>, or C<< accept => 'ERROR-' >>.
-
-B<Be warned> that the parameter to C<try> is a CODE reference.  This means
-that you shall not use a comma after the block when there are %options
-specified.  On the other hand, you shall use a semi-colon after the
-block if there are no arguments.
-
-B<Be warned> that the {} are interpreted as subroutine, which means that,
-for instance, it has its own C<@_>.  The manual-page of Try::Tiny
-lists a few more side-effects of this.
-
-example: 
-
- my $x = try { 3/$x };  # mind the ';' !!
- if($@) {               # signals something went wrong
-
- if(try {...}) {        # block ended normally, returns bool
-
- try { ... }            # no comma!!
-    mode => 'DEBUG', accept => 'ERROR-';
-
- try sub { ... },       # with comma, also \&function
-    mode => 'DEBUG', accept => 'ALL';
-
- my $response = try { $ua->request($request) };
- if(my $e = $@->wasFatal) ...
-
-=back
-
-=head2 Abbreviations for report()
-
-The following functions are all wrappers for calls to L<report()|Log::Report/"Report Production and Configuration">,
-and available when "syntax is SHORT" (by default, see L<import()|Log::Report/"Configuration">).
-You cannot specify additional options to influence the behavior of
-C<report()>, which are usually not needed anyway.
-
-=over 4
-
-=item B<alert>($message)
-
-Short for C<< report ALERT => $message >>
-
-=item B<assert>($message)
-
-Short for C<< report ASSERT => $message >>
-
-=item B<error>($message)
-
-Short for C<< report ERROR => $message >>
-
-=item B<failure>($message)
-
-Short for C<< report FAILURE => $message >>
-
-=item B<fault>($message)
-
-Short for C<< report FAULT => $message >>
-
-=item B<info>($message)
-
-Short for C<< report INFO => $message >>
-
-=item B<mistake>($message)
-
-Short for C<< report MISTAKE => $message >>
-
-=item B<notice>($message)
-
-Short for C<< report NOTICE => $message >>
-
-=item B<panic>($message)
-
-Short for C<< report PANIC => $message >>
-
-=item B<trace>($message)
-
-Short for C<< report TRACE => $message >>
-
-=item B<warning>($message)
-
-Short for C<< report WARNING => $message >>
-
-=back
-
-=head2 Messages (optionally translatable)
-
-Even when you do not support translations (yet) you may want to use
-message objects to improve the logging feature. For instance,
-you get very powerful interpolation from L<String::Print|String::Print>.
-
-The language translations are initiate by limited set of functions
-which contain B<two under-scores> (C<__>) in their name.  Most
-of them return a L<Log::Report::Message|Log::Report::Message> object.
-
-B<Be warned(1)> that -in general- its considered very bad practice to
-combine multiple translations into one message: translating may also
-affect the order of the translated components. Besides, when the person
-which translates only sees smaller parts of the text, his (or her) job
-becomes more complex.  So:
-
- print __"Hello" . ', ' . __"World!";  # works, but to be avoided
- print __"Hello, World!";              # preferred, complete sentence
-
-The the former case, tricks with overloading used by the
-L<Log::Report::Message|Log::Report::Message> objects will still make delayed translations
-work.
-
-In normal situations, it is not a problem to translate interpolated
-values:
-
- print __"the color is {c}", c => __"red";
-
-B<Be warned(2)> that using C<< __'Hello' >> will produce a syntax error like
-"String found where operator expected at .... Can't find string terminator
-"'" anywhere before EOF".  The first quote is the cause of the complaint,
-but the second generates the error.  In the early days of Perl, the single
-quote was used to separate package name from function name, a role which
-was later replaced by a double-colon.  So C<< __'Hello' >> gets interpreted
-as C<< __::Hello ' >>.  Then, there is a trailing single quote which has
-no counterpart.
-
-=over 4
-
-=item B<N__>($msgid)
-
-Label to indicate that the string is a text which will be translated
-later.  The function itself does nothing.  See also L<N__w()|Log::Report/"Messages (optionally translatable)">.
-
-This no-op function is used as label to the xgettext program to build the
-translation tables.
-
-example: how to use N__()
-
- # add three msgids to the translation table
- my @colors = (N__"red", N__"green", N__"blue");
- my @colors = N__w "red green blue";   # same
- print __ $colors[1];                  # translate green
-
- # using __(), would work as well
- my @colors = (__"red", __"green", __"blue");
- print $colors[1];
- # however: this will always create all Log::Report::Message objects,
- # where maybe only one is used.
-
-=item B<N__n>($single_msgid, $plural_msgid)
-
-Label to indicate that the two MSGIDs are related, the first as
-single, the seconds as its plural.  Only used to find the text
-fragments to be translated.  The function itself does nothing.
-
-example: how to use L<N__n()|Log::Report/"Messages (optionally translatable)">
-
- my @save = N__n "save file", "save files";
- my @save = (N__n "save file", "save files");
- my @save = N__n("save file", "save files");
-
- # be warned about SCALARs in prototype!
- print __n @save, $nr_files;  # wrong!
- print __n $save[0], $save[1], @files, %vars;
-
-=item B<N__w>(STRING)
-
-This extension to the Locale::TextDomain syntax, is a combined
-C<qw> (list of quoted words) and L<N__()|Log::Report/"Messages (optionally translatable)"> into a list of translatable
-words.
-
-example: of L<N__w()|Log::Report/"Messages (optionally translatable)">
-
-  my @colors = (N__"red", N__"green", N__"blue");
-  my @colors = N__w"red green blue";  # same
-  print __ $colors[1];
-
-=item B<__>($msgid)
-
-This function (name is B<two> under-score characters) will cause the $msgid
-to be replaced by the translations when doing the actual output.  Returned
-is a L<Log::Report::Message|Log::Report::Message> object, which will be used in translation
-later.  Translating is invoked when the object gets stringified.  When
-you have no translation tables, the $msgid will be shown untranslated.
-
-If you need options for L<Log::Report::Message::new()|Log::Report::Message/"Constructors"> then use L<__x()|Log::Report/"Messages (optionally translatable)">;
-the prototype of this function does not permit parameters: it is a
-prefix operator!
-
-example: how to use __()
-
- print __"Hello World";      # translated into user's language
- print __'Hello World';      # syntax error!
- print __('Hello World');    # ok, translated
- print __"Hello", " World";  # World not translated
-
- my $s = __"Hello World";    # creates object, not yet translated
- print ref $s;               # Log::Report::Message
- print $s;                   # ok, translated
- print $s->toString('fr');   # ok, forced into French
-
-=item B<__n>($msgid, $plural_msgid, $count, PAIRS)
-
-It depends on the value of $count (and the selected language) which
-text will be displayed.  When translations can not be performed, then
-$msgid will be used when $count is 1, and PLURAL_MSGSID in other cases.
-However, some languages have more complex schemes than English.
-
-The PAIRS are options for L<Log::Report::Message::new()|Log::Report::Message/"Constructors"> and variables
-to be filled in.
-
-example: how to use __n()
-
- print __n "one", "more", $a;
- print __n("one", "more", $a), "\n";
- print +(__n "one", "more", $a), "\n";
-
- # new-lines are ignore at lookup, but printed.
- print __n "one\n", "more\n", $a;
-
- # count is in scalar context
- # the value is also available as _count
- print __n "found one\n", "found {_count}\n", @r;
-
- # ARRAYs and HASHes are counted
- print __n "one", "more", \@r;
-
-=item B<__nx>($msgid, $plural_msgid, $count, PAIRS)
-
-It depends on the value of $count (and the selected language) which
-text will be displayed.  See details in L<__n()|Log::Report/"Messages (optionally translatable)">.  After translation,
-the VARIABLES will be filled-in.
-
-The PAIRS are options for L<Log::Report::Message::new()|Log::Report::Message/"Constructors"> and variables
-to be filled in.
-
-example: how to use __nx()
-
- print __nx "one file", "{_count} files", $nr_files;
- print __nx "one file", "{_count} files", @files;
-
- local $" = ', ';
- print __nx "one file: {f}", "{_count} files: {f}", @files, f => \@files;
-
-=item B<__x>($msgid, PAIRS)
-
-Translate the $msgid and then interpolate the VARIABLES in that string.
-Of course, translation and interpolation is delayed as long as possible.
-Both OPTIONS and VARIABLES are key-value pairs.
-
-The PAIRS are options for L<Log::Report::Message::new()|Log::Report::Message/"Constructors"> and variables
-to be filled in.
-
-=item B<__xn>($single_msgid, $plural_msgid, $count, $paurs)
-
-Same as L<__nx()|Log::Report/"Messages (optionally translatable)">, because we have no preferred order for 'x' and 'n'.
-
-=back
-
-=head3 Messages with msgctxt
-
-In Log::Report, the message context (mgsctxt in the PO-files --in the
-translation tables) can be used in a very powerful way.  Read all about
-it in L<Log::Report::Translator::Context|Log::Report::Translator::Context>
-
-The msgctxt versions of the tranditional gettext infrastructure are far
-less useful for Log::Report, because we can easily work with different
-text domains within the same program.  That should avoid most of the
-accidental translation conflicts between components of the code.
-
-Just for compatibility with Locale::TextDomain and completeness, the
-'p' versions of above methods are supported.  See examples for these
-functions in Locale::TextDomain.
-
-B<Warnings:> Functions C<N__p()> and C<N__np()> seem not to be usable in
-reality, hence not implemented.  The script xgettext-perl and
-L<Log::Report::Extract::PerlPPI|Log::Report::Extract::PerlPPI> (both in the L<Log::Report::Lexicon|Log::Report::Lexicon>
-distribution) do not yet support these functions.
-
-=over 4
-
-=item B<__np>($msgctxt, $msgid, $plural, count)
-
-=item B<__npx>($msgctxt, $msgid, $plural, count, PAIRS)
-
-=item B<__p>($msgctxt, $msgid)
-
-=item B<__px>($msgctxt, $msgid, PAIRS)
-
-=back
-
-=head2 Configuration
-
-=over 4
-
-=item $obj-E<gt>B<import>( [$level,][$domain,] %options )
-
-The import is automatically called when the package is compiled.  For all
-packages but one in your distribution, it will only contain the name of
-the $domain.
-
-For one package, the import list may additionally contain textdomain
-configuration %options.  These %options are used for all packages which
-use the same $domain.  These are alternatives:
-
-  # Do not use variables in the %*config!  They are not yet initialized
-  # when Log::Report->import is run!!!
-  use Log::Report 'my-domain', %config, %domain_config;
-
-  use Log::Report 'my-domain', %config;
-  textdomain 'my-domain', %domain_config;   # vars allowed
-
-The latter syntax has major advantages, when the configuration of the
-domain is determined at run-time.  It is probably also easier to understand.
-
-See L<Log::Report::Domain::configure()|Log::Report::Domain/"Attributes">, for the B<list of %options>
-for the domain configuration.  Here, we only list the options which are
-related to the normal import behavior.
-
-The export $level is a plus (+) followed by a number, for instance C<+1>,
-to indicate to on which caller level we need to work.  This is used
-in L<Log::Report::Optional|Log::Report::Optional>.  It defaults to '0': my direct caller.
-
- -Option       --Default
-  import         undef
-  message_class  Log::Report::Message
-  mode           'NORMAL'
-  syntax         'SHORT'
-
-=over 2
-
-=item import => FUNCTION|ARRAY
-
-[0.998] When not specified, the C<syntax> option determines the list
-of functions which are being exported.  With this option, the C<syntax>
-option is ignored and only the specified FUNCTION(s) are imported.
-
-=item message_class => CLASS
-
-[1.08] Use a more powerful message object class, for instance because
-your messages need extra attributes.  The provided CLASS must extend
-L<Log::Report::Message|Log::Report::Message>
-
-=item mode => LEVEL
-
-This sets the default mode for all created dispatchers.  You can
-also selectively change the output mode, like
- dispatcher PERL => 'default', mode => 3
-
-=item syntax => 'REPORT'|'SHORT'|'LONG'
-
-The SHORT syntax will add the report abbreviations (like function
-L<error()|Log::Report/"Abbreviations for report()">) to your name-space.  Otherwise, each message must be produced
-with L<report()|Log::Report/"Report Production and Configuration">. C<LONG> is an alternative to C<REPORT>: both do not
-pollute your namespace with the useful abbrev functions.
-
-=back
-
-example: of import
-
- use Log::Report mode => 3;     # '3' or 'DEBUG'
-
- use Log::Report 'my-domain';   # in each package producing messages
-
- use Log::Report 'my-domain'    # in one package, top of distr
-  , mode            => 'VERBOSE'
-  , syntax          => 'REPORT' # report ERROR, not error()
-  , translator      => Log::Report::Translator::POT->new
-     ( lexicon => '/home/mine/locale'  # translation tables
-     )
-  , native_language => 'nl_NL'; # untranslated msgs are Dutch
-
- use Log::Report import => 'try';      # or ARRAY of functions
-
-=item B<textdomain>( <[$name],$config>|<$name, 'DELETE'|'EXISTS'>|$domain )
-
-[1.00] Without CONFIGuration, this returns the L<Log::Report::Domain|Log::Report::Domain> object
-which administers the $domain, by default the domain effective in the scope
-of the package.
-
-A very special case is "DELETE", which will remove the domain
-configuration. [1.20] "EXISTS" will check for existence: when it exists,
-it will be returned, but a domain will not be automagically created.
-
-[1.20] You may also pass a pre-configured domain.
-
-=back
-
-=head2 Reasons
-
-=over 4
-
-=item Log::Report-E<gt>B<needs>( $reason, [$reasons] )
-
-Returns true when the reporter needs any of the $reasons, when any of
-the active dispatchers is collecting messages in the specified level.
-This is useful when the processing of data for the message is relatively
-expensive, but for instance only required in debug mode.
-
-example: 
-
-  if(Log::Report->needs('TRACE'))
-  {   my @args = ...expensive calculation...;
-      trace "your options are: @args";
-  }
-
-=back
-
-=head1 DETAILS
-
-=head2 Introduction
-
-Getting messages to users and logs. The distincting concept of this module,
-is that three tasks which are strongly related are merged into one simple
-syntax.  The three tasks:
-
-=over 4
-
-=item produce some text on a certain condition,
-
-=item translate it to the proper language, and
-
-=item deliver it in some way to a user.
-
-=back
-
-Text messages in Perl are produced by commands like C<print>, C<die>,
-C<warn>, C<carp>, or C<croak>.  But where is that output directed to?
-Translations is hard.  There is no clean exception mechanism.
-
-Besides, the C<print>/C<warn>/C<die> together produce only three different
-output "levels" with a message.  Think of the variation syslog offers:
-more than 7 levels.  Many people manually implement their own tricks to
-get additional levels, like verbose and debug flags.  Log::Report offers
-that variety.
-
-The (optional) translations use the beautiful syntax defined by
-Locale::TextDomain, with some own extensions (of course).  A very
-important difference is that translations are delayed till the delivery
-step: until a dispatcher actually writes your message into a file, sends
-it to syslog, or shows it on the screen.  This means that the pop-up in
-the graphical interface of the user may show the text in the language
-of the user --say Chinese in utf8--, but at the same time syslog may
-write the latin1 English version of the same message.
-
-=head2 Background ideas
-
-The following ideas are the base of this implementation:
-
-=over 4
-
-=item . simplification
-
-Handling errors and warnings is probably the most labor-intensive
-task for a programmer: when programs are written correctly, up-to
-three-quarters of the code is related to testing, reporting, and
-handling (problem) conditions.  Simplifying the way to create reports,
-simplifies programming and maintenance.
-
-=item . multiple dispatchers
-
-It is not the location where the (for instance) error occurs which
-determines what will happen with the text, but the main application which
-uses the the complaining module has control.  Messages have a reason.
-Based on the `reason' classification, they can get ignored, send to one
-or multiple dispatchers, like Log::Dispatch, Log::Log4perl,
-or UNIX syslog.
-
-=item . delayed translations
-
-The background ideas are that of Locale::TextDomain, based
-on C<gettext()>.  However, in the C<Log::Report> infrastructure,
-translations are postponed until the text is dispatched to a screen
-or log-file; the same report can be sent to syslog in (for instance)
-English and to the user interface in Dutch.
-
-=item . context sensitive
-
-Using contexts, you can set-up how to translate or rewrite messages,
-to improve messages.  A typical problem is whether to use gender in
-text (use 'his' or 'her'): you can set a gender in a context, and the
-use translation tables to pick the right one.
-
-=back
-
-=head2 Error handling models
-
-There are two approaches to handling errors and warnings.  In the first
-approach, as produced by C<die>, C<warn> and the C<carp> family of
-commands, the program handles the problem immediately on the location
-where the problem appears.  In the second approach, an I<exception>
-is thrown on the spot where the problem is created, and then somewhere
-else in the program the condition is handled.
-
-The implementation of exceptions in Perl5 is done with a eval-die pair:
-on the spot where the problem occurs, C<die> is called.  But, because of
-the execution of that routine is placed within an C<eval>, the program
-as a whole will not die, just the execution of a part of the program
-will seize.  However, what if the condition which caused the routine to die
-is solvable on a higher level?  Or what if the user of the code doesn't
-bother that a part fails, because it has implemented alternatives for
-that situation?  Exception handling is quite clumsy in Perl5.
-
-The C<Log::Report> set of distributions let modules concentrate on the
-program flow, and let the main program decide on the report handling
-model.  The infrastructure to translate messages into multiple languages,
-whether to create exceptions or carp/die, to collect longer explanations
-with the messages, to log to mail or syslog, and so on, is decided in
-pluggable back-ends.
-
-=head3 The Reason for the report
-
-Traditionally, perl has a very simple view on error reports: you
-either have a warning or an error.  However, it would be much clearer
-for user's and module-using applications, when a distinction is made
-between various causes.  For instance, a configuration error is quite
-different from a disk-full situation.  In C<Log::Report>, the produced
-reports in the code tell I<what> is wrong.  The main application defines
-loggers, which interpret the cause into (syslog) levels.
-
-Defined by C<Log::Report> are
-
-=over 4
-
-=item . trace (debug, program)
-
-The message will be used when some logger has debugging enabled.  The
-messages show steps taken by the program, which are of interest by the
-developers and maintainers of the code, but not for end-users.
-
-=item . assert (program)
-
-Shows an unexpected condition, but continues to run.  When you want the
-program to abort in such situation, that use C<panic>.
-
-=item . info (verbose, program)
-
-These messages show larger steps in the execution of the program.
-Experienced users of the program usually do not want to see all these
-intermediate steps.  Most programs will display info messages (and
-higher) when some C<verbose> flag is given on the command-line.
-
-=item . notice (program)
-
-An user may need to be aware of the program's accidental smart behavior,
-for instance, that it initializes a lasting C<Desktop> directory in your
-home directory.  Notices should be sparse.
-
-=item . warning (program)
-
-The program encountered some problems, but was able to work around it
-by smart behavior.  For instance, the program does not understand a
-line from a log-file, but simply skips the line.
-
-=item . mistake (user)
-
-When a user does something wrong, but what is correctable by smart
-behavior of the program.  For instance, in some configuration file,
-you can fill-in "yes" or "no", but the user wrote "yeah".  The program
-interprets this as "yes", producing a mistake message as warning.
-
-It is much nicer to tell someone that he/she made a mistake, than
-to call that an error.
-
-=item . error (user)
-
-The user did something wrong, which is not automatically correctable
-or the program is not willing to correct it automatically for reasons
-of code quality.  For instance, an unknown option flag is given on the
-command-line.  These are configuration issues, and have no useful
-value in C<$!>.  The program will be stopped, usually before taken off.
-
-=item . fault (system)
-
-The program encountered a situation where it has no work-around.  For
-instance, a file cannot be opened to be written.  The cause of that
-problem can be some user error (i.e. wrong filename), or external
-(you accidentally removed a directory yesterday).  In any case, the
-C<$!> (C<$ERRNO>) variable is set here.
-
-=item . alert (system)
-
-Some external cause disturbs the execution of the program, but the
-program stays alive and will try to continue operation.  For instance,
-the connection to the database is lost.  After a few attempts, the
-database can be reached and the program continues as if nothing happened.
-The cause is external, so C<$!> is set.  Usually, a system administrator
-needs to be informed about the problem.
-
-=item . failure (system)
-
-Some external cause makes it impossible for this program to continue.
-C<$!> is set, and usually the system administrator wants to be
-informed.  The program will die.
-
-The difference with C<fault> is subtile and not always clear.  A fault
-reports an error returned by an operating system call, where the failure
-would report an operational problem, like a failing mount.
-
-=item . panic (program)
-
-All above report classes are expected: some predictable situation
-is encountered, and therefore a message is produced.  However, programs
-often do some internal checking.  Of course, these conditions should
-never be triggered, but if they do... then we can only stop.
-
-For instance, in an OO perl module, the base class requires all
-sub-classes to implement a certain method.  The base class will produce
-a stub method with triggers a panic when called.  The non-dieing version
-of this test C<assert>.
-
-=back
-
-I<Debugging> or being C<verbose> are run-time behaviors, and have nothing
-directly to do with the type of message which is produced.  These two
-are B<modes> which can be set on the dispatchers: one dispatcher may
-be more verbose that some other.
-
-On purpose, we do not use the terms C<die> or C<fatal>, because the
-dispatcher can be configured what to do in cause of which condition.
-For instance, it may decide to stop execution on warnings as well.
-
-The terms C<carp> and C<croak> are avoided, because the program cause
-versus user cause distinction (warn vs carp) is reflected in the use
-of different reasons.  There is no need for C<confess> and C<croak>
-either, because the dispatcher can be configured to produce stack-trace
-information (for a limited sub-set of dispatchers)
-
-=head3 Report levels
-
-Various frameworks used with perl programs define different labels
-to indicate the reason for the message to be produced.
-
- Perl5 Log::Dispatch Syslog Log4Perl Log::Report
- print   0,debug     debug  debug    trace
- print   0,debug     debug  debug    assert
- print   1,info      info   info     info
- warn\n  2,notice    notice info     notice
- warn    3,warning   warn   warn     mistake
- carp    3,warning   warn   warn     warning
- die\n   4,error     err    error    error
- die     5,critical  crit   fatal    fault
- croak   6,alert     alert  fatal    alert  
- croak   7,emergency emerg  fatal    failure
- confess 7,emergency emerg  fatal    panic
-
-=head3 Run modes
-
-The run-mode change which messages are passed to a dispatcher, but
-from a different angle than the dispatch filters; the mode changes
-behavioral aspects of the messages, which are described in detail in
-L<Log::Report::Dispatcher/Processing the message>.  However, it should
-behave as you expect: the DEBUG mode shows more than the VERBOSE mode,
-and both show more than the NORMAL mode.
-
-B<. Example: extract run mode from Getopt::Long>
-
-The C<GetOptions()> function will count the number of C<v> options
-on the command-line when a C<+> is after the option name.
-
- use Log::Report;
- use Getopt::Long qw(:config no_ignore_case bundling);
-
- my $mode;    # defaults to NORMAL
- GetOptions 'v+'        => \$mode
-          , 'verbose=i' => \$mode
-          , 'mode=s'    => \$mode
-     or exit 1;
-
- dispatcher 'PERL', 'default', mode => $mode;
-
-Now, C<-vv> will set C<$mode> to C<2>, as will C<--verbose 2> and
-C<--verbose=2> and C<--mode=ASSERT>.  Of course, you do not need to
-provide all these options to the user: make a choice.
-
-B<. Example: the mode of a dispatcher>
-
- my $mode = dispatcher(find => 'myname')->mode;
-
-B<. Example: run-time change mode of a dispatcher>
-
-To change the running mode of the dispatcher, you can do
-  dispatcher mode => DEBUG => 'myname';
-
-However, be warned that this does not change the types of messages
-accepted by the dispatcher!  So: probably you will not receive
-the trace, assert, and info messages after all.  So, probably you
-need to replace the dispatcher with a new one with the same name:
-  dispatcher FILE => 'myname', to => ..., mode => 'DEBUG';
-
-This may reopen connections (depends on the actual dispatcher), which
-might be not what you wish to happened.  In that case, you must take
-the following approach:
-
-  # at the start of your program
-  dispatcher FILE => 'myname', to => ...
-     , accept => 'ALL';    # overrule the default 'NOTICE-' !!
-
-  # now it works
-  dispatcher mode => DEBUG => 'myname';    # debugging on
-  ...
-  dispatcher mode => NORMAL => 'myname';   # debugging off
-
-Of course, this comes with a small overall performance penalty.
-
-=head3 Exceptions
-
-The simple view on live says: you 're dead when you die.  However,
-more complex situations try to revive the dead.  Typically, the "die"
-is considered a terminating exception, but not terminating the whole
-program, but only some logical block.  Of course, a wrapper round
-that block must decide what to do with these emerging problems.
-
-Java-like languages do not "die" but throw exceptions which contain the
-information about what went wrong.  Perl modules like C<Exception::Class>
-simulate this.  It's a hassle to create exception class objects for each
-emerging problem, and the same amount of work to walk through all the
-options.
-
-Log::Report follows a simpler scheme.  Fatal messages will "die", which is
-caught with "eval", just the Perl way (used invisible to you).  However,
-the wrapper gets its hands on the message as the user has specified it:
-untranslated, with all unprocessed parameters still at hand.
-
- try { fault __x "cannot open file {file}", file => $fn };
- if($@)                         # is Log::Report::Dispatcher::Try
- {   my $cause = $@->wasFatal;  # is Log::Report::Exception
-     $cause->throw if $cause->message->msgid =~ m/ open /;
-     # all other problems ignored
- }
-
-See L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> and L<Log::Report::Exception|Log::Report::Exception>.
-
-=head2 Comparison
-
-Some notes on differences between the Log::Report approach and other
-Perl concepts.
-
-=head3 die/warn/Carp
-
-Perl's built-in exception system is very primitive: "die" and "warn".
-Most programming languages provide a much more detailed exception
-mechanism.
-
-A typical perl program can look like this:
-
- my $dir = '/etc';
-
- File::Spec->file_name is_absolute($dir)
-     or die "ERROR: directory name must be absolute.\n";
-
- -d $dir
-     or die "ERROR: what platform are you on?";
-
- until(opendir DIR, $dir)
- {   warn "ERROR: cannot read system directory $dir: $!";
-     sleep 60;
- }
-
- print "Processing directory $dir\n"
-     if $verbose;
-
- while(defined(my $file = readdir DIR))
- {   if($file =~ m/\.bak$/)
-     {   warn "WARNING: found backup file $dir/$f\n";
-         next;
-     }
-
-     die "ERROR: file $dir/$file is binary"
-         if $debug && -B "$dir/$file";
-
-     print "DEBUG: processing file $dir/$file\n"
-         if $debug;
-
-     open FILE, "<", "$dir/$file"
-         or die "ERROR: cannot read from $dir/$f: $!";
-
-     close FILE
-         or croak "ERROR: read errors in $dir/$file: $!";
- }
-
-Where C<die>, C<warn>, and C<print> are used for various tasks.  With
-C<Log::Report>, you would write
-
- use Log::Report;
-
- # can be left-out when there is no debug/verbose
- dispatcher PERL => 'default', mode => 'DEBUG';
-
- my $dir = '/etc';
-
- File::Spec->file_name is_absolute($dir)
-     or mistake "directory name must be absolute";
-
- -d $dir
-     or panic "what platform are you on?";
-
- until(opendir DIR, $dir)
- {   alert "cannot read system directory $dir";
-     sleep 60;
- }
-
- info "Processing directory $dir";
-
- while(defined(my $file = readdir DIR))
- {   if($file =~ m/\.bak$/)
-     {   notice "found backup file $dir/$f";
-         next;
-     }
-
-     assert "file $dir/$file is binary"
-         if -B "$dir/$file";
-
-     trace "processing file $dir/$file";
-
-     unless(open FILE, "<", "$dir/$file")
-     {   error "no permission to read from $dir/$f"
-             if $!==ENOPERM;
-         fault "unable to read from $dir/$f";
-     }
-
-     close FILE
-         or failure "read errors in $dir/$file";
- }
-
-A lot of things are quite visibly different, and there are a few smaller
-changes.  There is no need for a new-line after the text of the message.
-When applicable (error about system problem), then the C<$!> is added
-automatically.
-
-=head3 Log::Dispatch and Log::Log4perl
-
-The two major logging frameworks for Perl are Log::Dispatch and
-Log::Log4perl; both provide a pluggable logging interface.
-
-Both frameworks do not have (gettext or maketext) language translation
-support, which has various consequences.  When you wish for to report
-in some other language, it must be translated before the logging
-function is called.   This may mean that an error message is produced
-in Chinese, and therefore also ends-up in the syslog file in Chinese.
-When this is not your language, you have a problem.
-
-Log::Report translates only in the back-end, which means that the user may
-get the message in Chinese, but you get your report in your beloved Dutch.
-When no dispatcher needs to report the message, then no time is lost in
-translating.
-
-With both logging frameworks, you use terminology comparable to
-syslog: the module programmer determines the seriousness of the
-error message, not the application which integrates multiple modules.
-This is the way perl programs usually work, but often the cause for
-inconsequent user interaction.
-
-=head3 Locale::gettext and Locate::TextDomain
-
-Both on GNU gettext based implementations can be used as translation
-frameworks.  Locale::TextDomain syntax is supported, with quite some
-extensions. Read the excellent documentation of Locale::Textdomain.
-Only the tried access via C<$__> and C<%__> are not supported.
-
-The main difference with these modules is the moment when the translation
-takes place.  In Locale::TextDomain, an C<__x()> will result in an
-immediate translation request via C<gettext()>.  C<Log::Report>'s version
-of C<__x()> will only capture what needs to be translated in an object.
-When the object is used in a print statement, only then the translation
-will take place.  This is needed to offer ways to send different
-translations of the message to different destinations.
-
-To be able to postpone translation, objects are returned which stringify
-into the translated text.
-
-=head1 DIAGNOSTICS
-
-=over 4
-
-=item Error: in SCALAR context, only one dispatcher name accepted
-
-The L<dispatcher()|Log::Report/"Report Production and Configuration"> method returns the L<Log::Report::Dispatcher|Log::Report::Dispatcher>
-objects which it has accessed.  When multiple names where given, it
-wishes to return a LIST of objects, not the count of them.
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/DBIC/Profiler.pm b/lib/Log/Report/DBIC/Profiler.pm
index 6b4b08f..99255d8 100644
--- a/lib/Log/Report/DBIC/Profiler.pm
+++ b/lib/Log/Report/DBIC/Profiler.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::DBIC::Profiler;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'DBIx::Class::Storage::Statistics';
 
 use strict;
@@ -18,6 +11,33 @@ use warnings;
 use Log::Report  'log-report', import => 'trace';
 use Time::HiRes  qw(time);
 
+=chapter NAME
+
+Log::Report::DBIC::Profiler - query profiler for DBIx::Class
+
+=chapter SYNOPSIS
+
+  use Log::Report::DBIC::Profiler;
+  $schema->storage->debugobj(Log::Report::DBIC::Profiler->new);
+  $schema->storage->debug(1);
+
+  # And maybe (if no exceptions expected from DBIC)
+  $schema->exception_action(sub { panic @_ });
+  
+  # Log to syslog
+  use Log::Report;
+  dispatcher SYSLOG => 'myapp'
+    , identity => 'myapp'
+    , facility => 'local0'
+    , flags    => "pid ndelay nowait"
+    , mode     => 'DEBUG';
+
+=chapter DESCRIPTION
+
+This profile will log M<DBIx::Class> queries via M<Log::Report> to a
+selected back-end (via a dispatcher, see M<Log::Report::Dispatcher>)
+
+=cut
 
 my $start;
 
diff --git a/lib/Log/Report/DBIC/Profiler.pod b/lib/Log/Report/DBIC/Profiler.pod
deleted file mode 100644
index 35fa138..0000000
--- a/lib/Log/Report/DBIC/Profiler.pod
+++ /dev/null
@@ -1,46 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::DBIC::Profiler - query profiler for DBIx::Class
-
-=head1 INHERITANCE
-
- Log::Report::DBIC::Profiler
-   is a DBIx::Class::Storage::Statistics
-
-=head1 SYNOPSIS
-
-  use Log::Report::DBIC::Profiler;
-  $schema->storage->debugobj(Log::Report::DBIC::Profiler->new);
-  $schema->storage->debug(1);
-
-  # And maybe (if no exceptions expected from DBIC)
-  $schema->exception_action(sub { panic @_ });
-  
-  # Log to syslog
-  use Log::Report;
-  dispatcher SYSLOG => 'myapp'
-    , identity => 'myapp'
-    , facility => 'local0'
-    , flags    => "pid ndelay nowait"
-    , mode     => 'DEBUG';
-
-=head1 DESCRIPTION
-
-This profile will log DBIx::Class queries via L<Log::Report|Log::Report> to a
-selected back-end (via a dispatcher, see L<Log::Report::Dispatcher|Log::Report::Dispatcher>)
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Die.pm b/lib/Log/Report/Die.pm
index 5db0e75..e670583 100644
--- a/lib/Log/Report/Die.pm
+++ b/lib/Log/Report/Die.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Die;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Exporter';
 
 use warnings;
@@ -19,6 +12,48 @@ our @EXPORT = qw/die_decode exception_decode/;
 
 use POSIX  qw/locale_h/;
 
+=chapter NAME
+Log::Report::Die - compatibility routines with Perl's die/croak/confess
+
+=chapter SYNOPSIS
+ # use internally only
+
+=chapter DESCRIPTION
+
+This module is used internally, to translate output of 'die' and Carp
+functions into M<Log::Report::Message> objects.  Also, it tries to
+convert other kinds of exception frameworks into our message object.
+
+=chapter FUNCTIONS
+
+=function die_decode STRING, %options
+The STRING is the content of C<$@> after an eval() caught a die().
+croak(), or confess().  This routine tries to convert this into
+parameters for M<Log::Report::report()>.  This is done in a very
+smart way, even trying to find the stringifications of C<$!>.
+
+Return are four elements: the error string which is used to trigger
+a C<Log::Report> compatible C<die()>, and the options, reason, and
+text message.  The options is a HASH which, amongst other things,
+may contain a stack trace and location.
+
+Translated components will have exception classes C<perl>, and C<die> or
+C<confess>.  On the moment, the C<croak> cannot be distiguished from the
+C<confess> (when used in package main) or C<die> (otherwise).
+
+The returned reason depends on whether the translation of the current
+C<$!> is found in the STRING, and the presence of a stack trace.  The
+following table is used:
+
+  errstr  stack  =>  reason
+    no      no       ERROR   (die) application internal problem
+    yes     no       FAULT   (die) external problem, think open()
+    no      yes      PANIC   (confess) implementation error
+    yes     yes      ALERT   (confess) external problem, caught
+
+=option  on_die REASON
+=default on_die 'ERROR'
+=cut
 
 sub die_decode($%)
 {   my ($text, %args) = @_;
@@ -64,6 +99,17 @@ sub die_decode($%)
     ($dietxt, \%opt, $reason, join("\n", @msg));
 }
 
+=function exception_decode $exception, %options
+[1.23] This function attempts to translate object of other exception frameworks
+into information to create a M<Log::Report::Exception>.  It returns the
+same list of parameters as M<die_decode()> does.
+
+Currently supported:
+=over 4
+=item * DBIx::Class::Exception
+=item * XML::LibXML::Error
+=back
+=cut
 
 sub _exception_dbix($$)
 {   my ($exception, $args) = @_;
diff --git a/lib/Log/Report/Die.pod b/lib/Log/Report/Die.pod
deleted file mode 100644
index ca416e9..0000000
--- a/lib/Log/Report/Die.pod
+++ /dev/null
@@ -1,91 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Die - compatibility routines with Perl's die/croak/confess
-
-=head1 INHERITANCE
-
- Log::Report::Die
-   is a Exporter
-
-=head1 SYNOPSIS
-
- # use internally only
-
-=head1 DESCRIPTION
-
-This module is used internally, to translate output of 'die' and Carp
-functions into L<Log::Report::Message|Log::Report::Message> objects.  Also, it tries to
-convert other kinds of exception frameworks into our message object.
-
-=head1 FUNCTIONS
-
-=over 4
-
-=item B<die_decode>(STRING, %options)
-
-The STRING is the content of C<$@> after an eval() caught a die().
-croak(), or confess().  This routine tries to convert this into
-parameters for L<Log::Report::report()|Log::Report/"Report Production and Configuration">.  This is done in a very
-smart way, even trying to find the stringifications of C<$!>.
-
-Return are four elements: the error string which is used to trigger
-a C<Log::Report> compatible C<die()>, and the options, reason, and
-text message.  The options is a HASH which, amongst other things,
-may contain a stack trace and location.
-
-Translated components will have exception classes C<perl>, and C<die> or
-C<confess>.  On the moment, the C<croak> cannot be distiguished from the
-C<confess> (when used in package main) or C<die> (otherwise).
-
-The returned reason depends on whether the translation of the current
-C<$!> is found in the STRING, and the presence of a stack trace.  The
-following table is used:
-
-  errstr  stack  =>  reason
-    no      no       ERROR   (die) application internal problem
-    yes     no       FAULT   (die) external problem, think open()
-    no      yes      PANIC   (confess) implementation error
-    yes     yes      ALERT   (confess) external problem, caught
-
- -Option--Default
-  on_die  'ERROR'
-
-=over 2
-
-=item on_die => REASON
-
-=back
-
-=item B<exception_decode>($exception, %options)
-
-[1.23] This function attempts to translate object of other exception frameworks
-into information to create a L<Log::Report::Exception|Log::Report::Exception>.  It returns the
-same list of parameters as L<die_decode()|Log::Report::Die/"FUNCTIONS"> does.
-
-Currently supported:
-
-=over 4
-
-=item * DBIx::Class::Exception
-
-=item * XML::LibXML::Error
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher.pm b/lib/Log/Report/Dispatcher.pm
index 97856cb..353e6dd 100644
--- a/lib/Log/Report/Dispatcher.pm
+++ b/lib/Log/Report/Dispatcher.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 
 use warnings;
 use strict;
@@ -39,6 +32,87 @@ my %predef_dispatchers = map +(uc($_) => __PACKAGE__.'::'.$_)
 
 my @skip_stack = sub { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ };
 
+=chapter NAME
+Log::Report::Dispatcher - manage message dispatching, display or logging
+
+=chapter SYNOPSIS
+ use Log::Report;
+
+ # The following will be created for you automatically
+ dispatcher 'PERL', 'default', accept => 'NOTICE-';
+ dispatcher close => 'default';  # after deamonize
+
+ dispatcher 'FILE', 'log'
+   , mode => 'DEBUG', to => '/var/log/mydir/myfile';
+
+ # Full package name is used, same as 'FILE'
+ dispatcher Log::Report::Dispatch::File => 'stderr'
+   , to => \*STDERR, accept => 'NOTICE-';
+
+=chapter DESCRIPTION
+In M<Log::Report>, dispatchers are used to handle (exception) messages
+which are created somewhere else.  Those message were produced (thrown)
+by M<Log::Report::error()> and friends.
+
+This base-class handles the creation of dispatchers, plus the common
+filtering rules.  See the L</DETAILS> section, below.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+Create a dispatcher.  The $type of back-end to start is required, and listed
+in the L</DESCRIPTION> part of this manual-page. For various external
+back-ends, special wrappers are created.
+
+The $name must be uniquely identifying this dispatcher.  When a second
+dispatcher is created (via M<Log::Report::dispatcher()>) with the name
+of an existing dispatcher, the existing one will get replaced.
+
+All %options which are not consumed by this base constructor are passed
+to the wrapped back-end.  Some of them will check whether all %options
+are understood, other ignore unknown %options.
+
+=option  accept REASONS
+=default accept C<depend on mode>
+See M<Log::Report::Util::expand_reasons()> for possible values.  If
+the initial mode for this dispatcher does not need verbose or debug
+information, then those levels will not be accepted.
+
+When the mode equals "NORMAL" (the default) then C<accept>'s default
+is C<NOTICE->.  In case of "VERBOSE" it will be C<INFO->, C<ASSERT>
+results in C<ASSERT->, and "DEBUG" in C<ALL>.
+
+=option  locale LOCALE
+=default locale <system locale>
+Overrules the global setting.  Can be overruled by
+M<Log::Report::report(locale)>.
+
+=option  mode 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
+=default mode 'NORMAL'
+Possible values are C<NORMAL> (or C<0> or C<undef>), which will not show
+C<INFO> or debug messages, C<VERBOSE> (C<1>; shows C<INFO> not debug),
+C<ASSERT> (C<2>; only ignores C<TRACE> messages), or C<DEBUG> (C<3>)
+which shows everything.  See section L<Log::Report/Run modes>.
+
+You are advised to use the symbolic mode names when the mode is
+changed within your program: the numerical values are available
+for smooth M<Getopt::Long> integration.
+
+=option  format_reason 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
+=default format_reason 'LOWERCASE'
+How to show the reason text which is printed before the message. When
+a CODE is specified, it will be called with a translated text and the
+returned text is used.
+
+=option  charset CHARSET
+=default charset <undef>
+Convert the messages in the specified character-set (codeset).  By
+default, no conversion will take place, because the right choice cannot
+be determined automatically.
+
+=cut
 
 sub new(@)
 {   my ($class, $type, $name, %args) = @_;
@@ -90,6 +164,11 @@ sub init($)
     $self;
 }
 
+=method close
+Terminate the dispatcher activities.  The dispatcher gets disabled,
+to avoid the case that it is accidentally used.  Returns C<undef> (false)
+if the dispatcher was already closed.
+=cut
 
 sub close()
 {   my $self = shift;
@@ -102,12 +181,25 @@ sub DESTROY { in_global_destruction or shift->close }
 
 #----------------------------
 
+=section Accessors
+
+=method name
+Returns the unique name of this dispatcher.
+=cut
 
 sub name {shift->{name}}
 
+=method type
+The dispatcher $type, which is usually the same as the class of this
+object, but not in case of wrappers like for Log::Dispatch.
+=cut
 
 sub type() {shift->{type}}
 
+=method mode
+Returns the mode in use for the dispatcher as number.  See M<new(mode)>
+and L<Log::Report/Run modes>.
+=cut
 
 sub mode() {shift->{mode}}
 
@@ -137,9 +229,18 @@ sub _disabled($)
     @_ ? ($self->{disabled} = shift) : $self->{disabled};
 }
 
+=method isDisabled
+=cut
 
 sub isDisabled() {shift->{disabled}}
 
+=method needs [$reason]
+Returns the list with all REASONS which are needed to fulfill this
+dispatcher's needs.  When disabled, the list is empty, but not forgotten.
+
+[0.999] when only one $reason is specified, it is returned if in the
+list.
+=cut
 
 sub needs(;$)
 {   my $self = shift;
@@ -153,11 +254,23 @@ sub needs(;$)
 }
 
 #-----------
+=section Logging
+
+=method log HASH-$of-%options, $reason, $message, $domain
+This method is called by M<Log::Report::report()> and should not be called
+directly.  Internally, it will call M<translate()>, which does most $of
+the work.
+=cut
 
 sub log($$$$)
 {   panic "method log() must be extended per back-end";
 }
 
+=method translate HASH-$of-%options, $reason, $message
+See L</Processing the message>, which describes the actions taken by
+this method.  A string is returned, which ends on a new-line, and
+may be multi-line (in case a stack trace is produced).
+=cut
 
 sub translate($$$)
 {   my ($self, $opts, $reason, $msg) = @_;
@@ -228,6 +341,9 @@ sub translate($$$)
     $self->{charset_enc}->($text);
 }
 
+=ci_method collectStack [$maxdepth]
+Returns an ARRAY of ARRAYs with text, filename, line-number.
+=cut
 
 sub collectStack($)
 {   my ($thing, $max) = @_;
@@ -249,6 +365,24 @@ sub collectStack($)
   }
 }
 
+=ci_method addSkipStack @CODE
+[1.13] Add one or more CODE blocks of caller lines which should not be
+collected for stack-traces or location display.  A CODE gets
+called with an ARRAY of caller information, and returns true
+when that line should get skipped.
+
+B<Warning:> this logic is applied globally: on all dispatchers.
+
+=example
+By default, all lines in the Log::Report packages are skipped from
+display, with a simple CODE as this:
+
+  sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
+  Log::Report::Dispatcher->addSkipStack(\&in_lr);
+
+The only parameter to in_lr is the return of caller().  The first
+element of that ARRAY is the package name of a stack line.
+=cut
 
 sub addSkipStack(@)
 {   my $thing = shift;
@@ -256,6 +390,11 @@ sub addSkipStack(@)
     $thing;
 }
 
+=method skipStack
+[1.13] Returns the number of nestings in the stack which should be skipped
+to get outside the Log::Report (and related) modules.  The end-user
+does not want to see those internals in stack-traces.
+=cut
 
 sub skipStack()
 {   my $thing = shift;
@@ -269,9 +408,32 @@ sub skipStack()
     @$args ? $nest-1 : 1;
 }
 
+=ci_method collectLocation
+Collect the information to be displayed as line where the error occurred.
+=cut
 
 sub collectLocation() { [caller shift->skipStack] }
 
+=ci_method stackTraceLine %options
+=requires package CLASS
+=requires filename STRING
+=requires linenr INTEGER
+=requires call STRING
+=requires params ARRAY
+
+=option  max_line INTEGER
+=default max_line C<undef>
+
+=option  max_params INTEGER
+=default max_params 8
+
+=option  abstract INTEGER
+=default abstract 1
+The higher the abstraction value, the less details are given
+about the caller.  The minimum abstraction is specified, and
+then increased internally to make the line fit within the C<max_line>
+margin.
+=cut
 
 sub stackTraceLine(@)
 {   my ($thing, %args) = @_;
@@ -357,5 +519,139 @@ sub stackTraceParam($$$)
 }
 
 #------------
+=chapter DETAILS
+
+=section Available back-ends
+
+When a dispatcher is created (via M<new()> or M<Log::Report::dispatcher()>),
+you must specify the TYPE of the dispatcher.  This can either be a class
+name, which extends a M<Log::Report::Dispatcher>, or a pre-defined
+abbreviation of a class name.  Implemented are:
+
+=over 4
+=item M<Log::Report::Dispatcher::Perl> (abbreviation 'PERL')
+Use Perl's own C<print()>, C<warn()> and C<die()> to ventilate
+reports.  This is the default dispatcher.
+
+=item M<Log::Report::Dispatcher::File> (abbreviation 'FILE')
+Logs the message into a file, which can either be opened by the
+class or be opened before the dispatcher is created.
+
+=item M<Log::Report::Dispatcher::Syslog> (abbreviation 'SYSLOG')
+Send messages into the system's syslog infrastructure, using
+M<Sys::Syslog>.
+
+=item M<Log::Report::Dispatcher::Callback> (abbreviation 'CALLBACK')
+Calls any CODE reference on receipt of each selected message, for
+instance to send important message as email or SMS.
+
+=item C<Log::Dispatch::*>
+All of the M<Log::Dispatch::Output> extensions can be used directly.
+The M<Log::Report::Dispatcher::LogDispatch> will wrap around that
+back-end.
+
+=item C<Log::Log4perl>
+Use the M<Log::Log4perl> main object to write to dispatchers.  This
+infrastructure uses a configuration file.
+
+=item M<Log::Report::Dispatcher::Try> (abbreviation 'TRY')
+Used by function M<Log::Report::try()>.  It collects the exceptions
+and can produce them on request.
+
+=back
+
+=section Processing the message
+
+=subsection Addition information
+
+The modules which use C<Log::Report> will only specify the base of
+the message string.  The base dispatcher and the back-ends will extend
+this message with additional information:
+
+=over 4
+=item . the reason
+=item . the filename/line-number where the problem appeared
+=item . the filename/line-number where it problem was reported
+=item . the error text in C<$!>
+=item . a stack-trace
+=item . a trailing new-line
+=back
+
+When the message is a translatable object (M<Log::Report::Message>, for
+instance created with M<Log::Report::__()>), then the added components
+will get translated as well.  Otherwise, all will be in English.
+
+Exactly what will be added depends on the actual mode of the dispatcher
+(change it with M<mode()>, initiate it with M<new(mode)>).
+
+                        mode mode mode mode
+ REASON   SOURCE   TE!  NORM VERB ASSE DEBUG
+ trace    program  ...                 S
+ assert   program  ...            SL   SL
+ info     program  T..       S    S    S
+ notice   program  T..  S    S    S    S
+ mistake  user     T..  S    S    S    SL
+ warning  program  T..  S    S    SL   SL
+ error    user     TE.  S    S    SL   SC
+ fault    system   TE!  S    S    SL   SC
+ alert    system   T.!  SL   SL   SC   SC
+ failure  system   TE!  SL   SL   SC   SC
+ panic    program  .E.  SC   SC   SC   SC
+
+ T - usually translated
+ E - exception (execution interrupted)
+ ! - will include $! text at display
+ L - include filename and linenumber
+ S - show/print when accepted
+ C - stack trace (like Carp::confess())
+
+=subsection Filters
+
+With a filter, you can block or modify specific messages before
+translation.  There may be a wish to change the REASON of a report
+or its content.  It is not possible to avoid the exit which is
+related to the original message, because a module's flow depends
+on it to happen.
+
+When there are filters defined, they will be called in order of
+definition.  For each of the dispatchers which are called for a
+certain REASON (which C<accept> that REASON), it is checked whether
+its name is listed for the filter (when no names where specified,
+then the filter is applied to all dispatchers).
+
+When selected, the filter's CODE reference is called with four arguments:
+the dispatcher object (a M<Log::Report::Dispatcher>), the HASH-of-OPTIONS
+passed as optional first argument to M<Log::Report::report()>, the
+REASON, and the MESSAGE.  Returned is the new REASON and MESSAGE.
+When the returned REASON is C<undef>, then the message will be ignored
+for that dispatcher.
+
+Be warned about processing the MESSAGE: it is a M<Log::Report::Message>
+object which may have a C<prepend> string and C<append> string or
+object.  When the call to M<Log::Report::report()> contained multiple
+comma-separated components, these will already have been joined together
+using concatenation (see M<Log::Report::Message::concat()>.
+
+=example a filter on syslog
+ dispatcher filter => \&myfilter, 'syslog';
+
+ # ignore all translatable and non-translatable messages containing
+ # the word "skip"
+ sub myfilter($$$$)
+ {   my ($disp, $opts, $reason, $message) = @_;
+     return () if $message->untranslated =~ m/\bskip\b/;
+     ($reason, $message);
+ }
+
+=example take all mistakes and warnings serious
+ dispatch filter => \&take_warns_seriously;
+ sub take_warns_seriously($$$$)
+ {   my ($disp, $opts, $reason, $message) = @_;
+       $reason eq 'MISTAKE' ? (ERROR   => $message)
+     : $reason eq 'WARNING' ? (FAULT   => $message)
+     :                        ($reason => $message);
+ }
+
+=cut
 
 1;
diff --git a/lib/Log/Report/Dispatcher.pod b/lib/Log/Report/Dispatcher.pod
deleted file mode 100644
index 8e790ec..0000000
--- a/lib/Log/Report/Dispatcher.pod
+++ /dev/null
@@ -1,408 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher - manage message dispatching, display or logging
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher is extended by
-   Log::Report::Dispatcher::Callback
-   Log::Report::Dispatcher::File
-   Log::Report::Dispatcher::Log4perl
-   Log::Report::Dispatcher::LogDispatch
-   Log::Report::Dispatcher::Perl
-   Log::Report::Dispatcher::Syslog
-   Log::Report::Dispatcher::Try
-
-=head1 SYNOPSIS
-
- use Log::Report;
-
- # The following will be created for you automatically
- dispatcher 'PERL', 'default', accept => 'NOTICE-';
- dispatcher close => 'default';  # after deamonize
-
- dispatcher 'FILE', 'log'
-   , mode => 'DEBUG', to => '/var/log/mydir/myfile';
-
- # Full package name is used, same as 'FILE'
- dispatcher Log::Report::Dispatch::File => 'stderr'
-   , to => \*STDERR, accept => 'NOTICE-';
-
-=head1 DESCRIPTION
-
-In L<Log::Report|Log::Report>, dispatchers are used to handle (exception) messages
-which are created somewhere else.  Those message were produced (thrown)
-by L<Log::Report::error()|Log::Report/"Abbreviations for report()"> and friends.
-
-This base-class handles the creation of dispatchers, plus the common
-filtering rules.  See the L</DETAILS> section, below.
-
-=head1 METHODS
-
-=head2 Constructors
-
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Terminate the dispatcher activities.  The dispatcher gets disabled,
-to avoid the case that it is accidentally used.  Returns C<undef> (false)
-if the dispatcher was already closed.
-
-=item Log::Report::Dispatcher-E<gt>B<new>($type, $name, %options)
-
-Create a dispatcher.  The $type of back-end to start is required, and listed
-in the L</DESCRIPTION> part of this manual-page. For various external
-back-ends, special wrappers are created.
-
-The $name must be uniquely identifying this dispatcher.  When a second
-dispatcher is created (via L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">) with the name
-of an existing dispatcher, the existing one will get replaced.
-
-All %options which are not consumed by this base constructor are passed
-to the wrapped back-end.  Some of them will check whether all %options
-are understood, other ignore unknown %options.
-
- -Option       --Default
-  accept         depend on mode
-  charset        <undef>
-  format_reason  'LOWERCASE'
-  locale         <system locale>
-  mode           'NORMAL'
-
-=over 2
-
-=item accept => REASONS
-
-See L<Log::Report::Util::expand_reasons()|Log::Report::Util/"Reasons"> for possible values.  If
-the initial mode for this dispatcher does not need verbose or debug
-information, then those levels will not be accepted.
-
-When the mode equals "NORMAL" (the default) then C<accept>'s default
-is C<NOTICE->.  In case of "VERBOSE" it will be C<INFO->, C<ASSERT>
-results in C<ASSERT->, and "DEBUG" in C<ALL>.
-
-=item charset => CHARSET
-
-Convert the messages in the specified character-set (codeset).  By
-default, no conversion will take place, because the right choice cannot
-be determined automatically.
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-How to show the reason text which is printed before the message. When
-a CODE is specified, it will be called with a translated text and the
-returned text is used.
-
-=item locale => LOCALE
-
-Overrules the global setting.  Can be overruled by
-L<Log::Report::report(locale)|Log::Report/"Report Production and Configuration">.
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-Possible values are C<NORMAL> (or C<0> or C<undef>), which will not show
-C<INFO> or debug messages, C<VERBOSE> (C<1>; shows C<INFO> not debug),
-C<ASSERT> (C<2>; only ignores C<TRACE> messages), or C<DEBUG> (C<3>)
-which shows everything.  See section L<Log::Report/Run modes>.
-
-You are advised to use the symbolic mode names when the mode is
-changed within your program: the numerical values are available
-for smooth Getopt::Long integration.
-
-=back
-
-=back
-
-=head2 Accessors
-
-=over 4
-
-=item $obj-E<gt>B<isDisabled>()
-
-=item $obj-E<gt>B<mode>()
-
-Returns the mode in use for the dispatcher as number.  See L<new(mode)|Log::Report::Dispatcher/"Constructors">
-and L<Log::Report/Run modes>.
-
-=item $obj-E<gt>B<name>()
-
-Returns the unique name of this dispatcher.
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Returns the list with all REASONS which are needed to fulfill this
-dispatcher's needs.  When disabled, the list is empty, but not forgotten.
-
-[0.999] when only one $reason is specified, it is returned if in the
-list.
-
-=item $obj-E<gt>B<type>()
-
-The dispatcher $type, which is usually the same as the class of this
-object, but not in case of wrappers like for Log::Dispatch.
-
-=back
-
-=head2 Logging
-
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher-E<gt>B<addSkipStack>(@CODE)
-
-[1.13] Add one or more CODE blocks of caller lines which should not be
-collected for stack-traces or location display.  A CODE gets
-called with an ARRAY of caller information, and returns true
-when that line should get skipped.
-
-B<Warning:> this logic is applied globally: on all dispatchers.
-
-example: 
-
-By default, all lines in the Log::Report packages are skipped from
-display, with a simple CODE as this:
-
-  sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
-  Log::Report::Dispatcher->addSkipStack(\&in_lr);
-
-The only parameter to in_lr is the return of caller().  The first
-element of that ARRAY is the package name of a stack line.
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher-E<gt>B<collectLocation>()
-
-Collect the information to be displayed as line where the error occurred.
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher-E<gt>B<collectStack>( [$maxdepth] )
-
-Returns an ARRAY of ARRAYs with text, filename, line-number.
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-This method is called by L<Log::Report::report()|Log::Report/"Report Production and Configuration"> and should not be called
-directly.  Internally, it will call L<translate()|Log::Report::Dispatcher/"Logging">, which does most $of
-the work.
-
-=item $obj-E<gt>B<skipStack>()
-
-[1.13] Returns the number of nestings in the stack which should be skipped
-to get outside the Log::Report (and related) modules.  The end-user
-does not want to see those internals in stack-traces.
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher-E<gt>B<stackTraceLine>(%options)
-
- -Option    --Default
-  abstract    1
-  call        <required>
-  filename    <required>
-  linenr      <required>
-  max_line    undef
-  max_params  8
-  package     <required>
-  params      <required>
-
-=over 2
-
-=item abstract => INTEGER
-
-The higher the abstraction value, the less details are given
-about the caller.  The minimum abstraction is specified, and
-then increased internally to make the line fit within the C<max_line>
-margin.
-
-=item call => STRING
-
-=item filename => STRING
-
-=item linenr => INTEGER
-
-=item max_line => INTEGER
-
-=item max_params => INTEGER
-
-=item package => CLASS
-
-=item params => ARRAY
-
-=back
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-See L</Processing the message>, which describes the actions taken by
-this method.  A string is returned, which ends on a new-line, and
-may be multi-line (in case a stack trace is produced).
-
-=back
-
-=head1 DETAILS
-
-=head2 Available back-ends
-
-When a dispatcher is created (via L<new()|Log::Report::Dispatcher/"Constructors"> or L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">),
-you must specify the TYPE of the dispatcher.  This can either be a class
-name, which extends a L<Log::Report::Dispatcher|Log::Report::Dispatcher>, or a pre-defined
-abbreviation of a class name.  Implemented are:
-
-=over 4
-
-=item L<Log::Report::Dispatcher::Perl|Log::Report::Dispatcher::Perl> (abbreviation 'PERL')
-
-Use Perl's own C<print()>, C<warn()> and C<die()> to ventilate
-reports.  This is the default dispatcher.
-
-=item L<Log::Report::Dispatcher::File|Log::Report::Dispatcher::File> (abbreviation 'FILE')
-
-Logs the message into a file, which can either be opened by the
-class or be opened before the dispatcher is created.
-
-=item L<Log::Report::Dispatcher::Syslog|Log::Report::Dispatcher::Syslog> (abbreviation 'SYSLOG')
-
-Send messages into the system's syslog infrastructure, using
-Sys::Syslog.
-
-=item L<Log::Report::Dispatcher::Callback|Log::Report::Dispatcher::Callback> (abbreviation 'CALLBACK')
-
-Calls any CODE reference on receipt of each selected message, for
-instance to send important message as email or SMS.
-
-=item C<Log::Dispatch::*>
-
-All of the Log::Dispatch::Output extensions can be used directly.
-The L<Log::Report::Dispatcher::LogDispatch|Log::Report::Dispatcher::LogDispatch> will wrap around that
-back-end.
-
-=item C<Log::Log4perl>
-
-Use the Log::Log4perl main object to write to dispatchers.  This
-infrastructure uses a configuration file.
-
-=item L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> (abbreviation 'TRY')
-
-Used by function L<Log::Report::try()|Log::Report/"Report Production and Configuration">.  It collects the exceptions
-and can produce them on request.
-
-=back
-
-=head2 Processing the message
-
-=head3 Addition information
-
-The modules which use C<Log::Report> will only specify the base of
-the message string.  The base dispatcher and the back-ends will extend
-this message with additional information:
-
-=over 4
-
-=item . the reason
-
-=item . the filename/line-number where the problem appeared
-
-=item . the filename/line-number where it problem was reported
-
-=item . the error text in C<$!>
-
-=item . a stack-trace
-
-=item . a trailing new-line
-
-=back
-
-When the message is a translatable object (L<Log::Report::Message|Log::Report::Message>, for
-instance created with L<Log::Report::__()|Log::Report/"Messages (optionally translatable)">), then the added components
-will get translated as well.  Otherwise, all will be in English.
-
-Exactly what will be added depends on the actual mode of the dispatcher
-(change it with L<mode()|Log::Report::Dispatcher/"Accessors">, initiate it with L<new(mode)|Log::Report::Dispatcher/"Constructors">).
-
-                        mode mode mode mode
- REASON   SOURCE   TE!  NORM VERB ASSE DEBUG
- trace    program  ...                 S
- assert   program  ...            SL   SL
- info     program  T..       S    S    S
- notice   program  T..  S    S    S    S
- mistake  user     T..  S    S    S    SL
- warning  program  T..  S    S    SL   SL
- error    user     TE.  S    S    SL   SC
- fault    system   TE!  S    S    SL   SC
- alert    system   T.!  SL   SL   SC   SC
- failure  system   TE!  SL   SL   SC   SC
- panic    program  .E.  SC   SC   SC   SC
-
- T - usually translated
- E - exception (execution interrupted)
- ! - will include $! text at display
- L - include filename and linenumber
- S - show/print when accepted
- C - stack trace (like Carp::confess())
-
-=head3 Filters
-
-With a filter, you can block or modify specific messages before
-translation.  There may be a wish to change the REASON of a report
-or its content.  It is not possible to avoid the exit which is
-related to the original message, because a module's flow depends
-on it to happen.
-
-When there are filters defined, they will be called in order of
-definition.  For each of the dispatchers which are called for a
-certain REASON (which C<accept> that REASON), it is checked whether
-its name is listed for the filter (when no names where specified,
-then the filter is applied to all dispatchers).
-
-When selected, the filter's CODE reference is called with four arguments:
-the dispatcher object (a L<Log::Report::Dispatcher|Log::Report::Dispatcher>), the HASH-of-OPTIONS
-passed as optional first argument to L<Log::Report::report()|Log::Report/"Report Production and Configuration">, the
-REASON, and the MESSAGE.  Returned is the new REASON and MESSAGE.
-When the returned REASON is C<undef>, then the message will be ignored
-for that dispatcher.
-
-Be warned about processing the MESSAGE: it is a L<Log::Report::Message|Log::Report::Message>
-object which may have a C<prepend> string and C<append> string or
-object.  When the call to L<Log::Report::report()|Log::Report/"Report Production and Configuration"> contained multiple
-comma-separated components, these will already have been joined together
-using concatenation (see L<Log::Report::Message::concat()|Log::Report::Message/"Processing">.
-
-B<. Example: a filter on syslog>
-
- dispatcher filter => \&myfilter, 'syslog';
-
- # ignore all translatable and non-translatable messages containing
- # the word "skip"
- sub myfilter($$$$)
- {   my ($disp, $opts, $reason, $message) = @_;
-     return () if $message->untranslated =~ m/\bskip\b/;
-     ($reason, $message);
- }
-
-B<. Example: take all mistakes and warnings serious>
-
- dispatch filter => \&take_warns_seriously;
- sub take_warns_seriously($$$$)
- {   my ($disp, $opts, $reason, $message) = @_;
-       $reason eq 'MISTAKE' ? (ERROR   => $message)
-     : $reason eq 'WARNING' ? (FAULT   => $message)
-     :                        ($reason => $message);
- }
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/Callback.pm b/lib/Log/Report/Dispatcher/Callback.pm
index e8931d8..5d0dc6f 100644
--- a/lib/Log/Report/Dispatcher/Callback.pm
+++ b/lib/Log/Report/Dispatcher/Callback.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::Callback;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -17,6 +10,53 @@ use strict;
 
 use Log::Report 'log-report';
 
+=chapter NAME
+Log::Report::Dispatcher::Callback - call a code-ref for each log-line
+
+=chapter SYNOPSIS
+ sub cb($$$)
+ {   my ($disp, $options, $reason, $message) = @_;
+     ...
+ }
+
+ dispatcher Log::Report::Dispatcher::Callback => 'cb'
+    , callback => \&cb;
+
+ dispatcher CALLBACK => 'cb'   # same
+    , callback => \&cb;
+
+=chapter DESCRIPTION
+This basic file logger accepts a callback, which is called for each
+message which is to be logged. When you need complex things, you
+may best make your own extension to M<Log::Report::Dispatcher>, but
+for simple things this will do.
+
+=example
+  sub send_mail($$$)
+  {   my ($disp, $options, $reason, $message) = @_;
+      my $msg = Mail::Send->new(Subject => $reason
+        , To => 'admin@localhost');
+      my $fh  = $msg->open('sendmail');
+      print $fh $disp->translate($reason, $message);
+      close $fh;
+  }
+
+  dispatcher CALLBACK => 'mail', callback => \&send_mail;
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+
+=requires callback CODE
+Your C<callback> is called with five parameters: this dispatcher object,
+the options, a reason and a message.  The C<options> are the first
+parameter of M<Log::Report::report()> (read over there).  The C<reason>
+is a capitized string like C<ERROR>. Then, the C<message> (is a
+M<Log::Report::Message>).  Finally the text-domain of the message.
+
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -28,9 +68,16 @@ sub init($)
     $self;
 }
 
+=section Accessors
+
+=method callback
+Returns the code reference which will handle each logged message.
+=cut
 
 sub callback() {shift->{callback}}
 
+=section Logging
+=cut
 
 sub log($$$$)
 {   my $self = shift;
diff --git a/lib/Log/Report/Dispatcher/Callback.pod b/lib/Log/Report/Dispatcher/Callback.pod
deleted file mode 100644
index 0fc657d..0000000
--- a/lib/Log/Report/Dispatcher/Callback.pod
+++ /dev/null
@@ -1,187 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::Callback - call a code-ref for each log-line
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::Callback
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- sub cb($$$)
- {   my ($disp, $options, $reason, $message) = @_;
-     ...
- }
-
- dispatcher Log::Report::Dispatcher::Callback => 'cb'
-    , callback => \&cb;
-
- dispatcher CALLBACK => 'cb'   # same
-    , callback => \&cb;
-
-=head1 DESCRIPTION
-
-This basic file logger accepts a callback, which is called for each
-message which is to be logged. When you need complex things, you
-may best make your own extension to L<Log::Report::Dispatcher|Log::Report::Dispatcher>, but
-for simple things this will do.
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-B<. Example>
-
-  sub send_mail($$$)
-  {   my ($disp, $options, $reason, $message) = @_;
-      my $msg = Mail::Send->new(Subject => $reason
-        , To => 'admin@localhost');
-      my $fh  = $msg->open('sendmail');
-      print $fh $disp->translate($reason, $message);
-      close $fh;
-  }
-
-  dispatcher CALLBACK => 'mail', callback => \&send_mail;
-
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Inherited, see L<Log::Report::Dispatcher/"Constructors">
-
-=item Log::Report::Dispatcher::Callback-E<gt>B<new>($type, $name, %options)
-
- -Option       --Defined in             --Default
-  accept         Log::Report::Dispatcher  depend on mode
-  callback                                <required>
-  charset        Log::Report::Dispatcher  <undef>
-  format_reason  Log::Report::Dispatcher  'LOWERCASE'
-  locale         Log::Report::Dispatcher  <system locale>
-  mode           Log::Report::Dispatcher  'NORMAL'
-
-=over 2
-
-=item accept => REASONS
-
-=item callback => CODE
-
-Your C<callback> is called with five parameters: this dispatcher object,
-the options, a reason and a message.  The C<options> are the first
-parameter of L<Log::Report::report()|Log::Report/"Report Production and Configuration"> (read over there).  The C<reason>
-is a capitized string like C<ERROR>. Then, the C<message> (is a
-L<Log::Report::Message|Log::Report::Message>).  Finally the text-domain of the message.
-
-=item charset => CHARSET
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item locale => LOCALE
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<callback>()
-
-Returns the code reference which will handle each logged message.
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::Callback-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::Callback-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::Callback-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::Callback-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/File.pm b/lib/Log/Report/Dispatcher/File.pm
index 95f89bd..59973d9 100644
--- a/lib/Log/Report/Dispatcher/File.pm
+++ b/lib/Log/Report/Dispatcher/File.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::File;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -22,6 +15,119 @@ use POSIX        qw/strftime/;
 use Encode       qw/find_encoding/;
 use Fcntl        qw/:flock/;
 
+=chapter NAME
+Log::Report::Dispatcher::File - send messages to a file or file-handle
+
+=chapter SYNOPSIS
+ dispatcher Log::Report::Dispatcher::File => 'stderr'
+   , to => \*STDERR, accept => 'NOTICE-';
+
+ # close a dispatcher
+ dispatcher close => 'stderr';
+
+ # let dispatcher open and close the file
+ dispatcher FILE => 'mylog', to => '/var/log/mylog'
+   , charset => 'utf-8';
+ ...
+ dispatcher close => 'mylog';  # will close file
+
+ # open yourself, then also close yourself
+ open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
+     or fault "...";
+ dispatcher FILE => 'mylog', to => \*OUT;
+ ...
+ dispatcher close => 'mylog';  
+ close OUT;
+
+ # dispatch into a scalar
+ my $output = '';
+ open $outfile, '>', \$output;
+ dispatcher FILE => 'into-scalar', to => \$outfile;
+ ...
+ dispatcher close => 'into-scalar';
+ print $output;
+
+=chapter DESCRIPTION
+This basic file logger accepts an file-handle or filename as destination.
+
+[1.00] writing to the file protected by a lock, so multiple processes
+can write to the same file.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+
+=requires to FILENAME|FILEHANDLE|OBJECT|CODE
+You can either specify a FILENAME, which is opened in append mode with
+autoflush on. Or pass any kind of FILE-HANDLE or some OBJECT which
+implements a C<print()> method. You probably want to have autoflush
+enabled on your FILE-HANDLES.
+
+When cleaning-up the dispatcher, the file will only be closed in case
+of a FILENAME.
+
+[1.10] When you pass a CODE, then for each log message the function is
+called with two arguments: this dispatcher object and the message object.
+In some way (maybe via the message context) you have to determine the
+log filename.  This means that probably many log-files are open at the
+same time.
+
+   # configuration time
+   dispatcher FILE => 'logfile', to =>
+       sub { my ($disp, $msg) = @_; $msg->context->{logfile} };
+
+   # whenever you want to change the logfile
+   textdomain->updateContext(logfile => '/var/log/app');
+   (textdomain 'mydomain')->setContext(logfile => '/var/log/app');
+
+   # or
+   error __x"help", _context => {logfile => '/dev/tty'};
+   error __x"help", _context => "logfile=/dev/tty";
+
+=option  replace BOOLEAN
+=default replace C<false>
+Only used in combination with a FILENAME: throw away the old file
+if it exists.  Probably you wish to append to existing information.
+
+=default charset LOCALE
+Use the LOCALE setting by default, which is LC_CTYPE or LC_ALL or LANG
+(in that order).  If these contain a character-set which Perl understands,
+then that is used, otherwise silently ignored.
+
+=option  format CODE|'LONG'
+=default format <adds timestamp>
+[1.00] process each printed line.  By default, this adds a timestamp,
+but you may want to add hostname, process number, or more.
+
+   format => sub { '['.localtime().'] '.$_[0] }
+   format => sub { shift }   # no timestamp
+   format => 'LONG'
+
+The first parameter to format is the string to print; it is already
+translated and trailed by a newline.  The second parameter is the
+text-domain (if known).
+
+[1.10] As third parameter, you get the $msg raw object as well (maybe
+you want to use the message context?)
+[1.19] After the three positional parameters, there may be a list
+of pairs providing additional facts about the exception.  It may
+contain C<location> information.
+
+The "LONG" format is equivalent to:
+
+  my $t = strftime "%FT%T", gmtime;
+  "[$t $$] $_[1] $_[0]"
+
+Use of context:
+
+   format => sub { my ($msgstr, $domain, $msg, %more) = @_;
+      my $host = $msg->context->{host};
+      "$host $msgstr";
+   }
+
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -55,6 +161,10 @@ sub init($)
 }
 
 
+=method close
+Only when initiated with a FILENAME, the file will be closed.  In any
+other case, nothing will be done.
+=cut
 
 sub close()
 {   my $self = shift;
@@ -72,10 +182,22 @@ sub close()
 }
 
 #-----------
+=section Accessors
+
+=method filename
+Returns the name of the opened file, or C<undef> in case this dispatcher
+was started from a file-handle or file-object.
+
+=method format
+=cut
 
 sub filename() {shift->{LRDF_filename}}
 sub format()   {shift->{LRDF_format}}
 
+=method output $msg
+Returns the file-handle to write the log lines to. [1.10] This may
+depend on the $msg (especially message context)
+=cut
 
 sub output($)
 {   # fast simple case
@@ -109,6 +231,11 @@ sub output($)
 
 
 #-----------
+=section File maintenance
+
+=method rotate $filename|CODE
+[1.00] Move the current file to $filename, and start a new file.
+=cut
 
 sub rotate($)
 {   my ($self, $old) = @_;
@@ -139,6 +266,8 @@ sub rotate($)
 }
 
 #-----------
+=section Logging
+=cut
 
 sub log($$$$)
 {   my ($self, $opts, $reason, $msg, $domain) = @_;
diff --git a/lib/Log/Report/Dispatcher/File.pod b/lib/Log/Report/Dispatcher/File.pod
deleted file mode 100644
index e854bba..0000000
--- a/lib/Log/Report/Dispatcher/File.pod
+++ /dev/null
@@ -1,272 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::File - send messages to a file or file-handle
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::File
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- dispatcher Log::Report::Dispatcher::File => 'stderr'
-   , to => \*STDERR, accept => 'NOTICE-';
-
- # close a dispatcher
- dispatcher close => 'stderr';
-
- # let dispatcher open and close the file
- dispatcher FILE => 'mylog', to => '/var/log/mylog'
-   , charset => 'utf-8';
- ...
- dispatcher close => 'mylog';  # will close file
-
- # open yourself, then also close yourself
- open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
-     or fault "...";
- dispatcher FILE => 'mylog', to => \*OUT;
- ...
- dispatcher close => 'mylog';  
- close OUT;
-
- # dispatch into a scalar
- my $output = '';
- open $outfile, '>', \$output;
- dispatcher FILE => 'into-scalar', to => \$outfile;
- ...
- dispatcher close => 'into-scalar';
- print $output;
-
-=head1 DESCRIPTION
-
-This basic file logger accepts an file-handle or filename as destination.
-
-[1.00] writing to the file protected by a lock, so multiple processes
-can write to the same file.
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Only when initiated with a FILENAME, the file will be closed.  In any
-other case, nothing will be done.
-
-=item Log::Report::Dispatcher::File-E<gt>B<new>($type, $name, %options)
-
- -Option       --Defined in             --Default
-  accept         Log::Report::Dispatcher  depend on mode
-  charset        Log::Report::Dispatcher  LOCALE
-  format                                  <adds timestamp>
-  format_reason  Log::Report::Dispatcher  'LOWERCASE'
-  locale         Log::Report::Dispatcher  <system locale>
-  mode           Log::Report::Dispatcher  'NORMAL'
-  replace                                 false
-  to                                      <required>
-
-=over 2
-
-=item accept => REASONS
-
-=item charset => CHARSET
-
-=item format => CODE|'LONG'
-
-[1.00] process each printed line.  By default, this adds a timestamp,
-but you may want to add hostname, process number, or more.
-
-   format => sub { '['.localtime().'] '.$_[0] }
-   format => sub { shift }   # no timestamp
-   format => 'LONG'
-
-The first parameter to format is the string to print; it is already
-translated and trailed by a newline.  The second parameter is the
-text-domain (if known).
-
-[1.10] As third parameter, you get the $msg raw object as well (maybe
-you want to use the message context?)
-[1.19] After the three positional parameters, there may be a list
-of pairs providing additional facts about the exception.  It may
-contain C<location> information.
-
-The "LONG" format is equivalent to:
-
-  my $t = strftime "%FT%T", gmtime;
-  "[$t $$] $_[1] $_[0]"
-
-Use of context:
-
-   format => sub { my ($msgstr, $domain, $msg, %more) = @_;
-      my $host = $msg->context->{host};
-      "$host $msgstr";
-   }
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item locale => LOCALE
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=item replace => BOOLEAN
-
-Only used in combination with a FILENAME: throw away the old file
-if it exists.  Probably you wish to append to existing information.
-
-Use the LOCALE setting by default, which is LC_CTYPE or LC_ALL or LANG
-(in that order).  If these contain a character-set which Perl understands,
-then that is used, otherwise silently ignored.
-
-=item to => FILENAME|FILEHANDLE|OBJECT|CODE
-
-You can either specify a FILENAME, which is opened in append mode with
-autoflush on. Or pass any kind of FILE-HANDLE or some OBJECT which
-implements a C<print()> method. You probably want to have autoflush
-enabled on your FILE-HANDLES.
-
-When cleaning-up the dispatcher, the file will only be closed in case
-of a FILENAME.
-
-[1.10] When you pass a CODE, then for each log message the function is
-called with two arguments: this dispatcher object and the message object.
-In some way (maybe via the message context) you have to determine the
-log filename.  This means that probably many log-files are open at the
-same time.
-
-   # configuration time
-   dispatcher FILE => 'logfile', to =>
-       sub { my ($disp, $msg) = @_; $msg->context->{logfile} };
-
-   # whenever you want to change the logfile
-   textdomain->updateContext(logfile => '/var/log/app');
-   (textdomain 'mydomain')->setContext(logfile => '/var/log/app');
-
-   # or
-   error __x"help", _context => {logfile => '/dev/tty'};
-   error __x"help", _context => "logfile=/dev/tty";
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<filename>()
-
-Returns the name of the opened file, or C<undef> in case this dispatcher
-was started from a file-handle or file-object.
-
-=item $obj-E<gt>B<format>()
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<output>($msg)
-
-Returns the file-handle to write the log lines to. [1.10] This may
-depend on the $msg (especially message context)
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 File maintenance
-
-=over 4
-
-=item $obj-E<gt>B<rotate>($filename|CODE)
-
-[1.00] Move the current file to $filename, and start a new file.
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::File-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::File-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::File-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::File-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/Log4perl.pm b/lib/Log/Report/Dispatcher/Log4perl.pm
index 5d0eff4..9ec83d2 100644
--- a/lib/Log/Report/Dispatcher/Log4perl.pm
+++ b/lib/Log/Report/Dispatcher/Log4perl.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::Log4perl;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -44,6 +37,95 @@ Log::Log4perl->wrapper_register($_) for qw/
   Log::Report::Dispatcher::Try
 /;
 
+=chapter NAME
+Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl back-end
+
+=chapter SYNOPSIS
+
+ # start using log4perl via a config file
+ # The name of the dispatcher is the name of the default category.
+ dispatcher LOG4PERL => 'logger'
+   , accept => 'NOTICE-'
+   , config => "$ENV{HOME}/.log.conf";
+
+ # disable default dispatcher
+ dispatcher close => 'logger';
+
+ # configuration inline, not in file: adapted from the Log4perl manpage
+ my $name    = 'logger';
+ my $outfile = '/tmp/a.log';
+ my $config  = <<__CONFIG;
+ log4perl.category.$name            = INFO, Logfile
+ log4perl.logger.Logfile          = Log::Log4perl::Appender::File
+ log4perl.logger.Logfile.filename = $outfn
+ log4perl.logger.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
+ log4perl.logger.Logfile.layout.ConversionPattern = %d %F{1} %L> %m
+ __CONFIG
+
+ dispatcher LOG4PERL => $name, config => \$config;
+
+=chapter DESCRIPTION
+This dispatchers produces output tot syslog, based on the C<Sys::Log4perl>
+module (which will not be automatically installed for you).
+
+=section Reasons <--> Levels
+
+The REASONs for a message in M<Log::Report> are names quite similar to
+the log levels used by M<Log::Log4perl>.  The default mapping is list
+below.  You can change the mapping using M<new(to_level)>.
+
+  TRACE   => $DEBUG    ERROR   => $ERROR
+  ASSERT  => $DEBUG    FAULT   => $ERROR
+  INFO    => $INFO     ALERT   => $FATAL
+  NOTICE  => $INFO     FAILURE => $FATAL
+  WARNING => $WARN     PANIC   => $FATAL
+  MISTAKE => $WARN
+
+=section Categories
+
+C<Log::Report> uses text-domains for translation tables.  These are
+also used as categories for the Log4perl infrastructure.  So, typically
+every module start with:
+
+   use Log::Report 'my-text-domain', %more_options;
+
+Now, if there is a logger inside the log4perl configuration which is
+named 'my-text-domain', that will be used.  Otherwise, the name of the
+dispatcher is used to select the logger.
+
+=subsection Limitiations
+
+The global C<$caller_depth> concept of M<Log::Log4perl> is broken.
+That variable is used to find the filename and line number of the logged
+messages.  But these messages may have been caught, rerouted, eval'ed, and
+otherwise followed a unpredictable multi-leveled path before it reached
+the Log::Log4perl dispatcher.  This means that layout patterns C<%F>
+and C<%L> are not useful in the generic case, maybe in your specific case.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+The M<Log::Log4perl> infrastructure has all settings in a configuration
+file.  In that file, you should find a category with the $name.
+
+=option  to_level ARRAY-of-PAIRS
+=default to_level []
+See M<reasonToLevel()>.
+
+=option config FILENAME|SCALAR
+=default config <undef>
+When a SCALAR reference is passed in, that must refer to a string which
+contains the configuration text.  Otherwise, specify an existing FILENAME.
+
+By default, it is expected that M<Log::Log4perl> has been initialized
+externally.  That module uses global variables to communicate, which
+should be present before any logging is attempted.
+
+=default accept 'ALL'
+
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -80,6 +162,14 @@ sub init($)
 #    $self;
 #}
 
+=section Accessors
+
+=method logger [$domain]
+Returns the M<Log::Log4perl::Logger> object which is used for logging.
+When there is no specific logger for this $domain (logger with the exact
+name of the $domain) the default logger is being used, with the name of
+this dispatcher.
+=cut
 
 sub logger(;$)
 {   my ($self, $domain) = @_;
@@ -92,6 +182,8 @@ sub logger(;$)
        ||= Log::Log4perl->get_logger($self->name);
 }
 
+=section Logging
+=cut
 
 sub log($$$$)
 {   my ($self, $opts, $reason, $msg, $domain) = @_;
@@ -105,6 +197,20 @@ sub log($$$$)
     $self;
 }
 
+=method reasonToLevel $reason
+Returns a level which is understood by Log::Dispatch, based on
+a translation table.  This can be changed with M<new(to_level)>.
+
+=example
+
+ use Log::Log4perl     qw/:levels/;
+
+ # by default, ALERTs are output as $FATAL
+ dispatcher Log::Log4perl => 'logger'
+   , to_level => [ ALERT => $ERROR, ]
+   , ...;
+
+=cut
 
 sub reasonToLevel($) { $_[0]->{LRDL_levels}{$_[1]} }
 
diff --git a/lib/Log/Report/Dispatcher/Log4perl.pod b/lib/Log/Report/Dispatcher/Log4perl.pod
deleted file mode 100644
index 2f81475..0000000
--- a/lib/Log/Report/Dispatcher/Log4perl.pod
+++ /dev/null
@@ -1,243 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl back-end
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::Log4perl
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- # start using log4perl via a config file
- # The name of the dispatcher is the name of the default category.
- dispatcher LOG4PERL => 'logger'
-   , accept => 'NOTICE-'
-   , config => "$ENV{HOME}/.log.conf";
-
- # disable default dispatcher
- dispatcher close => 'logger';
-
- # configuration inline, not in file: adapted from the Log4perl manpage
- my $name    = 'logger';
- my $outfile = '/tmp/a.log';
- my $config  = <<__CONFIG;
- log4perl.category.$name            = INFO, Logfile
- log4perl.logger.Logfile          = Log::Log4perl::Appender::File
- log4perl.logger.Logfile.filename = $outfn
- log4perl.logger.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
- log4perl.logger.Logfile.layout.ConversionPattern = %d %F{1} %L> %m
- __CONFIG
-
- dispatcher LOG4PERL => $name, config => \$config;
-
-=head1 DESCRIPTION
-
-This dispatchers produces output tot syslog, based on the C<Sys::Log4perl>
-module (which will not be automatically installed for you).
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head2 Reasons <--> Levels
-
-The REASONs for a message in L<Log::Report|Log::Report> are names quite similar to
-the log levels used by Log::Log4perl.  The default mapping is list
-below.  You can change the mapping using L<new(to_level)|Log::Report::Dispatcher::Log4perl/"Constructors">.
-
-  TRACE   => $DEBUG    ERROR   => $ERROR
-  ASSERT  => $DEBUG    FAULT   => $ERROR
-  INFO    => $INFO     ALERT   => $FATAL
-  NOTICE  => $INFO     FAILURE => $FATAL
-  WARNING => $WARN     PANIC   => $FATAL
-  MISTAKE => $WARN
-
-=head2 Categories
-
-C<Log::Report> uses text-domains for translation tables.  These are
-also used as categories for the Log4perl infrastructure.  So, typically
-every module start with:
-
-   use Log::Report 'my-text-domain', %more_options;
-
-Now, if there is a logger inside the log4perl configuration which is
-named 'my-text-domain', that will be used.  Otherwise, the name of the
-dispatcher is used to select the logger.
-
-=head3 Limitiations
-
-The global C<$caller_depth> concept of Log::Log4perl is broken.
-That variable is used to find the filename and line number of the logged
-messages.  But these messages may have been caught, rerouted, eval'ed, and
-otherwise followed a unpredictable multi-leveled path before it reached
-the Log::Log4perl dispatcher.  This means that layout patterns C<%F>
-and C<%L> are not useful in the generic case, maybe in your specific case.
-
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Inherited, see L<Log::Report::Dispatcher/"Constructors">
-
-=item Log::Report::Dispatcher::Log4perl-E<gt>B<new>($type, $name, %options)
-
-The Log::Log4perl infrastructure has all settings in a configuration
-file.  In that file, you should find a category with the $name.
-
- -Option       --Defined in             --Default
-  accept         Log::Report::Dispatcher  'ALL'
-  charset        Log::Report::Dispatcher  <undef>
-  config                                  <undef>
-  format_reason  Log::Report::Dispatcher  'LOWERCASE'
-  locale         Log::Report::Dispatcher  <system locale>
-  mode           Log::Report::Dispatcher  'NORMAL'
-  to_level                                []
-
-=over 2
-
-=item accept => REASONS
-
-=item charset => CHARSET
-
-=item config => FILENAME|SCALAR
-
-When a SCALAR reference is passed in, that must refer to a string which
-contains the configuration text.  Otherwise, specify an existing FILENAME.
-
-By default, it is expected that Log::Log4perl has been initialized
-externally.  That module uses global variables to communicate, which
-should be present before any logging is attempted.
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item locale => LOCALE
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=item to_level => ARRAY-of-PAIRS
-
-See L<reasonToLevel()|Log::Report::Dispatcher::Log4perl/"Logging">.
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<logger>( [$domain] )
-
-Returns the Log::Log4perl::Logger object which is used for logging.
-When there is no specific logger for this $domain (logger with the exact
-name of the $domain) the default logger is being used, with the name of
-this dispatcher.
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::Log4perl-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::Log4perl-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::Log4perl-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<reasonToLevel>($reason)
-
-Returns a level which is understood by Log::Dispatch, based on
-a translation table.  This can be changed with L<new(to_level)|Log::Report::Dispatcher::Log4perl/"Constructors">.
-
-example: 
-
- use Log::Log4perl     qw/:levels/;
-
- # by default, ALERTs are output as $FATAL
- dispatcher Log::Log4perl => 'logger'
-   , to_level => [ ALERT => $ERROR, ]
-   , ...;
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::Log4perl-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/LogDispatch.pm b/lib/Log/Report/Dispatcher/LogDispatch.pm
index d0b3fb4..d3fb662 100644
--- a/lib/Log/Report/Dispatcher/LogDispatch.pm
+++ b/lib/Log/Report/Dispatcher/LogDispatch.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::LogDispatch;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -37,6 +30,66 @@ my %default_reasonToLevel =
 @reasons != keys %default_reasonToLevel
     and panic __"Not all reasons have a default translation";
 
+=chapter NAME
+Log::Report::Dispatcher::LogDispatch - send messages to Log::Dispatch back-end
+
+=chapter SYNOPSIS
+ use Log::Dispatch::File;
+ dispatcher Log::Dispatch::File => 'logger', accept => 'NOTICE-'
+   , filename => 'logfile', to_level => [ 'ALERT-' => 'err' ];
+
+ # disable default dispatcher
+ dispatcher close => 'logger';
+
+=chapter DESCRIPTION
+This dispatchers produces output to and C<Log::Dispatch> back-end.
+(which will NOT be automatically installed for you).
+
+The REASON for a message often uses names which are quite similar to the
+log-levels used by M<Log::Dispatch>.  However: they have a different
+approach.  The REASON of Log::Report limits the responsibility of the
+programmer to indicate the cause of the message: whether it was able to
+handle a certain situation.  The Log::Dispatch levels are there for the
+user's of the program.  However: the programmer does not known anything
+about the application (in the general case).  This is cause of much of
+the trickery in Perl programs.
+
+The default translation table is list below.  You can change the mapping
+using M<new(to_level)>.  See example in SYNOPSIS.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+The Log::Dispatch infrastructure has quite a large number of output
+TYPEs, each extending the M<Log::Dispatch::Output> base-class.  You
+do not create these objects yourself: Log::Report is doing it for you.
+
+The Log::Dispatch back-ends are very careful with validating their
+parameters, so you will need to restrict the options to what is supported
+for the specific back-end.  See their respective manual-pages.  The errors
+produced by the back-ends quite horrible and untranslated, sorry.
+
+=option  to_level ARRAY-of-PAIRS
+=default to_level []
+See M<reasonToLevel()>.
+
+=option  min_level LEVEL
+=default min_level C<debug>
+Restrict the messages which are passed through based on the LEVEL,
+so after the reason got translated into a Log::Dispatch compatible
+LEVEL.  The default will use Log::Report restrictions only.
+
+=option  max_level LEVEL
+=default max_level C<undef>
+Like C<min_level>.
+
+=option  callbacks CODE|ARRAY-of-CODE
+=default callbacks []
+See M<Log::Dispatch::Output>.
+
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -71,9 +124,16 @@ sub close()
     $self;
 }
 
+=section Accessors
+
+=method backend
+Returns the M<Log::Dispatch::Output> object which is used for logging.
+=cut
 
 sub backend() {shift->{backend}}
 
+=section Logging
+=cut
 
 sub log($$$$$)
 {   my $self  = shift;
@@ -84,6 +144,10 @@ sub log($$$$$)
     $self;
 }
 
+=method reasonToLevel $reason
+Returns a level which is understood by Log::Dispatch, based on
+a translation table.  This can be changed with M<new(to_level)>.
+=cut
 
 sub reasonToLevel($) { $_[0]->{level}{$_[1]} }
 
diff --git a/lib/Log/Report/Dispatcher/LogDispatch.pod b/lib/Log/Report/Dispatcher/LogDispatch.pod
deleted file mode 100644
index 467d3e2..0000000
--- a/lib/Log/Report/Dispatcher/LogDispatch.pod
+++ /dev/null
@@ -1,207 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::LogDispatch - send messages to Log::Dispatch back-end
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::LogDispatch
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- use Log::Dispatch::File;
- dispatcher Log::Dispatch::File => 'logger', accept => 'NOTICE-'
-   , filename => 'logfile', to_level => [ 'ALERT-' => 'err' ];
-
- # disable default dispatcher
- dispatcher close => 'logger';
-
-=head1 DESCRIPTION
-
-This dispatchers produces output to and C<Log::Dispatch> back-end.
-(which will NOT be automatically installed for you).
-
-The REASON for a message often uses names which are quite similar to the
-log-levels used by Log::Dispatch.  However: they have a different
-approach.  The REASON of Log::Report limits the responsibility of the
-programmer to indicate the cause of the message: whether it was able to
-handle a certain situation.  The Log::Dispatch levels are there for the
-user's of the program.  However: the programmer does not known anything
-about the application (in the general case).  This is cause of much of
-the trickery in Perl programs.
-
-The default translation table is list below.  You can change the mapping
-using L<new(to_level)|Log::Report::Dispatcher::LogDispatch/"Constructors">.  See example in SYNOPSIS.
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Inherited, see L<Log::Report::Dispatcher/"Constructors">
-
-=item Log::Report::Dispatcher::LogDispatch-E<gt>B<new>($type, $name, %options)
-
-The Log::Dispatch infrastructure has quite a large number of output
-TYPEs, each extending the Log::Dispatch::Output base-class.  You
-do not create these objects yourself: Log::Report is doing it for you.
-
-The Log::Dispatch back-ends are very careful with validating their
-parameters, so you will need to restrict the options to what is supported
-for the specific back-end.  See their respective manual-pages.  The errors
-produced by the back-ends quite horrible and untranslated, sorry.
-
- -Option       --Defined in             --Default
-  accept         Log::Report::Dispatcher  depend on mode
-  callbacks                               []
-  charset        Log::Report::Dispatcher  <undef>
-  format_reason  Log::Report::Dispatcher  'LOWERCASE'
-  locale         Log::Report::Dispatcher  <system locale>
-  max_level                               undef
-  min_level                               debug
-  mode           Log::Report::Dispatcher  'NORMAL'
-  to_level                                []
-
-=over 2
-
-=item accept => REASONS
-
-=item callbacks => CODE|ARRAY-of-CODE
-
-See Log::Dispatch::Output.
-
-=item charset => CHARSET
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item locale => LOCALE
-
-=item max_level => LEVEL
-
-Like C<min_level>.
-
-=item min_level => LEVEL
-
-Restrict the messages which are passed through based on the LEVEL,
-so after the reason got translated into a Log::Dispatch compatible
-LEVEL.  The default will use Log::Report restrictions only.
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=item to_level => ARRAY-of-PAIRS
-
-See L<reasonToLevel()|Log::Report::Dispatcher::LogDispatch/"Logging">.
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<backend>()
-
-Returns the Log::Dispatch::Output object which is used for logging.
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::LogDispatch-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::LogDispatch-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::LogDispatch-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<reasonToLevel>($reason)
-
-Returns a level which is understood by Log::Dispatch, based on
-a translation table.  This can be changed with L<new(to_level)|Log::Report::Dispatcher::LogDispatch/"Constructors">.
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::LogDispatch-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/Perl.pm b/lib/Log/Report/Dispatcher/Perl.pm
index ac4689a..f4e9810 100644
--- a/lib/Log/Report/Dispatcher/Perl.pm
+++ b/lib/Log/Report/Dispatcher/Perl.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::Perl;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -20,6 +13,33 @@ use IO::File;
 
 my $singleton = 0;   # can be only one (per thread)
 
+=chapter NAME
+Log::Report::Dispatcher::Perl - send messages to die and warn
+
+=chapter SYNOPSIS
+ dispatcher Log::Report::Dispatcher::Perl => 'default'
+   , accept => 'NOTICE-';
+
+ # close the default dispatcher
+ dispatcher close => 'default';
+
+=chapter DESCRIPTION
+Ventilate the problem reports via the standard Perl error mechanisms:
+C<die()>, C<warn()>, and C<print()>.  There can be only one such dispatcher
+(per thread), because once C<die()> is called, we are not able to return.
+Therefore, this dispatcher will always be called last.
+
+In the early releases of Log::Report, it tried to simulate the behavior
+of warn and die using STDERR and exit; however: that is not possible.
+
+=chapter METHODS
+
+=section Constructors
+
+=section Accessors
+
+=section Logging
+=cut
 
 sub log($$$$)
 {   my ($self, $opts, $reason, $message, $domain) = @_;
diff --git a/lib/Log/Report/Dispatcher/Perl.pod b/lib/Log/Report/Dispatcher/Perl.pod
deleted file mode 100644
index cb9f602..0000000
--- a/lib/Log/Report/Dispatcher/Perl.pod
+++ /dev/null
@@ -1,52 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::Perl - send messages to die and warn
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::Perl
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- dispatcher Log::Report::Dispatcher::Perl => 'default'
-   , accept => 'NOTICE-';
-
- # close the default dispatcher
- dispatcher close => 'default';
-
-=head1 DESCRIPTION
-
-Ventilate the problem reports via the standard Perl error mechanisms:
-C<die()>, C<warn()>, and C<print()>.  There can be only one such dispatcher
-(per thread), because once C<die()> is called, we are not able to return.
-Therefore, this dispatcher will always be called last.
-
-In the early releases of Log::Report, it tried to simulate the behavior
-of warn and die using STDERR and exit; however: that is not possible.
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/Syslog.pm b/lib/Log/Report/Dispatcher/Syslog.pm
index fe537b2..045827b 100644
--- a/lib/Log/Report/Dispatcher/Syslog.pm
+++ b/lib/Log/Report/Dispatcher/Syslog.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::Syslog;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -40,6 +33,96 @@ my %default_reasonToPrio =
 @reasons==keys %default_reasonToPrio
     or panic __"not all reasons have a default translation";
 
+=chapter NAME
+Log::Report::Dispatcher::Syslog - send messages to syslog
+
+=chapter SYNOPSIS
+ # add syslog dispatcher
+ dispatcher SYSLOG => 'syslog', accept => 'NOTICE-'
+   , format_reason => 'IGNORE'
+   , to_prio => [ 'ALERT-' => 'err' ];
+
+ # disable default dispatcher, when daemon
+ dispatcher close => 'default';
+
+=chapter DESCRIPTION
+This dispatchers produces output to syslog, based on the M<Sys::Syslog>
+module (which will NOT be automatically installed for you, because some
+systems have a problem with this dependency).
+
+The REASON for a message often uses names which are quite similar to
+the log-levels used by syslog.  However: they have a different purpose.
+The REASON is used by the programmer to indicate the cause of the message:
+whether it was able to handle a certain situation.  The syslog levels
+are there for the user's of the program (with syslog usually the
+system administrators).  It is not unusual to see a "normal" error
+or mistake as a very serious situation in a production environment. So,
+you may wish to translate any message above reason MISTAKE into a LOG_CRIT.
+
+The default translation table is list below.  You can change the mapping
+using M<new(to_prio)>.  See example in SYNOPSIS.
+
+  TRACE   => LOG_DEBUG    ERROR   => LOG_ERR
+  ASSERT  => LOG_DEBUG    FAULT   => LOG_ERR
+  INFO    => LOG_INFO     ALERT   => LOG_ALERT
+  NOTICE  => LOG_NOTICE   FAILURE => LOG_EMERG
+  WARNING => LOG_WARNING  PANIC   => LOG_CRIT
+  MISTAKE => LOG_WARNING
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+With syslog, people tend not to include the REASON of the message
+in the logs, because that is already used to determine the destination
+of the message.
+
+=default format_reason 'IGNORE'
+
+=option  identity STRING
+=default identity <basename $0>
+
+=option  flags STRING
+=default flags 'pid,nowait'
+Any combination of flags as defined by M<Sys::Syslog>, for instance
+C<pid>, C<ndelay>, and C<nowait>.
+
+=option  facility STRING
+=default facility 'user'
+The possible values for this depend (a little) on the system.  POSIX
+only defines C<user>, and C<local0> up to C<local7>.
+
+=option  to_prio ARRAY-of-PAIRS
+=default to_prio []
+See M<reasonToPrio()>.
+
+=option  logsocket 'unix'|'inet'|'stream'|HASH
+=default logsocket C<undef>
+If specified, the log socket type will be initialized to this before
+C<openlog()> is called.  If not specified, the system default is used.
+
+=option  include_domain BOOLEAN
+=default include_domain <false>
+[1.00] Include the text-domain of the message in each logged message.
+
+=option  charset CHARSET
+=default charset 'utf8'
+Translate the text-strings into the specified charset, otherwise the
+sysadmin may get unreadable text.
+
+=option  format CODE
+=default format <unchanged>
+[1.10] With a CODE reference you get your hands on the text before
+it gets sent to syslog.  The three parameters are: the (translated) text,
+the related text domain object, and the message object.  You may want to
+use context information from the latter.
+
+[1.19] After the three positional parameters, there may be a list of
+pairs (named parameters) with additional info.  This may contain a
+C<location> with an ARRAY of information produced by caller() about the
+origin of the exception.
+=cut
 
 my $active;
 
@@ -93,6 +176,11 @@ sub close()
 }
 
 #--------------
+=section Accessors
+
+=method format [CODE]
+Returns the CODE ref which formats the syslog line.
+=cut
 
 sub format(;$)
 {   my $self = shift;
@@ -100,6 +188,8 @@ sub format(;$)
 }
 
 #--------------
+=section Logging
+=cut
 
 sub log($$$$$)
 {   my ($self, $opts, $reason, $msg, $domain) = @_;
@@ -122,6 +212,10 @@ sub log($$$$$)
         for @text;
 }
 
+=method reasonToPrio $reason
+Returns a level which is understood by syslog(3), based on a translation
+table.  This can be changed with M<new(to_prio)>.
+=cut
 
 sub reasonToPrio($) { $_[0]->{prio}{$_[1]} }
 
diff --git a/lib/Log/Report/Dispatcher/Syslog.pod b/lib/Log/Report/Dispatcher/Syslog.pod
deleted file mode 100644
index dcb1122..0000000
--- a/lib/Log/Report/Dispatcher/Syslog.pod
+++ /dev/null
@@ -1,236 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::Syslog - send messages to syslog
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::Syslog
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- # add syslog dispatcher
- dispatcher SYSLOG => 'syslog', accept => 'NOTICE-'
-   , format_reason => 'IGNORE'
-   , to_prio => [ 'ALERT-' => 'err' ];
-
- # disable default dispatcher, when daemon
- dispatcher close => 'default';
-
-=head1 DESCRIPTION
-
-This dispatchers produces output to syslog, based on the Sys::Syslog
-module (which will NOT be automatically installed for you, because some
-systems have a problem with this dependency).
-
-The REASON for a message often uses names which are quite similar to
-the log-levels used by syslog.  However: they have a different purpose.
-The REASON is used by the programmer to indicate the cause of the message:
-whether it was able to handle a certain situation.  The syslog levels
-are there for the user's of the program (with syslog usually the
-system administrators).  It is not unusual to see a "normal" error
-or mistake as a very serious situation in a production environment. So,
-you may wish to translate any message above reason MISTAKE into a LOG_CRIT.
-
-The default translation table is list below.  You can change the mapping
-using L<new(to_prio)|Log::Report::Dispatcher::Syslog/"Constructors">.  See example in SYNOPSIS.
-
-  TRACE   => LOG_DEBUG    ERROR   => LOG_ERR
-  ASSERT  => LOG_DEBUG    FAULT   => LOG_ERR
-  INFO    => LOG_INFO     ALERT   => LOG_ALERT
-  NOTICE  => LOG_NOTICE   FAILURE => LOG_EMERG
-  WARNING => LOG_WARNING  PANIC   => LOG_CRIT
-  MISTAKE => LOG_WARNING
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Inherited, see L<Log::Report::Dispatcher/"Constructors">
-
-=item Log::Report::Dispatcher::Syslog-E<gt>B<new>($type, $name, %options)
-
-With syslog, people tend not to include the REASON of the message
-in the logs, because that is already used to determine the destination
-of the message.
-
- -Option        --Defined in             --Default
-  accept          Log::Report::Dispatcher  depend on mode
-  charset                                  'utf8'
-  facility                                 'user'
-  flags                                    'pid,nowait'
-  format                                   <unchanged>
-  format_reason   Log::Report::Dispatcher  'IGNORE'
-  identity                                 <basename $0>
-  include_domain                           <false>
-  locale          Log::Report::Dispatcher  <system locale>
-  logsocket                                undef
-  mode            Log::Report::Dispatcher  'NORMAL'
-  to_prio                                  []
-
-=over 2
-
-=item accept => REASONS
-
-=item charset => CHARSET
-
-Translate the text-strings into the specified charset, otherwise the
-sysadmin may get unreadable text.
-
-=item facility => STRING
-
-The possible values for this depend (a little) on the system.  POSIX
-only defines C<user>, and C<local0> up to C<local7>.
-
-=item flags => STRING
-
-Any combination of flags as defined by Sys::Syslog, for instance
-C<pid>, C<ndelay>, and C<nowait>.
-
-=item format => CODE
-
-[1.10] With a CODE reference you get your hands on the text before
-it gets sent to syslog.  The three parameters are: the (translated) text,
-the related text domain object, and the message object.  You may want to
-use context information from the latter.
-
-[1.19] After the three positional parameters, there may be a list of
-pairs (named parameters) with additional info.  This may contain a
-C<location> with an ARRAY of information produced by caller() about the
-origin of the exception.
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item identity => STRING
-
-=item include_domain => BOOLEAN
-
-[1.00] Include the text-domain of the message in each logged message.
-
-=item locale => LOCALE
-
-=item logsocket => 'unix'|'inet'|'stream'|HASH
-
-If specified, the log socket type will be initialized to this before
-C<openlog()> is called.  If not specified, the system default is used.
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=item to_prio => ARRAY-of-PAIRS
-
-See L<reasonToPrio()|Log::Report::Dispatcher::Syslog/"Logging">.
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<format>( [CODE] )
-
-Returns the CODE ref which formats the syslog line.
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::Syslog-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::Syslog-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::Syslog-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<reasonToPrio>($reason)
-
-Returns a level which is understood by syslog(3), based on a translation
-table.  This can be changed with L<new(to_prio)|Log::Report::Dispatcher::Syslog/"Constructors">.
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::Syslog-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Dispatcher/Try.pm b/lib/Log/Report/Dispatcher/Try.pm
index ba87779..47f16d5 100644
--- a/lib/Log/Report/Dispatcher/Try.pm
+++ b/lib/Log/Report/Dispatcher/Try.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Dispatcher::Try;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Dispatcher';
 
 use warnings;
@@ -20,6 +13,68 @@ use Log::Report::Exception ();
 use Log::Report::Util      qw/%reason_code/;
 use List::Util             qw/first/;
 
+=chapter NAME
+Log::Report::Dispatcher::Try - capture all reports as exceptions
+
+=chapter SYNOPSIS
+ try { ... };       # mind the ';' !!
+ if($@) {           # signals something went wrong
+
+ if(try {...}) {    # block ended normally
+
+ my $x = try { read_temperature() };
+ my @x = try { read_lines_from_file() };
+
+ try { ... }        # no comma!!
+    mode => 'DEBUG', accept => 'ERROR-';
+
+ try sub { ... },   # with comma
+    mode => 'DEBUG', accept => 'ALL';
+
+ try \&myhandler, accept => 'ERROR-';
+ try { ... } hide => 'TRACE';
+
+ print ref $@;      # Log::Report::Dispatcher::Try
+
+ $@->reportFatal;   # re-dispatch result of try block
+ $@->reportAll;     # ... also warnings etc
+ if($@) {...}       # if errors
+ if($@->failed) {   # same       # }
+ if($@->success) {  # no errors  # }
+
+ try { # something causes an error report, which is caught
+       failure 'no network';
+     };
+ $@->reportFatal(to => 'syslog');  # overrule destination
+
+ print $@->exceptions; # no re-cast, just print
+
+=chapter DESCRIPTION
+The M<Log::Report::try()> catches errors in the block (CODE
+reference) which is just following the function name.  All
+dispatchers are temporarily disabled by C<try>, and messages
+which are reported are collected within a temporary dispatcher
+named C<try>.  When the CODE has run, that C<try> dispatcher
+is returned in C<$@>, and all original dispatchers reinstated.
+
+Then, after the C<try> has finished, the routine which used
+the "try" should decide what to do with the collected reports.
+These reports are collected as M<Log::Report::Exception> objects.
+They can be ignored, or thrown to a higher level try... causing
+an exit of the program if there is none.
+
+=chapter OVERLOADING
+
+=overload boolean
+Returns true if the previous try block did produce a terminal
+error.  This "try" object is assigned to C<$@>, and the usual
+perl syntax is C<if($@) {...error-handler...}>.
+
+=overload stringify
+When C<$@> is used the traditional way, it is checked to have
+a string content.  In this case, stringify into the fatal error
+or nothing.
+=cut
 
 use overload
     bool     => 'failed'
@@ -27,6 +82,31 @@ use overload
   , fallback => 1;
 
 #-----------------
+=chapter METHODS
+
+=section Constructors
+
+=c_method new $type, $name, %options
+=option  exceptions ARRAY
+=default exceptions []
+ARRAY of M<Log::Report::Exception> objects.
+
+=option  died STRING
+=default died C<undef>
+The exit string ($@) of the eval'ed block.
+
+=option  hide REASON|ARRAY|'ALL'|'NONE'
+=default hide 'NONE'
+[1.09] see M<hide()>
+
+=option  on_die 'ERROR'|'PANIC'
+=default on_die 'ERROR'
+When code which runs in this block exits with a die(), it will get
+translated into a M<Log::Report::Exception> using
+M<Log::Report::Die::die_decode()>.  How serious are we about these
+errors?
+
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -39,21 +119,49 @@ sub init($)
 }
 
 #-----------------
+=section Accessors
+
+=method died [STRING]
+The message which was reported by C<eval>, which is used internally
+to catch problems in the try block.
+=cut
 
 sub died(;$)
 {   my $self = shift;
     @_ ? ($self->{died} = shift) : $self->{died};
 }
 
+=method exceptions
+Returns all collected C<Log::Report::Exceptions>.  The last of
+them may be a fatal one.  The other are non-fatal.
+=cut
 
 sub exceptions() { @{shift->{exceptions}} }
 
+=method hides REASON
+=cut
 
 sub hides($)
 {   my $h = shift->{hides} or return 0;
     keys %$h ? $h->{(shift)} : 1;
 }
 
+=method hide REASON|REASONS|ARRAY|'ALL'|'NONE'
+[1.09] By default, the try will only catch messages which stop the
+execution of the block (errors etc, internally a 'die').  Other messages
+are passed to parent try blocks, if none than to the dispatchers.
+
+This option gives the opportunity to block, for instance, trace messages.
+Those messages are still collected inside the try object, so may get
+passed-on later via M<reportAll()> if you like.
+
+Be warned: Using this method will reset the whole 'hide' configuration:
+it's a I<set> not an I<add>.
+
+=example change the setting of the running block
+  my $parent_try = dispatcher 'active-try';
+  parent_try->hide('NONE');
+=cut
 
 sub hide(@)
 {   my $self = shift;
@@ -66,10 +174,23 @@ sub hide(@)
       :    +{ map +($_ => 1), @h };
 }
 
+=method die2reason
+Returns the value of M<new(on_die)>.
+=cut
 
 sub die2reason() { shift->{on_die} }
 
 #-----------------
+=section Logging
+
+=method log $opts, $reason, $message
+Other dispatchers translate the message here, and make it leave the
+program.  However, messages in a "try" block are only captured in
+an intermediate layer: they may never be presented to an end-users.
+And for sure, we do not know the language yet.
+
+The $message is either a STRING or a M<Log::Report::Message>.
+=cut
 
 sub log($$$$)
 {   my ($self, $opts, $reason, $message, $domain) = @_;
@@ -98,16 +219,46 @@ sub log($$$$)
     $self;
 }
 
+=method reportAll %options
+Re-cast the messages in all collect exceptions into the defined
+dispatchers, which were disabled during the try block. The %options
+will end-up as HASH of %options to M<Log::Report::report()>; see
+M<Log::Report::Exception::throw()> which does the job.
+
+=method reportFatal
+Re-cast only the fatal message to the defined dispatchers.  If the
+block was left without problems, then nothing will be done.  The %options
+will end-up as HASH of %options to M<Log::Report::report()>; see
+M<Log::Report::Exception::throw()> which does the job.
+=cut
 
 sub reportFatal(@) { $_->throw(@_) for shift->wasFatal   }
 sub reportAll(@)   { $_->throw(@_) for shift->exceptions }
 
 #-----------------
+=section Status
+
+=method failed
+Returns true if the block was left with an fatal message.
+
+=method success
+Returns true if the block exited normally.
+=cut
 
 sub failed()  {   defined shift->{died}}
 sub success() { ! defined shift->{died}}
 
 
+=method wasFatal %options
+Returns the M<Log::Report::Exception> which caused the "try" block to
+die, otherwise an empty LIST (undef).
+
+=option  class CLASS|REGEX
+=default class C<undef>
+Only return the exception if it was fatal, and in the same time in
+the specified CLASS (as string) or matches the REGEX.
+See M<Log::Report::Message::inClass()>
+=cut
 
 sub wasFatal(@)
 {   my ($self, %args) = @_;
@@ -120,6 +271,14 @@ sub wasFatal(@)
     (!$args{class} || $ex->inClass($args{class})) ? $ex : ();
 }
 
+=method showStatus
+If this object is kept in C<$@>, and someone uses this as string, we
+want to show the fatal error message.
+
+The message is not very informative for the good cause: we do not want
+people to simply print the C<$@>, but wish for a re-cast of the message
+using M<reportAll()> or M<reportFatal()>.
+=cut
 
 sub showStatus()
 {   my $self  = shift;
diff --git a/lib/Log/Report/Dispatcher/Try.pod b/lib/Log/Report/Dispatcher/Try.pod
deleted file mode 100644
index a5271c6..0000000
--- a/lib/Log/Report/Dispatcher/Try.pod
+++ /dev/null
@@ -1,325 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Dispatcher::Try - capture all reports as exceptions
-
-=head1 INHERITANCE
-
- Log::Report::Dispatcher::Try
-   is a Log::Report::Dispatcher
-
-=head1 SYNOPSIS
-
- try { ... };       # mind the ';' !!
- if($@) {           # signals something went wrong
-
- if(try {...}) {    # block ended normally
-
- my $x = try { read_temperature() };
- my @x = try { read_lines_from_file() };
-
- try { ... }        # no comma!!
-    mode => 'DEBUG', accept => 'ERROR-';
-
- try sub { ... },   # with comma
-    mode => 'DEBUG', accept => 'ALL';
-
- try \&myhandler, accept => 'ERROR-';
- try { ... } hide => 'TRACE';
-
- print ref $@;      # Log::Report::Dispatcher::Try
-
- $@->reportFatal;   # re-dispatch result of try block
- $@->reportAll;     # ... also warnings etc
- if($@) {...}       # if errors
- if($@->failed) {   # same       # }
- if($@->success) {  # no errors  # }
-
- try { # something causes an error report, which is caught
-       failure 'no network';
-     };
- $@->reportFatal(to => 'syslog');  # overrule destination
-
- print $@->exceptions; # no re-cast, just print
-
-=head1 DESCRIPTION
-
-The L<Log::Report::try()|Log::Report/"Report Production and Configuration"> catches errors in the block (CODE
-reference) which is just following the function name.  All
-dispatchers are temporarily disabled by C<try>, and messages
-which are reported are collected within a temporary dispatcher
-named C<try>.  When the CODE has run, that C<try> dispatcher
-is returned in C<$@>, and all original dispatchers reinstated.
-
-Then, after the C<try> has finished, the routine which used
-the "try" should decide what to do with the collected reports.
-These reports are collected as L<Log::Report::Exception|Log::Report::Exception> objects.
-They can be ignored, or thrown to a higher level try... causing
-an exit of the program if there is none.
-
-Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
- 
-=over 4
-
-=item $obj-E<gt>B<close>()
-
-Inherited, see L<Log::Report::Dispatcher/"Constructors">
-
-=item Log::Report::Dispatcher::Try-E<gt>B<new>($type, $name, %options)
-
- -Option       --Defined in             --Default
-  accept         Log::Report::Dispatcher  depend on mode
-  charset        Log::Report::Dispatcher  <undef>
-  died                                    undef
-  exceptions                              []
-  format_reason  Log::Report::Dispatcher  'LOWERCASE'
-  hide                                    'NONE'
-  locale         Log::Report::Dispatcher  <system locale>
-  mode           Log::Report::Dispatcher  'NORMAL'
-  on_die                                  'ERROR'
-
-=over 2
-
-=item accept => REASONS
-
-=item charset => CHARSET
-
-=item died => STRING
-
-The exit string ($@) of the eval'ed block.
-
-=item exceptions => ARRAY
-
-ARRAY of L<Log::Report::Exception|Log::Report::Exception> objects.
-
-=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
-
-=item hide => REASON|ARRAY|'ALL'|'NONE'
-
-[1.09] see L<hide()|Log::Report::Dispatcher::Try/"Accessors">
-
-=item locale => LOCALE
-
-=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
-
-=item on_die => 'ERROR'|'PANIC'
-
-When code which runs in this block exits with a die(), it will get
-translated into a L<Log::Report::Exception|Log::Report::Exception> using
-L<Log::Report::Die::die_decode()|Log::Report::Die/"FUNCTIONS">.  How serious are we about these
-errors?
-
-=back
-
-=back
-
-=head2 Accessors
-
-Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
- 
-=over 4
-
-=item $obj-E<gt>B<die2reason>()
-
-Returns the value of L<new(on_die)|Log::Report::Dispatcher::Try/"Constructors">.
-
-=item $obj-E<gt>B<died>( [STRING] )
-
-The message which was reported by C<eval>, which is used internally
-to catch problems in the try block.
-
-=item $obj-E<gt>B<exceptions>()
-
-Returns all collected C<Log::Report::Exceptions>.  The last of
-them may be a fatal one.  The other are non-fatal.
-
-=item $obj-E<gt>B<hide>(REASON|REASONS|ARRAY|'ALL'|'NONE')
-
-[1.09] By default, the try will only catch messages which stop the
-execution of the block (errors etc, internally a 'die').  Other messages
-are passed to parent try blocks, if none than to the dispatchers.
-
-This option gives the opportunity to block, for instance, trace messages.
-Those messages are still collected inside the try object, so may get
-passed-on later via L<reportAll()|Log::Report::Dispatcher::Try/"Logging"> if you like.
-
-Be warned: Using this method will reset the whole 'hide' configuration:
-it's a I<set> not an I<add>.
-
-example: change the setting of the running block
-
-  my $parent_try = dispatcher 'active-try';
-  parent_try->hide('NONE');
-
-=item $obj-E<gt>B<hides>(REASON)
-
-=item $obj-E<gt>B<isDisabled>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<mode>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<needs>( [$reason] )
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=item $obj-E<gt>B<type>()
-
-Inherited, see L<Log::Report::Dispatcher/"Accessors">
-
-=back
-
-=head2 Logging
-
-Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
- 
-=over 4
-
-=item $obj-E<gt>B<addSkipStack>(@CODE)
-
-=item Log::Report::Dispatcher::Try-E<gt>B<addSkipStack>(@CODE)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectLocation>()
-
-=item Log::Report::Dispatcher::Try-E<gt>B<collectLocation>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<collectStack>( [$maxdepth] )
-
-=item Log::Report::Dispatcher::Try-E<gt>B<collectStack>( [$maxdepth] )
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<log>($opts, $reason, $message)
-
-Other dispatchers translate the message here, and make it leave the
-program.  However, messages in a "try" block are only captured in
-an intermediate layer: they may never be presented to an end-users.
-And for sure, we do not know the language yet.
-
-The $message is either a STRING or a L<Log::Report::Message|Log::Report::Message>.
-
-=item $obj-E<gt>B<reportAll>(%options)
-
-Re-cast the messages in all collect exceptions into the defined
-dispatchers, which were disabled during the try block. The %options
-will end-up as HASH of %options to L<Log::Report::report()|Log::Report/"Report Production and Configuration">; see
-L<Log::Report::Exception::throw()|Log::Report::Exception/"Processing"> which does the job.
-
-=item $obj-E<gt>B<reportFatal>()
-
-Re-cast only the fatal message to the defined dispatchers.  If the
-block was left without problems, then nothing will be done.  The %options
-will end-up as HASH of %options to L<Log::Report::report()|Log::Report/"Report Production and Configuration">; see
-L<Log::Report::Exception::throw()|Log::Report::Exception/"Processing"> which does the job.
-
-=item $obj-E<gt>B<skipStack>()
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<stackTraceLine>(%options)
-
-=item Log::Report::Dispatcher::Try-E<gt>B<stackTraceLine>(%options)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
-
-Inherited, see L<Log::Report::Dispatcher/"Logging">
-
-=back
-
-=head2 Status
-
-=over 4
-
-=item $obj-E<gt>B<failed>()
-
-Returns true if the block was left with an fatal message.
-
-=item $obj-E<gt>B<showStatus>()
-
-If this object is kept in C<$@>, and someone uses this as string, we
-want to show the fatal error message.
-
-The message is not very informative for the good cause: we do not want
-people to simply print the C<$@>, but wish for a re-cast of the message
-using L<reportAll()|Log::Report::Dispatcher::Try/"Logging"> or L<reportFatal()|Log::Report::Dispatcher::Try/"Logging">.
-
-=item $obj-E<gt>B<success>()
-
-Returns true if the block exited normally.
-
-=item $obj-E<gt>B<wasFatal>(%options)
-
-Returns the L<Log::Report::Exception|Log::Report::Exception> which caused the "try" block to
-die, otherwise an empty LIST (undef).
-
- -Option--Default
-  class   undef
-
-=over 2
-
-=item class => CLASS|REGEX
-
-Only return the exception if it was fatal, and in the same time in
-the specified CLASS (as string) or matches the REGEX.
-See L<Log::Report::Message::inClass()|Log::Report::Message/"Processing">
-
-=back
-
-=back
-
-=head1 DETAILS
-
-Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
- 
-=head1 OVERLOADING
-
-=over 4
-
-=item overload: B<boolean>
-
-Returns true if the previous try block did produce a terminal
-error.  This "try" object is assigned to C<$@>, and the usual
-perl syntax is C<if($@) {...error-handler...}>.
-
-=item overload: B<stringify>
-
-When C<$@> is used the traditional way, it is checked to have
-a string content.  In this case, stringify into the fatal error
-or nothing.
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Domain.pm b/lib/Log/Report/Domain.pm
index 43d8885..f295363 100644
--- a/lib/Log/Report/Domain.pm
+++ b/lib/Log/Report/Domain.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Domain;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use base 'Log::Report::Minimal::Domain';
 
 use warnings;
@@ -21,6 +14,63 @@ use Scalar::Util       qw/blessed/;
 
 use Log::Report::Translator;
 
+=chapter NAME
+Log::Report::Domain - administer one text-domain
+
+=chapter SYNOPSIS
+
+ # internal usage
+ use Log::Report::Domain;
+ my $domain = Log::Report::Domain->new(name => $name);
+
+ # find a ::Domain object
+ use Log::Report 'my-domain';
+ my $domain = textdomain 'my-domain'; # find domain config
+ my $domain = textdomain;             # config of this package
+
+ # explicit domain configuration
+ package My::Package;
+ use Log::Report 'my-domain';         # set textdomain for package
+
+ textdomain $name, %configure;        # set config, once per program
+ (textdomain $name)->configure(%configure); # same
+ textdomain->configure(%configure);   # same if current package in $name
+
+ # implicit domain configuration
+ package My::Package;
+ use Log::Report 'my-domain', %configure;
+ 
+ # external file for configuration (perl or json format)
+ use Log::Report 'my-domain', config => $filename;
+
+ use Log::Report 'my-domain';
+ textdomain->configure(config => $filename);
+
+=chapter DESCRIPTION 
+
+L<Log::Report> can handle multiple sets of packages at the same
+time: in the usual case a program consists of more than one software
+distribution, each containing a number of packages.  Each module
+in an application belongs to one of these sets, by default the domain set
+'default'.
+
+For C<Log::Report>, those packags sets are differentiated via the
+text-domain value in the C<use> statement:
+
+  use Log::Report 'my-domain';
+
+There are many things you can configure per (text)domain.  This is not
+only related to translations, but also -for instance- for text formatting
+configuration.  The administration for the configuration is managed in
+this package.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new %options
+Create a new Domain object.
+=cut
 
 sub init($)
 {   my ($self, $args) = @_;
@@ -30,12 +80,55 @@ sub init($)
 }
 
 #----------------
+=section Attributes
+=method nativeLanguage
+=method translator
+=method contextRules
+=cut
 
 sub nativeLanguage() {shift->{LRD_native}}
 sub translator()     {shift->{LRD_transl}}
 sub contextRules()   {shift->{LRD_ctxt_rules}}
 
 #----------------
+=method configure %options
+The import is automatically called when the package is compiled.  For all
+but one packages in your distribution, it will only contain the name of
+the DOMAIN.  For one package, it will contain configuration information.
+These %options are used for all packages which use the same DOMAIN.
+See chapter L</Configuring> below.
+
+=option  formatter CODE|HASH|'PRINTI'
+=default formatter C<PRINTI>
+Selects the formatter used for the errors messages.  The default is C<PRINTI>,
+which will use M<String::Print::printi()>: interpolation with curly
+braces around the variable names.
+
+=option  translator M<Log::Report::Translator>|HASH
+=default translator C<created internally>
+Set the object which will do the translations for this domain.
+
+=option  native_language CODESET 
+=default native_language 'en_US'
+This is the language which you have used to write the translatable and
+the non-translatable messages in.  In case no translation is needed,
+you still wish the system error messages to be in the same language
+as the report.  Of course, each textdomain can define its own.
+
+=option  context_rules HASH|OBJECT
+=default context_rules C<undef>
+When rules are provided, the translator will use the C<msgctxt> fields
+as provided by PO-files (gettext).  This parameter is used to initialize
+a M<Log::Report::Translator::Context> helper object.
+
+=option  config FILENAME
+=default config C<undef>
+Read the settings from the file.  The parameters found in the file are
+used as default for the parameters above.  This parameter is especially
+useful for the C<context_rules>, which need to be shared between the
+running application and F<xgettext-perl>.  See M<readConfig()>
+
+=cut
 
 sub configure(%)
 {   my ($self, %args) = @_;
@@ -99,6 +192,17 @@ sub _reportMissingKey($$)
     undef;
 }
 
+=method setContext STRING|HASH|ARRAY|PAIRS
+Temporary set the default translation context for messages.  This is used
+when the message is created without a C<_context> parameter. The context
+can be retrieved with M<defaultContext()>.
+
+Contexts are totally ignored then there are no C<context_rules>.  When
+you do not wish to change settings, you may simply provide a HASH.
+
+=example
+   use Log::Report 'my-domain', context_rules => {};
+=cut
 
 sub setContext(@)
 {   my $self = shift;
@@ -108,6 +212,9 @@ sub setContext(@)
     $self->{LRD_ctxt_def} = $cr->needDecode(set => @_);
 }
 
+=method updateContext STRING|HASH|ARRAY|PAIRS
+[1.10] Make changes and additions to the active context (see M<setContext()>).
+=cut
 
 sub updateContext(@)
 {   my $self = shift;
@@ -120,9 +227,25 @@ sub updateContext(@)
     $r;
 }
 
+=method defaultContext
+Returns the current default translation context settings as HASH.  You should
+not modify the content of that HASH: change it by called M<setContext()> or
+M<updateContext()>.
+=cut
 
 sub defaultContext() { shift->{LRD_ctxt_def} }
 
+=ci_method readConfig $filename
+Helper method, which simply parses the content $filename into a HASH to be
+used as parameters to M<configure()>. The filename must end on '.pl',
+to indicate that it uses perl syntax (can be processed with Perl's C<do>
+command) or end on '.json'.  See also chapter L</Configuring> below.
+
+Currently, this file can be in Perl native format (when ending on C<.pl>)
+or JSON (when it ends with C<.json>).  Various modules may explain parts
+of what can be found in these files, for instance
+M<Log::Report::Translator::Context>.
+=cut
 
 sub readConfig($)
 {   my ($self, $fn) = @_;
@@ -147,6 +270,11 @@ sub readConfig($)
 }
 
 #-------------------
+=section Action
+
+=method translate $message, $language
+Translate the $message into the $language.
+=cut
 
 sub translate($$)
 {   my ($self, $msg, $lang) = @_;
@@ -180,3 +308,73 @@ sub translate($$)
 1;
 
 __END__
+=chapter DETAILS
+
+=section Configuring
+
+Configuration of a domain can happen in many ways: either explicitly or
+implicitly.  The explicit form:
+
+   package My::Package;
+   use Log::Report 'my-domain';
+
+   textdomain 'my-domain', %configuration;
+   textdomain->configure(%configuration);
+   textdomain->configure(\%configuration);
+
+   textdomain->configure(conf => $filename);
+
+The implicit form is (no variables possible, only constants!)
+
+   package My::Package;
+   use Log::Report 'my-domain', %configuration;
+   use Log::Report 'my-domain', conf => '/filename';
+
+You can only configure your domain in one place in your program.  The
+textdomain setup is then used for all packages in the same domain.
+
+This also works for M<Log::Report::Optional>, which is a dressed-down
+version of M<Log::Report>.
+
+=subsection configuring your own formatter
+
+[0.91] The C<PRINTI> is a special constants for M<configure(formatter)>, and
+will use M<String::Print> function C<printi()>, with the standard tricks.
+
+  textdomain 'some-domain'
+    formatter =>
+      { class     => 'String::Print'    # default
+      , method    => 'sprinti'          # default
+      , %options    # constructor options for the class
+      );
+
+When you want your own formatter, or configuration of C<String::Print>,
+you need to pass a CODE.  Be aware that you may loose magic added by
+M<Log::Report> and other layers, like M<Log::Report::Template>:
+
+  textdomain 'some-domain'
+    , formatter => \&my_formatter;
+
+=subsection configuring global values
+
+Say, you log for a (Dancer) webserver, where you wish to include the website
+name in some of the log lines.  For this, (ab)use the translation context:
+
+  ### first enabled translation contexts
+  use Log::Report 'my-domain', context_rules => {};
+  # or
+  use Log::Report 'my-domain';
+  textdomain->configure(context_rules => {});
+  # or
+  textdomain 'my-domain'
+    , content_rules => {};
+  
+  ### every time you start working for a different virtual host
+  (textdomain 'my-domain')->setContext(host => $host);
+
+  ### now you can use that in your code
+  package My::Package;
+  use Log::Report 'my-domain';
+  error __x"in {_context.host} not logged-in {user}", user => $username;
+
+=cut
diff --git a/lib/Log/Report/Domain.pod b/lib/Log/Report/Domain.pod
deleted file mode 100644
index ac8da36..0000000
--- a/lib/Log/Report/Domain.pod
+++ /dev/null
@@ -1,297 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Domain - administer one text-domain
-
-=head1 INHERITANCE
-
- Log::Report::Domain
-   is a Log::Report::Minimal::Domain
-
- Log::Report::Domain is extended by
-   Log::Report::Template::Textdomain
-
-=head1 SYNOPSIS
-
- # internal usage
- use Log::Report::Domain;
- my $domain = Log::Report::Domain->new(name => $name);
-
- # find a ::Domain object
- use Log::Report 'my-domain';
- my $domain = textdomain 'my-domain'; # find domain config
- my $domain = textdomain;             # config of this package
-
- # explicit domain configuration
- package My::Package;
- use Log::Report 'my-domain';         # set textdomain for package
-
- textdomain $name, %configure;        # set config, once per program
- (textdomain $name)->configure(%configure); # same
- textdomain->configure(%configure);   # same if current package in $name
-
- # implicit domain configuration
- package My::Package;
- use Log::Report 'my-domain', %configure;
- 
- # external file for configuration (perl or json format)
- use Log::Report 'my-domain', config => $filename;
-
- use Log::Report 'my-domain';
- textdomain->configure(config => $filename);
-
-=head1 DESCRIPTION
-
-L<Log::Report> can handle multiple sets of packages at the same
-time: in the usual case a program consists of more than one software
-distribution, each containing a number of packages.  Each module
-in an application belongs to one of these sets, by default the domain set
-'default'.
-
-For C<Log::Report>, those packags sets are differentiated via the
-text-domain value in the C<use> statement:
-
-  use Log::Report 'my-domain';
-
-There are many things you can configure per (text)domain.  This is not
-only related to translations, but also -for instance- for text formatting
-configuration.  The administration for the configuration is managed in
-this package.
-
-Extends L<"DESCRIPTION" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"DESCRIPTION">.
- 
-=head1 METHODS
-
-Extends L<"METHODS" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"METHODS">.
- 
-=head2 Constructors
-
-Extends L<"Constructors" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Constructors">.
- 
-=over 4
-
-=item Log::Report::Domain-E<gt>B<new>(%options)
-
-Create a new Domain object.
-
- -Option--Defined in                  --Default
-  name    Log::Report::Minimal::Domain  <required>
-
-=over 2
-
-=item name => STRING
-
-=back
-
-=back
-
-=head2 Attributes
-
-Extends L<"Attributes" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Attributes">.
- 
-=over 4
-
-=item $obj-E<gt>B<configure>(%options)
-
-The import is automatically called when the package is compiled.  For all
-but one packages in your distribution, it will only contain the name of
-the DOMAIN.  For one package, it will contain configuration information.
-These %options are used for all packages which use the same DOMAIN.
-See chapter L</Configuring> below.
-
- -Option         --Defined in                  --Default
-  config                                         undef
-  context_rules                                  undef
-  formatter                                      PRINTI
-  native_language                                'en_US'
-  translator                                     created internally
-  where            Log::Report::Minimal::Domain  <required>
-
-=over 2
-
-=item config => FILENAME
-
-Read the settings from the file.  The parameters found in the file are
-used as default for the parameters above.  This parameter is especially
-useful for the C<context_rules>, which need to be shared between the
-running application and F<xgettext-perl>.  See L<readConfig()|Log::Report::Domain/"Attributes">
-
-=item context_rules => HASH|OBJECT
-
-When rules are provided, the translator will use the C<msgctxt> fields
-as provided by PO-files (gettext).  This parameter is used to initialize
-a L<Log::Report::Translator::Context|Log::Report::Translator::Context> helper object.
-
-=item formatter => CODE|HASH|'PRINTI'
-
-Selects the formatter used for the errors messages.  The default is C<PRINTI>,
-which will use L<String::Print::printi()|String::Print/"FUNCTIONS">: interpolation with curly
-braces around the variable names.
-
-=item native_language => CODESET
-
-This is the language which you have used to write the translatable and
-the non-translatable messages in.  In case no translation is needed,
-you still wish the system error messages to be in the same language
-as the report.  Of course, each textdomain can define its own.
-
-=item translator => L<Log::Report::Translator|Log::Report::Translator>|HASH
-
-Set the object which will do the translations for this domain.
-
-=item where => ARRAY
-
-=back
-
-=item $obj-E<gt>B<contextRules>()
-
-=item $obj-E<gt>B<defaultContext>()
-
-Returns the current default translation context settings as HASH.  You should
-not modify the content of that HASH: change it by called L<setContext()|Log::Report::Domain/"Attributes"> or
-L<updateContext()|Log::Report::Domain/"Attributes">.
-
-=item $obj-E<gt>B<isConfigured>()
-
-Inherited, see L<Log::Report::Minimal::Domain/"Attributes">
-
-=item $obj-E<gt>B<name>()
-
-Inherited, see L<Log::Report::Minimal::Domain/"Attributes">
-
-=item $obj-E<gt>B<nativeLanguage>()
-
-=item $obj-E<gt>B<readConfig>($filename)
-
-=item Log::Report::Domain-E<gt>B<readConfig>($filename)
-
-Helper method, which simply parses the content $filename into a HASH to be
-used as parameters to L<configure()|Log::Report::Domain/"Attributes">. The filename must end on '.pl',
-to indicate that it uses perl syntax (can be processed with Perl's C<do>
-command) or end on '.json'.  See also chapter L</Configuring> below.
-
-Currently, this file can be in Perl native format (when ending on C<.pl>)
-or JSON (when it ends with C<.json>).  Various modules may explain parts
-of what can be found in these files, for instance
-L<Log::Report::Translator::Context|Log::Report::Translator::Context>.
-
-=item $obj-E<gt>B<setContext>(STRING|HASH|ARRAY|PAIRS)
-
-Temporary set the default translation context for messages.  This is used
-when the message is created without a C<_context> parameter. The context
-can be retrieved with L<defaultContext()|Log::Report::Domain/"Attributes">.
-
-Contexts are totally ignored then there are no C<context_rules>.  When
-you do not wish to change settings, you may simply provide a HASH.
-
-example: 
-
-   use Log::Report 'my-domain', context_rules => {};
-
-=item $obj-E<gt>B<translator>()
-
-=item $obj-E<gt>B<updateContext>(STRING|HASH|ARRAY|PAIRS)
-
-[1.10] Make changes and additions to the active context (see L<setContext()|Log::Report::Domain/"Attributes">).
-
-=back
-
-=head2 Action
-
-Extends L<"Action" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Action">.
- 
-=over 4
-
-=item $obj-E<gt>B<interpolate>( $msgid, [$args] )
-
-Inherited, see L<Log::Report::Minimal::Domain/"Action">
-
-=item $obj-E<gt>B<translate>($message, $language)
-
-Translate the $message into the $language.
-
-=back
-
-=head1 DETAILS
-
-=head2 Configuring
-
-Configuration of a domain can happen in many ways: either explicitly or
-implicitly.  The explicit form:
-
-   package My::Package;
-   use Log::Report 'my-domain';
-
-   textdomain 'my-domain', %configuration;
-   textdomain->configure(%configuration);
-   textdomain->configure(\%configuration);
-
-   textdomain->configure(conf => $filename);
-
-The implicit form is (no variables possible, only constants!)
-
-   package My::Package;
-   use Log::Report 'my-domain', %configuration;
-   use Log::Report 'my-domain', conf => '/filename';
-
-You can only configure your domain in one place in your program.  The
-textdomain setup is then used for all packages in the same domain.
-
-This also works for L<Log::Report::Optional|Log::Report::Optional>, which is a dressed-down
-version of L<Log::Report|Log::Report>.
-
-=head3 configuring your own formatter
-
-[0.91] The C<PRINTI> is a special constants for L<configure(formatter)|Log::Report::Domain/"Attributes">, and
-will use L<String::Print|String::Print> function C<printi()>, with the standard tricks.
-
-  textdomain 'some-domain'
-    formatter =>
-      { class     => 'String::Print'    # default
-      , method    => 'sprinti'          # default
-      , %options    # constructor options for the class
-      );
-
-When you want your own formatter, or configuration of C<String::Print>,
-you need to pass a CODE.  Be aware that you may loose magic added by
-L<Log::Report|Log::Report> and other layers, like L<Log::Report::Template|Log::Report::Template>:
-
-  textdomain 'some-domain'
-    , formatter => \&my_formatter;
-
-=head3 configuring global values
-
-Say, you log for a (Dancer) webserver, where you wish to include the website
-name in some of the log lines.  For this, (ab)use the translation context:
-
-  ### first enabled translation contexts
-  use Log::Report 'my-domain', context_rules => {};
-  # or
-  use Log::Report 'my-domain';
-  textdomain->configure(context_rules => {});
-  # or
-  textdomain 'my-domain'
-    , content_rules => {};
-  
-  ### every time you start working for a different virtual host
-  (textdomain 'my-domain')->setContext(host => $host);
-
-  ### now you can use that in your code
-  package My::Package;
-  use Log::Report 'my-domain';
-  error __x"in {_context.host} not logged-in {user}", user => $username;
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Exception.pm b/lib/Log/Report/Exception.pm
index 2ee6271..83e3f03 100644
--- a/lib/Log/Report/Exception.pm
+++ b/lib/Log/Report/Exception.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Exception;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 
 use warnings;
 use strict;
@@ -19,12 +12,51 @@ use Log::Report::Util qw/is_fatal to_html/;
 use POSIX             qw/locale_h/;
 use Scalar::Util      qw/blessed/;
 
+=chapter NAME
+Log::Report::Exception - a collected report
+
+=chapter SYNOPSIS
+ # created within a try block
+ try { error "help!" };
+ my $exception = $@->wasFatal;
+ $exception->throw if $exception;
+
+ $@->reportFatal;  # combination of above two lines
+
+ my $message = $exception->message;   # the Log::Report::Message
+
+ if($message->inClass('die')) ...
+ if($exception->inClass('die')) ...   # same
+ if($@->wasFatal(class => 'die')) ... # same
+
+=chapter DESCRIPTION
+In Log::Report, exceptions are not as extended as available in
+languages as Java: you do not create classes for them.  The only
+thing an exception object does, is capture some information about
+an (untranslated) report.
+
+=chapter OVERLOADING
+
+=overload stringification
+Produces "reason: message".
+=cut
 
 use overload
     '""'     => 'toString'
   , 'bool'   => sub {1}    # avoid accidental serialization of message
   , fallback => 1;
 
+=chapter METHODS
+
+=section Constructors
+=c_method new %options
+
+=option  report_opts HASH
+=default report_opts {}
+
+=requires reason REASON
+=requires message Log::Report::Message
+=cut
 
 sub new($@)
 {   my ($class, %args) = @_;
@@ -33,18 +65,44 @@ sub new($@)
 }
 
 #----------------
+=section Accessors
+
+=method report_opts
+=cut
 
 sub report_opts() {shift->{report_opts}}
 
+=method reason [$reason]
+=cut
 
 sub reason(;$)
 {   my $self = shift;
     @_ ? $self->{reason} = uc(shift) : $self->{reason};
 }
 
+=method isFatal
+Returns whether this exception has a severity which makes it fatal
+when thrown.  See M<Log::Report::Util::is_fatal()>.
+=example
+  if($ex->isFatal) { $ex->throw(reason => 'ALERT') }
+  else { $ex->throw }
+=cut
 
 sub isFatal() { is_fatal shift->{reason} }
 
+=method message [$message]
+Change the $message of the exception, must be a M<Log::Report::Message>
+object.
+
+When you use a C<Log::Report::Message> object, you will get a new one
+returned. Therefore, if you want to modify the message in an exception,
+you have to re-assign the result of the modification.
+
+=examples
+ $e->message->concat('!!')); # will not work!
+ $e->message($e->message->concat('!!'));
+ $e->message(__x"some message {msg}", msg => $xyz);
+=cut
 
 sub message(;$)
 {   my $self = shift;
@@ -57,9 +115,32 @@ sub message(;$)
 }
 
 #----------------
+=section Processing
+
+=method inClass $class|Regexp
+Check whether any of the classes listed in the message match $class
+(string) or the Regexp.  This uses M<Log::Report::Message::inClass()>.
+=cut
 
 sub inClass($) { $_[0]->message->inClass($_[1]) }
 
+=method throw %options
+Insert the message contained in the exception into the currently
+defined dispatchers.  The C<throw> name is commonly known
+exception related terminology for C<report>.
+
+The %options overrule the captured options to M<Log::Report::report()>.
+This can be used to overrule a destination.  Also, the reason can
+be changed.
+
+=example overrule defaults to report
+ try { print {to => 'stderr'}, ERROR => 'oops!' };
+ $@->reportFatal(to => 'syslog');
+
+ $exception->throw(to => 'syslog');
+
+ $@->wasFatal->throw(reason => 'WARNING');
+=cut
 
 sub throw(@)
 {   my $self    = shift;
@@ -82,6 +163,15 @@ sub throw(@)
 # where the throw is handled is not interesting
 sub PROPAGATE($$) {shift}
 
+=method toString [$locale]
+Prints the reason and the message.  Differently from M<throw()>, this
+only represents the textual content: it does not re-cast the exceptions to
+higher levels.
+
+=examples printing exceptions
+ print $_->toString for $@->exceptions;
+ print $_ for $@->exceptions;   # via overloading
+=cut
 
 sub toString(;$)
 {   my ($self, $locale) = @_;
@@ -89,9 +179,19 @@ sub toString(;$)
     lc($self->{reason}).': '.(ref $msg ? $msg->toString($locale) : $msg)."\n";
 }
 
+=method toHTML [$locale]
+[1.11] as M<toString()>, and escape HTML volatile characters.
+=cut
 
 sub toHTML(;$) { to_html($_[0]->toString($_[1])) }
 
+=method print [$fh]
+The default filehandle is STDOUT.
+
+=examples
+ print $exception;  # via overloading
+ $exception->print; # OO style
+=cut
 
 sub print(;$)
 {   my $self = shift;
diff --git a/lib/Log/Report/Exception.pod b/lib/Log/Report/Exception.pod
deleted file mode 100644
index 1b7243a..0000000
--- a/lib/Log/Report/Exception.pod
+++ /dev/null
@@ -1,165 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Exception - a collected report
-
-=head1 SYNOPSIS
-
- # created within a try block
- try { error "help!" };
- my $exception = $@->wasFatal;
- $exception->throw if $exception;
-
- $@->reportFatal;  # combination of above two lines
-
- my $message = $exception->message;   # the Log::Report::Message
-
- if($message->inClass('die')) ...
- if($exception->inClass('die')) ...   # same
- if($@->wasFatal(class => 'die')) ... # same
-
-=head1 DESCRIPTION
-
-In Log::Report, exceptions are not as extended as available in
-languages as Java: you do not create classes for them.  The only
-thing an exception object does, is capture some information about
-an (untranslated) report.
-
-=head1 METHODS
-
-=head2 Constructors
-
-=over 4
-
-=item Log::Report::Exception-E<gt>B<new>(%options)
-
- -Option     --Default
-  message      <required>
-  reason       <required>
-  report_opts  {}
-
-=over 2
-
-=item message => Log::Report::Message
-
-=item reason => REASON
-
-=item report_opts => HASH
-
-=back
-
-=back
-
-=head2 Accessors
-
-=over 4
-
-=item $obj-E<gt>B<isFatal>()
-
-Returns whether this exception has a severity which makes it fatal
-when thrown.  See L<Log::Report::Util::is_fatal()|Log::Report::Util/"Reasons">.
-
-example: 
-
-  if($ex->isFatal) { $ex->throw(reason => 'ALERT') }
-  else { $ex->throw }
-
-=item $obj-E<gt>B<message>( [$message] )
-
-Change the $message of the exception, must be a L<Log::Report::Message|Log::Report::Message>
-object.
-
-When you use a C<Log::Report::Message> object, you will get a new one
-returned. Therefore, if you want to modify the message in an exception,
-you have to re-assign the result of the modification.
-
-example: 
-
- $e->message->concat('!!')); # will not work!
- $e->message($e->message->concat('!!'));
- $e->message(__x"some message {msg}", msg => $xyz);
-
-=item $obj-E<gt>B<reason>( [$reason] )
-
-=item $obj-E<gt>B<report_opts>()
-
-=back
-
-=head2 Processing
-
-=over 4
-
-=item $obj-E<gt>B<inClass>($class|Regexp)
-
-Check whether any of the classes listed in the message match $class
-(string) or the Regexp.  This uses L<Log::Report::Message::inClass()|Log::Report::Message/"Processing">.
-
-=item $obj-E<gt>B<print>( [$fh] )
-
-The default filehandle is STDOUT.
-
-example: 
-
- print $exception;  # via overloading
- $exception->print; # OO style
-
-=item $obj-E<gt>B<throw>(%options)
-
-Insert the message contained in the exception into the currently
-defined dispatchers.  The C<throw> name is commonly known
-exception related terminology for C<report>.
-
-The %options overrule the captured options to L<Log::Report::report()|Log::Report/"Report Production and Configuration">.
-This can be used to overrule a destination.  Also, the reason can
-be changed.
-
-example: overrule defaults to report
-
- try { print {to => 'stderr'}, ERROR => 'oops!' };
- $@->reportFatal(to => 'syslog');
-
- $exception->throw(to => 'syslog');
-
- $@->wasFatal->throw(reason => 'WARNING');
-
-=item $obj-E<gt>B<toHTML>( [$locale] )
-
-[1.11] as L<toString()|Log::Report::Exception/"Processing">, and escape HTML volatile characters.
-
-=item $obj-E<gt>B<toString>( [$locale] )
-
-Prints the reason and the message.  Differently from L<throw()|Log::Report::Exception/"Processing">, this
-only represents the textual content: it does not re-cast the exceptions to
-higher levels.
-
-example: printing exceptions
-
- print $_->toString for $@->exceptions;
- print $_ for $@->exceptions;   # via overloading
-
-=back
-
-=head1 OVERLOADING
-
-=over 4
-
-=item overload: B<stringification>
-
-Produces "reason: message".
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Message.pm b/lib/Log/Report/Message.pm
index a92a2e8..804f4c7 100644
--- a/lib/Log/Report/Message.pm
+++ b/lib/Log/Report/Message.pm
@@ -1,15 +1,8 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Message;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 
 use warnings;
 use strict;
@@ -27,6 +20,60 @@ use Log::Report::Util qw/to_html/;
   *LC_MESSAGES = sub(){5} if $@;
 }
 
+=chapter NAME
+Log::Report::Message - a piece of text to be translated
+
+=chapter SYNOPSIS
+ # Objects created by Log::Report's __ functions
+ # Full feature description in the DETAILS section
+
+ # no interpolation
+ __"Hello, World";
+
+ # with interpolation
+ __x"age {years}", years => 12;
+
+ # interpolation for one or many
+ my $nr_files = @files;
+ __nx"one file", "{_count} files", $nr_files;
+ __nx"one file", "{_count} files", \@files;
+
+ # interpolation of arrays
+ __x"price-list: {prices%.2f}", prices => \@prices, _join => ', ';
+
+ # white-spacing on msgid preserved
+ print __"\tCongratulations,\n";
+ print "\t", __("Congratulations,"), "\n";  # same
+
+=chapter DESCRIPTION
+Any use of a translation function exported by M<Log::Report>, like
+C<__()> (the function is named underscore-underscore) or C<__x()>
+(underscore-underscore-x) will result in this object.  It will capture
+some environmental information, and delay the translation until it
+is needed.
+
+Creating an object first and translating it later, is slower than
+translating it immediately.  However, on the location where the message
+is produced, we do not yet know in what language to translate it to:
+that depends on the front-end, the log dispatcher.
+
+
+=chapter OVERLOADING
+
+=overload stringification
+When the object is used in string context, it will get translated.
+Implemented as M<toString()>.
+
+=overload as $function
+When the object is used to call as $function, a new object is
+created with the data from the original one but updated with the
+new parameters.  Implemented in C<clone()>.
+
+=overload concatenation
+An (accidental) use of concatenation (a dot where a comma should be
+used) would immediately stringify the object.  This is avoided by
+overloading that operation.
+=cut
 
 use overload
     '""'  => 'toString'
@@ -34,6 +81,115 @@ use overload
   , '.'   => 'concat'
   , fallback => 1;
 
+=chapter METHODS
+
+=section Constructors
+
+=c_method new %options
+B<End-users: do not use this method directly>, but use M<Log::Report::__()>
+and friends.  The %options is a mixed list of object initiation parameters
+(all with a leading underscore) and variables to be filled in into the
+translated C<_msgid> string.
+
+=option  _expand BOOLEAN
+=default _expand C<false>
+Indicates whether variables are to be filled-in.
+
+=option  _domain STRING
+=default _domain <from "use Log::Report">
+The text-domain (translation table) to which this C<_msgid> belongs.
+
+With this parameter, your can "borrow" translations from other textdomains.
+Be very careful with this (although there are good use-cases)  The xgettext
+msgid extractor may add the used msgid to this namespace as well.  To
+avoid that, add a harmless '+':
+
+  print __x(+"errors", _domain => 'global');
+
+The extractor will not take the msgid when it is an expression.  The '+'
+has no effect on the string at runtime.
+
+=option  _count INTEGER|ARRAY|HASH
+=default _count C<undef>
+When defined, the C<_plural> need to be defined as well.  When an
+ARRAY is provided, the length of the ARRAY is taken.  When a HASH
+is given, the number of keys in the HASH is used.
+
+=option  _plural MSGID
+=default _plural C<undef>
+Can be used together with C<_count>.  This plural form of the C<_msgid>
+text is used to simplify the work of translators, and as fallback when
+no translation is possible: therefore, this can best resemble an
+English message.
+
+White-space at the beginning and end of the string are stripped off.
+The white-space provided by the C<_msgid> will be used.
+
+=option  _msgid MSGID
+=default _msgid C<undef>
+The message label, which refers to some translation information.
+Usually a string which is close the English version of the message.
+This will also be used if there is no translation possible/known.
+
+Leading white-space C<\s> will be added to C<_prepend>.  Trailing
+white-space will be added before C<_append>.
+
+=option  _category INTEGER
+=default _category C<undef>
+The category when the real gettext library is used, for instance
+LC_MESSAGES.
+
+=option  _prepend STRING|MESSAGE
+=default _prepend C<undef>
+Text as STRING or MESSAGE object to be displayed before the display
+of this message.
+
+=option  _append  STRING|MESSAGE
+=default _append  C<undef>
+Text as STRING or MESSAGE object to be displayed after the display
+of this message.
+
+=option  _class   STRING|ARRAY
+=default _class   []
+When messages are used for exception based programming, you add
+C<_class> parameters to the argument list.  Later, with for instance
+M<Log::Report::Dispatcher::Try::wasFatal(class)>, you can check the
+category of the message.
+
+One message can be part of multiple classes.  The STRING is used as
+comma- and/or blank separated list of class tokens (barewords), the
+ARRAY lists all tokens separately. See M<classes()>.
+
+=option  _classes STRING|ARRAY
+=default _classes []
+Alternative for C<_class>, which cannot be used at the same time.
+
+=option  _to NAME
+=default _to <undef>
+Specify the NAME of a dispatcher as destination explicitly. Short
+for  C<< report {to => NAME}, ... >>  See M<to()>
+
+=option  _join STRING
+=default _join C<$">  C<$LIST_SEPARATOR>
+Which STRING to be used then an ARRAY is being filled-in.
+
+=option  _lang ISO
+=default _lang <from locale>
+[1.00] Override language setting from locale, for instance because that
+is not configured correctly (yet).  This does not extend to prepended
+or appended translated message object.
+
+=option  _context WORDS|ARRAY
+=default _context C<undef>
+[1.00] Set keywords which can be used to select alternatives
+between translations.  Read the DETAILS section in
+M<Log::Report::Translator::Context>
+
+=option  _msgctxt STRING
+=default _msgctxt C<undef>
+[1.22] Message context in the translation file, the traditional use.  Cannot
+be combined with C<_context> on the same msgids.
+=cut
 
 sub new($@)
 {   my ($class, %s) = @_;
@@ -63,12 +219,28 @@ sub new($@)
 # internal use only: to simplify __*p* functions
 sub _msgctxt($) {$_[0]->{_msgctxt} = $_[1]; $_[0]}
 
+=method clone %options, $variables
+Returns a new object which copies info from original, and updates it
+with the specified %options and $variables.  The advantage is that the
+cached translations are shared between the objects.
+
+=examples use of clone()
+ my $s = __x "found {nr} files", nr => 5;
+ my $t = $s->clone(nr => 3);
+ my $t = $s->(nr => 3);      # equivalent
+ print $s;     # found 5 files
+ print $t;     # found 3 files
+=cut
 
 sub clone(@)
 {   my $self = shift;
     (ref $self)->new(%$self, @_);
 }
 
+=c_method fromTemplateToolkit $domain, $msgid, $params
+See M<Log::Report::Extract::Template> on the details how to integrate
+Log::Report translations with Template::Toolkit (version 1 and 2)
+=cut
 
 sub fromTemplateToolkit($$;@)
 {   my ($class, $domain, $msgid) = splice @_, 0, 3;
@@ -91,6 +263,31 @@ sub fromTemplateToolkit($$;@)
 }
 
 #----------------
+=section Accessors
+
+=method prepend
+Returns the string which is prepended to this one.  Usually C<undef>.
+
+=method msgid
+Returns the msgid which will later be translated.
+
+=method append
+Returns the string or M<Log::Report::Message> object which is appended
+after this one.  Usually C<undef>.
+
+=method domain
+Returns the domain of the first translatable string in the structure.
+
+=method count
+Returns the count, which is used to select the translation
+alternatives.
+
+=method context
+Returns an HASH if there is a context defined for this message.
+
+=method msgctxt
+The message context for the translation table lookup.
+=cut
 
 sub prepend() {shift->{_prepend}}
 sub msgid()   {shift->{_msgid}}
@@ -100,22 +297,73 @@ sub count()   {shift->{_count}}
 sub context() {shift->{_context}}
 sub msgctxt() {shift->{_msgctxt}}
 
+=method classes
+Returns the LIST of classes which are defined for this message; message
+group indicators, as often found in exception-based programming.
+=cut
 
 sub classes()
 {   my $class = $_[0]->{_class} || $_[0]->{_classes} || [];
     ref $class ? @$class : split(/[\s,]+/, $class);
 }
 
+=method to [$name]
+Returns the $name of a dispatcher if explicitly specified with
+the '_to' key. Can also be used to set it.  Usually, this will
+return undef, because usually all dispatchers get all messages.
+=cut
 
 sub to(;$)
 {   my $self = shift;
     @_ ? $self->{_to} = shift : $self->{_to};
 }
 
+=method valueOf $parameter
+Lookup the named $parameter for the message.  All pre-defined names
+have their own method which should be used with preference.
+
+=example
+When the message was produced with
+
+  my @files = qw/one two three/;
+  my $msg = __xn "found one file: {file}"
+               , "found {nrfiles} files: {files}"
+               , scalar @files
+               , file    => $files[0]
+               , files   => \@files
+               , nrfiles => @files+0
+               , _class  => 'IO, files'
+               , _join   => ', ';
+
+then the values can be takes from the produced message as
+
+  my $files = $msg->valueOf('files');  # returns ARRAY reference
+  print @$files;              # 3
+  my $count = $msg->count;    # 3
+  my @class = $msg->classes;  # 'IO', 'files'
+  if($msg->inClass('files'))  # true
+
+Simplified, the above example can also be written as:
+
+  local $" = ', ';
+  my $msg  = __xn "found one file: {files}"
+                , "found {_count} files: {files}"
+                , @files      # has scalar context
+                , files   => \@files
+                , _class  => 'IO, files';
+
+
+=cut
 
 sub valueOf($) { $_[0]->{$_[1]} }
 
 #--------------
+=section Processing
+
+=method inClass $class|Regexp
+Returns true if the message is in the specified $class (string) or
+matches the Regexp.  The trueth value is the (first matching) class.
+=cut
 
 sub inClass($)
 {   my @classes = shift->classes;
@@ -124,6 +372,9 @@ sub inClass($)
     : (first { $_ eq $_[0] } @classes);
 }
     
+=method toString [$locale]
+Translate a message.  If not specified, the default locale is used.
+=cut
 
 sub toString(;$)
 {   my ($self, $locale) = @_;
@@ -170,11 +421,26 @@ sub toString(;$)
 }
 
 
+=method toHTML [$locale]
+[1.11] Translate the message, and then entity encode HTML volatile characters.
+
+[1.20] When used in combination with a templating system, you may want to
+use C<<content_for => 'HTML'>> in M<Log::Report::Domain::configure(formatter)>.
+
+=example
+
+  print $msg->toHTML('NL');
+
+=cut
 
 my %tohtml = qw/  > gt   < lt   " quot  & amp /;
 
 sub toHTML(;$) { to_html($_[0]->toString($_[1])) }
 
+=method untranslated
+Return the concatenation of the prepend, msgid, and append strings.  Variable
+expansions within the msgid is not performed.
+=cut
 
 sub untranslated()
 {  my $self = shift;
@@ -183,6 +449,17 @@ sub untranslated()
    . (defined $self->{_append}  ? $self->{_append}  : '');
 }
 
+=method concat STRING|$object, [$prepend]
+This method implements the overloading of concatenation, which is needed
+to delay translations even longer.  When $prepend is true, the STRING
+or $object (other C<Log::Report::Message>) needs to prepended, otherwise
+it is appended.
+
+=examples of concatenation
+ print __"Hello" . ' ' . __"World!";
+ print __("Hello")->concat(' ')->concat(__"World!")->concat("\n");
+
+=cut
 
 sub concat($;$)
 {   my ($self, $what, $reversed) = @_;
@@ -196,5 +473,190 @@ sub concat($;$)
 }
 
 #----------------
+=chapter DETAILS
+
+=section OPTIONS and VARIABLES
+The M<Log::Report> functions which define translation request can all
+have OPTIONS.  Some can have VARIABLES to be interpolated in the string as
+well.  To distinguish between the OPTIONS and VARIABLES (both a list
+of key-value pairs), the keys of the OPTIONS start with an underscore C<_>.
+As result of this, please avoid the use of keys which start with an
+underscore in variable names.  On the other hand, you are allowed to
+interpolate OPTION values in your strings.
+
+=subsection Interpolating
+With the C<__x()> or C<__nx()>, interpolation will take place on the
+translated MSGID string.  The translation can contain the VARIABLE
+and OPTION names between curly brackets.  Text between curly brackets
+which is not a known parameter will be left untouched.
+
+ fault __x"cannot open open {filename}", filename => $fn;
+
+ print __xn"directory {dir} contains one file"
+          ,"directory {dir} contains {nr_files} files"
+          , scalar(@files)            # (1) (2)
+          , nr_files => scalar @files # (3)
+          , dir      => $dir;
+
+(1) this required third parameter is used to switch between the different
+plural forms.  English has only two forms, but some languages have many
+more.
+
+(2) the "scalar" keyword is not needed, because the third parameter is
+in SCALAR context.  You may also pass C< \@files > there, because ARRAYs
+will be converted into their length.  A HASH will be converted into the
+number of keys in the HASH.
+
+(3) the C<scalar> keyword is required here, because it is LIST context:
+otherwise all filenames will be filled-in as parameters to C<__xn()>.
+See below for the available C<_count> valure, to see how the C<nr_files>
+parameter can disappear.
+
+=subsection Interpolation of VARIABLES
+
+C<Log::Report> uses L<String::Print> to interpolate values in(translated)
+messages.  This is a very powerful syntax, and you should certainly read
+that manual-page.  Here, we only described additional features, specific
+to the usage of C<String::Print> in C<Log::Report::Message> objects.
+
+There is no way of checking beforehand whether you have provided all
+required values, to be interpolated in the translated string.
+
+For interpolating, the following rules apply:
+=over 4
+=item *
+Simple scalar values are interpolated "as is"
+=item *
+References to SCALARs will collect the value on the moment that the
+output is made.  The C<Log::Report::Message> object which is created with
+the C<__xn> can be seen as a closure.  The translation can be reused.
+See example below.
+=item *
+Code references can be used to create the data "under fly".  The
+C<Log::Report::Message> object which is being handled is passed as
+only argument.  This is a hash in which all OPTIONS and VARIABLES
+can be found.
+=item *
+When the value is an ARRAY, all members will be interpolated with C<$">
+between the elements.  Alternatively (maybe nicer), you can pass an
+interpolation parameter via the C<_join> OPTION.
+=back
+
+ local $" = ', ';
+ error __x"matching files: {files}", files => \@files;
+
+ error __x"matching files: {files}", files => \@files, _join => ', ';
+
+=subsection Interpolation of OPTIONS
+
+You are permitted the interpolate OPTION values in your string.  This may
+simplify your coding.  The useful names are:
+
+=over 4
+=item _msgid
+The MSGID as provided with M<Log::Report::__()> and M<Log::Report::__x()>
+
+=item _plural, _count
+The PLURAL MSGIDs, respectively the COUNT as used with
+M<Log::Report::__n()> and M<Log::Report::__nx()>
+
+=item _textdomain
+The label of the textdomain in which the translation takes place.
+
+=item _class or _classes
+Are to be used to group reports, and can be queried with M<inClass()>,
+M<Log::Report::Exception::inClass()>, or
+M<Log::Report::Dispatcher::Try::wasFatal()>.
+=back
+
+=example using the _count
+With M<Locale::TextDomain>, you have to do
+
+  use Locale::TextDomain;
+  print __nx ( "One file has been deleted.\n"
+             , "{num} files have been deleted.\n"
+             , $num_files
+             , num => $num_files
+             );
+
+With C<Log::Report>, you can do
+
+  use Log::Report;
+  print __nx ( "One file has been deleted.\n"
+             , "{_count} files have been deleted.\n"
+             , $num_files
+             );
+
+Of course, you need to be aware that the name used to reference the
+counter is fixed to C<_count>.  The first example works as well, but
+is more verbose.
+
+=subsection Handling white-spaces
+
+In above examples, the msgid and plural form have a trailing new-line.
+In general, it is much easier to write
+
+   print __x"Hello, World!\n";
+
+than
+
+   print __x("Hello, World!") . "\n";
+
+For the translation tables, however, that trailing new-line is "over
+information"; it is an layout issue, not a translation issue.
+
+Therefore, the first form will automatically be translated into the
+second.  All leading and trailing white-space (blanks, new-lines, tabs,
+...) are removed from the msgid before the look-up, and then added to
+the translated string.
+
+Leading and trailing white-space on the plural form will also be
+removed.  However, after translation the spacing of the msgid will
+be used.
+
+=subsection Avoiding repetative translations
+
+This way of translating is somewhat expensive, because an object to
+handle the C<__x()> is created each time.
+
+ for my $i (1..100_000)
+ {   print __x "Hello World {i}\n", i => $i;
+ }
+
+The suggestion that M<Locale::TextDomain> makes to improve performance,
+is to get the translation outside the loop, which only works without
+interpolation:
+
+ use Locale::TextDomain;
+ my $i = 42;
+ my $s = __x("Hello World {i}\n", i => $i);
+ foreach $i (1..100_000)
+ {   print $s;
+ }
+
+Oops, not what you mean because the first value of C<$i> is captured
+in the initial message object.  With Log::Report, you can do it (except
+when you use contexts)
+
+ use Log::Report;
+ my $i;
+ my $s = __x("Hello World {i}\n", i => \$i);
+ foreach $i (1..100_000)
+ {   print $s;
+ }
+
+Mind you not to write: C<for my $i> in above case!!!!
+
+You can also write an incomplete translation:
+
+ use Log::Report;
+ my $s = __x "Hello World {i}\n";
+ foreach my $i (1..100_000)
+ {   print $s->(i => $i);
+ }
+
+In either case, the translation will be looked-up only once.
+
+=cut
 
 1;
diff --git a/lib/Log/Report/Message.pod b/lib/Log/Report/Message.pod
deleted file mode 100644
index e0f6eb0..0000000
--- a/lib/Log/Report/Message.pod
+++ /dev/null
@@ -1,566 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Message - a piece of text to be translated
-
-=head1 INHERITANCE
-
- Log::Report::Message is extended by
-   Dancer2::Plugin::LogReport::Message
-
-=head1 SYNOPSIS
-
- # Objects created by Log::Report's __ functions
- # Full feature description in the DETAILS section
-
- # no interpolation
- __"Hello, World";
-
- # with interpolation
- __x"age {years}", years => 12;
-
- # interpolation for one or many
- my $nr_files = @files;
- __nx"one file", "{_count} files", $nr_files;
- __nx"one file", "{_count} files", \@files;
-
- # interpolation of arrays
- __x"price-list: {prices%.2f}", prices => \@prices, _join => ', ';
-
- # white-spacing on msgid preserved
- print __"\tCongratulations,\n";
- print "\t", __("Congratulations,"), "\n";  # same
-
-=head1 DESCRIPTION
-
-Any use of a translation function exported by L<Log::Report|Log::Report>, like
-C<__()> (the function is named underscore-underscore) or C<__x()>
-(underscore-underscore-x) will result in this object.  It will capture
-some environmental information, and delay the translation until it
-is needed.
-
-Creating an object first and translating it later, is slower than
-translating it immediately.  However, on the location where the message
-is produced, we do not yet know in what language to translate it to:
-that depends on the front-end, the log dispatcher.
-
-=head1 METHODS
-
-=head2 Constructors
-
-=over 4
-
-=item $obj-E<gt>B<clone>(%options, $variables)
-
-Returns a new object which copies info from original, and updates it
-with the specified %options and $variables.  The advantage is that the
-cached translations are shared between the objects.
-
-example: use of clone()
-
- my $s = __x "found {nr} files", nr => 5;
- my $t = $s->clone(nr => 3);
- my $t = $s->(nr => 3);      # equivalent
- print $s;     # found 5 files
- print $t;     # found 3 files
-
-=item Log::Report::Message-E<gt>B<fromTemplateToolkit>($domain, $msgid, $params)
-
-See L<Log::Report::Extract::Template|Log::Report::Extract::Template> on the details how to integrate
-Log::Report translations with Template::Toolkit (version 1 and 2)
-
-=item Log::Report::Message-E<gt>B<new>(%options)
-
-B<End-users: do not use this method directly>, but use L<Log::Report::__()|Log::Report/"Messages (optionally translatable)">
-and friends.  The %options is a mixed list of object initiation parameters
-(all with a leading underscore) and variables to be filled in into the
-translated C<_msgid> string.
-
- -Option   --Default
-  _append    undef
-  _category  undef
-  _class     []
-  _classes   []
-  _context   undef
-  _count     undef
-  _domain    <from "use Log::Report">
-  _expand    false
-  _join      $" $LIST_SEPARATOR
-  _lang      <from locale>
-  _msgctxt   undef
-  _msgid     undef
-  _plural    undef
-  _prepend   undef
-  _to        <undef>
-
-=over 2
-
-=item _append => STRING|MESSAGE
-
-Text as STRING or MESSAGE object to be displayed after the display
-of this message.
-
-=item _category => INTEGER
-
-The category when the real gettext library is used, for instance
-LC_MESSAGES.
-
-=item _class => STRING|ARRAY
-
-When messages are used for exception based programming, you add
-C<_class> parameters to the argument list.  Later, with for instance
-L<Log::Report::Dispatcher::Try::wasFatal(class)|Log::Report::Dispatcher::Try/"Status">, you can check the
-category of the message.
-
-One message can be part of multiple classes.  The STRING is used as
-comma- and/or blank separated list of class tokens (barewords), the
-ARRAY lists all tokens separately. See L<classes()|Log::Report::Message/"Accessors">.
-
-=item _classes => STRING|ARRAY
-
-Alternative for C<_class>, which cannot be used at the same time.
-
-=item _context => WORDS|ARRAY
-
-[1.00] Set keywords which can be used to select alternatives
-between translations.  Read the DETAILS section in
-L<Log::Report::Translator::Context|Log::Report::Translator::Context>
-
-=item _count => INTEGER|ARRAY|HASH
-
-When defined, the C<_plural> need to be defined as well.  When an
-ARRAY is provided, the length of the ARRAY is taken.  When a HASH
-is given, the number of keys in the HASH is used.
-
-=item _domain => STRING
-
-The text-domain (translation table) to which this C<_msgid> belongs.
-
-With this parameter, your can "borrow" translations from other textdomains.
-Be very careful with this (although there are good use-cases)  The xgettext
-msgid extractor may add the used msgid to this namespace as well.  To
-avoid that, add a harmless '+':
-
-  print __x(+"errors", _domain => 'global');
-
-The extractor will not take the msgid when it is an expression.  The '+'
-has no effect on the string at runtime.
-
-=item _expand => BOOLEAN
-
-Indicates whether variables are to be filled-in.
-
-=item _join => STRING
-
-Which STRING to be used then an ARRAY is being filled-in.
-
-=item _lang => ISO
-
-[1.00] Override language setting from locale, for instance because that
-is not configured correctly (yet).  This does not extend to prepended
-or appended translated message object.
-
-=item _msgctxt => STRING
-
-[1.22] Message context in the translation file, the traditional use.  Cannot
-be combined with C<_context> on the same msgids.
-
-=item _msgid => MSGID
-
-The message label, which refers to some translation information.
-Usually a string which is close the English version of the message.
-This will also be used if there is no translation possible/known.
-
-Leading white-space C<\s> will be added to C<_prepend>.  Trailing
-white-space will be added before C<_append>.
-
-=item _plural => MSGID
-
-Can be used together with C<_count>.  This plural form of the C<_msgid>
-text is used to simplify the work of translators, and as fallback when
-no translation is possible: therefore, this can best resemble an
-English message.
-
-White-space at the beginning and end of the string are stripped off.
-The white-space provided by the C<_msgid> will be used.
-
-=item _prepend => STRING|MESSAGE
-
-Text as STRING or MESSAGE object to be displayed before the display
-of this message.
-
-=item _to => NAME
-
-Specify the NAME of a dispatcher as destination explicitly. Short
-for  C<< report {to => NAME}, ... >>  See L<to()|Log::Report::Message/"Accessors">
-
-=back
-
-=back
-
-=head2 Accessors
-
-=over 4
-
-=item $obj-E<gt>B<append>()
-
-Returns the string or L<Log::Report::Message|Log::Report::Message> object which is appended
-after this one.  Usually C<undef>.
-
-=item $obj-E<gt>B<classes>()
-
-Returns the LIST of classes which are defined for this message; message
-group indicators, as often found in exception-based programming.
-
-=item $obj-E<gt>B<context>()
-
-Returns an HASH if there is a context defined for this message.
-
-=item $obj-E<gt>B<count>()
-
-Returns the count, which is used to select the translation
-alternatives.
-
-=item $obj-E<gt>B<domain>()
-
-Returns the domain of the first translatable string in the structure.
-
-=item $obj-E<gt>B<msgctxt>()
-
-The message context for the translation table lookup.
-
-=item $obj-E<gt>B<msgid>()
-
-Returns the msgid which will later be translated.
-
-=item $obj-E<gt>B<prepend>()
-
-Returns the string which is prepended to this one.  Usually C<undef>.
-
-=item $obj-E<gt>B<to>( [$name] )
-
-Returns the $name of a dispatcher if explicitly specified with
-the '_to' key. Can also be used to set it.  Usually, this will
-return undef, because usually all dispatchers get all messages.
-
-=item $obj-E<gt>B<valueOf>($parameter)
-
-Lookup the named $parameter for the message.  All pre-defined names
-have their own method which should be used with preference.
-
-example: 
-
-When the message was produced with
-
-  my @files = qw/one two three/;
-  my $msg = __xn "found one file: {file}"
-               , "found {nrfiles} files: {files}"
-               , scalar @files
-               , file    => $files[0]
-               , files   => \@files
-               , nrfiles => @files+0
-               , _class  => 'IO, files'
-               , _join   => ', ';
-
-then the values can be takes from the produced message as
-
-  my $files = $msg->valueOf('files');  # returns ARRAY reference
-  print @$files;              # 3
-  my $count = $msg->count;    # 3
-  my @class = $msg->classes;  # 'IO', 'files'
-  if($msg->inClass('files'))  # true
-
-Simplified, the above example can also be written as:
-
-  local $" = ', ';
-  my $msg  = __xn "found one file: {files}"
-                , "found {_count} files: {files}"
-                , @files      # has scalar context
-                , files   => \@files
-                , _class  => 'IO, files';
-
-=back
-
-=head2 Processing
-
-=over 4
-
-=item $obj-E<gt>B<concat>( STRING|$object, [$prepend] )
-
-This method implements the overloading of concatenation, which is needed
-to delay translations even longer.  When $prepend is true, the STRING
-or $object (other C<Log::Report::Message>) needs to prepended, otherwise
-it is appended.
-
-example: of concatenation
-
- print __"Hello" . ' ' . __"World!";
- print __("Hello")->concat(' ')->concat(__"World!")->concat("\n");
-
-=item $obj-E<gt>B<inClass>($class|Regexp)
-
-Returns true if the message is in the specified $class (string) or
-matches the Regexp.  The trueth value is the (first matching) class.
-
-=item $obj-E<gt>B<toHTML>( [$locale] )
-
-[1.11] Translate the message, and then entity encode HTML volatile characters.
-
-[1.20] When used in combination with a templating system, you may want to
-use C<<content_for => 'HTML'>> in L<Log::Report::Domain::configure(formatter)|Log::Report::Domain/"Attributes">.
-
-example: 
-
-  print $msg->toHTML('NL');
-
-=item $obj-E<gt>B<toString>( [$locale] )
-
-Translate a message.  If not specified, the default locale is used.
-
-=item $obj-E<gt>B<untranslated>()
-
-Return the concatenation of the prepend, msgid, and append strings.  Variable
-expansions within the msgid is not performed.
-
-=back
-
-=head1 DETAILS
-
-=head2 OPTIONS and VARIABLES
-
-The L<Log::Report|Log::Report> functions which define translation request can all
-have OPTIONS.  Some can have VARIABLES to be interpolated in the string as
-well.  To distinguish between the OPTIONS and VARIABLES (both a list
-of key-value pairs), the keys of the OPTIONS start with an underscore C<_>.
-As result of this, please avoid the use of keys which start with an
-underscore in variable names.  On the other hand, you are allowed to
-interpolate OPTION values in your strings.
-
-=head3 Interpolating
-
-With the C<__x()> or C<__nx()>, interpolation will take place on the
-translated MSGID string.  The translation can contain the VARIABLE
-and OPTION names between curly brackets.  Text between curly brackets
-which is not a known parameter will be left untouched.
-
- fault __x"cannot open open {filename}", filename => $fn;
-
- print __xn"directory {dir} contains one file"
-          ,"directory {dir} contains {nr_files} files"
-          , scalar(@files)            # (1) (2)
-          , nr_files => scalar @files # (3)
-          , dir      => $dir;
-
-(1) this required third parameter is used to switch between the different
-plural forms.  English has only two forms, but some languages have many
-more.
-
-(2) the "scalar" keyword is not needed, because the third parameter is
-in SCALAR context.  You may also pass C< \@files > there, because ARRAYs
-will be converted into their length.  A HASH will be converted into the
-number of keys in the HASH.
-
-(3) the C<scalar> keyword is required here, because it is LIST context:
-otherwise all filenames will be filled-in as parameters to C<__xn()>.
-See below for the available C<_count> valure, to see how the C<nr_files>
-parameter can disappear.
-
-=head3 Interpolation of VARIABLES
-
-C<Log::Report> uses L<String::Print> to interpolate values in(translated)
-messages.  This is a very powerful syntax, and you should certainly read
-that manual-page.  Here, we only described additional features, specific
-to the usage of C<String::Print> in C<Log::Report::Message> objects.
-
-There is no way of checking beforehand whether you have provided all
-required values, to be interpolated in the translated string.
-
-For interpolating, the following rules apply:
-
-=over 4
-
-=item *
-
-Simple scalar values are interpolated "as is"
-
-=item *
-
-References to SCALARs will collect the value on the moment that the
-output is made.  The C<Log::Report::Message> object which is created with
-the C<__xn> can be seen as a closure.  The translation can be reused.
-See example below.
-
-=item *
-
-Code references can be used to create the data "under fly".  The
-C<Log::Report::Message> object which is being handled is passed as
-only argument.  This is a hash in which all OPTIONS and VARIABLES
-can be found.
-
-=item *
-
-When the value is an ARRAY, all members will be interpolated with C<$">
-between the elements.  Alternatively (maybe nicer), you can pass an
-interpolation parameter via the C<_join> OPTION.
-
-=back
-
- local $" = ', ';
- error __x"matching files: {files}", files => \@files;
-
- error __x"matching files: {files}", files => \@files, _join => ', ';
-
-=head3 Interpolation of OPTIONS
-
-You are permitted the interpolate OPTION values in your string.  This may
-simplify your coding.  The useful names are:
-
-=over 4
-
-=item _msgid
-
-The MSGID as provided with L<Log::Report::__()|Log::Report/"Messages (optionally translatable)"> and L<Log::Report::__x()|Log::Report/"Messages (optionally translatable)">
-
-=item _plural, _count
-
-The PLURAL MSGIDs, respectively the COUNT as used with
-L<Log::Report::__n()|Log::Report/"Messages (optionally translatable)"> and L<Log::Report::__nx()|Log::Report/"Messages (optionally translatable)">
-
-=item _textdomain
-
-The label of the textdomain in which the translation takes place.
-
-=item _class or _classes
-
-Are to be used to group reports, and can be queried with L<inClass()|Log::Report::Message/"Processing">,
-L<Log::Report::Exception::inClass()|Log::Report::Exception/"Processing">, or
-L<Log::Report::Dispatcher::Try::wasFatal()|Log::Report::Dispatcher::Try/"Status">.
-
-=back
-
-B<. Example: using the _count>
-
-With Locale::TextDomain, you have to do
-
-  use Locale::TextDomain;
-  print __nx ( "One file has been deleted.\n"
-             , "{num} files have been deleted.\n"
-             , $num_files
-             , num => $num_files
-             );
-
-With C<Log::Report>, you can do
-
-  use Log::Report;
-  print __nx ( "One file has been deleted.\n"
-             , "{_count} files have been deleted.\n"
-             , $num_files
-             );
-
-Of course, you need to be aware that the name used to reference the
-counter is fixed to C<_count>.  The first example works as well, but
-is more verbose.
-
-=head3 Handling white-spaces
-
-In above examples, the msgid and plural form have a trailing new-line.
-In general, it is much easier to write
-
-   print __x"Hello, World!\n";
-
-than
-
-   print __x("Hello, World!") . "\n";
-
-For the translation tables, however, that trailing new-line is "over
-information"; it is an layout issue, not a translation issue.
-
-Therefore, the first form will automatically be translated into the
-second.  All leading and trailing white-space (blanks, new-lines, tabs,
-...) are removed from the msgid before the look-up, and then added to
-the translated string.
-
-Leading and trailing white-space on the plural form will also be
-removed.  However, after translation the spacing of the msgid will
-be used.
-
-=head3 Avoiding repetative translations
-
-This way of translating is somewhat expensive, because an object to
-handle the C<__x()> is created each time.
-
- for my $i (1..100_000)
- {   print __x "Hello World {i}\n", i => $i;
- }
-
-The suggestion that Locale::TextDomain makes to improve performance,
-is to get the translation outside the loop, which only works without
-interpolation:
-
- use Locale::TextDomain;
- my $i = 42;
- my $s = __x("Hello World {i}\n", i => $i);
- foreach $i (1..100_000)
- {   print $s;
- }
-
-Oops, not what you mean because the first value of C<$i> is captured
-in the initial message object.  With Log::Report, you can do it (except
-when you use contexts)
-
- use Log::Report;
- my $i;
- my $s = __x("Hello World {i}\n", i => \$i);
- foreach $i (1..100_000)
- {   print $s;
- }
-
-Mind you not to write: C<for my $i> in above case!!!!
-
-You can also write an incomplete translation:
-
- use Log::Report;
- my $s = __x "Hello World {i}\n";
- foreach my $i (1..100_000)
- {   print $s->(i => $i);
- }
-
-In either case, the translation will be looked-up only once.
-
-=head1 OVERLOADING
-
-=over 4
-
-=item overload: B<as $function>
-
-When the object is used to call as $function, a new object is
-created with the data from the original one but updated with the
-new parameters.  Implemented in C<clone()>.
-
-=item overload: B<concatenation>
-
-An (accidental) use of concatenation (a dot where a comma should be
-used) would immediately stringify the object.  This is avoided by
-overloading that operation.
-
-=item overload: B<stringification>
-
-When the object is used in string context, it will get translated.
-Implemented as L<toString()|Log::Report::Message/"Processing">.
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/Log/Report/Translator.pm b/lib/Log/Report/Translator.pm
index 15d567c..0464452 100644
--- a/lib/Log/Report/Translator.pm
+++ b/lib/Log/Report/Translator.pm
@@ -1,28 +1,63 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package Log::Report::Translator;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 
 use warnings;
 use strict;
 
 use Log::Report 'log-report';
 
+=chapter NAME
+Log::Report::Translator - base implementation for translating messages
+
+=chapter SYNOPSIS
+ # internal infrastructure
+ my $msg = Log::Report::Message->new(_msgid => "Hello World\n");
+ print Log::Report::Translator->new(...)->translate($msg);
+
+ # normal use
+ textdomain 'my-domain'
+   , translator => Log::Report::Translator->new;  # default
+ print __"Hello World\n";
+
+=chapter DESCRIPTION
+A module (or distribution) has a certain way of translating messages,
+usually C<gettext>.  The translator is based on some C<textdomain>
+for the message, which can be specified as option per text element,
+but usually is package scoped.
+
+This base class does not translate at all: it will use the MSGID
+(and MSGID_PLURAL if available).  It's a nice fallback if the
+language packs are not installed.
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new %options
+
+=cut
 
 sub new(@) { my $class = shift; (bless {}, $class)->init({@_}) }
 sub init($) { shift }
 
 #------------
+=section Accessors
+
+=cut
 
 #------------
+=section Translating
+
+=method translate $message, [$language, $ctxt]
+Returns the translation of the $message, a C<Log::Report::Message> object,
+based on the current locale.
+
+Translators are permitted to peek into the internal HASH of the
+message object, for performance reasons.
+=cut
 
 # this is called as last resort: if a translator cannot find
 # any lexicon or has no matching language.
@@ -34,6 +69,11 @@ sub translate($$$)
     : $msg->{_msgid};
 }
 
+=method load $domain, $locale
+Load the translation information in the text $domain for the indicated $locale.
+Multiple calls to M<load()> should not cost significant performance: the
+data must be cached.
+=cut
 
 sub load($@) { undef }
 
diff --git a/lib/Log/Report/Translator.pod b/lib/Log/Report/Translator.pod
deleted file mode 100644
index 714db65..0000000
--- a/lib/Log/Report/Translator.pod
+++ /dev/null
@@ -1,79 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-Log::Report::Translator - base implementation for translating messages
-
-=head1 INHERITANCE
-
- Log::Report::Translator is extended by
-   Log::Report::Translator::Gettext
-   Log::Report::Translator::POT
-
-=head1 SYNOPSIS
-
- # internal infrastructure
- my $msg = Log::Report::Message->new(_msgid => "Hello World\n");
- print Log::Report::Translator->new(...)->translate($msg);
-
- # normal use
- textdomain 'my-domain'
-   , translator => Log::Report::Translator->new;  # default
- print __"Hello World\n";
-
-=head1 DESCRIPTION
-
-A module (or distribution) has a certain way of translating messages,
-usually C<gettext>.  The translator is based on some C<textdomain>
-for the message, which can be specified as option per text element,
-but usually is package scoped.
-
-This base class does not translate at all: it will use the MSGID
-(and MSGID_PLURAL if available).  It's a nice fallback if the
-language packs are not installed.
-
-=head1 METHODS
-
-=head2 Constructors
-
-=over 4
-
-=item Log::Report::Translator-E<gt>B<new>(%options)
-
-=back
-
-=head2 Accessors
-
-=head2 Translating
-
-=over 4
-
-=item $obj-E<gt>B<load>($domain, $locale)
-
-Load the translation information in the text $domain for the indicated $locale.
-Multiple calls to L<load()|Log::Report::Translator/"Translating"> should not cost significant performance: the
-data must be cached.
-
-=item $obj-E<gt>B<translate>( $message, [$language, $ctxt] )
-
-Returns the translation of the $message, a C<Log::Report::Message> object,
-based on the current locale.
-
-Translators are permitted to peek into the internal HASH of the
-message object, for performance reasons.
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/lib/MojoX/Log/Report.pm b/lib/MojoX/Log/Report.pm
index 6272f9c..b821e6d 100644
--- a/lib/MojoX/Log/Report.pm
+++ b/lib/MojoX/Log/Report.pm
@@ -1,19 +1,49 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 # This code is part of distribution Log-Report. Meta-POD processed with
 # OODoc into POD and HTML manual-pages.  See README.md
 # Copyright Mark Overmeer.  Licensed under the same terms as Perl itself.
 
 package MojoX::Log::Report;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use Mojo::Base 'Mojo::Log';  # implies use strict etc
 
 use Log::Report 'log-report', import => 'report';
 
+=chapter NAME
+
+MojoX::Log::Report - divert log messages into Log::Report 
+
+=chapter SYNOPSIS
+
+  use MojoX::Log::Report;
+  my $log = MojoX::Log::Report->new(%options);
+  $app->log($log);  # install logger in the Mojo::App
+  
+=chapter DESCRIPTION 
+
+[Included since Log::Report v1.00]
+Mojo likes to log messages directly into a file, by default.  Log::Report
+constructs a M<Log::Report::Exception> object first.
+
+Be aware that this extension does catch the messages to be logged,
+but that the dispatching of the error follows a different route now.
+For instance, you cannot use C<$ENV{MOJO_LOG_LEVEL}> to control the output
+level, but you need to use M<Log::Report::dispatcher()> action C<mode>.
+
+Mojo defines five "levels" of messages, which map onto Log::Report's
+reasons this way:
+
+  debug  TRACE
+  info   INFO
+  warn   WARNING
+  error  ERROR
+  fatal  ALERT
+
+=chapter METHODS
+
+=section Constructors
+
+=c_method new %options
+Inherited %options C<path> and C<level> are ignored.
+=cut
 
 sub new(@) {
     my $class = shift;
diff --git a/lib/MojoX/Log/Report.pod b/lib/MojoX/Log/Report.pod
deleted file mode 100644
index 28d6e2a..0000000
--- a/lib/MojoX/Log/Report.pod
+++ /dev/null
@@ -1,62 +0,0 @@
-=encoding utf8
-
-=head1 NAME
-
-MojoX::Log::Report - divert log messages into Log::Report 
-
-=head1 INHERITANCE
-
- MojoX::Log::Report
-   is a Mojo::Log
-
-=head1 SYNOPSIS
-
-  use MojoX::Log::Report;
-  my $log = MojoX::Log::Report->new(%options);
-  $app->log($log);  # install logger in the Mojo::App
-
-=head1 DESCRIPTION
-
-[Included since Log::Report v1.00]
-Mojo likes to log messages directly into a file, by default.  Log::Report
-constructs a L<Log::Report::Exception|Log::Report::Exception> object first.
-
-Be aware that this extension does catch the messages to be logged,
-but that the dispatching of the error follows a different route now.
-For instance, you cannot use C<$ENV{MOJO_LOG_LEVEL}> to control the output
-level, but you need to use L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration"> action C<mode>.
-
-Mojo defines five "levels" of messages, which map onto Log::Report's
-reasons this way:
-
-  debug  TRACE
-  info   INFO
-  warn   WARNING
-  error  ERROR
-  fatal  ALERT
-
-=head1 METHODS
-
-=head2 Constructors
-
-=over 4
-
-=item MojoX::Log::Report-E<gt>B<new>(%options)
-
-Inherited %options C<path> and C<level> are ignored.
-
-=back
-
-=head1 SEE ALSO
-
-This module is part of Log-Report distribution version 1.28,
-built on May 14, 2019. Website: F<http://perl.overmeer.net/CPAN/>
-
-=head1 LICENSE
-
-Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
-
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-See F<http://dev.perl.org/licenses/>
-
diff --git a/t/00use.t b/t/00use.t
old mode 100644
new mode 100755
diff --git a/t/09message.t b/t/09message.t
old mode 100644
new mode 100755
diff --git a/t/10interp.t b/t/10interp.t
old mode 100644
new mode 100755
diff --git a/t/11concat.t b/t/11concat.t
old mode 100644
new mode 100755
diff --git a/t/12missing.t b/t/12missing.t
old mode 100644
new mode 100755
diff --git a/t/31stack.t b/t/31stack.t
old mode 100644
new mode 100755
diff --git a/t/41die.t b/t/41die.t
old mode 100644
new mode 100755
diff --git a/t/42exc-dbix-class.t b/t/42exc-dbix-class.t
old mode 100644
new mode 100755
diff --git a/t/43exc-xml-libxml.t b/t/43exc-xml-libxml.t
old mode 100644
new mode 100755
diff --git a/t/50file.t b/t/50file.t
old mode 100644
new mode 100755
diff --git a/t/51syslog.t b/t/51syslog.t
old mode 100644
new mode 100755
diff --git a/t/52logdisp.t b/t/52logdisp.t
old mode 100644
new mode 100755
diff --git a/t/53log4perl.t b/t/53log4perl.t
old mode 100644
new mode 100755
diff --git a/t/54try.t b/t/54try.t
old mode 100644
new mode 100755
diff --git a/t/55throw.t b/t/55throw.t
old mode 100644
new mode 100755
diff --git a/t/60mojo.t b/t/60mojo.t
old mode 100644
new mode 100755
diff --git a/t/70dancer2.t b/t/70dancer2.t
old mode 100644
new mode 100755
diff --git a/t/DieTests.pm b/t/DieTests.pm
index bcc6a39..05e09f2 100644
--- a/t/DieTests.pm
+++ b/t/DieTests.pm
@@ -1,11 +1,4 @@
-# Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>].
-#  For other contributors see ChangeLog.
-# See the manual pages for details on the licensing terms.
-# Pod stripped from pm file by OODoc 2.02.
 package DieTests;
-use vars '$VERSION';
-$VERSION = '1.28';
-
 use warnings;
 use strict;
 
@@ -13,7 +6,15 @@ use Log::Report::Die qw/die_decode/;
 use Log::Report      qw/log-report/;
 use Carp;
 
-use Test::More tests => 27;
+use Test::More;
+
+BEGIN {
+    plan skip_all => "Error messages on $^O differ too much."
+        if $^O =~ /haiku$/;
+
+    plan tests => 27;
+}
+
 use DieTests;
 
 $! = 3;
diff --git a/xt/99pod.t b/xt/99pod.t
old mode 100644
new mode 100755