.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Maketext::Utils::Phrase::Norm::Consider 3"
.TH Locale::Maketext::Utils::Phrase::Norm::Consider 3 "2014-11-18" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Normalization"
.IX Header "Normalization"
The checks in here are for various best practices to consider while crafting phrases.
.SS "Rationale"
.IX Subsection "Rationale"
These are warnings only and are meant to help point out things that typically are best done differently but could possibly be legit and thus a human needs to consider and sort it out.
.SH "possible violations"
.IX Header "possible violations"
None
.SH "possible warnings"
.IX Header "possible warnings"
.IP "Entire phrase is bracket notation, is there a better way in this case?" 4
.IX Item "Entire phrase is bracket notation, is there a better way in this case?"
This will append '[comment,does this phrase really need to be entirely bracket notation?]' to the phrase.
.Sp
The idea behind it is that a phrase that is entirely bracket notation is a sure sign that it needs done differently.
.Sp
For example:
.RS 4
.IP "method" 4
.IX Item "method"
.Vb 1
\&    $lh\->maketext(\*(Aq[numf,_1]\*(Aq,$n);
.Ve
.Sp
There is no need to translate that, it’d be the same in every locale!
.Sp
You would simply do this:
.Sp
.Vb 1
\&    $lh\->numf($n)
.Ve
.IP "overly complex" 4
.IX Item "overly complex"
.Vb 1
\&    $lh\->maketext(\*(Aq[boolean,_1,Your foo has been installed.,Your foo has been uninstalled.]\*(Aq,$is_install);
.Ve
.Sp
Unnecessarily difficult to read/work with and without benefit. You can't use any other bracket notation. You can probably spot other issues too.
.Sp
Depending on the situation you might do either of these:
.Sp
.Vb 6
\&    if ($is_install) {
\&        $lh\->maketext(\*(AqYour foo has been installed.\*(Aq);
\&    }
\&    else {
\&        $lh\->maketext(\*(AqYour foo has been uninstalled.\*(Aq);
\&    }
.Ve
.Sp
or if you prefer to keep the variant–pair as one unit:
.Sp
.Vb 1
\&    $lh\->maketext(\*(AqYour foo has been [boolean,_1,installed,uninstalled].\*(Aq,$is_install);
.Ve
.RE
.RS 4
.RE
.IP "Hard coded URLs can be a maintenance nightmare, why not pass the \s-1URL\s0 in so the phrase does not change if the \s-1URL\s0 does" 4
.IX Item "Hard coded URLs can be a maintenance nightmare, why not pass the URL in so the phrase does not change if the URL does"
.Vb 1
\&     $lh\->maketext(\*(AqYou can [output,url,http://support.example.com,visit our support page] for further assistance.\*(Aq);
.Ve
.Sp
What happens when support.example.com changes to custcare.example.com? You have to change, not only the caller but the lexicons and translations, ick!
.Sp
Then after you do that your boss says, oh wait actually it needs to be customer.example.com …
.Sp
But if you had passed it in as an argument:
.Sp
.Vb 1
\&     $lh\->maketext(\*(AqYou can [output,url,_1,visit our support page] for further assistance.\*(Aq, $url_db{\*(Aqsupport_url\*(Aq});
.Ve
.Sp
Now when support.example.com changes to custcare.example.com you update 'support_url' in \f(CW%url_db\fR–done.
.Sp
He wants it to be customer.example.com, no problem update 'support_url' in \f(CW%url_db\fR–done.
.IP "Bare variable can lead to ambiguous output" 4
.IX Item "Bare variable can lead to ambiguous output"
.Vb 1
\&    $lh\->maketext(\*(AqThe checksum was [_1].\*(Aq, $sum);
.Ve
.Sp
If \f(CW$sum\fR is empty or undef you get odd spacing (e.g. “was .” instead of “was.”), could lose info, (e.g. “wait, the checksum is what now?”), or change meaning completely (e.g. what if the checksum was the string “BAD”).
.Sp
.Vb 2
\&    \*(AqThe checksum was .\*(Aq
\&    \*(AqThe checksum was BAD.\*(Aq # what! my data is corrupt ⁈
.Ve
.Sp
That applies even if it is decorated some way:
.Sp
.Vb 2
\&    \*(AqThe checksum was <code></code>.\*(Aq
\&    \*(AqThe checksum was <code>BAD</code>.\*(Aq # what my data is corrupt ⁈
.Ve
.Sp
It promotes evil partial phrases (i.e. that are untranslatable which is sort of the opposite of localizing things no?)
.Sp
.Vb 1
\&    $lh\->maketext(\*(AqThe checksum was [_1].\*(Aq, $lh\->maketext(\*(Aqinserted into the database)); # !!!! DON’T DO THIS !!!!
.Ve
.Sp
One way to visually distinguish what you intend regardless of the value given is simply to quote it:
.Sp
.Vb 1
\&   The checksum was “[_1]”.
.Ve
.Sp
becomes:
.Sp
.Vb 4
\&   The checksum was “”.                    # It is obvious that the sum is empty
\&   The checksum was “ ”.                   # It is obvious that the sum is all whitespace
\&   The checksum was “BAD”.                 # It is obvious that it is a string made up of B, A, and D and not a statement that the sum has a problem
\&   The checksum was “perfectly awesome”.   # It looks weird so someone probably will notice and ask you to fix your code
.Ve
.Sp
In other words:
.RS 4
.IP "\fIUsing “ and ” disambiguates the entire string’s intent.\fR No accidental or malicious meaning changes." 4
.IX Item "Using “ and ” disambiguates the entire string’s intent. No accidental or malicious meaning changes."
.PD 0
.IP "\fIThey also provide substance to a variable that may very well be null.\fR" 4
.IX Item "They also provide substance to a variable that may very well be null."
.PD
For browsers, any span-level tag which is empty is not expressed in the rendering of the page. Therefore if we wrap variable expressions in span-level \s-1DOM,\s0 the user stands a very real chance of seeing incompleteness or potentially not noticing errors at all.
.IP "\fIHaving this dis-ambiguation also assists the translator:\fR" 4
.IX Item "Having this dis-ambiguation also assists the translator:"
.RS 4
.PD 0
.IP "They can use whatever their locale uses without needing bracket notation (e.g. « and »)." 4
.IX Item "They can use whatever their locale uses without needing bracket notation (e.g. « and »)."
.PD
This allows for flexibility since brakcet notation is not nestable (and should not be since it isn’t a templating engine).
.IP "When the translators see <strong> or any other wrapping element in the phrase, they will not immediately know what’s going on." 4
.IX Item "When the translators see <strong> or any other wrapping element in the phrase, they will not immediately know what’s going on."
.RE
.RS 4
.RE
.PD 0
.IP "\fIIt helps programmers make better choices.\fR" 4
.IX Item "It helps programmers make better choices."
.RE
.RS 4
.PD
.Sp
\&\fIPerhaps quotes are the wrong thing in a given instance:\fR Depending on what you’re doing other things might work too:
.IP "Trailing introductory “:”:" 4
.IX Item "Trailing introductory “:”:"
.Vb 1
\&   An error has occured: [_2]
.Ve
.IP "Alternate text:" 4
.IX Item "Alternate text:"
.Vb 1
\&   Sorry, [is_defined,_2,“_2” is an invalid,you must specify a valid] value for “[_1]”.
.Ve
.IP "Parentheses:" 4
.IX Item "Parentheses:"
.Vb 1
\&   The domain ([_1]) could not be found.
\&
\&   The clown (AKA [_1]) is down.
\&
\&   The network ([_1] in IPv6) is up.
.Ve
.IP "Comma reference:" 4
.IX Item "Comma reference:"
.Vb 1
\&   The user, [_1], already exists.
.Ve
.IP "Etc etc" 4
.IX Item "Etc etc"
.RE
.RS 4
.RE
.SH "Checks only run under extra filter mode:"
.IX Header "Checks only run under extra filter mode:"
None.