[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[no subject]
|
From: |
Patrice Dumas |
|
Date: |
Sat, 15 Jan 2022 08:40:25 -0500 (EST) |
branch: master
commit 1a5a9ca172a9bc0a78cba836e229eb858cdbc405
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Jan 15 14:39:51 2022 +0100
Minor changes in comments, pod, reorder code.
---
tp/Texinfo/Config.pm | 8 ++++--
tp/Texinfo/Convert/HTML.pm | 11 ++++++---
tp/Texinfo/Convert/Unicode.pm | 4 +--
tp/Texinfo/Convert/Utils.pm | 8 +++---
tp/Texinfo/ParserNonXS.pm | 4 +--
tp/Texinfo/Structuring.pm | 2 +-
tp/Texinfo/Translations.pm | 47 +++++++++++++++++++++++++++---------
tp/Texinfo/XS/parsetexi/Parsetexi.pm | 11 ++++-----
8 files changed, 64 insertions(+), 31 deletions(-)
diff --git a/tp/Texinfo/Config.pm b/tp/Texinfo/Config.pm
index ae91c45a82..eb07d24e0e 100644
--- a/tp/Texinfo/Config.pm
+++ b/tp/Texinfo/Config.pm
@@ -34,11 +34,15 @@ use Carp;
# for __( and p__( and some functions
use Texinfo::Common;
+
# for error messages, passed from main program through initialization
# function.
my $real_command_name = '';
+
+#####################################################################
# customization API, used from main program and from init files
+
my $cmdline_options;
my $main_program_default_options;
my $init_files_options = {};
@@ -182,7 +186,7 @@ sub GNUT_set_main_program_default($$)
}
# called both from main program and init files, for %options_as_lists
-# options with lists set un main program.
+# options with lists set in main program.
sub texinfo_add_to_option_list($$)
{
my $var = shift;
@@ -241,7 +245,7 @@ sub texinfo_add_valid_customization_option($)
# Output format API. Handled differently from customization option
# because a function from main program need to be called on formats, so
# there is a function called from the main program to get the format set
-# by in the init file.
+# in init files.
my $init_file_format;
sub texinfo_set_format_from_init_file($)
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index a30f962eba..4f1b35354c 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -67,15 +67,16 @@ use File::Copy qw(copy);
use Storable;
use Texinfo::Common;
-use Texinfo::Structuring;
+use Texinfo::Config;
+use Texinfo::Encoding;
use Texinfo::Convert::Unicode;
-use Texinfo::Convert::Utils;
use Texinfo::Convert::Texinfo;
+use Texinfo::Convert::Utils;
use Texinfo::Convert::Text;
-use Texinfo::Convert::Converter;
use Texinfo::Convert::NodeNameNormalization;
+use Texinfo::Structuring;
+use Texinfo::Convert::Converter;
-use Texinfo::Config;
require Exporter;
use vars qw($VERSION @ISA);
@@ -2320,6 +2321,8 @@ sub _convert_email_command($$$$)
$default_commands_conversion{'email'} = \&_convert_email_command;
+# FIXME set and use 'explained_commands' converter state. Should
+# there be an API instead?
sub _convert_explained_command($$$$)
{
my $self = shift;
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index 7a5fb772f7..5ae80669a5 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -52,7 +52,7 @@ sub import {
goto &Exporter::import;
}
-use vars qw($VERSION @ISA @EXPORT_OK %EXPORT_TAGS);
+use vars qw($VERSION @EXPORT_OK %EXPORT_TAGS);
%EXPORT_TAGS = ( 'all' => [ qw(
unicode_accent
@@ -1539,7 +1539,7 @@ sub string_width($)
return unpack("U0%32A*", $string);
if (! defined($string)) {
- Carp::cluck();
+ cluck();
}
my $width = 0;
foreach my $character(split '', $string) {
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index 25841c8b4a..eb77fc674e 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -303,7 +303,7 @@ __END__
=head1 NAME
-Texinfo::Convert::Utils - miscellaneous functions usable in simple converters
+Texinfo::Convert::Utils - miscellaneous functions usable in all converters
=head1 SYNOPSIS
@@ -325,8 +325,8 @@ No method is exported in the default case.
Most methods takes a I<$converter> as argument, in general optionally,
to get some information and use methods for error reporting,
-see L<Texinfo::Convert::Converter> and L<Texinfo::Report>. Also
-to tranlate strings, see L<Texinfo::Translations>.
+see L<Texinfo::Convert::Converter> and L<Texinfo::Report>.
+On strings translations, see L<Texinfo::Translations>.
=over
@@ -361,6 +361,8 @@ This function returns the heading with a number and the
appendix
part if needed. If I<$converter> is not defined, the resulting
string won't be translated.
+=back
+
=head1 SEE ALSO
L<Texinfo::Convert::Converter> and L<Texinfo::Translations>.
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index 7da4e7df41..964339d02c 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -749,7 +749,7 @@ sub _setup_parser {
}
}
foreach my $explained_command(keys(%explained_commands)) {
- if (!defined($parser->{'explained_commands'}->{$explained_command})) {
+ if (!defined($parser->{'explained_commands'}->{$explained_command})) {
$parser->{'explained_commands'}->{$explained_command} = {};
}
}
@@ -801,7 +801,7 @@ sub simple_parser(;$)
$parser->{'close_preformatted_commands'} =
$simple_parser_close_preformatted_commands;
foreach my $explained_command(keys(%explained_commands)) {
- if (!defined($parser->{'explained_commands'}->{$explained_command})) {
+ if (!defined($parser->{'explained_commands'}->{$explained_command})) {
$parser->{'explained_commands'}->{$explained_command} = {};
}
}
diff --git a/tp/Texinfo/Structuring.pm b/tp/Texinfo/Structuring.pm
index 561c0852b7..722107c34e 100644
--- a/tp/Texinfo/Structuring.pm
+++ b/tp/Texinfo/Structuring.pm
@@ -1922,7 +1922,7 @@ is set, use section names instead of node names in menu.
=item $entry = new_node_menu_entry($node, $use_sections)
Returns the texinfo tree corresponding to a single menu entry pointing to
-I<$node>. If I<$use_section> is set, use the section name instead of node
name.
+I<$node>. If I<$use_sections> is set, use the section name instead of node
name.
=item $top_node = nodes_tree($registrar, $configuration_informations,
$parser_informations, $nodes_list, $labels)
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index 9074c4b3c3..e62de40bee 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -28,6 +28,12 @@ use Encode;
use POSIX qw(setlocale LC_ALL);
use Locale::Messages;
+# note that there is a circular dependency with the parser module, as
+# the parser uses complete_indices() from this modules, while this modules
+# can use a parser. There is not problematic, however, as the
+# modules do not setup data such that their order of loading is not
+# important, as long as they load after their dependencies.
+
# to be able to load a (simple) parser if none was given to gdt.
use Texinfo::Parser;
@@ -197,7 +203,13 @@ sub gdt($$;$$$)
# next line taken from libintl perl, copyright Guido. sub __expand
$translation_result =~ s/\{($re)\}/\@txiinternalvalue\{$1\}/g;
}
-
+
+ # FIXME not sure if the added complexity of getting information from parser
+ # is worth it. The current use case, that is allow to specify the state of
+ # clickstyle and kbdinputstyle is relevant (though not implemented in thet XS
+ # parser, but could be) but not necessarily determining. Converters and
+ # users could easily avoir using @kbd and @click in the translated messages.
+
# determine existing parser, if any
my $current_parser;
if ($self) {
@@ -208,11 +220,12 @@ sub gdt($$;$$$)
}
}
- # Don't reuse the current parser itself, as (tested) the parsing goes
- # wrong, certainly because the parsed text can affect the parser state.
+ # We never reuse a parser directly as it is cleaner to get only the
+ # relevant information (if any). It could also mess with the parser
+ # state, though this has not been checked for a long time.
- # configuration only found in parser. Note that it is only available
- # for the NonXS parser.
+ # configuration only found in parser, not available through get_conf().
+ # Note that it is only available for the NonXS parser.
my $parser_conf;
if ($current_parser) {
foreach my $duplicated_conf ('clickstyle', 'kbdinputstyle') {
@@ -228,7 +241,8 @@ sub gdt($$;$$$)
}
}
}
- # accept @txiinternalvalue as a valid Texinfo command
+ # accept @txiinternalvalue as a valid Texinfo command, used to mark
+ # location in tree of substituted brace enclosed strings.
$parser_conf->{'accept_internalvalue'} = 1;
my $parser = Texinfo::Parser::simple_parser($parser_conf);
if ($parser->{'DEBUG'}) {
@@ -400,11 +414,11 @@ described as it is described in details elsewhere.
No method is exported.
The C<gdt> method is used to translate strings to be output in
-converted documents, and return a texinfo tree.
+converted documents, and returns, in general, a texinfo tree.
=over
-=item $tree = $converter->gdt($string, $replaced_substrings, $mode)
+=item $tree = $object->gdt($string, $replaced_substrings, $mode, $lang)
The I<$string> is a string to be translated. In the default case,
the function returns a Texinfo tree, as the string is interpreted
@@ -415,6 +429,20 @@ reference identifies what is to be substituted, and 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 I<$replaced_substrings> are replaced.
+The I<$object> is typically a converter, but can be any object that implements
+C<get_conf()>, or undefined (C<undef>). If not undefined, the information in
the
+I<$object> is used to determine the encoding, the documentlanguage and get some
+configuration information. I<$lang> is optional. If set, it overrides the
+documentlanguage.
+
+=begin comment
+
+If the I<$object> is a parser or is associated to a parser some
+information may be used, but it is different for the NonXS and
+XS parser, and may also not be such a good idea, therefore no
+documentation.
+
+=end comment
For example, in the following call, the string
I<See {reference} in @cite{{book}}> is translated, then
@@ -426,9 +454,6 @@ replaced by the associated texinfo tree text element:
{'reference' => $tree_reference,
'book' => {'text' => $book_name}});
-C<gdt> uses the information in the I<$converter> to know the
-encoding and documentlanguage.
-
C<gdt> uses a gettext-like infrastructure to retrieve the
translated strings, using the I<texinfo_document> domain.
diff --git a/tp/Texinfo/XS/parsetexi/Parsetexi.pm
b/tp/Texinfo/XS/parsetexi/Parsetexi.pm
index cc38f27b3a..84684f0087 100644
--- a/tp/Texinfo/XS/parsetexi/Parsetexi.pm
+++ b/tp/Texinfo/XS/parsetexi/Parsetexi.pm
@@ -30,13 +30,15 @@ use 5.00405;
use strict;
use warnings;
-require Exporter;
+use Storable qw(dclone); # standard in 5.007003
use Texinfo::Common;
use Texinfo::Report;
use Texinfo::Convert::NodeNameNormalization;
use Texinfo::Translations;
+require Exporter;
+
our @ISA = qw(Exporter);
our %EXPORT_TAGS = ( 'all' => [ qw(
parser
@@ -48,6 +50,8 @@ our %EXPORT_TAGS = ( 'all' => [ qw(
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
+my %parser_default_configuration =
+ (%Texinfo::Common::default_parser_customization_values);
sub get_conf($$)
{
@@ -56,11 +60,6 @@ sub get_conf($$)
return $self->{$var};
}
-my %parser_default_configuration =
- (%Texinfo::Common::default_parser_customization_values);
-
-use Storable qw(dclone); # standard in 5.007003
-
sub simple_parser {
goto &parser;
}