12.1.1 Command Tree Element Conversion Functions ¶

User defined functions called for an @-command element conversion, after arguments and contents have been formatted, are registered with texinfo_register_command_formatting:

Function: texinfo_register_command_formatting ($command_name, \&handler) ¶

$command_name is an @-command name, without the leading @. \&handler is the user defined function reference.

The call of the user defined functions is:

Function Reference: $text command_conversion ($converter, $command_name, \%element, \@args, $content) ¶

$converter is a converter object. $command_name is the @-command name without the @. \%element is the Texinfo element.

\@args, if defined, is a reference on the formatted arguments of the @-command. Each of the array items correspond to each of the @-command argument. Each array item is either undef if the argument is empty, or a hash reference, with keys corresponding to possible argument formatting contexts:

normal

Argument formatted in a normal context

monospace

Argument formatted in a context where spaces are kept as is, as well as quotes and minus characters, for instance in ‘--’ and ‘``’. Both in preformatted and code context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

monospacestring

Same as monospace, but in addition in string context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

monospacetext

Same as monospace, but in addition the argument is converted to plain text.

filenametext

Same as monospacetext, but in addition the document encoding is used to convert accented letters and special insertion @-commands to plain text independently of customization variables.

raw

Text is kept as is, special HTML characters are not protected. Appears only as @inlineraw second argument.

string

In string context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

arg_tree

The Texinfo tree element corresponding to the argument. See Texinfo Tree Elements in User Defined Functions.

url

Similar with filenametext. The difference is that UTF-8 encoding is always used for the conversion of accented and special insertion @-commands to plain text. This is best for percent encoding of URLs, which should always be produced from UTF-8 encoded strings.

The formatted arguments contexts depend on the @-command, there could be none, for @footnote argument which is not directly converted where the footnote command is, or multiple, for example for the fourth argument of @image which is both available as ‘normal’ and ‘string’. See Table 12.1, for the converted arguments contexts. @-commands not specified in the table have their arguments in ‘normal’ context.

For example, $args->[0]->{'normal'} is the first argument converted in normal context. It should be present for most @-commands with arguments, but not for all, for example @anchor argument is only available as monospacestring.

$content is the @-command formatted contents. It corresponds to the contents of block @-commands, and to Texinfo code following @node, sectioning commands, @tab and @item in @enumerate and @itemize. $content can be undef or the empty string.

The $text returned is the result of the @-command conversion.

To call a conversion function from user defined code, the function reference should first be retrieved using command_conversion:

Function: \&command_conversion = $converter->command_conversion ($command_name) ¶

$command_name is the @-command name without the @. Returns the conversion function reference for $command_name, or ‘undef’ if there is none, which should only be the case for @-commands ignored in HTML not defined by the user.

for example, to call the conversion function for the @tab @-command, passing arguments that may correspond to another @-command:

&{$converter->command_conversion('tab')}($converter, $cmdname,
                                     $command, $args, $content);

It is possible to have access to the default conversion function reference. The function used is:

Function: \&default_command_conversion = $converter->default_command_conversion ($command_name) ¶

$command_name is the @-command name without the @. Returns the default conversion function reference for $command_name, or ‘undef’ if there is none, which should only be the case for @-commands ignored in HTML.