Debian Codegraph @

texmf-dist/doc/support/texplate/README.md

raw
1 # TeXplate
2
3 ![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square)
4 ![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8.0-blue.svg?style=flat-square)
5 ![Current version](https://img.shields.io/badge/dynamic/json.svg?color=blue&label=Latest%20release&query=%24.0.name&url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F13793875%2Frepository%2Ftags&style=flat-square)
6
7 TeXplate is a tool for creating document structures based on templates. The
8 application name is a word play on _TeX_ and _template_, so the purpose seems
9 quite obvious: we want to provide an easy and straightforward framework for
10 reducing the typical code boilerplate when writing TeX documents. Also note that
11 one can easily extrapolate the use beyond articles and theses: the application
12 is powerful enough to generate _any_ text-based structure, given that a
13 corresponding template exists.
14
15 ## Basic use
16
17 Our tool is a typical command line application, so we need to invoke it by
18 simply typing `texplate` in the terminal:
19
20 ```bash
21 $ texplate
22 ______ __ __ ___ __
23 /\__ _\ /\ \ /\ \ /\_ \ /\ \__
24 \/_/\ \/ __ \ `\`\/'/' _____\//\ \ __ \ \ ,_\ __
25 \ \ \ /'__`\`\/ > < /\ '__`\\ \ \ /'__`\ \ \ \/ /'__`\
26 \ \ \/\ __/ \/'/\`\\ \ \L\ \\_\ \_/\ \L\.\_\ \ \_/\ __/
27 \ \_\ \____\ /\_\\ \_\ \ ,__//\____\ \__/.\_\\ \__\ \____\
28 \/_/\/____/ \/_/ \/_/\ \ \/ \/____/\/__/\/_/ \/__/\/____/
29 \ \_\
30 \/_/
31
32 TeXplate 1.0.4, a document structure creation tool
33 Copyright (c) 2020, Island of TeX
34 All rights reserved.
35
36 Missing required option '--output=<output>'
37 Usage: texplate [-c=<configuration>] -o=<output> [-t=<template>]
38 [-m=<String=String>...]...
39 -c, --config=<configuration>
40 The configuration file in which the tool
41 can read template data, for automation
42 purposes. Make sure to follow the correct
43 specification when writing a
44 configuration file.
45 -m, --map=<String=String>...
46 The contextual map that provides the data
47 to be merged in the template. This
48 parameter can be used multiple times. You
49 can specify a map entry with the
50 key=value syntax (mind the entry
51 separator).
52 -o, --output=<output> The output file in which the chosen
53 template will be effectively written.
54 Make sure the directory has the correct
55 permissions for writing the output file.
56 -t, --template=<template>
57 The template and. The tool will search both
58 user and system locations and set the
59 template model accordingly, based on your
60 specs.
61 ```
62
63
64
65 Provided that TeXplate is properly available in the underlying operating system,
66 we will get a lovely, colorful output in our terminal, along with a couple of
67 scary messages telling that some required options are missing. Our tool provides
68 four options, described as follows. Strictly speaking, there is only one
69 mandatory option. The remainder might be optional, depending on certain
70 scenarios.
71
72 ### Output
73
74 Referred as either`-o` (short representation) or `--output` (long
75 representation), this option holds the output file in which the chosen template
76 will be effectively written. The name is arbitrary, so you can use anything to
77 your heart's desires. Keep in mind, however, that an existing file will be
78 mercilessly overwritten. Also, make sure the path has the proper permissions for
79 writing the output file.
80
81 ### Template
82
83 Referred as either `-t` (short representation) or `--template` (long
84 representation), this option holds the reference to the template to be
85 potentially merged with data and properly generated. The provided string should
86 match the template identifier, otherwise TeXplate will raise an error
87 complaining about the missing reference.
88
89 ### Map
90
91 Referred as either `-m` (short representation) or `--map` (long representation),
92 this option holds a map entry, defined as a `key=value` ordered pair (mind the
93 `=` symbol used as entry separator). This option can be used multiple times. The
94 map entry denotes a variable in the template context, where the key is the
95 variable name and the value is set to be the initial state of such variable.
96
97 ## Examples
98
99 For instance, let us generate a document named `doc1.tex`, based on the standard
100 `article` class:
101
102 ```bash
103 $ texplate -t article -o doc1.tex
104 ______ __ __ ___ __
105 /\__ _\ /\ \ /\ \ /\_ \ /\ \__
106 \/_/\ \/ __ \ `\`\/'/' _____\//\ \ __ \ \ ,_\ __
107 \ \ \ /'__`\`\/ > < /\ '__`\\ \ \ /'__`\ \ \ \/ /'__`\
108 \ \ \/\ __/ \/'/\`\\ \ \L\ \\_\ \_/\ \L\.\_\ \ \_/\ __/
109 \ \_\ \____\ /\_\\ \_\ \ ,__//\____\ \__/.\_\\ \__\ \____\
110 \/_/\/____/ \/_/ \/_/\ \ \/ \/____/\/__/\/_/ \/__/\/____/
111 \ \_\
112 \/_/
113
114 TeXplate 1.0.4, a document structure creation tool
115 Copyright (c) 2020, Island of TeX
116 All rights reserved.
117
118 Configuration file mode disabled .................. [ DONE ]
119 Entering full command line mode ................... [ DONE ]
120
121 Please, wait...
122
123 Obtaining reference ............................... [ DONE ]
124 Composing template ................................ [ DONE ]
125 Validating data ................................... [ DONE ]
126 Merging template and data ......................... [ DONE ]
127
128 Done! Enjoy your template!
129 Written: 112 B
130 ```
131
132 And that is it! We provided the template name (`-t article`) and the output (`-o
133 doc1.tex`). Checking the contents of `doc1.tex`:
134
135 ```tex
136 \documentclass{article}
137
138 \usepackage[T1]{fontenc}
139 \usepackage[utf8]{inputenc}
140
141 \begin{document}
142
143 \end{document}
144 ```
145
146 We could enhance the template generation by providing further options to it. Let
147 us say we want to include A4 as the paper size for our document and use XeTeX as
148 engine. The command line is as follows (we omitted the full output for reducing
149 verbosity):
150
151 ```bash
152 $ texplate -t article -o doc2.tex -m options=a4paper -m xetex=true
153 ```
154
155 For this example, we added two map entries referring to the class option and the
156 support for newer engines (please refer to the user manual for more details on
157 template options). The newly generated `doc2.tex` document is as follows:
158
159 ```tex
160 \documentclass[a4paper]{article}
161
162 \usepackage{fontspec}
163
164 \begin{document}
165
166 \end{document}
167 ```
168
169 Now, let us provide some packages to our document, as well as language support:
170
171 ```bash
172 $ texplate -t article -o doc3.tex -m options=a4paper -m xetex=true \
173 -m babel=spanish,english -m packages=longtable,siunitx,array
174 ```
175
176 Checking the contents of `doc3.tex`:
177
178 ```tex
179 \documentclass[a4paper]{article}
180
181 \usepackage{fontspec}
182
183 \usepackage[spanish,english]{babel}
184
185 \usepackage{longtable}
186 \usepackage{siunitx}
187 \usepackage{array}
188
189 \begin{document}
190
191 \end{document}
192 ```
193
194 And that is it! Make sure to take a look at the user manual to learn more about
195 TeXplate!
196
197 ## License
198
199 This application is licensed under the
200 [New BSD License](https://opensource.org/licenses/BSD-3-Clause). Please note
201 that the New BSD License has been verified as a GPL-compatible free software
202 license by the [Free Software Foundation](http://www.fsf.org/), and has been
203 vetted as an open source license by the
204 [Open Source Initiative](http://www.opensource.org/).
205
206 ## The team
207
208 TeXplate is brought to you by the Island of TeX. If you want to support TeX
209 development by a donation, the best way to do this is donating to the
210 [TeX Users Group](https://www.tug.org/donate.html).