convert( $latex_string, %options )¶

Convert the text in $latex_string into a plain(er) Unicode string. Escape sequences for accented and special characters (e.g., "\i", "\"a", ...) are converted. A few basic formatting commands (e.g., "{\it ...}") are removed. See the LaTeX::ToUnicode::Tables submodule for the full conversion tables.

These keys are recognized in %options:

"entities"

Output "&#xUUUU;" entities (valid in XML); in this case, also convert the <, >, "&" metacharacters to entities. Recognized non-ASCII Unicode characters in the original input are also converted to entities, not only the translations from TeX commands.

The default is to output literal (binary) Unicode characters, and not change any metacharacters.

"german"

If this option is set, the commands introduced by the package `german' (e.g. ""a" eq "ä", note the missing backslash) are also handled.

"html"

If this option is set, the output is simplistic html rather than plain text. This affects only a few things: 1) the output of urls from "\url" and "\href"; 2) the output of markup commands like "\textbf" (but nested markup commands don't work); 3) two other random commands, "\enquote" and "\path", because they are needed.

"hook"

The value must be a function that takes two arguments and returns a string. The first argument is the incoming string (may be multiple lines), and the second argument is a hash reference of options, exactly what was passed to this "convert" function. Thus the hook can detect whether html is needed.

The hook is called (almost) right away, before any of the other conversions have taken place. That way the hook can make use of the predefined conversions instead of repeating them. The only changes made to the input string before the hook is called are trivial: leading and trailing whitespace (space and tab) on each line are removed, and, for HTML output, incoming ampersand, less-than, and greater-than characters are replaced with their entities.

Any substitutions that result in Unicode code points must use "\\x{nnnn}" on the right hand side: that's two backslashes and a four-digit hex number.

As an example, here is a skeleton of the hook function for TUGboat:

  sub LaTeX_ToUnicode_convert_hook {
    my ($string,$options) = @_;
    my $endcw = $LaTeX::ToUnicode::endcw;
    die "no endcw regexp in LaTeX::ToUnicode??" if ! $endcw;
    ...
    $string =~ s/\\newline$endcw/ /g;
    # TUB's \acro{} takes an argument, but we do nothing with it.
    # The braces will be removed by convert().
    $string =~ s/\\acro$endcw//g;
    ...
    $string =~ s/\\CTAN$endcw/CTAN/g;
    $string =~ s/\\Dash$endcw/\\x{2014}/g; # em dash; replacement is string
    ...
    # ignore \begin{abstract} and \end{abstract} commands.
    $string =~ s,\\(begin|end)$endcw\{abstract\}\s*,,g;
    # Output for our url abbreviations, and other commands, depends on
    # whether we're generating plain text or HTML.
    if ($options->{html}) {
        # HTML.
        # \tbsurl{URLBASE} -> <a href="https://URLBASE">URLBASE</a>
        $string =~ s,\\tbsurl$endcw\{([^}]*)\}
                    ,<a href="https://$1">$1</a>,gx;
        ...
        # varepsilon, and no line break at hyphen.
        $string =~ s,\\eTeX$endcw,\\x{03B5}<nobr>-</nobr>TeX,g;
    } else {
        # for plain text, we can just prepend the protocol://.
        $string =~ s,\\tbsurl$endcw,https://,g;
        ...
        $string =~ s,\\eTeX$endcw,\\x{03B5}-TeX,g;
    }
    ...
    return $string;
  }
    

As shown here for "\eTeX" (an abbreviation macro defined in the TUGboat style files), if markup is desired in the output, the substitutions must be different for HTML and plain text. Otherwise, the desired HTML markup is transliterated as if it were plain text. Or else the translations must be extended so that TeX markup can be used on the rhs to be replaced with the desired HTML ("&lt;nobr&gt;" in this case).

For the full definition (and plenty of additional information), see the file "ltx2crossrefxml-tugboat.cfg" in the TUGboat source repository at <https://github.com/TeXUsersGroup/tugboat/tree/trunk/capsules/crossref>.

The hook function is specified in the "convert()" call like this:

  LaTeX::ToUnicode::convert(..., { hook => \&LaTeX_ToUnicode_convert_hook })
    

debuglevel( $level )¶

Output debugging information if $level is nonzero.

$endcw¶

A predefined regexp for terminating TeX control words (not control symbols!). Can be used in, for example, hook functions:

  my $endcw = $LaTeX::ToUnicode::endcw;
  $string =~ s/\\newline$endcw/ /g; # translate \newline to space

It's defined as follows:

  our $endcw = qr/(?<=[a-zA-Z])(?=[^a-zA-Z]|$)\s*/;

That is, look behind for an alphabetic character, then look ahead for a non-alphabetic character (or end of line), then consume whitespace. Fingers crossed.