[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: Change in comment and in modules and texi2any fun
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: Change in comment and in modules and texi2any functions documentation |
|
Date: |
Sun, 16 Jul 2023 08:01:56 -0400 |
This is an automated email from the git hooks/post-receive script.
pertusus pushed a commit to branch master
in repository texinfo.
The following commit(s) were added to refs/heads/master by this push:
new df67caaf9b Change in comment and in modules and texi2any functions
documentation
df67caaf9b is described below
commit df67caaf9bdfa795fe3adcc5b18d0fe89ce3a909
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Jul 16 14:00:18 2023 +0200
Change in comment and in modules and texi2any functions documentation
---
doc/texi2any_api.texi | 27 ++++++++++++++--------
tp/Texinfo/Convert/Converter.pm | 3 +++
tp/Texinfo/Convert/DocBook.pm | 5 +++-
tp/Texinfo/Convert/HTML.pm | 6 +++--
tp/Texinfo/Convert/IXINSXML.pm | 11 +++++----
tp/Texinfo/Convert/Info.pm | 1 +
tp/Texinfo/Convert/LaTeX.pm | 18 ++++++++-------
tp/Texinfo/Convert/NodeNameNormalization.pm | 6 ++---
tp/Texinfo/Convert/PlainTexinfo.pm | 1 +
tp/Texinfo/Convert/Plaintext.pm | 6 +++--
tp/Texinfo/Convert/TexinfoSXML.pm | 5 +++-
tp/Texinfo/Convert/TexinfoXML.pm | 5 +++-
tp/Texinfo/Convert/TextContent.pm | 1 +
tp/Texinfo/Convert/Unicode.pm | 10 ++++----
tp/Texinfo/Convert/Utils.pm | 36 ++++++++++++++++++-----------
tp/texi2any.pl | 3 ++-
16 files changed, 94 insertions(+), 50 deletions(-)
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index 3dfcb65f3c..a46e9fbe75 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -215,7 +215,7 @@ In the @code{Texinfo::Config} namespace, the functions
names beginning with
functions in init files should never begin with those prefixes.
The HTML converter is not available directly in the init files namespace,
-instead it is passed to functions defined in init files and registered as
+instead it is passed to functions defined in init files that are registered as
functions to be called from the converter. @xref{User Defined Functions}.
@@ -229,8 +229,14 @@ retrieve their values. New variables can also be added.
The customization variables also valid in the main program out of the HTML
converter are handled differently if they are strings or
-arrays. The customization variables only relevant for the conversion phase
-are always set like string variables, in particular array or hash references.
+arrays. Conversely, customization variables only relevant for the conversion
+phase set in the main program are always set like string variables, in
+particular by associating array or hash references to customization variables.
+
+This section describes customization variables set in the main program. These
+variables are in general passed to converters. It is also possible to set
+customization variables in the converters only, not in the main program.
+This is explained later on (@pxref{Conversion Customization Variables}).
@node Setting Main Program String Variables
@subsection Setting Main Program String Variables
@@ -320,11 +326,11 @@ list associated with the variable with
@code{texinfo_add_to_option_list}, and re
@subsection Setting Converter Variables in Main Program
Array and hash references customization variables values relevant in converters
-only (not in main program) can be set through the main program in init files.
-These variables cannot be set on the command-line. They are documented in the
-customization documentation, not in the main Texinfo manual. Such arrays or
-hashes references can be passed through @code{texinfo_set_from_init_file}. For
-example:
+only (not in main program, but in the HTML converter) can be set through the
+main program in init files. These variables cannot be set on the command-line.
+They are documented in the customization documentation, not in the main Texinfo
+manual. Such arrays or hashes references can be passed through
+@code{texinfo_set_from_init_file}. For example:
@example
my @@SECTION_BUTTONS =
@@ -1627,10 +1633,11 @@ converter. Some variables are also set in the converter
based on the main
program customization variables. Finally, some variables should be set or
reset
during conversion, in particular when converting the tree representing the
Texinfo document, when expanding the tree element corresponding to @@-commands
-associated with customization variables.
+associated with customization variables
+(@pxref{Customization Variables for @@-Commands,,, texinfo, Texinfo}).
The functions described here should be used in user defined functions, but
-should not be used out of functions. Conversly, the similar functions used to
+should not be used out of functions. Conversely, the similar functions used to
set customization variables from init files without a converter should not be
used in functions, but should be used out of functions in init files
(@pxref{Managing Customization Variables}).
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 09467afcfe..ee4dec6847 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -75,12 +75,15 @@ my %defaults = (
# rarely, output_format. It would be good to keep it that way and add
# customization options instead.
my %common_converters_defaults = (
+ # Following are set in the main program
'language_config_dirs' => undef,
'converted_format' => undef,
# can be different from the converted_format, for example, epub3
# output format converted format is html.
'output_format' => undef,
'structuring' => undef,
+
+ # Not set in the main program
'translated_commands' => {'error' => 'error@arrow{}',},
# This is the default, mainly for tests; the caller should set them. These
diff --git a/tp/Texinfo/Convert/DocBook.pm b/tp/Texinfo/Convert/DocBook.pm
index 05eec0b88b..87bd87d982 100644
--- a/tp/Texinfo/Convert/DocBook.pm
+++ b/tp/Texinfo/Convert/DocBook.pm
@@ -50,10 +50,13 @@ my %brace_commands = %Texinfo::Commands::brace_commands;
my $nbsp = '&#'.hex('00A0').';';
my %defaults = (
+ # Not a customization option variable
+ 'converted_format' => 'docbook',
+
+ # Customization option variables
'FORMAT_MENU' => 'nomenu',
'EXTENSION' => 'xml', # dbk?
'OUTPUT_ENCODING_NAME' => 'utf-8',
- 'converted_format' => 'docbook',
'SPLIT' => 0,
'documentlanguage' => undef,
'OPEN_QUOTE_SYMBOL' => '&#'.hex('2018').';',
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index f43e0d9dd2..2ee269ff01 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -1860,6 +1860,10 @@ sub convert_tree_new_formatting_context($$;$$$)
}
my %defaults = (
+ # Not a customization option variable
+ 'converted_format' => 'html',
+
+ # Customization option variables
'AVOID_MENU_REDUNDANCY' => 0,
'BIG_RULE' => '<hr>',
'BODYTEXT' => undef,
@@ -1943,8 +1947,6 @@ my %defaults = (
'Toc_Frame' => '_toc_frame',
},
- # non-customization variable converter defaults
- 'converted_format' => 'html',
);
foreach my $buttons ('CHAPTER_BUTTONS', 'MISC_BUTTONS', 'TOP_BUTTONS') {
diff --git a/tp/Texinfo/Convert/IXINSXML.pm b/tp/Texinfo/Convert/IXINSXML.pm
index 0945452e91..bc4b252832 100644
--- a/tp/Texinfo/Convert/IXINSXML.pm
+++ b/tp/Texinfo/Convert/IXINSXML.pm
@@ -43,15 +43,18 @@ $VERSION = '7.0dev';
my %defaults = (
- 'FORMAT_MENU' => 'menu',
- 'EXTENSION' => 'ixin',
- 'OUTPUT_ENCODING_NAME' => 'utf-8',
+ # Not customization option variables
# next two are replaced by the main program value if called from
# the main program. 'output_format' is also 'ixinsxml' when set by
# the main program, but 'converted_format' is set to 'ixinsxml'.
# More on that subject below.
'converted_format' => 'texinfosxml',
'output_format' => 'ixinsxml',
+
+ # Customization option variables
+ 'FORMAT_MENU' => 'menu',
+ 'EXTENSION' => 'ixin',
+ 'OUTPUT_ENCODING_NAME' => 'utf-8',
'SPLIT' => 0,
'documentlanguage' => 'en',
'USE_NODES' => 1,
@@ -71,7 +74,7 @@ sub converter_defaults($$)
# inheriting format specific functions is used to select the output format,
# but it could theoretically be needed for a flexible conversion
# (since the IXIN project is inactive, the corresponding code is not updated
-# acively either, so it is unlikely to change, though).
+# actively either, so it is unlikely to change, though).
sub converter_initialize($) { my $self = shift;
$self->{'converted_format'} = $defaults{'converted_format'};
diff --git a/tp/Texinfo/Convert/Info.pm b/tp/Texinfo/Convert/Info.pm
index 890850ed3e..9ea94c3b3f 100644
--- a/tp/Texinfo/Convert/Info.pm
+++ b/tp/Texinfo/Convert/Info.pm
@@ -42,6 +42,7 @@ $VERSION = '7.0dev';
my $STDIN_DOCU_NAME = 'stdin';
my %defaults = Texinfo::Convert::Plaintext::converter_defaults(undef, undef);
+# Customization option variables
$defaults{'FORMAT_MENU'} = 'menu';
$defaults{'EXTENSION'} = 'info';
$defaults{'USE_SETFILENAME_EXTENSION'} = 1;
diff --git a/tp/Texinfo/Convert/LaTeX.pm b/tp/Texinfo/Convert/LaTeX.pm
index bb3033022a..50b336e38b 100644
--- a/tp/Texinfo/Convert/LaTeX.pm
+++ b/tp/Texinfo/Convert/LaTeX.pm
@@ -777,23 +777,25 @@ foreach my $command
(keys(%{$LaTeX_style_brace_commands{'cmd_text'}})) {
my %defaults = (
- 'OUTPUT_CHARACTERS' => 0,
- 'FORMAT_MENU' => 'nomenu',
- 'EXTENSION' => 'tex',
-
- 'documentlanguage' => undef,
- 'paragraphindent' => undef, # global default is for Info/Plaintext
-
+ # Not customization option variables
'converted_format' => 'latex',
# FIXME this sets an option that is not a customization variable
# and will not be documented anywhere. It should probably be better
- # to add and document a customization in the Texinfo manual if needed.
+ # to add and document a customization variable in the Texinfo manual
+ # if needed.
# For LaTeX in general, it could make sense to have some customization,
# for example of packages, fonts, document type, to be discussed/though
# about how to setup this customization.
# FIXME any idea what could be used?
'floats_extension' => 'tfl',
+
+ # Customization option variables
+ 'OUTPUT_CHARACTERS' => 0,
+ 'FORMAT_MENU' => 'nomenu',
+ 'EXTENSION' => 'tex',
+ 'documentlanguage' => undef,
+ 'paragraphindent' => undef, # global default is for Info/Plaintext
);
diff --git a/tp/Texinfo/Convert/NodeNameNormalization.pm
b/tp/Texinfo/Convert/NodeNameNormalization.pm
index 31d6dd1ffc..d95cf722b8 100644
--- a/tp/Texinfo/Convert/NodeNameNormalization.pm
+++ b/tp/Texinfo/Convert/NodeNameNormalization.pm
@@ -441,7 +441,7 @@ Texinfo::Convert::NodeNameNormalization - Normalize and
transliterate Texinfo tr
=head1 SYNOPSIS
use Texinfo::Convert::NodeNameNormalization qw(normalize_node
- normalize_transliterate_texinfo);
+ normalize_transliterate_texinfo);
my $normalized = normalize_node({'contents' => $node_contents});
@@ -457,8 +457,8 @@ Texinfo to other formats. There is no promise of API
stability.
C<Texinfo::Convert::NodeNameNormalization> allows to normalize node names,
with C<normalize_node> following the specification described in the
-Texinfo manual I<HTML Xref> node. This is usefull each time one want a
-unique identifier for Texinfo content that is only composed of letter,
+Texinfo manual I<HTML Xref> node. This is useful whenever one want a
+unique identifier for Texinfo content, which is only composed of letter,
digits, C<-> and C<_>. In L<Texinfo::Parser>, C<normalize_node> is used
for C<@node>, C<@float> and C<@anchor> names normalization, but also C<@float>
types and C<@acronym> and C<@abbr> first argument.
diff --git a/tp/Texinfo/Convert/PlainTexinfo.pm
b/tp/Texinfo/Convert/PlainTexinfo.pm
index 2e1b69c524..4c24a946b8 100644
--- a/tp/Texinfo/Convert/PlainTexinfo.pm
+++ b/tp/Texinfo/Convert/PlainTexinfo.pm
@@ -35,6 +35,7 @@ $VERSION = '7.0dev';
my %defaults = (
+ # Customization option variables
'EXTENSION' => 'texi',
# different from the default, which is undef
'OUTFILE' => '-',
diff --git a/tp/Texinfo/Convert/Plaintext.pm b/tp/Texinfo/Convert/Plaintext.pm
index 4a1504b399..6bc9b59fba 100644
--- a/tp/Texinfo/Convert/Plaintext.pm
+++ b/tp/Texinfo/Convert/Plaintext.pm
@@ -358,6 +358,10 @@ foreach my $command ('var', 'cite', 'dmn',
keys(%brace_code_commands)) {
}
my %defaults = (
+ # Not a customization option variable
+ 'converted_format' => '',
+
+ # Customization options
'ENABLE_ENCODING' => 1,
'ASCII_DASHES_AND_QUOTES' => 1,
'ASCII_GLYPH' => 0,
@@ -369,8 +373,6 @@ my %defaults = (
# different from the default, which is undef
'OUTFILE' => '-',
'documentlanguage' => undef,
-
- 'converted_format' => '',
'USE_NODES' => 1,
);
diff --git a/tp/Texinfo/Convert/TexinfoSXML.pm
b/tp/Texinfo/Convert/TexinfoSXML.pm
index 13e7b4ee62..962366d158 100644
--- a/tp/Texinfo/Convert/TexinfoSXML.pm
+++ b/tp/Texinfo/Convert/TexinfoSXML.pm
@@ -36,10 +36,13 @@ $VERSION = '7.0dev';
# SXML specific
my %defaults = (
+ # Not a customization option variable
+ 'converted_format' => 'texinfosxml',
+
+ # Customization option variables
'FORMAT_MENU' => 'menu',
'EXTENSION' => 'sxml',
'OUTPUT_ENCODING_NAME' => 'utf-8',
- 'converted_format' => 'texinfosxml',
'SPLIT' => 0,
'documentlanguage' => 'en',
);
diff --git a/tp/Texinfo/Convert/TexinfoXML.pm b/tp/Texinfo/Convert/TexinfoXML.pm
index d076c1f4d1..594d4fdd06 100644
--- a/tp/Texinfo/Convert/TexinfoXML.pm
+++ b/tp/Texinfo/Convert/TexinfoXML.pm
@@ -40,10 +40,13 @@ $VERSION = '7.0dev';
# TexinfoXML specific
my %defaults = (
+ # Not a customization option variable
+ 'converted_format' => 'xml',
+
+ # Customization option variables
'FORMAT_MENU' => 'menu',
'EXTENSION' => 'xml',
'OUTPUT_ENCODING_NAME' => 'utf-8',
- 'converted_format' => 'xml',
'SPLIT' => 0,
'documentlanguage' => 'en',
);
diff --git a/tp/Texinfo/Convert/TextContent.pm
b/tp/Texinfo/Convert/TextContent.pm
index a3d3fd50d3..d9d26009db 100644
--- a/tp/Texinfo/Convert/TextContent.pm
+++ b/tp/Texinfo/Convert/TextContent.pm
@@ -59,6 +59,7 @@ foreach my $type ('ignorable_spaces_after_command',
}
my %defaults = (
+ # Customization option variables
'FORMAT_MENU' => 'menu',
# different from the default, which is undef
'OUTFILE' => '-',
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index 18341f8fd9..2dfb7511ec 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -1661,6 +1661,7 @@ Texinfo::Convert::Unicode - Representation as Unicode
characters
use Texinfo::Convert::Unicode qw(unicode_accent encoded_accents
unicode_text);
+ use Texinfo::Convert::Text qw(convert_to_text);
my ($innermost_contents, $stack)
= Texinfo::Convert::Utils::find_innermost_accent_contents($accent);
@@ -1682,10 +1683,11 @@ C<Texinfo::Convert::Unicode> provides methods dealing
with Unicode representatio
and conversion of Unicode code points, to be used in converters.
When an encoding supported in Texinfo is given as argument of a method of the
-module, the accented letters or characters should only be represented by
Unicode
-code points if it is known that Perl should manage to convert the Unicode code
-points to encoded characters in the encoding character set. Note that the
-actual conversion is done by Perl, not by the module.
+module, the accented letters or characters returned by the method should only
+be represented by Unicode code points if it is known that Perl should manage
+to convert the Unicode code points to encoded characters in the encoding
+character set. Note that the actual conversion is done by Perl, not by the
+module.
=head1 METHODS
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index 689d071a9e..336d5317a4 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -408,16 +408,22 @@ Texinfo to other formats. There is no promise of API
stability.
miscellaneous methods that may be useful for backends converting texinfo
trees. This module contains the methods that can be used in converters
-that do not inherit L<Texinfo::Convert::Converter>.
+which do not inherit from L<Texinfo::Convert::Converter>.
=head1 METHODS
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>.
-On strings translations, see L<Texinfo::Translations>.
+Most methods takes a I<$converter> as argument, in some cases optionally,
+to get some information, see
+L<Texinfo::Convert::Converter/Getting and setting customization variables>
+and use methods for error reporting, see L<Texinfo::Convert::Converter>
+and L<Texinfo::Report>, and for
+strings translations, see L<Texinfo::Translations>.
+
+Even when the caller does not inherit from L<Texinfo::Convert::Converter>, it
+could implement the required interfaces and could also have a converter
+available in some cases, to call the functions which require a converter.
=over
@@ -426,7 +432,7 @@ X<C<definition_arguments_content>>
I<$element> should be a C<@def*> Texinfo tree element. The
I<$category>, I<$class>, I<$type>, I<$name> are elements corresponding
-to the definition command line. Texinfo elements
+to the definition @-command line. Texinfo elements
on the @-command line corresponding to arguments in the function
definition are returned in the I<$arguments> array reference.
Arguments correspond to text following the other elements
@@ -456,22 +462,26 @@ information.
=item $tree = expand_today($converter)
X<C<expand_today>>
-Expand today's date, as a texinfo tree with translations.
+Expand today's date, as a texinfo tree with translations. The I<$converter>
+argument is not optional and is used both to retreive customization information
+and to translate strings.
=item $tree = expand_verbatiminclude($registrar, $customization_information,
$verbatiminclude)
X<C<expand_verbatiminclude>>
-The I<$registrar> argument may be undef. I<$verbatiminclude> is a
-C<@verbatiminclude> tree element. This function returns a
-C<@verbatim> tree elements after finding the included file and
-reading it. If I<$registrar> is not defined, errors messages are
-not registered.
+The I<$registrar> argument may be undef. The I<$customization_information>
+argument is required and is used to retrieve customization information
+L<Texinfo::Convert::Converter/Getting and setting customization variables>.
+I<$verbatiminclude> is a C<@verbatiminclude> tree element. This function
+returns a C<@verbatim> tree elements after finding the included file and
+reading it. If I<$registrar> is not defined, errors messages are not
+registered.
=item (\@contents, \@accent_commands) =
find_innermost_accent_contents($element)
X<C<find_innermost_accent_contents>>
I<$element> should be an accent command Texinfo tree element. Returns
-an array reference containing the innermost accent command contents,
+an array reference containing the innermost accent @-command contents,
normally a text element with one or two letter, and an array reference
containing the accent commands nested in I<$element> (including
I<$element>).
diff --git a/tp/texi2any.pl b/tp/texi2any.pl
index cbc18e3d32..cf95015dd1 100755
--- a/tp/texi2any.pl
+++ b/tp/texi2any.pl
@@ -1627,7 +1627,8 @@ while(@input_files) {
};
# NOTE nothing set in $main_configuration is passed, which is
- # clean, the Converters can find that information their way.
+ # clean, the Converters can find that information in $converter_options,
+ # determine it themselves or use their defaults.
# It could be possible to pass some information if it allows
# for instance to have some consistent information for Structuring
# and Converters.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: Change in comment and in modules and texi2any functions documentation,
Patrice Dumas <=