@node Texinfo::Report
@chapter Texinfo::Report

@menu
* Texinfo@asis{::}Report NAME::
* Texinfo@asis{::}Report SYNOPSIS::
* Texinfo@asis{::}Report DESCRIPTION::
* Texinfo@asis{::}Report METHODS::
* Texinfo@asis{::}Report AUTHOR::
* Texinfo@asis{::}Report COPYRIGHT AND LICENSE::
@end menu

@node Texinfo::Report NAME
@section NAME

Texinfo::Report - Error storing and string translations for Texinfo modules

@node Texinfo::Report SYNOPSIS
@section SYNOPSIS

@verbatim
  @ISA = qw(Texinfo::Report);

  $converter->Texinfo::Report::new();
  
  if ($warning_happened) {
    $converter->line_warn(sprintf($converter->__("\@%s is wrongly used"),
                       $current->{'cmdname'}), $current->{'line_nr'});
  }
  
  my ($errors, $errors_count) = $converter->errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

  my $tree_translated = $converter->gdt('See {reference} in @cite{{book}}',
                       {'reference' => $tree_reference,
                        'book'  => {'text' => $book_name}});
@end verbatim

@node Texinfo::Report DESCRIPTION
@section DESCRIPTION

The Texinfo::Report module helps with string translations and errors 
handling.  It is used by Texinfo modules, Texinfo::Parser and 
Texinfo::Convert::Converter.  To use this module, the usual way is
to inherit Texinfo::Report methods and initialize Texinfo::Report
variables for a @emph{$converter} object, by calling 
@code{Texinfo::Report::new()} on the @emph{$converter} object.  This is done by 
Texinfo::Convert::Converter, for instance, so every module that inherits
Texinfo::Convert::Converter can automatically use the Texinfo::Report
methods in an object oriented way.

Besides the @code{new} method, @code{gdt} is used for strings translations, 
@code{errors} to report errors and the other methods to store errors
(and warnings).

@node Texinfo::Report METHODS
@section METHODS

No method is exported in the default case.  

The @code{new} method initializes Texinfo::Report related fields:

@verbatim
  $converter->Texinfo::Report::new()
@end verbatim

The @code{gdt} method is used to translate strings to be output in 
converted documents, and return a texinfo tree.

@table @asis
@item $tree = $converter->gdt($string, $replaced_substrings, $mode)
@anchor{Texinfo::Report $tree = $converter->gdt($string@comma{} $replaced_substrings@comma{} $mode)}

The @emph{$string} is a string to be translated.  In the default case, 
the function returns a Texinfo tree, as the string is 
interpreted as Texinfo code after
translation.  @emph{$replaced_substrings} is an optional 
hash reference specifying some 
substitution to be done after the translation.  The key of 
the @emph{$replaced_substrings} hash reference identifies what is to 
be substituted, the value is some string, texinfo tree or array content 
that is substituted in the resulting texinfo tree.
In the string to be translated word in brace matching keys of 
@emph{$replaced_substrings} are replaced.

@emph{$mode} is an optional string which may modify how the function
behave.  The possible values are

@table @asis
@item translated_text
@anchor{Texinfo::Report translated_text}

In that case the string is not considered to be Texinfo, a plain string
that is returned after translation and substitution.  The substitutions
may only be strings in that case.

@item translated_paragraph
@anchor{Texinfo::Report translated_paragraph}

In that case, the parsing of the Texinfo string is done in a 
context of a paragraph, not in the context of an inline text.

@end table

For example in the following call, the string 
@emph{See @{reference@} in @@cite@{@{book@}@}} is translated, then
parsed as a Texinfo string, with @emph{@{reference@}} substituted by
@emph{$tree_reference} in the resulting tree, and @emph{@{book@}} 
replaced by the associated texinfo tree text element:

@verbatim
  $tree = $converter->gdt('See {reference} in @cite{{book}}',
                       {'reference' => $tree_reference,
                        'book'  => {'text' => $book_name}});
@end verbatim

@code{gdt} uses the information in the @emph{$converter} to know the
encoding and documentlanguage.  More precisely, 
@code{$converter->@{'encoding_name'@}}, @code{$converter->@{'perl_encoding'@}}
and @code{$converter->get_conf('documentlanguage')} are used.

@code{gdt} use a gettext-like infrastructure to retrieve the 
translated strings, using the @emph{texinfo_document} domain.

@end table

The errors collected are available through the @code{errors} method, the other
methods allow to register errors and warnings.

@table @asis
@item ($error_warnings_list, $error_count) = errors ($converter)
@anchor{Texinfo::Report ($error_warnings_list@comma{} $error_count) = errors ($converter)}

This function returns as @emph{$error_count} the count of errors since
calling @code{new}.  The @emph{$error_warnings_list} is an array of hash references
one for each error, warning or error line continuation.  Each of these has 
the following keys:

@table @asis
@item type
@anchor{Texinfo::Report type}

May be @code{warning}, @code{error}, or @code{error continuation} (for a continuation of
an error line).

@item text
@anchor{Texinfo::Report text}

The text of the error.

@item error_line
@anchor{Texinfo::Report error_line}

The text of the error formatted with the file name, line number and macro
name, as needed.

@item line_nr
@anchor{Texinfo::Report line_nr}

The line number of the error or warning.

@item file_name
@anchor{Texinfo::Report file_name}

The file name where the error or warning occurs.

@item macro
@anchor{Texinfo::Report macro}

The user macro name that is expanded at the location of 
the error or warning.

@end table

@item $converter->line_warn($text, $line_nr)
@anchor{Texinfo::Report $converter->line_warn($text@comma{} $line_nr)}

@item $converter->line_error($text, $line_nr, $continuation)
@anchor{Texinfo::Report $converter->line_error($text@comma{} $line_nr@comma{} $continuation)}

Register a warning or an error.  The @emph{$text} is the text of the
error or warning.  The optional @emph{$line_nr} holds the information
on the error or warning location.  It is associated with the @emph{line_nr} 
key of Texinfo tree elements as described in @ref{Texinfo::Parser line_nr}
for the @@-commands.  The @emph{$line_nr} structure is described in @ref{, errors,, error_warnings_list_error_count__errors_converter}
above.  If @emph{$continuation} is set, the line is an error message continuation
line and not a new error.

@item $converter->document_warn($text)
@anchor{Texinfo::Report $converter->document_warn($text)}

@item $converter->document_error($text)
@anchor{Texinfo::Report $converter->document_error($text)}

Register a document-wide error or warning.  @emph{$text} is the error or
warning message.

@item $converter->file_line_warn($text, $file, $line_nr)
@anchor{Texinfo::Report $converter->file_line_warn($text@comma{} $file@comma{} $line_nr)}

Register the warning message @emph{$text} for file @emph{$file}, with, optionally
the line @emph{$line_nr} in the file.

@item $converter->file_line_error($text, $file, $line_nr)
@anchor{Texinfo::Report $converter->file_line_error($text@comma{} $file@comma{} $line_nr)}

Register the error message @emph{$text} for file @emph{$file}, with, optionally
the line @emph{$line_nr} in the file.

@end table

@node Texinfo::Report AUTHOR
@section AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo::Report COPYRIGHT AND LICENSE
@section COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License,
or (at your option) any later version.