.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Log::Report::Extract::PerlPPI 3pm"
.TH Log::Report::Extract::PerlPPI 3pm "2018-04-16" "perl v5.26.1" "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 "NAME"
Log::Report::Extract::PerlPPI \- Collect translatable strings from Perl using PPI
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Log::Report::Extract::PerlPPI
\&   is a Log::Report::Extract
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& my $ppi = Log::Report::Extract::PerlPPI\->new
\&  ( lexicon => \*(Aq/usr/share/locale\*(Aq
\&  );
\& $ppi\->process(\*(Aqlib/My/Pkg.pm\*(Aq);  # call for each .pm file
\& $ppi\->showStats;                 # optional
\& $ppi\->write;
\&
\& # See script  xgettext\-perl
\& bin/xgettext\-perl \-p $lexdir @source_dirs
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module helps maintaining the \s-1POT\s0 files, updating the list of
message-ids which are kept in them.  After initiation, the \fIprocess()\fR
method needs to be called with all files which changed since last processing
and the existing \s-1PO\s0 files will get updated accordingly.
.PP
If no translations exist yet, one \f(CW\*(C`$lexicon/$domain.po\*(C'\fR file will be
created.  If you want to start a translation, copy \f(CW\*(C`$lexicon/$domain.po\*(C'\fR
to \f(CW\*(C`$lexicon/$domain/$lang.po\*(C'\fR and edit that file.  You may use
\&\f(CW\*(C`poedit\*(C'\fR to edit po-files.  There are many smart translation management
applications which can hand po-files, for instance Pootle and Weblate.
.PP
Do not forget to add the new po-file to your distribution (\s-1MANIFEST\s0)
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Log::Report::Extract.
.SS "The extraction process"
.IX Subsection "The extraction process"
All pm-files need to be processed in one go: no incremental processing!
.PP
The Perl source is parsed using \s-1PPI,\s0 which does understand Perl syntax
quite well, but does not support all features.
.PP
Automatically, the textdomain of the translations is discovered, as
first parameter of \f(CW\*(C`use Log::Report\*(C'\fR.  You may switch textdomain inside
one pm-file.
.PP
When all files have been processed, during the \fIwrite()\fR, all existing
po-files for all discovered textdomains will get updated.  Not only the
\&\f(CW\*(C`$lexicon/$domain.po\*(C'\fR template, but also all \f(CW\*(C`$lexicon/$domain/$lang.po\*(C'\fR
will be replaced.  When a msgid has disappeared, existing translations
will get disabled, not removed.  New msgids will be added and flagged
\&\*(L"fuzzy\*(R".
.PP
\fIWhat is extracted?\fR
.IX Subsection "What is extracted?"
.PP
This script will extract the msgids used in \f(CW\*(C`_\|_()\*(C'\fR, \f(CW\*(C`_\|_x()\*(C'\fR, \f(CW\*(C`_\|_xn()\*(C'\fR,
and \f(CW\*(C`_\|_n()\*(C'\fR (implemented by Log::Report) For instance
.PP
.Vb 5
\&  _\|_x"msgid", @more
\&  _\|_x\*(Aqmsgid\*(Aq, @more  <\-\-\- no!  syntax error!
\&  _\|_x("msgid", @more)
\&  _\|_x(\*(Aqmsgid\*(Aq, @more)
\&  _\|_x(msgid => @more)
.Ve
.PP
Besides, there are some helpers which are no-ops in the code, only to fill
the po-tables: \f(CW\*(C`N_\|_()\*(C'\fR, \f(CW\*(C`N_\|_n()\*(C'\fR, \f(CW\*(C`N_\|_()\*(C'\fR
.PP
\fIWhat is not extracted?\fR
.IX Subsection "What is not extracted?"
.PP
\&\fBNot\fR extracted are the usage of anything above, where the first
parameter is not a simple string.  Not extracted are
.PP
.Vb 4
\&  _\|_x($format, @more)
\&  _\|_x$format, @more
\&  _\|_x(+$format, _domain => \*(Aqother domain\*(Aq, @more)
\&  _\|_x($first.$second, @more)
.Ve
.PP
In these cases, you have to use \f(CW\*(C`N_\|_()\*(C'\fR functions to declare the possible
values of \f(CW$format\fR.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Log::Report::Extract.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Log::Report::Extract.
.IP "Log::Report::Extract::PerlPPI\->\fBnew\fR(%options)" 4
.IX Item "Log::Report::Extract::PerlPPI->new(%options)"
Inherited, see \*(L"Constructors\*(R" in Log::Report::Extract
.SS "Accessors"
.IX Subsection "Accessors"
Extends \*(L"Accessors\*(R" in Log::Report::Extract.
.ie n .IP "$obj\->\fBaddPot\fR($domain, $pot, %options)" 4
.el .IP "\f(CW$obj\fR\->\fBaddPot\fR($domain, \f(CW$pot\fR, \f(CW%options\fR)" 4
.IX Item "$obj->addPot($domain, $pot, %options)"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBcharset\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBcharset\fR()" 4
.IX Item "$obj->charset()"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBdomains\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdomains\fR()" 4
.IX Item "$obj->domains()"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBindex\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBindex\fR()" 4
.IX Item "$obj->index()"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBpots\fR($domain)" 4
.el .IP "\f(CW$obj\fR\->\fBpots\fR($domain)" 4
.IX Item "$obj->pots($domain)"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.SS "Processors"
.IX Subsection "Processors"
Extends \*(L"Processors\*(R" in Log::Report::Extract.
.ie n .IP "$obj\->\fBcleanup\fR(%options)" 4
.el .IP "\f(CW$obj\fR\->\fBcleanup\fR(%options)" 4
.IX Item "$obj->cleanup(%options)"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBprocess\fR($filename, %options)" 4
.el .IP "\f(CW$obj\fR\->\fBprocess\fR($filename, \f(CW%options\fR)" 4
.IX Item "$obj->process($filename, %options)"
Update the domains mentioned in the \f(CW$filename\fR.  All textdomains defined
in the file will get updated automatically, but not written before
all files where processed.
.Sp
.Vb 2
\& \-Option \-\-Default
\&  charset  \*(Aqiso\-8859\-1\*(Aq
.Ve
.RS 4
.IP "charset => \s-1STRING\s0" 2
.IX Item "charset => STRING"
.RE
.RS 4
.RE
.PD 0
.ie n .IP "$obj\->\fBshowStats\fR( [$domains] )" 4
.el .IP "\f(CW$obj\fR\->\fBshowStats\fR( [$domains] )" 4
.IX Item "$obj->showStats( [$domains] )"
.PD
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBstore\fR( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )" 4
.el .IP "\f(CW$obj\fR\->\fBstore\fR( \f(CW$domain\fR, \f(CW$filename\fR, \f(CW$linenr\fR, \f(CW$context\fR, \f(CW$msg\fR, [$msg_plural] )" 4
.IX Item "$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBwrite\fR( [$domain] )" 4
.el .IP "\f(CW$obj\fR\->\fBwrite\fR( [$domain] )" 4
.IX Item "$obj->write( [$domain] )"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Log-Report-Lexicon distribution version 1.11,
built on March 22, 2018. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2007\-2018 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR