Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LaTeX::Encode(3)      User Contributed Perl Documentation     LaTeX::Encode(3)

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. "AL" 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

perl v5.32.0			  2017-05-09		      LaTeX::Encode(3)

NAME | SYNOPSIS | VERSION | DESCRIPTION | WARNING ABOUT UTF-8 DATA | SUBROUTINES/METHODS | EXAMPLES | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=LaTeX::Encode&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help