NAME

       LaTeX::Encode - encode characters for LaTeX formatting

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

       This manual page describes version 0.091.5 of the "LaTeX::Encode" module.

DESCRIPTION

       This module provides a function to encode text that is to be formatted with LaTeX.  It
       encodes characters that are special to LaTeX or that are represented in LaTeX by LaTeX
       text-mode commands.

       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

       Note that "latex_encode()" will encode a UTF8 string (a string with the UTF8 flag set) or
       a non-UTF8 string, which will normally be regarded as ISO-8859-1 (Latin 1) and will be
       upgraded to UTF8.  The UTF8 flag indicates whether the contents of a string are regarded
       as a sequence of Unicode characters or as a string of bytes.  Refer to the Unicode Support
       in Perl, Perl Unicode Introduction and Perl Unicode Tutorial manual pages for more
       details.

       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. "X" 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:

           "except"
               Lists the characters that should be excluded from encoding.  By default no special
               characters are excluded, but it may be useful to specify "except = "\\{}"" to
               allow the input string to contain LaTeX commands such as "this is \\textbf{bold}
               text" (the doubled backslashes in the strings represent Perl escapes, and will be
               evaluated to single backslashes).

           "iquotes"
               If true then single or double quotes around words will be changed to LaTeX single
               or double quotes; double quotes around a phrase will be converted to "``" and "''"
               and single quotes to "`" and "'".  This is sometimes called "intelligent quotes"

           "packages"
               If passed a reference to a hash "latex_encode()" will update the hash with names
               of LaTeX packages that are required for typesetting the encoded string.

       "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

       The following snippet shows how data from a database can be encoded and inserted into a
       LaTeX table, the source of which is generated with "LaTeX::Table".

           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

       None.  You could probably break the "latex_encode" function by passing it an array
       reference as the options, but there are no checks for that.

CONFIGURATION AND ENVIRONMENT

       Not applicable.

DEPENDENCIES

       The "HTML::Entities" and "Pod::LaTeX" modules were used for building the encoding table
       but this is not rebuilt at installation time.  The "LaTeX::Driver" module is used for
       formatting the character encodings reference document.

INCOMPATIBILITIES

       None known.

BUGS AND LIMITATIONS

       Not all LaTeX special characters are included in the encoding tables (more may be added
       when I track down the definitions).

AUTHOR

       Andrew Ford <a.ford@ford-mason.co.uk>

LICENSE AND COPYRIGHT

       Copyright (C) 2007-2012 Andrew Ford.  All Rights Reserved.

       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

       Template::Plugin::Latex

       Unicode Support in Perl

       Perl Unicode Introduction

       Perl Unicode Tutorial