12.2.3 Text Tree Elements Conversion ¶

Tree elements holding text are converted by the function reference registered for the text type conversion irrespective of the actual tree element type. For example, a tree element with type spaces_before_paragraph and text and a tree element without type but with text are both converted by the function reference registered for text.

The definition and registration of a conversion function for all the tree elements holding text should be along:

sub my_convert_text($$$)
{
  my $converter = shift;
  my $type = shift;
  my $element = shift;
  my $text = shift;

  # ...

  $text = uc($text) if ($converter->in_upper_case());

  # ...
}

texinfo_register_type_formatting ('text', \&my_convert_text);

The $type free conversion function argument is the actual type of the converted element (can be undef).

Formatting of text requires to use informative functions on specific contexts only relevant for text. User defined functions should convert the text according to the context.

Each context is associated with a function:

code

Function: $in_code = $converter->in_code () ¶

Return true if in code context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

math

Function: $in_math = $converter->in_math () ¶

Return true if in math context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

raw

Function: $in_raw = $converter->in_raw () ¶

Return true if in raw format, in @inlineraw or in @html. In such a context, text should be kept as is and special HTML characters should not be protected.

verbatim

Function: $in_verbatim = $converter->in_verbatim () ¶

Return true if in verbatim context, corresponding to @verb and @verbatim. In general, HTML characters should be protected in this context.

upper-case

Function: $in_upper_case = $converter->in_upper_case () ¶

Return true if in upper-case context, corresponding to @sc.

non-breakable space

Function: $in_non_breakable_space = $converter->in_non_breakable_space () ¶

Return true if in context where line breaks are forbidden, corresponding to @w.

space protected

Function: $in_space_protected = $converter->in_space_protected () ¶

Return true if in context where space and newline characters are kept, corresponding to @verb.