summaryrefslogtreecommitdiff
path: root/macros/texinfo/texinfo/doc/tp_api/api_includes/Texinfo-Common.texi
blob: 772afd752253bd3177fff8f5e145613770227b75 (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
@node Texinfo::Common
@chapter Texinfo::Common

@menu
* Texinfo@asis{::}Common NAME::
* Texinfo@asis{::}Common SYNOPSIS::
* Texinfo@asis{::}Common DESCRIPTION::
* Texinfo@asis{::}Common COMMAND CLASSES::
* Texinfo@asis{::}Common METHODS::
* Texinfo@asis{::}Common SEE ALSO::
* Texinfo@asis{::}Common AUTHOR::
@end menu

@node Texinfo::Common NAME
@section NAME

Texinfo::Common - Classification of commands and miscellaneous methods

@node Texinfo::Common SYNOPSIS
@section SYNOPSIS

@verbatim
  use Texinfo::Common qw(expand_today expand_verbatiminclude);
  if ($Texinfo::Common::accent_commands{$a_command}) {
    print STDERR "$a_command is an accent command\n";
  }
  
  my $today_tree = expand_today($converter);
  my $verbatiminclude_tree 
     = expand_verbatiminclude(undef, $verbatiminclude);
@end verbatim

@node Texinfo::Common DESCRIPTION
@section DESCRIPTION

Texinfo::Common holds interesting hashes classifying Texinfo @@-commands,
as well as miscellaneous methods that may be useful for any backend
converting texinfo trees.

It also defines, as our variable a hash for default indices,
named @code{%index_names}.  The format of this hash is described in 
@ref{Texinfo::Parser indices_information}.

@node Texinfo::Common COMMAND CLASSES
@section COMMAND CLASSES

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::Common %all_commands}

All the @@-commands.

@item %no_brace_commands
@anchor{Texinfo::Common %no_brace_commands}

Commands without brace with a single character as name, like @code{*}
or @code{:}.  The value is an ascii representation of the command.  It
may be an empty string.

@item %misc_commands
@anchor{Texinfo::Common %misc_commands}

Command that do not take braces and are not block commands either, like
@code{@@node}, @code{@@chapter}, @code{@@cindex}, @code{@@deffnx}, @code{@@end}, @code{@@footnotestyle}, 
@code{@@set}, @code{@@settitle}, @code{@@indent}, @code{@@definfoenclose}, @code{@@comment} and many 
others.

@item %default_index_commands
@anchor{Texinfo::Common %default_index_commands}

Index entry commands corresponding to default indices. For example 
@code{@@cindex}.

@item %root_commands
@anchor{Texinfo::Common %root_commands}

Commands that are at the root of a Texinfo document, namely
@code{@@node} and sectioning commands, except heading commands.

@item %sectioning_commands
@anchor{Texinfo::Common %sectioning_commands}

All the sectioning and heading commands.

@item %brace_commands
@anchor{Texinfo::Common %brace_commands}

The commands that take braces.  The associated value is the maximum
number of arguments.

@item %letter_no_arg_commands
@anchor{Texinfo::Common %letter_no_arg_commands}

@@-commands with braces but no argument corresponding to letters, 
like @code{@@AA@{@}} or @code{@@ss@{@}} or @code{@@o@{@}}.

@item %accent_commands
@anchor{Texinfo::Common %accent_commands}

