NAME

SYNOPSIS

  use LaTeX::Encode ':all', add => { '@' => 'AT' }, remove => [ '$' ];

  $latex_string  = latex_encode($text, %options);

  %old_encodings = add_latex_encodings( chr(0x2002) => '\\hspace{.6em}' );
  %old_encodings = remove_latex_encodings( '<', '>' );

  reset_latex_encodings(1);

VERSION

DESCRIPTION

The special characters are: "\" (command character), "{" (open group), "}" (end group), "&" (table column separator), "#" (parameter specifier), "%" (comment character), "_" (subscript), "^" (superscript), "~" (non-breakable space), "$" (mathematics mode).

Note that some of the LaTeX commands for characters are defined in the LaTeX "textcomp" package. If your text includes such characters, you will need to include the following lines in the preamble to your LaTeX document.

    \usepackage[T1]{fontenc}
    \usepackage{textcomp}

The function is useful for encoding data that is interpolated into LaTeX document templates, say with "Template::Plugin::Latex" (shameless plug!).

WARNING ABOUT UTF-8 DATA

If you are seeing spurious LaTeX commands in the output of "latex_encode()" then it may be that you are reading from a UTF-8 input or have data with UTF-8 characters in a literal but the UTF8 flag is not being set correctly. The fact that your programs are dealing with UTF-8 characters on a byte-by-byte basis may not be apparent normally as the terminal may make no distinction and happily display the byte sequence in the program's output as the UTF-8 characters they represent, however in a Perl program that deals with individual characters, what happens is that the individual bytes that make up multi-byte characters are regarded as separate characters; if the strings are promoted to UTF8 strings then the individual bytes are converted separately to UTF8. This is termed double encoding. "latex_encode()" will then map the double-encoded characters.

If the input text is Western European text then what you are likely to see in the output from "latex_encode()" is spurious sequences of "{\^A}" or "{\~A}" followed by the mapping of an apparently random character (or the right character if it is a symbol such as the Sterling POUND sign, i.e. "£" will map to "{\^A}\textsterling"); this is because the initial byte of a two-byte UTF-8 character in the LATIN1 range will either be 0xC2 or 0xC3 and the next byte will always have the top two bits set to 10 to indicate that it is a continuation byte.

SUBROUTINES/METHODS

"latex_encode($text, %options)"

Encodes the specified text such that it is suitable for processing with LaTeX. The behaviour of the filter is modified by the options:

"add_latex_encodings(%encodings)"

Adds a set of new or modified encodings. Returns a hash of any encodings that were modified.

"remove_latex_encodings(@keys)"

Removes a set of encodings. Returns a hash of the removed encodings.

"reset_latex_encodings($forget_import_specifiers)"

Resets the LaTeX encodings to the state that they were when the module was loaded (including any additions and removals specified on the 'use' statement), or to the standard set of encodings if $forget_import_specifiers is true.

EXAMPLES

    my $sth = $dbh->prepare('select col1, col2, col3 from table where $expr');
    $sth->execute;
    while (my $href = $sth->fetchrow_hashref) {
        my @row;
        foreach my $col (qw(col1 col2 col3)) {
            push(@row, latex_encode($href->{$col}));
        }
        push @data, \@row;
    }

    my $headings = [ [ 'Col1', 'Col2', 'Col3' ] ];

    my $table = LaTeX::Table->new( { caption => 'My caption',
                                     label   => 'table:caption',
                                     type    => 'xtab',
                                     header  => $header,
                                     data    => \@data } );

    my $table_text = $table->generate_string;

Now $table_text can be interpolated into a LaTeX document template.

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

Unicode Support in Perl

Perl Unicode Introduction

Perl Unicode Tutorial