summaryrefslogtreecommitdiff
path: root/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Common.texi
blob: 2f277cf21fe67c50bd9a144d74416cf21f5672e1 (plain)
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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
@node Texinfo@asis{::}Common
@chapter Texinfo::Common

@node Texinfo@asis{::}Common NAME
@section Texinfo::Common NAME

Texinfo::Common - Texinfo modules common data and miscellaneous methods

@node Texinfo@asis{::}Common SYNOPSIS
@section Texinfo::Common SYNOPSIS

@verbatim
  use Texinfo::Common;


  my @commands_to_collect = ('math');
  my $collected_commands
    = Texinfo::Common::collect_commands_in_tree($document_root,
                                             \@commands_to_collect);
@end verbatim

@node Texinfo@asis{::}Common NOTES
@section Texinfo::Common 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.

@node Texinfo@asis{::}Common DESCRIPTION
@section Texinfo::Common DESCRIPTION

Texinfo::Common holds hashes with miscellaneous information and some
hashes with information on Texinfo @@-commands, as well as miscellaneous
methods.

@node Texinfo@asis{::}Common MISC INFORMATION
@section MISC INFORMATION

Hashes are defined as @code{our} variables, and are therefore available
outside of the module.

TODO: undocumented
%null_device_file %default_parser_customization_values %document_settable_multiple_at_commands %document_settable_unique_at_commands %default_converter_command_line_options %default_main_program_customization_options %default_converter_customization @@variable_string_settables %document_settable_at_commands %def_map %command_structuring_level %level_to_structuring_command

@table @asis
@item %texinfo_output_formats
@anchor{Texinfo@asis{::}Common %texinfo_output_formats}
@cindex @code{%texinfo_output_formats}

Cannonical output formats that have associated conditionals.  In
practice corresponds to @code{format_raw} @code{%block_commands} plus @code{info}
and @code{plaintext}.

@end table

@node Texinfo@asis{::}Common @@-COMMAND INFORMATION
@section @@-COMMAND INFORMATION

Hashes are defined as @code{our} variables, and are therefore available
outside of the module.

The key of the hashes are @@-command names without the @@.  The
following hashes are available:

@table @asis
@item %all_commands
@anchor{Texinfo@asis{::}Common %all_commands}
@cindex @code{%all_commands}

All the @@-commands.

@item %brace_code_commands
@anchor{Texinfo@asis{::}Common %brace_code_commands}
@cindex @code{%brace_code_commands}

Brace commands that have their argument in code style, like
@code{@@code}.

@item %def_aliases
@anchor{Texinfo@asis{::}Common %def_aliases}

@item %def_no_var_arg_commands
@anchor{Texinfo@asis{::}Common %def_no_var_arg_commands}
@cindex @code{%def_aliases}
@cindex @code{%def_no_var_arg_commands}

@code{%def_aliases} associates an aliased command to the original command, for
example @code{defun} is associated to @code{deffn}.

@code{%def_no_var_arg_commands} associates a definition command name with
a true value if the @emph{argument} on the definition command line can contain
non-metasyntactic variables.  For instance, it is true for @code{deftypevr}
but false for @code{defun}, since @code{@@defun} @emph{argument} is supposed to contain
metasyntactic variables only.

@item %explained_commands
@anchor{Texinfo@asis{::}Common %explained_commands}
@cindex @code{%explained_commands}

@@-commands whose second argument explain first argument and further
@@-command call without first argument, as @code{@@abbr} and @code{@@acronym}.

@item %inline_conditional_commands
@anchor{Texinfo@asis{::}Common %inline_conditional_commands}

@item %inline_format_commands
@anchor{Texinfo@asis{::}Common %inline_format_commands}
@cindex @code{%inline_conditional_commands}
@cindex @code{%inline_format_commands}

Inline conditional commands, like @code{@@inlineifclear}, and inline format
commands like @code{inlineraw} and @code{inlinefmt}.

@item %nobrace_symbol_text
@anchor{Texinfo@asis{::}Common %nobrace_symbol_text}
@cindex @code{%nobrace_symbol_text}

Values are ASCII representation of single character non-alphabetical commands
without brace such as @code{*} or @code{:}.  The value may be an empty string.

