1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter
@chapter Texinfo::Example::TreeElementConverter
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter NAME
@section Texinfo::Example::TreeElementConverter NAME
Texinfo::Example::TreeElementConverter - Parent class for TreeElement based converters
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter SYNOPSIS
@section Texinfo::Example::TreeElementConverter SYNOPSIS
@verbatim
package Texinfo::Convert::MyConverter;
use Texinfo::Convert::Converter;
use Texinfo::Example::TreeElementConverter;
our @ISA = qw(Texinfo::Example::TreeElementConverter);
# define the methods needed for Texinfo::Convert::Converter
...
sub convert_tree($$) {
...
}
...
# end of Texinfo::Convert::MyConverter
my $converter = Texinfo::Convert::MyConverter->converter();
$converter->output($texinfo_parsed_document);
@end verbatim
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter NOTES
@section Texinfo::Example::TreeElementConverter NOTES
The Texinfo Perl module main purpose is to be used in @code{texi2any} to convert
Texinfo to other formats. There is no promise of API stability.
Note that this module is not used in @code{texi2any}.
Note that this module could be removed at any time.
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter DESCRIPTION
@section Texinfo::Example::TreeElementConverter DESCRIPTION
@code{Texinfo::Example::TreeElementConverter} is a super class that helps
using the @ref{Texinfo@asis{::}TreeElement NAME,, Texinfo::TreeElement} interface in converters. It provides
implementations of methods from other Texinfo Perl modules using the
TreeElement @ref{Texinfo@asis{::}TreeElement NAME,, Texinfo::TreeElement} interface only. The original
methods can be in the @ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter}, @ref{Texinfo@asis{::}Common NAME,, Texinfo::Common},
@ref{Texinfo@asis{::}Convert@asis{::}Utils NAME,, Texinfo::Convert::Utils} and @ref{Texinfo@asis{::}Structuring NAME,, Texinfo::Structuring} modules.
The Texinfo Perl modules can be setup to use Perl XS module extensions in
native code (written in C) that replace Perl package or methods by native code
for faster execution.
The Texinfo modules XS interface is designed such that the Texinfo tree
actually processed is not the Perl elements tree, but a tree stored in
native code in XS extensions, corresponding to compiled C data structures.
If XS extensions are loaded, finding a Perl element associated C data
is required in some cases, namely to initialize
@ref{Texinfo@asis{::}Reader @code{Texinfo@asis{::}Reader} and XS extensions} with XS
on an element (except for the tree root) or to find replaced substrings
elements in translations.
The @code{Texinfo::Example::TreeElementConverter} modules helps with
setting up the link from Perl elements to C, first by providing the
methods using the TreeElement interface
since the @ref{Texinfo@asis{::}TreeElement NAME,, Texinfo::TreeElement} interface automatically sets up this link.
The module also provides XS interfaces for methods also available in other
modules that setup the link from Perl elements to C. Lastly, some methods are
also available to create or access Texinfo tree elements that also setup
Texinfo elements with the link from Perl elements to C.
Using the Reader, the TreeElement interface and the methods provided in this
module with XS to access and create elements also allows to go through the
Texinfo tree without ever building full Perl element data. This may be all the
more important that building full Perl element data wipes out the link from
Perl elements to C element data.
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter METHODS
@section Texinfo::Example::TreeElementConverter METHODS
The following methods allow to create new elements and get elements.
If XS extensions are used, elements should be created and accessed through
these methods to have a link from Perl to C data setup for the created or
returned element.
@table @asis
@item $converter->new_tree_element($element, $use_sv)
@anchor{Texinfo@asis{::}Example@asis{::}TreeElementConverter $converter->new_tree_element($element@comma{} $use_sv)}
@cindex @code{new_tree_element}
Create a new tree elements based on the @emph{$element} hash reference. The
@emph{$use_sv} argument is optional; if set and XS is used, the @emph{$element} hash
reference is associated to the new tree element data in C, otherwise it is
discarded.
@item ($index_entry, $index_info) = $converter->get_tree_element_index_entry($element)
@anchor{Texinfo@asis{::}Example@asis{::}TreeElementConverter ($index_entry@comma{} $index_info) = $converter->get_tree_element_index_entry($element)}
@cindex @code{get_tree_element_index_entry}
Finds the index entry and index information associated to the tree
element @emph{$element}. See @ref{Texinfo@asis{::}Common ($index_entry@comma{} $index_info) = lookup_index_entry($index_entry_info@comma{} $indices_information),, Texinfo::Common lookup_index_entry}
for a general description of the return values. Note that the returned
@emph{$index_info} information does not contain the index entries associated to
the index, only some basic information on the index.
@item $element = $converter->get_global_unique_tree_element($command_name)
@anchor{Texinfo@asis{::}Example@asis{::}TreeElementConverter $element = $converter->get_global_unique_tree_element($command_name)}
@item $elements = global_commands_information_command_list($document, $command_name)
@anchor{Texinfo@asis{::}Example@asis{::}TreeElementConverter $elements = global_commands_information_command_list($document@comma{} $command_name)}
@cindex @code{get_global_unique_tree_element}
@cindex @code{global_commands_information_command_list}
Returns the tree element or tree elements corresponding to the
@emph{$command_name} @@-command with a link from Perl to C element data setup.
Only for @@-commands that could also be accessed
through @ref{Texinfo@asis{::}Document $commands = global_commands_information($document),, Texinfo::Document global_commands_information}
(if the link from Perl to C element data was not needed).
@code{get_global_unique_tree_element} should be called for @@-commands that should
appear only once in a Texinfo document. This method returns the element.
@code{global_commands_information_command_list} requires a @code{Texinfo::Document}
@emph{$document} argument. The @emph{$document} could be available as
@code{$converter->@{'document'@}}. This method should be called for @@-commands
that may appear more than once in a Texinfo document. This method returns
a reference on the array of all the @emph{$command_name} @@-command tree elements
appearing in the document.
@end table
The other methods are documented in the modules that provide the
non-TreeElement interface or the methods that do not setup elements with
link from Perl to C element data. The method name is either the same
as in this module, if the method is used as a wrapper around the method
with the same name, or can be obtained by removing a leading @code{tree_element_}.
For example, the @code{index_content_element} documentation can be used for the
@code{tree_element_index_content_element} method of this module.
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter Related methods from other modules
@subsection Related methods from other modules
To associate sectioning commands and nodes tree elements Perl to C data, the
@code{register_document_relations_lists_elements} @code{Texinfo::Document}
method may be called after getting the tree before starting the tree
conversion, such that sectioning commands and nodes elements accessed through
nodes and section relations have the association to C data already setup:
@verbatim
$converter->{'document'}->register_document_relations_lists_elements()
@end verbatim
If you use the @ref{Texinfo@asis{::}Reader NAME,, Texinfo::Reader} to go through the tree you can call
reader methods to associate Perl to C data based on the current element
being read, @ref{Texinfo@asis{::}Reader $reader->register_token_element(),, Texinfo::Reader @code{register_token_element}}
and @ref{Texinfo@asis{::}Reader $reader->register_token_element_child($index),, Texinfo::Reader @code{register_token_element_child}}.
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter SEE ALSO
@section Texinfo::Example::TreeElementConverter SEE ALSO
@ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter}, @ref{Texinfo@asis{::}Common NAME,, Texinfo::Common}, @ref{Texinfo@asis{::}Convert@asis{::}Utils NAME,, Texinfo::Convert::Utils}
and @ref{Texinfo@asis{::}Structuring NAME,, Texinfo::Structuring}.
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter AUTHOR
@section Texinfo::Example::TreeElementConverter AUTHOR
Patrice Dumas, <bug-texinfo@@gnu.org>
@node Texinfo@asis{::}Example@asis{::}TreeElementConverter COPYRIGHT AND LICENSE
@section Texinfo::Example::TreeElementConverter COPYRIGHT AND LICENSE
Copyright 2011- Free Software Foundation, Inc. See the source file for
all copyright years.
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.
|
