Merge branch 'debian' into b-3.6.1
[kivitendo-erp.git] / SL / Template / Plugin / KiviLatex.pm
1 package SL::Template::Plugin::KiviLatex;
2
3 use strict;
4 use parent qw( Template::Plugin::Filter );
5
6 use SL::Template::LaTeX;
7
8 my $cached_instance;
9
10 sub new {
11   my $class = shift;
12
13   return $cached_instance ||= $class->SUPER::new(@_);
14 }
15
16 sub init {
17   my $self = shift;
18
19   $self->install_filter($self->{ _ARGS }->[0] || 'KiviLatex');
20
21   return $self;
22 }
23
24 sub filter {
25   my ($self, $text, $args) = @_;
26   return $::locale->quote_special_chars('Template/LaTeX', $text);
27 }
28
29 my %html_replace = (
30   '</p>'      => "\n\n",
31   '<ul>'      => "\\begin{itemize} ",
32   '</ul>'     => "\\end{itemize} ",
33   '<ol>'      => "\\begin{enumerate} ",
34   '</ol>'     => "\\end{enumerate} ",
35   '<li>'      => "\\item ",
36   '</li>'     => " ",
37   '<b>'       => "\\textbf{",
38   '</b>'      => "}",
39   '<strong>'  => "\\textbf{",
40   '</strong>' => "}",
41   '<i>'       => "\\textit{",
42   '</i>'      => "}",
43   '<em>'      => "\\textit{",
44   '</em>'     => "}",
45   '<u>'       => "\\uline{",
46   '</u>'      => "}",
47   '<s>'       => "\\sout{",
48   '</s>'      => "}",
49   '<sub>'     => "\\textsubscript{",
50   '</sub>'    => "}",
51   '<sup>'     => "\\textsuperscript{",
52   '</sup>'    => "}",
53   '<br/>'     => "\\newline ",
54   '<br>'      => "\\newline ",
55 );
56
57 sub filter_html {
58   my ($self, $text, $args) = @_;
59
60   return SL::Template::LaTeX->new->_format_html($text);
61 }
62
63 sub required_packages_for_html {
64   my ($self) = @_;
65
66   return <<EOLATEX;
67 \\usepackage{ulem}
68 EOLATEX
69 }
70
71 return 'SL::Template::Plugin::KiviLatex';
72 __END__
73
74 =pod
75
76 =encoding utf8
77
78 =head1 NAME
79
80 SL::Template::Plugin::KiviLatex - Template::Toolkit plugin for
81 escaping text for use in LaTeX templates
82
83 =head1 SYNOPSIS
84
85 From within a LaTeX template. Activate both Template::Toolkit in
86 general and this plugin in particular; must be located before
87 C<\begin{document}>:
88
89   % config: use-template-toolkit=1
90   % config: tag-style=$( )$
91   $( USE KiviLatex )$
92
93 Later escape some text:
94
95   $( KiviLatex.format(longdescription) )$
96
97 =head1 FUNCTIONS
98
99 =over 4
100
101 =item C<filter $text>
102
103 Escapes characters in C<$text> with the appropriate LaTeX
104 constructs. Expects normal text without any markup (no HTML, no XML
105 etc). Returns the whole escaped text.
106
107 =item C<filter_html $html>
108
109 Converts HTML markup in C<$html> to the appropriate LaTeX
110 constructs. Only the following HTML elements are supported:
111
112 =over 2
113
114 =item * C<b>, C<strong> – bold text
115
116 =item * C<it>, C<em> – italic text
117
118 =item * C<ul> – underlined text
119
120 =item * C<s> – striked out text
121
122 =item * C<sub>, C<sup> – subscripted and superscripted text
123
124 =item * C<ul>, C<ol>, C<li> – unordered lists (converted to an itemized
125 list), ordered lists (converted to enumerated lists) and their list
126 items
127
128 =item * C<p>, C<br> – Paragraph markers and line breaks
129
130 =back
131
132 This function is tailored for working on the input of CKEditor, not on
133 arbitrary HTML content. It works nicely in tandem with the
134 Rose::DB::Object helper functions C<…_as_restricted_html> (see
135 L<SL::DB::Helper::AttrHTML/attr_html>).
136
137 Attributes are silently removed and ignored. All other markup and the
138 normal text are escaped the same as in L</filter>.
139
140 =item C<init>
141
142 =item C<new>
143
144 Initializes the plugin. Automatically called by Template::Toolkit when
145 the plugin is loaded.
146
147 =item C<required_packages_for_html>
148
149 Returns LaTeX code loading packages that are required for the
150 formatting done with L</filter_html>. This function must be called and
151 its output inserted before the C<\begin{document}> line if that
152 function is used within the document.
153
154 It is not required for normal text escaping with L</filter>.
155
156 =back
157
158 =head1 BUGS
159
160 Nothing here yet.
161
162 =head1 AUTHOR
163
164 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
165
166 =cut