@item %small_block_associated_command
@anchor{Texinfo@asis{::}Common %small_block_associated_command}
@cindex @code{%small_block_associated_command}

Associate small command like @code{smallexample} to the regular command
@code{example}.

@end table

@node Texinfo@asis{::}Common METHODS
@section Texinfo::Common METHODS

Two methods are exported in the default case for Texinfo modules messages
translation in the Uniforum gettext framework, @code{__} and @code{__p}.

The Texinfo tree and Texinfo tree elements used in argument of some functions
are documented in @ref{Texinfo@asis{::}Parser TEXINFO TREE}.  When customization
information is needed, an object that defines @code{set_conf} and/or @code{get_conf} is
expected, for example a converter inheriting from
@code{Texinfo::Convert::Converter}, see @ref{Texinfo@asis{::}Convert@asis{::}Converter Getting and
setting customization variables}.

@table @asis
@item $translated_string = __($msgid)
@anchor{Texinfo@asis{::}Common $translated_string = __($msgid)}

@item $translated_string = __p($msgctxt, $msgid)
@anchor{Texinfo@asis{::}Common $translated_string = __p($msgctxt@comma{} $msgid)}

Returns the @emph{$msgid} string translated in the Texinfo messages text domain.
@code{__p} can be used instead of @code{__} to pass a @emph{$msgctxt} context string to
provide translators with information on the string context when the string is
short or if the translation could depend on the context. @code{__} corresponds to
the @code{gettext} function and @code{__p} to the @code{pgettext} function.

It is not advised to use those functions in user-defined code.  It is not
practical either, as the translatable strings marked by @code{__} or @code{__p} need to
be collected and added to the Texinfo messages domain.  This facility could
only be used in user-defined code with translatable strings already present in
the domain anyway.  In fact, these functions are documented mainly because they
are automatically exported.

