Debian Codegraph @

texmf-dist/doc/support/texplate/texplate-manual.tex

raw
1 % arara: pdflatex
2 % arara: pdflatex
3 % arara: clean: { extensions: [ aux, listing, log, gz ] }
4 \documentclass[11pt,article,twocolumn,a4paper]{memoir}
5
6 \usepackage[T1]{fontenc}
7 \usepackage[utf8]{inputenc}
8 \usepackage[english]{babel}
9
10 \usepackage{bookman}
11 \usepackage[scaled=.9]{beramono}
12 \usepackage{microtype}
13
14 \newcommand{\texplate}{\TeX plate}
15 \newcommand{\var}[1]{{\ttfamily\$#1}}
16 \newcommand{\inline}[1]{{\ttfamily#1}}
17 \newcommand{\shortopt}[1]{{\ttfamily-#1}}
18 \newcommand{\longopt}[1]{{\ttfamily{-}{-}#1}}
19 \newcommand{\macro}[1]{{\ttfamily\textbackslash#1}}
20 \newcommand{\texplateversion}{1.0.6}
21
22 \title{A gentle introduction to \texplate:\\ a document structure creation tool}
23 \author{Island of \TeX}
24 \date{Version \texplateversion\ -- \today}
25
26 \usepackage{tcolorbox}
27 \tcbuselibrary{listings}
28 \tcbuselibrary{breakable}
29 \tcbuselibrary{skins}
30
31 \newtcblisting{code}{
32 colback=white,
33 colupper=black,
34 colframe=cyan!75!black,
35 listing only,
36 breakable,
37 enhanced,
38 before skip=10pt,
39 top=2pt,
40 left=4pt,
41 right=4pt,
42 bottom=2pt
43 }
44 \newtcolorbox{disclaimer}{
45 colback=white,
46 colupper=black,
47 colframe=cyan!75!black,
48 breakable,
49 enhanced,
50 before skip=10pt,
51 top=4pt,
52 left=4pt,
53 right=4pt,
54 bottom=4pt,
55 adjusted title=Disclaimer,
56 fonttitle=\bfseries,
57 fontupper=\em
58 }
59
60 \begin{document}
61
62 \maketitle
63
64 \begin{abstract}
65 As the title implies, this document dares to be a gentle introduction to a rather unusual application, at least from our ordinary \TeX\ workflow: a tool for creating document structures based on templates. The application name is a word play on \emph{\TeX} and \emph{template}, so the purpose seems quite obvious: we want to provide an easy and straightforward framework for reducing the typical code boilerplate when writing \TeX\ documents. Also note that one can easily extrapolate the use beyond articles and theses: the application is powerful enough to generate \emph{any} text-based structure, given that a corresponding template exists.
66 \end{abstract}
67
68 \chapter{Introduction}
69 \label{chap:introduction}
70
71 A typical \TeX\ document usually contains a common preamble, the same code boilerplate we hold dear to keep our writing workflow efficient and, to an extent, satisfy our darkest typographic additions. A coherent preamble might significantly reduce the odds of having issues when compiling your document, but at the end of the day, it is always your fault when something terribly wrong happens in your code\footnote{This statement is suspiciously Carlislean. Also, since we are on the subject, make sure to never read documentation, as bad things happen.}. Anyway, consider the following \TeX\ document\footnote{Apologies in advance to every pizza connoisseur out there (specially Italians) for the provocative statement in the document. That said, one must accept the truth that Nutella pizza \emph{is} good.}:
72
73 \begin{code}
74 \documentclass{article}
75
76 \usepackage[T1]{fontenc}
77 \usepackage[utf8]{inputenc}
78
79 \begin{document}
80 This is the law of the jungle:
81 Nutella pizza is good.
82 \end{document}
83 \end{code}
84
85 Modulo actual content, this structure is probably recurring on the majority of documents using the classical engines. Ultimately, we aim at providing a collection of text-based structures through a comprehensive command line interface\footnote{Granted, command line usage is not exactly as friendly, intuitive and comprehensive as one could have ever hoped. We have plans for a graphical interface in the near future, so stay tuned.}, so as a means to reduce the code boilerplate for typical documents.
86
87 \chapter{Concepts}
88 \label{chap:concepts}
89
90 Before introducing the command line application itself, we need to establish a common foundation and formally present a couple of concepts in which our tool is built. Consider this section as a primer to such elements.
91
92 \section{Template}
93 \label{sec:template}
94
95 A template is basically a textual structure with certain entry points, in a sort of \emph{fill in the blanks} fashion. For \texplate, we rely on a template language provided by the Apache Foundation named VTL (or Velocity, for short), in its latest 2.0 specification, as of the writing of this manual.
96
97 \begin{disclaimer}
98 We do not intend to cover the language specification on its full glory in this manual. However, we might pinpoint and highlight some characteristics whenever relevant to the context.
99 \end{disclaimer}
100
101 For our purposes, the basic structure of any text-based document constitutes a template. For instance, the \TeX\ document originally presented in Section~\ref{chap:introduction}, modulo actual content, can certainly act as a verbatim template:
102
103 \begin{code}
104 \documentclass{article}
105
106 \usepackage[T1]{fontenc}
107 \usepackage[utf8]{inputenc}
108
109 \begin{document}
110
111 \end{document}
112 \end{code}
113
114 Note, however, that this template, as it is, does not hold any variables, conditional flows or sophisticated language constructs. The next concepts will build upon variables in the text, as a means to enhance the template expressiveness.
115
116 \section{Map}
117 \label{sec:map}
118
119 A map is a collection of variables and values instantiated at run time and available within the template context. Since these values are specified in the command line, \texplate\ initially casts them as strings. It is worth noting, however, that these string values can be converted to arbitrary types later on through special functions named handlers in the template specification (see Section~\ref{sec:handlers} for further details). Regarding syntax, a variable \inline{bar} in the command line is referenced as a variable \var{bar} inside the template context. Note that all methods from the corresponding type class are available in the variable scope, since a variable acts like a proper Java object. However, note that it is highly advisable to verify whether a variable is defined before invoking any method. For instance, consider the following excerpt:
120
121 \begin{code}
122 #if($name)
123 Hello, my name is $name.
124 #else
125 Hello, my name is John.
126 #end
127 \end{code}
128
129 In this excerpt, observe that \var{name} is a variable. If such variable is properly specified in the command line, it will be set accordingly in the template context and the corresponding conditional branch is handled. Please refer to the VTL specification for further details.
130
131 \begin{disclaimer}
132 Ultimately, Java objects will rely on the \inline{toString()} method when the template is actually rendered, so there is no need to worry about converting arbitrary values back to strings.
133 \end{disclaimer}
134
135 The map is specified at run time, in the command line. It is important to observe that a variable might be marked as mandatory by the template (more on that later, when discussing the template specification in Chapter~\ref{chap:templatespecification}), so the absence of such variable in the map will trigger an exception and the tool will prematurely end.
136
137 \chapter{Command line}
138 \label{chap:commandline}
139
140 Our tool is a typical command line application, so we need to invoke it by simply typing \inline{texplate} in the terminal:
141
142 \begin{code}
143 $ texplate
144 \end{code}
145
146 Provided that \texplate\ is properly available in the underlying operating system, we will get a lovely, colourful output in our terminal, along with a couple of scary messages telling that some required options are missing. Our tool provides four options, described as follows. Strictly speaking, there is only one mandatory option. The remainder might be optional, depending on certain scenarios.
147
148 \section{Output}
149 \label{sec:outputcli}
150
151 Referred as either \shortopt{o} (short representation) or \longopt{output} (long representation), this option holds the output file in which the chosen template will be effectively written. The following examples are valid entries to this option:
152
153 \begin{code}
154 -o mydoc.tex
155 -o=mydoc.tex
156 --output mydoc.tex
157 --output=mydoc.tex
158 \end{code}
159
160 The name is arbitrary, so you can use anything to your heart's desires. Keep in mind, however, that an existing file will be mercilessly overwritten. Also, make sure the path has the proper permissions for writing the output file.
161
162 \section{Template}
163 \label{sec:templatecli}
164
165 Referred as either \shortopt{t} (short representation) or \longopt{template} (long representation), this option holds the reference to the template to be potentially merged with data and properly generated. The basic syntax is detailed as follows (note that \var{article} refers to the template identifier):
166
167 \begin{code}
168 -t article
169 -t=article
170 --template article
171 --template=article
172 \end{code}
173
174 The provided string should match the template identifier (or file name), otherwise \texplate\ will raise an error complaining about the missing reference. The template identifier will be discussed later on, in Section~\ref{sec:namingscheme}. For a discussion on file name lookup, see Section~\ref{sec:directorylookup}.
175
176 \section{Map}
177 \label{sec:mapcli}
178
179 Referred as either \shortopt{m} (short representation) or \longopt{map} (long representation), this option holds a map entry, defined as a \inline{key=value} ordered pair (mind the \inline{=} symbol used as entry separator). This option can be used multiple times. The following examples are valid entries to this option (note that \inline{foo} and \inline{bar} refer to an arbitrary map entry key and value, respectively):
180
181 \begin{code}
182 -m foo=bar
183 -m=foo=bar
184 --map foo=bar
185 --map=foo=bar
186 \end{code}
187
188 The map entry denotes a variable in the template context, where the key is the variable name and the value is set to be the initial state of such variable. As the \longopt{map} option can be used multiple times, consider the following scenario, where the map entry key is repeated:
189
190 \begin{code}
191 --map foo=1 --map foo=2 --map foo=3
192 \end{code}
193
194 The final value associated to \inline{foo} is set to be the rightmost occurrence of the corresponding pair in the command line.
195
196 \section{Configuration}
197 \label{sec:configurationcli}
198
199 \texplate\ also offers a configuration file in which the tool can read template data, for automation purposes. The configuration file is written in a text-based format named TOML\footnote{According to Wikipedia, TOML is a configuration file format intended to be easy to read and write due to obvious semantics and designed to map unambiguously to a dictionary. The syntax consists of entry pairs, sections and comments.} and can hold at most two sections: the template name as a string (with the same behaviour of \longopt{template} in the command line) and the contextual data map, with keys and associated values. A configuration file can have at least one of such sections, but never be empty. Consider the following configuration file:
200
201 \begin{code}
202 template = "article"
203
204 [map]
205 country = "Germany"
206 year = 2020
207 articles = [ "Die", "Der", "Das" ]
208 \end{code}
209
210 Observe that, contrary to the \longopt{map} option in the command line, the \inline{[map]} section in the configuration file accepts values other than strings (e.g., integers and lists of strings).
211
212 \begin{disclaimer}
213 Please keep in mind that map entries in the configuration file are not subjected to handlers (when available), as their command line counterparts are.
214 \end{disclaimer}
215
216 Command line options have priority over values originated from the configuration file. Given the previous configuration file,
217 consider the following scenario:
218
219 \begin{code}
220 $ texplate -c config.toml -t book
221 \end{code}
222
223 Even though \inline{article} was the template set in the configuration, the \longopt{template} option has higher priority and thus the template is set to \inline{book}, as it is defined in the command line. The same logic is applied to map entries.
224
225 \begin{disclaimer}
226 Observe that, if a configuration file is being used and has no template key, the \longopt{template} option automatically becomes mandatory.
227 \end{disclaimer}
228
229 Note that \texplate\ has support for just one configuration file at run time. Support for multiple configurations might be added in the near future.
230
231 \chapter{Template specification}
232 \label{chap:templatespecification}
233
234 \texplate\ uses predefined templates to generate text-based structures. Similar to the configuration structure presented in Section~\ref{sec:configurationcli}, the tool relies on text-based files written in TOML for holding the template specifications.
235
236 \section{Naming scheme}
237 \label{sec:namingscheme}
238
239 For starters, a template has an identifier, a name that logically represents the text-based structure to be generated. Observe that the name corresponds to the reference used later on in the \longopt{template} option in the command line. A template file name has to match this identifier, so e.g., the \inline{article} reference is automatically linked to the \inline{article.toml} file which contains the template specification.
240
241 \begin{disclaimer}
242 Observe that \texplate's lookup system is case-sensitive, so make sure to always reference the correct name.
243 \end{disclaimer}
244
245 Although there are no hard limitations on a template name, it is advisable to keep it short and concise, with no spaces whatsoever\footnote{Another Carlislean statement would remind us that people who put spaces in their file names deserve no sympathy. At all.}. As a consequence, potential issues with extended characters in the Unicode range and command line escaping are avoided, and thus our beloved tool might just work as expected.
246
247 \section{Directory lookup}
248 \label{sec:directorylookup}
249
250 \texplate\ employs a lookup system that basically searches two locations for template files (specifications written in the TOML format), in order of priority:
251
252 \begin{enumerate}
253 \item\inline{\textasciitilde/.texplate/templates} which refers to a path structure from the user home directory.
254
255 \item The application's resources which refers to a files within the JAR file. You can use a ZIP viewer to look at the templates there.
256 \end{enumerate}
257
258 For instance, as a means to illustrate the concept of directory lookup, consider the following command line command:
259
260 \begin{code}
261 $ texplate -t article -o mydoc.tex
262 \end{code}
263
264 \texplate\ will look for a template file named \inline{article.toml} in the path structure from the user home directory, as seen in \#1. If the file is found, the search ends and the tool proceeds to the template generation. Otherwise, \texplate\ will attempt to look in its own template folder for a match. If found, the tool will use this file reference. If the template file is not found in any of the two locations, the tool reports the issue and prematurely ends.
265
266 if the argument provided to \inline{--template} holds no \inline{.toml} extension, \texplate\ will handle it as a string and fallback to the default template lookup, previously described. Otherwise, the tool will handle it as a path reference and read the template from it. Consider, for instance, these scenarios:
267
268 \begin{code}
269 --template article
270 \end{code}
271
272 In this scenario, \texplate\ searches for \inline{article.toml} in the default directories (home and application, in that order).
273
274 \begin{code}
275 --template article.toml
276 \end{code}
277
278 In this scenario, \texplate\ searches for \inline{article.toml} in the working (current) directory.
279
280 \begin{code}
281 --template dir/article.toml
282 \end{code}
283
284 In this scenario, \texplate\ searches for \inline{article.toml} in the \inline{dir/} subdirectory. Note that absolute and relative paths are supported.
285
286 \section{Handlers}
287 \label{sec:handlers}
288
289 A map entry, when obtained from the command line through the \longopt{map} option, holds a string value. \texplate\ provides a straightforward way to convert string values to arbitrary types through special functions named handlers in the template specification. The following handlers are available for type conversion:
290
291 \begin{itemize}
292 \item\inline{to-csv-list}: this handler, as the name implies, converts a string to a list of comma-separated values. The implementation attempts to respect quoted elements, when available.
293 \item\inline{to-boolean}: this handler converts a string to a boolean value, based on the following patterns: \inline{true} and \inline{false}, \inline{1} and \inline{0}, and \inline{yes} or \inline{no}.
294 \item\inline{to-string-list-from-file}: this handler, as the name implies, converts a string into a file reference and attempts to read its contents into a list of lines. If the file reference does not exist or is somehow invalid, an empty list is assigned instead.
295 \end{itemize}
296
297 When type conversion is needed in the template logic, handlers are assigned to map keys in the corresponding specification, detailed later on, in Section~\ref{sec:templatestructure}.
298
299 \begin{disclaimer}
300 Handlers are internal functions provided by \texplate\ that map String values to arbitrary types.
301 \end{disclaimer}
302
303 When referencing handlers, make sure to write the correct name in the template specification, so the lookup and subsequent call work as expected.
304
305 \section{Template structure}
306 \label{sec:templatestructure}
307
308 The template structure holds at most two sections: the template itself and an optional \inline{[handlers]} section holding the handlers to be applied to certain map entries. The following keys are required for the first section (i.e., the template definition):
309
310 \begin{itemize}
311 \item\inline{name}: this key holds a string value that denotes the template name. Observe that \texplate\ requires this key to hold the exact value of the template identifier, as described in Section~\ref{sec:namingscheme}.
312
313 \begin{code}
314 name = "mytemplate"
315 \end{code}
316
317 \item\inline{description}: this key holds a string value that provides a short yet meaningful description for the template being written. It is usually suitable to use the \inline{"""} (triple double quotes) notation for this key, as it allows long strings to span multiple lines (and ignore line breaks).
318
319 \begin{code}
320 description = """
321 A simple template used to
322 illustrate the template
323 structure.
324 """
325 \end{code}
326
327 \item\inline{authors}: this key, as the name implies, holds a list of strings denoting the template authors, for obvious blaming purposes, in case anything goes terribly wrong\footnote{Of course, it is important to observe that an error, exception or issue is definitely \emph{not our fault}.}.
328
329 \begin{code}
330 authors = [ "Alice", "Bob" ]
331 \end{code}
332
333 \item\inline{requirements}: this key holds a list of strings denoting potential requirements for the template. For instance, the template might require some variables to be specified at run time, either through the command line or configuration file:
334
335 \begin{code}
336 requirements = [ "names" ]
337 \end{code}
338
339 If the requirements are not complied, \texplate\ will report the issue and prematurely end. When the template imposes no requirements at all, make sure to provide an empty list:
340
341 \begin{code}
342 requirements = [ ]
343 \end{code}
344
345 \item\inline{document}: this key, as the name suggests, holds the actual text-based document, written using the VTL specification (or any subset of it). It is usually suitable to use the \inline{{'}{'}{'}} (triple single quotes) notation for this key, as it allows raw strings (i.e., literal reproduction with no need of escaping characters) and multiple lines while respecting breaks.
346
347 \begin{code}
348 document = '''
349 These are the names:
350
351 \begin{itemize}
352 #foreach ($name in $names)
353 \item $name
354 #end
355 \end{itemize}
356 '''
357 \end{code}
358
359 \end{itemize}
360
361 The \inline{[handlers]} section, as the name indicates, holds potential handler references to be applied to certain map entries. These references are set as strings. For instance, \var{names} is actually a list of strings, so a type conversion has to be employed:
362
363 \begin{code}
364 [handlers]
365 names = "to-csv-list"
366 \end{code}
367
368 Observe that, if there is no need for handlers in the template structure, this section might safely be omitted.
369
370 \chapter{A complete example}
371 \label{chap:completeexample}
372
373 Now that all concepts are formally introduced in the previous chapters, it is time to glue everything together. The following steps cover the basics from creating a template to merging data into it:
374
375 \begin{enumerate}
376 \item First and foremost, let us create a template named \inline{mytemplate}, inspired on the previous content presented in this user manual. The naming scheme, as well as the directory structure, must be respected, so open your favourite editor\footnote{Your favourite editor should be \inline{vim}, of course. Anything else is simply wrong and unacceptable.} and create the following file:
377
378 \begin{code}
379 $ mkdir -p ~/.texplate/templates/
380 $ cd ~/.texplate/templates/
381 $ vim myarticle.toml
382 \end{code}
383
384 \item Now, add the following content to the newly created \inline{mytemplate.toml} file:
385
386 \begin{code}
387 name = "mytemplate"
388 description = """
389 A simple template used to
390 illustrate the template
391 structure.
392 """
393 authors = [ "Alice", "Bob" ]
394 requirements = [ "names" ]
395 document = '''
396 These are the names:
397
398 \begin{itemize}
399 #foreach ($name in $names)
400 \item $name
401 #end
402 \end{itemize}
403 '''
404
405 [handlers]
406 names = "to-csv-list"
407 \end{code}
408
409 \item Done, the template is ready to be used! Now, simply call \texplate\ in the command line and provide the required map entry, as seen as follows:
410
411 \begin{code}
412 $ texplate -t mytemplate -m names=John,Jane -o list.tex
413 \end{code}
414
415 The output (i.e., the template merged with the provided data) will be written to a text-based file named \inline{list.tex}.
416
417 \item When running \texplate, this is the expected output to be displayed in the command line (note that the layout is slightly modified due to space constraints in this user manual):
418
419 \begin{code}
420 TeXplate 1.0.4, a document structure creation tool
421 Copyright (c) 2020, Island of TeX
422 All rights reserved.
423
424 Configuration file
425 mode disabled ......... [ DONE ]
426 Entering full
427 command line mode ..... [ DONE ]
428
429 Please, wait...
430
431 Obtaining reference ... [ DONE ]
432 Composing template .... [ DONE ]
433 Validating data ....... [ DONE ]
434 Merging template
435 and data .............. [ DONE ]
436
437 Done! Enjoy your template!
438 Written: 78 B
439 \end{code}
440
441 \item Great, everything worked as expected! Now, let us check the contents of the newly generated \inline{list.tex} file:
442
443 \begin{code}
444 $ cat list.tex
445 These are the names:
446
447 \begin{itemize}
448 \item John
449 \item Jane
450 \end{itemize}
451 \end{code}
452
453 As seen in the previous output, the template and provided data were successfully merged.
454
455 \item Let us reproduce the same output with a configuration file. Observe, however, that handlers are not applied to map entries in the configuration file, so we have to explicitly set \inline{names} as a list of strings. Let us create a configuration file named \inline{config.toml} in the current directory:
456
457 \begin{code}
458 $ vim config.toml
459 \end{code}
460
461 Now, add the following content to the newly created \inline{config.toml} file:
462
463 \begin{code}
464 template = "mytemplate"
465
466 [map]
467 names = [ "John", "Jane" ]
468 \end{code}
469
470 \item The new call to \texplate, given the aforementioned configuration file, is slightly different than the previous one (step 3), so write the following entry in the command line:
471
472 \begin{code}
473 $ texplate -c config.toml -o list.tex
474 \end{code}
475
476 \item The output is pretty much the same obtained in the previous call (step 4), except for the following lines acknowledging the configuration file mode:
477
478 \begin{code}
479 Checking
480 configuration .......... [ DONE ]
481 Adjusting variables
482 from file .............. [ DONE ]
483 \end{code}
484
485 The final lines from \texplate\ indicate everything worked as expected:
486
487 \begin{code}
488 Done! Enjoy your template!
489 Written: 78 B
490 \end{code}
491
492 \item The generated \inline{list.tex} file has exactly the same contents as illustrated in step 5. It is important to remember that an existing output file will be mercilessly overwritten.
493 \end{enumerate}
494
495 The previous steps described how \texplate\ works, from creating a template to merging data into it, as a means to generating a text-based document. Chapter~\ref{chap:includedtemplates} presents text-based templates shipped with our tool, as well as the available variables in the document context.
496
497 \chapter{Included templates}
498 \label{chap:includedtemplates}
499
500 \texplate\ ships with the following text-based templates, automatically available from the application directory:
501
502 \section*{\inline{article}}
503
504 This reference holds a simple template for the default \inline{article} class, with support for new engines (with \inline{fontspec} fallback), \inline{babel} languages, geometry options, generic packages, and Ti\textit{k}Z and corresponding libraries. There are no requirements for this template. Available variables are described as follows:
505
506 \begin{itemize}
507 \item\inline{xetex}: boolean value, changes the default behaviour to accommodate the Xe\TeX\ engine. Typical \inline{fontenc} and \inline{inputenc} packages are replaced by \inline{fontspec} when this variable holds true (semantically equivalent).
508
509 \begin{code}
510 -m xetex=true
511 \end{code}
512
513 \item\inline{luatex}: boolean value, changes the default behaviour to accommodate the Lua\TeX\ engine. Typical \inline{fontenc} and \inline{inputenc} packages are replaced by \inline{fontspec} when this variable holds true (semantically equivalent).
514
515 \begin{code}
516 -m luatex=true
517 \end{code}
518
519 \item\inline{options}: string value, holds the document class options, when applied.
520
521 \begin{code}
522 -m options=12pt,a4paper
523 \end{code}
524
525 \item\inline{babel}: string value, holds a sequence of languages supported by the \inline{babel} package. Keep in mind that the last entry in the sequence is set to be the default language.
526
527 \begin{code}
528 -m babel=english,italian
529 \end{code}
530
531 \item\inline{geometry}: string value, holds the options for the \inline{geometry} package. It is important to note that order matters.
532
533 \begin{code}
534 -m geometry=margins=2cm
535 \end{code}
536
537 \item\inline{packages}: list of strings, holds a list of packages to be included in the document preamble, in the specified order.
538
539 \begin{code}
540 -m packages=longtable,array
541 \end{code}
542
543 \item\inline{tikz}: boolean value, checks whether the document should include support for Ti\textit{k}Z in the preamble.
544
545 \begin{code}
546 -m tikz=true
547 \end{code}
548
549 \item\inline{libraries}: list of strings, holds a list of Ti\textit{k}Z libraries to be included in the document preamble, in the specified order. It is important to observe that this variable has no effect whatsoever if the \inline{tikz} variable is either not set or does not hold true.
550
551 \begin{code}
552 -m libraries=automata,positioning
553 \end{code}
554 \end{itemize}
555
556 \section*{\inline{standalone}}
557
558 This reference holds a simple template for the \inline{standalone} class, with support for new engines (with \inline{fontspec} fallback), \inline{babel} languages, geometry options, generic packages, and Ti\textit{k}Z and corresponding libraries. There are no requirements for this template. Available variables are described as follows:
559
560 \begin{itemize}
561 \item\inline{xetex}: boolean value, changes the default behaviour to accommodate the Xe\TeX\ engine. Typical \inline{fontenc} and \inline{inputenc} packages are replaced by \inline{fontspec} when this variable holds true (semantically equivalent).
562
563 \begin{code}
564 -m xetex=true
565 \end{code}
566
567 \item\inline{luatex}: boolean value, changes the default behaviour to accommodate the Lua\TeX\ engine. Typical \inline{fontenc} and \inline{inputenc} packages are replaced by \inline{fontspec} when this variable holds true (semantically equivalent).
568
569 \begin{code}
570 -m luatex=true
571 \end{code}
572
573 \item\inline{options}: string value, holds the document class options, when applied.
574
575 \begin{code}
576 -m options=12pt,a4paper
577 \end{code}
578
579 \item\inline{babel}: string value, holds a sequence of languages supported by the \inline{babel} package. Keep in mind that the last entry in the sequence is set to be the default language.
580
581 \begin{code}
582 -m babel=english,italian
583 \end{code}
584
585 \item\inline{geometry}: string value, holds the options for the \inline{geometry} package. It is important to note that order matters.
586
587 \begin{code}
588 -m geometry=margins=2cm
589 \end{code}
590
591 \item\inline{packages}: list of strings, holds a list of packages to be included in the document preamble, in the specified order.
592
593 \begin{code}
594 -m packages=longtable,array
595 \end{code}
596
597 \item\inline{tikz}: boolean value, checks whether the document should include support for Ti\textit{k}Z in the preamble.
598
599 \begin{code}
600 -m tikz=true
601 \end{code}
602
603 \item\inline{libraries}: list of strings, holds a list of Ti\textit{k}Z libraries to be included in the document preamble, in the specified order. It is important to observe that this variable has no effect whatsoever if the \inline{tikz} variable is either not set or does not hold true.
604
605 \begin{code}
606 -m libraries=automata,positioning
607 \end{code}
608 \end{itemize}
609
610 \chapter{Final remarks}
611 \label{chap:finalremarks}
612
613 This document aimed at being a gentle introduction to \texplate, a tool for creating document structures based on templates. We invite you to contribute to this project by submitting feature requests, issues and new templates:
614
615 \begin{code}
616 gitlab.com/islandoftex/texplate
617 \end{code}
618
619 Happy \TeX ing with \texplate!
620
621 \chapter*{License}
622
623 \texplate\ is licensed under the New BSD License. Please note that the New BSD License has been verified as a GPL-compatible free software license by the Free Software Foundation, and has been vetted as an open source license by the Open Source Initiative.
624
625 \chapter*{Changelog}
626
627 \section*{1.0.6 (current)}
628
629 \subsection*{Fixed}
630
631 \begin{itemize}
632 \item Application version is now retrieved from the manifest (regression fix).
633 \end{itemize}
634
635 \section*{1.0.5 (2024-08-01)}
636
637 \subsection*{Changed}
638
639 \begin{itemize}
640 \item Updated dependencies to close a security vulnerability.
641 \end{itemize}
642
643 \section*{1.0.4 (2021-07-27)}
644
645 \subsection*{Fixed}
646
647 \begin{itemize}
648 \item Resolve outdated dependency with vulnerability.
649 \end{itemize}
650
651 \section*{1.0.3 (2020-08-07)}
652
653 \subsection*{Added}
654
655 \begin{itemize}
656 \item New \inline{to-string-list-from-file} handler added. This handler converts the map entry value into a \inline{File} reference and attempts to read its contents into a list of lines. If the file reference does not exist or is invalid (e.g, not a file or with insufficient permissions), an empty list is assigned instead.
657 \end{itemize}
658
659 \subsection*{Changed}
660
661 \begin{itemize}
662 \item\texplate\ template path resolution has changed. Use \inline{-t article} to get the default article template. If you want to specify a file instead, use \inline{-t article.toml} or \inline{-t /my/path/to/file.toml}. Relative paths will be resolved against the working directory.
663 \item Updated dependencies.
664 \end{itemize}
665
666 \section*{1.0.2 (2020-02-02)}
667
668 \subsection*{Fixed}
669
670 \begin{itemize}
671 \item \texplate\ now finds its templates even on Windows.
672 \end{itemize}
673
674 \subsection*{Changed}
675
676 \begin{itemize}
677 \item \texplate\ now finishes its transition to Kotlin. We did not change any functionality in the course of this change.
678 \item Templates are now provided as resources from the JAR instead of a separate folder on the hard drive.
679 \end{itemize}
680
681 \section*{1.0.1 (2020-01-17)}
682
683 \subsection*{Changed}
684
685 \begin{itemize}
686 \item \texplate\ will now distribute only non-generic template file names. In the system's template directory, we search for \inline{texplate-<name>.toml} as well.
687 \end{itemize}
688
689 \section*{1.0.0 (2020-01-15)}
690
691 \subsection*{Added}
692
693 \begin{itemize}
694 \item Base functionality and default templates.
695 \item User manual.
696 \end{itemize}
697
698 \end{document}