The diagnostics module extends the terse diagnostics normally emitted by
both the Perl compiler and the Perl interpreter, augmenting them with the more
explicative and endearing descriptions found in Chapter 9, Diagnostic Messages.
It affects the compilation phase of your program rather than merely the
execution phase.

To use in your program as a pragma, merely say:

use diagnostics;

at the start (or near the start) of your program. (Note
that this enables Perl's -w flag.) Your whole
compilation will then be subject to the enhanced diagnostics.
These are still issued to STDERR.

Due to the interaction between run-time and compile-time issues,
and because it's probably not a very good idea anyway,
you may not use:

no diagnostics

to turn diagnostics off at compile time. However, you can turn diagnostics on or
off at run-time by invoking diagnostics::enable() and
diagnostics::disable(), respectively.

The -verbose argument first prints out the perldiag(1) manpage
introduction before any other diagnostics. The $diagnostics::PRETTY
variable, if set in a BEGIN block, results in nicer escape sequences
for pagers:

While apparently a whole other program, splain is actually nothing
more than a link to the (executable) diagnostics.pm module.
It acts upon the standard error output of a Perl program, which you may
have treasured up in a file, or piped directly to splain.

The -v flag has the same effect as:

use diagnostics -verbose

The -p flag sets
$diagnostics::PRETTY to true. Since you're post-processing
with splain, there's no sense in being able to
enable() or disable() diagnostics.