See @ref{,,, libintl-perl},
@url{https://www.gnu.org/software/gettext/manual/html_node/gettext.html, @code{gettext} C interface},
@url{https://www.gnu.org/software/gettext/manual/html_node/Perl.html, Perl in GNU Gettext}.
For translation of strings in output, see @ref{Texinfo@asis{::}Translations NAME,, Texinfo::Translations}.

@item collect_commands_in_tree($tree, $commands_list)
@anchor{Texinfo@asis{::}Common collect_commands_in_tree($tree@comma{} $commands_list)}
@cindex @code{collect_commands_in_tree}

Returns a hash reference with keys @@-commands names specified
in the @emph{$commands_list} array reference and values arrays of
tree elements corresponding to those @@-command found in @emph{$tree}
by traversing the tree.

@item collect_commands_list_in_tree($tree, $commands_list)
@anchor{Texinfo@asis{::}Common collect_commands_list_in_tree($tree@comma{} $commands_list)}
@cindex @code{collect_commands_list_in_tree}

Return a list reference containing the tree elements corresponding
to the @@-commands names specified in the @emph{$commands_list} found
in @emph{$tree} by traversing the tree.  The order of the @@-commands
should be kept.

@item $result = element_is_inline($element, $check_current)
@anchor{Texinfo@asis{::}Common $result = element_is_inline($element@comma{} $check_current)}
@cindex @code{element_is_inline}

Return true if the element passed in argument is in running text
context.  If the optional @emph{$check_current} argument is set,
check the element itself, in addition to the parent context.

@item ($encoded_file_name, $encoding) = encode_file_name($file_name, $input_encoding)
@anchor{Texinfo@asis{::}Common ($encoded_file_name@comma{} $encoding) = encode_file_name($file_name@comma{} $input_encoding)}

Encode the @emph{$file_name} text string to a binary string @emph{$encoded_file_name}
based on @emph{$input_encoding}.  Also returns the @emph{$encoding} name actually
used which may have undergone some normalization.  This function is mostly
a wrapper around @ref{encode,, Encode::encode, Encode} which avoids calling the module if not
needed.  Do nothing if @emph{$input_encoding} is @code{undef}.

@item $text = enumerate_item_representation($specification, $number)
@anchor{Texinfo@asis{::}Common $text = enumerate_item_representation($specification@comma{} $number)}
@cindex @code{enumerate_item_representation}

This function returns the number or letter correponding to item
number @emph{$number} for an @code{@@enumerate} specification @emph{$specification},
appearing on an @code{@@enumerate} line.  For example

@verbatim
  enumerate_item_representation('c', 3)
@end verbatim

is @code{e}.

@item $command = find_parent_root_command($object, $tree_element)
@anchor{Texinfo@asis{::}Common $command = find_parent_root_command($object@comma{} $tree_element)}
@cindex @code{find_parent_root_command}

Find the parent root command (sectioning command or node) of a tree element.
The @emph{$object} argument is optional, its @code{global_commands} field is used
to continue through @code{@@insertcopying} if in a @code{@@copying}.

@item $result = is_content_empty($tree, $do_not_ignore_index_entries)
@anchor{Texinfo@asis{::}Common $result = is_content_empty($tree@comma{} $do_not_ignore_index_entries)}
@cindex @code{is_content_empty}

Return true if the @emph{$tree} has content that could be formatted.
@emph{$do_not_ignore_index_entries} is optional.  If set, index entries
are considered to be formatted.

@item $file = locate_include_file($customization_information, file_path)
@anchor{Texinfo@asis{::}Common $file = locate_include_file($customization_information@comma{} file_path)}
@cindex @code{locate_include_file}

Locate @emph{$file_path}.  If @emph{$file_path} is an absolute path or has @code{.}
or @code{..} in the path directories it is checked that the path exists and is a
file.  Otherwise, the file name in @emph{$file_path} is located in include
directories also used to find texinfo files included in Texinfo documents.
@emph{$file_path} should be a binary string.  @code{undef} is returned if the file was
not found, otherwise the file found is returned as a binary string.

@item move_index_entries_after_items_in_tree($tree)
@anchor{Texinfo@asis{::}Common move_index_entries_after_items_in_tree($tree)}
@cindex @code{move_index_entries_after_items_in_tree}

In @code{@@enumerate} and @code{@@itemize} from the tree, move index entries
appearing just before @code{@@item} after the @code{@@item}.  Comment lines
between index entries are moved too.

@item $normalized_name = normalize_top_node_name($node_string)
@anchor{Texinfo@asis{::}Common $normalized_name = normalize_top_node_name($node_string)}
@cindex @code{normalize_top_node_name}

Normalize the node name string given in argument, by normalizing
Top node case.

@item protect_colon_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_colon_in_tree($tree)}

@item protect_node_after_label_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_node_after_label_in_tree($tree)}
@cindex @code{protect_colon_in_tree}
@cindex @code{protect_node_after_label_in_tree}

Protect colon with @code{protect_colon_in_tree} and characters that
are special in node names after a label in menu entries (tab
dot and comma) with @code{protect_node_after_label_in_tree}.
The protection is achieved by putting protected characters
in @code{@@asis@{@}}.

@item protect_comma_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_comma_in_tree($tree)}
@cindex @code{protect_comma_in_tree}

Protect comma characters, replacing @code{,} with @@comma@{@} in tree.

@item $contents_result = protect_first_parenthesis($contents)
@anchor{Texinfo@asis{::}Common $contents_result = protect_first_parenthesis($contents)}
@cindex @code{protect_first_parenthesis}

Return a contents array reference with first parenthesis in the
contents array reference protected.  If @emph{$contents} is undef
a fatal error with a backtrace will be emitted.

@item relate_index_entries_to_table_entries_in_tree($tree)
@anchor{Texinfo@asis{::}Common relate_index_entries_to_table_entries_in_tree($tree)}
@cindex @code{relate_index_entries_to_table_entries_in_tree}

In @@*table @@-commands, reassociate the index entry information from an index
@@-command appearing right after an @@item line to the @@item first element.
Remove the index @@-command from the tree.

@item $level = section_level($section)
@anchor{Texinfo@asis{::}Common $level = section_level($section)}
@cindex @code{section_level}

Return numbered level of the tree sectioning element @emph{$section}, as modified by
raise/lowersections.

