When Perl is run with the -Do switch or its equivalent, overloading
induces diagnostic messages.
[ cut para for brevity's sake]
The module might issue the following warnings:
(W) The call to overload::constant contained an odd number of arguments.
The arguments should come in pairs.
(W) You tried to overload a constant type the overload package is unaware of.
(W) The second (fourth, sixth, ...) argument of overload::constant needs
to be a code reference. Either an anonymous subroutine, or a reference
to a subroutine.
------------------ example ends ----------------------
In this case, the only thing to do is insert a start tag for the
presentation (which will be available through the -verbose flag),
another one for the messages, and the corresponding end flags.
The result is:
----------------- example begins ---------------------
start description
When Perl is run with the -Do switch or its equivalent, overloading
induces diagnostic messages.
[ cut para for brevity's sake]
stop
The module might issue the following warnings:
start items
Odd number of arguments for overload::constant
(W) The call to overload::constant contained an odd number of arguments.
The arguments should come in pairs.
`%s' is not an overloadable type
(W) You tried to overload a constant type the overload package is unaware of.
`%s' is not a code reference
(W) The second (fourth, sixth, ...) argument of overload::constant needs
to be a code reference. Either an anonymous subroutine, or a reference
to a subroutine.
stop
------------------ example ends ----------------------
That's all!
In this case, the generic messages have only printf-like specifiers, no
Perl-like variable interpolation, so there was nothing to change.
If the message includes interpolated variables, they must be replaced
by printf-like specifiers. E.g.
would be replaced by
NOT SO GOOD, THE EXPLANATIONS DO NOT EXIST
------------------------------------------
If the pod documentation does not contain the error messages and
their explanations, well... you have to type them (that is, if you
think explanations will help your users; if you don't think so, don't bother
about it). Use the same format as perldiag.pod and overload.pm, and
include the start and stop tags.
SPECIAL CASE, THE % CHARACTER
-----------------------------
This character must be handled specially because it is the prefix for
printf specifiers. Depending on the characters following the %, you
may have to double it. In other cases, no confusion can arise, so you
can use a single % char, for example, if the error message refers to
%ENV.
If you double the % character (either you have to, or you choose to do so),
it may puzzle a (rather dumb) user. If you do not, the message
would be reported by the -debug=128 option, whose purpose is to check
that all printf specifiers are correctly dealt with by the diagnostics.pm
module. So this debug option reports all the % character that are not accounted
for. But if a user that uses this option is a user bright enough
to look under the hood of my (and your) module, and to recognize
a false positive when seeing one.
SPECIAL CASE, THE \377 CHARACTER
--------------------------------
The lingua franca on CPAN (and most computer-related activities) is English.
So, you should normally code and document your module in English. Therefore,
your error messages will contain 7-bit ASCII only.
Yet, there are a few modules that are useful to a single
community. Most notably, there are Cz:: and No:: modules, which
include error messages and documentation in Czech and Norwegian. So,
the error messages may contain ISO-8859-n characters.
The problem is, the \377 char (y with umlaut) has a special role in
diagnostics.pm. So, you should either rephrase your error message and
use words that do not contain this letter, or replace it by %c.
