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