@item $element = set_global_document_command($customization_information, $global_commands_information, $cmdname, $command_location)
@anchor{Texinfo@asis{::}Common $element = set_global_document_command($customization_information@comma{} $global_commands_information@comma{} $cmdname@comma{} $command_location)}
@cindex @code{set_global_document_command}

Set the Texinfo configuration option corresponding to @emph{$cmdname} in
@emph{$customization_information}.  The @emph{$global_commands_information} should
contain information about global commands in a Texinfo document, typically obtained
from a parser @ref{Texinfo@asis{::}Parser $commands = global_commands_information($parser),, $parser->global_commands_information()}.
@emph{$command_location} specifies where in the document the value should be taken from,
for commands that may appear more than once. The possibilities are:

@table @asis
@item last
@anchor{Texinfo@asis{::}Common last}

Set to the last value for the command.

@item preamble
@anchor{Texinfo@asis{::}Common preamble}

Set sequentially to the values in the Texinfo preamble.

@item preamble_or_first
@anchor{Texinfo@asis{::}Common preamble_or_first}

Set to the first value of the command if the first command is not
in the Texinfo preamble, else set as with @emph{preamble},
sequentially to the values in the Texinfo preamble.

@end table

The @emph{$element} returned is the last element that was used to set the
configuration value, or @code{undef} if no configuration value was found.

Notice that the only effect of this function is to set a customization
variable value, no @@-command side effects are run, no associated customization
variables are set.

@item set_informative_command_value($customization_information, $element)
@anchor{Texinfo@asis{::}Common set_informative_command_value($customization_information@comma{} $element)}
@cindex @code{set_informative_command_value}

Set the Texinfo configuration option corresponding to the tree element
@emph{$element}.  The command associated to the tree element should be
a command that sets some information, such as @code{@@documentlanguage},
@code{@@contents} or @code{@@footnotestyle} for example.

@item set_output_encodings($customization_information, $parser_information)
@anchor{Texinfo@asis{::}Common set_output_encodings($customization_information@comma{} $parser_information)}
@cindex @code{set_output_encodings}

If not already set, set @code{OUTPUT_ENCODING_NAME} based on input file
encoding.  Also set @code{OUTPUT_PERL_ENCODING} accordingly which is used
to output in the correct encoding.  In general, @code{OUTPUT_PERL_ENCODING}
should not be set directly by user-defined code such that it corresponds
to @code{OUTPUT_ENCODING_NAME}.

@item $split_contents = split_custom_heading_command_contents($contents)
@anchor{Texinfo@asis{::}Common $split_contents = split_custom_heading_command_contents($contents)}
@cindex @code{split_custom_heading_command_contents}

Split the @emph{$contents} array reference at @code{@@|} in at max three parts.
Return an array reference containing the split parts.  The @emph{$contents}
array reference is supposed to be @code{$element->@{'args'@}->[0]->@{'contents'@}}
of @code{%Texinfo::Commands::heading_spec_commands} commands such as @code{@@everyheading}.

@item trim_spaces_comment_from_content($contents)
@anchor{Texinfo@asis{::}Common trim_spaces_comment_from_content($contents)}
@cindex @code{trim_spaces_comment_from_content}

Remove empty spaces after commands or braces at begin and
spaces and comments at end from a content array, modifying it.

@item valid_customization_option($name)
@anchor{Texinfo@asis{::}Common valid_customization_option($name)}
@cindex @code{valid_option}

Return true if the @emph{$name} is a known customization option.

@item valid_tree_transformation($name)
@anchor{Texinfo@asis{::}Common valid_tree_transformation($name)}
@cindex @code{valid_tree_transformation}

Return true if the @emph{$name} is a known tree transformation name
that may be passed with @code{TREE_TRANSFORMATIONS} to modify a texinfo
tree.

@end table

@node Texinfo@asis{::}Common SEE ALSO
@section Texinfo::Common SEE ALSO

@ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}, @ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter} and @ref{Texinfo@asis{::}Report NAME,, Texinfo::Report}.

@node Texinfo@asis{::}Common AUTHOR
@section Texinfo::Common AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Common COPYRIGHT AND LICENSE
@section Texinfo::Common COPYRIGHT AND LICENSE

Copyright 2010- 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.