Accent @@-commands taking an argument, like @code{@@'} or @code{@@ringaccent} 
including @code{@@dotless} and @code{@@tieaccent}.

@item %style_commands
@anchor{Texinfo::Common %style_commands}

Commands that mark a fragment of texinfo, like @code{@@strong},
@code{@@cite}, @code{@@code} or @code{@@asis}.

@item %code_style_commands
@anchor{Texinfo::Common %code_style_commands}

@emph{style_commands} that have their argument in code style, like 
@code{@@code}.

@item %regular_font_style_commands
@anchor{Texinfo::Common %regular_font_style_commands}

@emph{style_commands} that have their argument in regular font, like
@code{@@r} or @code{@@slanted}.

@item %context_brace_commands
@anchor{Texinfo::Common %context_brace_commands}

@@-commands with brace like @code{@@footnote}, @code{@@caption} and @code{@@math}
whose argument is outside of the main text flow in one way or another.

@item %ref_commands
@anchor{Texinfo::Common %ref_commands}

Cross reference @@-command referencing nodes, like @code{@@xref}.

@item %explained_commands
@anchor{Texinfo::Common %explained_commands}

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

@item %block commands
@anchor{Texinfo::Common %block commands}

Commands delimiting a block with a closing @code{@@end}.  The value
is @emph{conditional} for @code{@@if} commands, @emph{def} for definition
commands like @code{@@deffn}, @emph{raw} for @@-commands that have no expansion
of @@-commands in their bodies and @emph{multitable} for @code{@@multitable}.  
Otherwise it is set to the number of arguments separated by commas 
that may appear on the @@-command line. That means 0 in most cases, 
1 for @code{@@quotation} and 2 for @code{@@float}.

@item %raw_commands
@anchor{Texinfo::Common %raw_commands}

@@-commands that have no expansion of @@-commands in their bodies,
as @code{@@macro}, @code{@@verbatim} or @code{@@ignore}.

@item %format_raw_commands
@anchor{Texinfo::Common %format_raw_commands}

@@-commands associated with raw output format, like @code{@@html}, or
@code{@@docbook}.

@item %texinfo_output_formats
@anchor{Texinfo::Common %texinfo_output_formats}

Cannonical output formats that have associated conditionals.  In
practice @code{%format_raw_commands} plus @code{info} and @code{plaintext}.

@item %def_commands
@anchor{Texinfo::Common %def_commands}

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

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

@item %menu_commands
@anchor{Texinfo::Common %menu_commands}

@@-commands with menu entries.

@item %align_commands
@anchor{Texinfo::Common %align_commands}

@@-commands related with alignement of text.

@item %region_commands
@anchor{Texinfo::Common %region_commands}

Block @@-commands that enclose full text regions, like @code{@@titlepage}.

@item %preformatted_commands
@anchor{Texinfo::Common %preformatted_commands}

@item %preformatted_code_commands
@anchor{Texinfo::Common %preformatted_code_commands}

@emph{%preformatted_commands} is for commands whose content should not 
be filled, like @code{@@example} or @code{@@display}.  If the command is meant 
for code, it is also in @emph{%preformatted_code_commands}, like @code{@@example}.

@item %item_container_commands
@anchor{Texinfo::Common %item_container_commands}

Commands holding @code{@@item} with @code{@@item} that contains blocks of text, 
like @code{@@itemize}.

@item %item_line_commands
@anchor{Texinfo::Common %item_line_commands}

Commands with @code{@@item} that have their arguments on their lines, like
@code{@@ftable}.

@end table

@node Texinfo::Common METHODS
@section METHODS

No method is exported in the default case.

Most methods takes a @emph{$converter} as argument, sometime optionally, 
to get some information and use methods for error reporting, 
see @ref{Texinfo::Convert::Converter NAME} and @ref{Texinfo::Report NAME}.

@table @asis
@item $tree = expand_today($converter)
@anchor{Texinfo::Common $tree = expand_today($converter)}

Expand today's date, as a texinfo tree with translations.

@item $tree = expand_verbatiminclude($converter, $verbatiminclude)
@anchor{Texinfo::Common $tree = expand_verbatiminclude($converter@comma{} $verbatiminclude)}

The @emph{$converter} argument may be undef.  @emph{$verbatiminclude} is a
@code{@@verbatiminclude} tree element.  This function returns a 
@code{@@verbatim} tree elements after finding the included file and
reading it.  If @emph{$converter} is not defined, the document encoding 
is not taken into account when reading the file.

@item $tree = definition_category($converter, $def_line)
@anchor{Texinfo::Common $tree = definition_category($converter@comma{} $def_line)}

The @emph{$converter} argument may be undef.  @emph{$def_line} is a 
@code{def_line} texinfo tree container.  This function
returns a texinfo tree corresponding to the category of the
@emph{$def_line} taking the class into account, if there is one.
If @emph{$converter} is not defined, the resulting string won't be
translated.

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

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

@item $result = numbered_heading ($converter, $heading_element, $heading_text, $do_number)
@anchor{Texinfo::Common $result = numbered_heading ($converter@comma{} $heading_element@comma{} $heading_text@comma{} $do_number)}

The @emph{$converter} argument may be undef.  @emph{$heading_element} is 
a heading command tree element.  @emph{$heading_text} is the already 
formatted heading text.  if the @emph{$do_number} optional argument is 
defined and false, no number is used and the text is returned as is.
This function returns the heading with a number and the appendix 
part if needed.  If @emph{$converter} is not defined, the resulting 
string won't be translated.

@item ($caption, $prepended) = float_name_caption ($converter, $float)
@anchor{Texinfo::Common ($caption@comma{} $prepended) = float_name_caption ($converter@comma{} $float)}

@emph{$float} is a texinfo tree @code{@@float} element.  This function 
returns the caption that should be used for the float formatting 
and the @emph{$prepended} texinfo tree combining the type and label
of the float.

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

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 trim_spaces_comment_from_content($contents)
@anchor{Texinfo::Common trim_spaces_comment_from_content($contents)}

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

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

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

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

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

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

@item protect_node_after_label_in_tree($tree)
@anchor{Texinfo::Common protect_node_after_label_in_tree($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 $contents_result = protect_first_parenthesis ($contents)
@anchor{Texinfo::Common $contents_result = protect_first_parenthesis ($contents)}

Return a contents array reference with first parenthesis in the 
contents array reference protected.

@item protect_hashchar_at_line_beginning($parser, $tree)
@anchor{Texinfo::Common protect_hashchar_at_line_beginning($parser@comma{} $tree)}

Protect hash character at beginning of line if the line is a cpp
line directive.  The @emph{$parser} argument maybe undef, if it is 
defined it is used for error reporting in case an hash character
could not be protected because it appeared in a raw environment.

@item move_index_entries_after_items_in_tree($tree)
@anchor{Texinfo::Common move_index_entries_after_items_in_tree($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 $command = find_parent_root_command($parser, $tree_element)
@anchor{Texinfo::Common $command = find_parent_root_command($parser@comma{} $tree_element)}

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

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

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.

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

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.

@end table

@node Texinfo::Common SEE ALSO
@section SEE ALSO

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

@node Texinfo::Common AUTHOR
@section AUTHOR

Patrice Dumas, <pertusus@@free.fr>