LaTeX::Encode(3pm)

💖 LaTeX::Encode — encoding characters for LaTeX formatting 💖

okay bestie, gather round, because this is the manual page for LaTeX::Encode (that's the 3pm one, perl module manual, you know the vibe) and honestly? it's giving "tiny module, big personality." let's get into it 🦋

---

✨ SYNOPSIS ✨

no thoughts, just look at the code:

  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);

that's it. that's the whole entrance. slay 💅

---

🎀 VERSION 🎀

this manual page is describing version 0.091.5 of the LaTeX::Encode module. periodt.

---

🌸 DESCRIPTION 🌸

so here's the deal, bestie. this module hands you a function that encodes text so it can be formatted with LaTeX. it takes characters that are special to LaTeX, or characters that LaTeX represents using LaTeX text-mode commands, and it encodes them. no cap.

the special characters are:

• \ — the command character
• { — open group
• } — end group
• & — table column separator
• # — parameter specifier
• % — comment character
• _ — subscript
• ^ — superscript
• ~ — non-breakable space
• $ — mathematics mode

heads up queen 👑 — some of the LaTeX commands for these characters are actually defined in the LaTeX textcomp package. so if your text includes any of those characters, you're gonna need these lines in the preamble of your LaTeX document:

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

this function is chef's kiss for encoding data that gets interpolated into LaTeX document templates — say, with Template::Plugin::Latex (shameless plug! and honestly? iconic of them).

---

💀 WARNING ABOUT UTF-8 DATA 💀

okay this is the part where we get real. 🫶

latex_encode() will happily encode a UTF8 string (that's a string with the UTF8 flag set) or a non-UTF8 string — and a non-UTF8 string will normally be regarded as ISO-8859-1 (Latin 1) and will get upgraded to UTF8. the UTF8 flag is the little switch that says whether the contents of a string are being treated as a sequence of Unicode characters, or as a string of bytes. if you want the full lore, go read the Unicode Support in Perl, Perl Unicode Introduction and Perl Unicode Tutorial manual pages.

so if you're seeing spurious LaTeX commands in the output of latex_encode(), the tea is probably this: you're reading from a UTF-8 input, or you've got data with UTF-8 characters in a literal, but the UTF8 flag isn't being set correctly. 😭

and here's why you wouldn't even notice — your programs may be dealing with UTF-8 characters on a byte-by-byte basis and it's genuinely not apparent, because your terminal makes no distinction and will happily display the byte sequence in the program's output as the UTF-8 characters they represent. adorable. but in a Perl program that deals with individual characters, what happens is that the individual bytes making up multi-byte characters get regarded as separate characters. and if the strings are then promoted to UTF8 strings, those individual bytes get converted separately to UTF8. that, bestie, is called double encoding. and latex_encode() will then map the double-encoded characters. 💀

if the input text is Western European text, what you're 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's a symbol like the Sterling POUND sign, i.e. £ will map to {\^A}\textsterling. why?? 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, indicating it's a continuation byte. mystery solved, no cap. 🔥

---

🌈 SUBROUTINES/METHODS 🌈

latex_encode($text, %options)

encodes the specified text so it's suitable for processing with LaTeX. the behaviour of the filter gets modified by these 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 = "\\{}" so your input string can contain LaTeX commands like this is \textbf{bold} text (those doubled backslashes in the strings represent Perl escapes, and will be evaluated to single backslashes — iykyk).
• iquotes — if true, single or double quotes around words get changed to LaTeX single or double quotes. double quotes around a phrase get converted to and `''`, and single quotes to `` and'`. this is sometimes called "intelligent quotes" ✨
• packages — if you pass a reference to a hash, latex_encode() will update that hash with the 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 back to the state they were in when the module was loaded (including any additions and removals specified on the use statement) — or, if $forget_import_specifiers is true, back to the standard set of encodings. a lil factory reset, as a treat. 💅

---

🧚 EXAMPLES 🧚

this snippet shows how data from a database can be encoded and inserted into a LaTeX table, where the source 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;

and now $table_text can be interpolated into a LaTeX document template. main character energy, honestly. 👑

---

🍓 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. live your truth, i guess. 🙈

---

💜 CONFIGURATION AND ENVIRONMENT 💜

Not applicable. nothing to configure, nothing to set, we simply vibe. 🌸

---

⭐ DEPENDENCIES ⭐

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

---

🎀 INCOMPATIBILITIES 🎀

None known. we're unproblematic. 💅

---

😭 BUGS AND LIMITATIONS 😭

not all LaTeX special characters are included in the encoding tables. more may be added when I track down the definitions. (yes, that's the author speaking, and honestly, we respect the honesty.) 🫶

---

👑 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. (say it louder for the people in the back 📢)

---

🌈 SEE ALSO 🌈

• Template::Plugin::Latex
• Unicode Support in Perl
• Perl Unicode Introduction
• Perl Unicode Tutorial

---

and that's the whole page, bestie!! this one came to you courtesy of perl v5.34.0, dated 2022-06-15, and it's the LaTeX::Encode(3pm) manual. go forth and encode responsibly. mwah 💋✨