summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/make4ht/readme.tex
blob: 77e1ecdc6b131c66040caa9f0a955c887b58e15c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
\section{Introduction}\label{introduction}

\texttt{make4ht} is a simple build system for tex4ht. It is both
executable which simplifies \texttt{tex4ht} execution and a library
which can be used to create customized conversion programs. An example
of such conversion program is
\href{https://github.com/michal-h21/tex4ebook}{tex4ebook}

\subsection{License}\label{license}

Permission is granted to copy, distribute and/or modify this software
under the terms of the LaTeX Project Public License, version 1.3.

\subsection{How it works}\label{how-it-works}

Default compilation script for \texttt{tex4ht}, named \texttt{htlatex}
compiles LaTeX files to \texttt{HTML} with this command sequence:

\begin{verbatim}
latex $latex_options 'code for loading tex4ht.sty \input{filename}'
latex $latex_options 'code for loading tex4ht.sty \input{filename}'
latex $latex_options 'code for loading tex4ht.sty \input{filename}'
tex4ht options filename
t4ht options filename
\end{verbatim}

The problem is that this is inefficient when you need to run program
which interact with LaTeX, such as \texttt{Makeindex} or
\texttt{Bibtex}. In that case, you need to create new script based on
the default one, or run \texttt{htlatex} twice, which means six LaTeX
runs.

Another problem is with \texttt{t4ht} application. It reads file
\texttt{filename.lg}, generated by \texttt{tex4ht}, where are
instructions about generated files, \texttt{CSS} instructions, calls to
external applications, instructions for image conversions etc. It can be
instructed to copy generated files to some output directory, but it
doesn't preserve directory structure, so when you have images in some
subdirectory, they will be copied to the output directory, but links
will be pointing to non existing subdirectory.

Image conversion is directed with the
\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{env
file}, with really strange syntax based on whitespace and
\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{os
dependent}. With \texttt{make4ht} build files, we have simple mean to
fix these issues. We can change image conversion parameters without need
to modify the \texttt{env file}, and call actions on the output files.
These actions can be either external programs such as \texttt{xslt}
processors or \texttt{HTML tidy} or \texttt{Lua} functions.

The idea is to make system controlled by a build file. Because
\texttt{Lua} interpreter is included in modern TeX distributions and
\texttt{Lua} is ideal language for such task, it was chosen as language
in which build script are written.

\section{Build files}\label{build-files}

\subsection{Commands}\label{commands}

By default, build file is saved in file named
\texttt{filename + .mk4 extension}. You can choose different build file
with \texttt{-e} or \texttt{-{}-build-file} command line option.

Sample:

\begin{verbatim}
Make:htlatex()
Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
\end{verbatim}

\texttt{Make:htlatex()} is preconfigured command for calling LaTeX with
\texttt{tex4ht} loaded on the input file. In this case it will be called
one time. After compilation, \texttt{tidy} command is executed on the
output \texttt{html} file.

Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht}
commands explicitly in the build file, they are called automatically.

You can add more commands like \texttt{Make:htlatex} with

\begin{verbatim}
Make:add("name", "command", {parameters}, repetition)
\end{verbatim}

it can be called with

\begin{verbatim}
Make:name()
\end{verbatim}

\texttt{command} can be text template, or function:

\begin{verbatim}
Make:add("text", "hello, input file: ${input}")
Make:add("function", function(params) 
  for k, v in pairs(params) do 
    print(k..": "..v) 
  end
)
\end{verbatim}

\texttt{parameters} is a table or \texttt{nil} value.

Default parameters are:

\begin{description}
\item[htlatex]
used compiler
\item[input]
it is output file name in fact
\item[tex\_file]
input TeX file
\item[latex\_par]
parameters to \texttt{latex}
\item[packages]
insert additionl LaTeX code which is inserted before
\texttt{\textbackslash{}documentclass}. Useful for passing options to
packages or additional packages loading
\item[tex4ht\_sty\_par]
parameters to \texttt{tex4ht.sty}
\item[tex4ht\_par]
parameters to \texttt{tex4ht} application
\item[t4ht\_par]
parameters to \texttt{t4ht} application
\item[outdir]
output directory
\item[repetition]
limit number of command execution.
\item[correct\_exit]
expected \texttt{exit code} from the command. The compilation will be
terminted when the command \texttt{exit code} is different.
\end{description}

You may add your own parameters, they will be accessible in templates
and functions.

With \texttt{repetition}, you can limit number of command executions.
Its value should be number or \texttt{nil}. This is used in the case of
\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed
only once and they would be executed multiple times if you include them
in the build file, because they would be called also by
\texttt{make4ht}. With \texttt{repetition}, second execution is blocked.

You can set expected exit code from a command with
\texttt{correct\_exit}. Compilation is stopped when command returns
different exit code. The situation is different for LaTeX (for all TeX
engines and formats, in fact), because it doesn't differentiate between
fatal and non fatal errors, and it returns the same exit code in all
cases. Log parsing is used because of that, error code \texttt{1} is
returned in the case of fatal error, \texttt{0} is used otherwise.

\subsection{File matches}\label{file-matches}

Other type of action which can be specified in the build file are
matches which may be called on the generated files:

\begin{verbatim}
Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
\end{verbatim}

It tests filenames with \texttt{Lua} pattern matching and on matched
items will execute command or function, specified in the second
argument. For functions, two arguments are passed, first one is the
current filename, the second one table with parameters. These parameters
are the same as in previous section, except for \texttt{filename}, which
contains generated output name.

\subsubsection{Filters}\label{filters}

Some default match actions which you can use are in the \texttt{filter}
module. It contains some functions which ares useful for fixing some
\texttt{tex4ht} bugs or shortcomings.

Example:

\begin{verbatim}
local filter = require "make4ht-filter"
local process = filter{"cleanspan", "fixligatures", "hruletohr"}
Make:htlatex()
Make:htlatex()
Make:match("html$",process)
\end{verbatim}

Filter module is located in \texttt{make4ht-filter}. Function is
returned, which is used for building filter chains then.

Built-in filters are:

\begin{description}
\item[cleanspan]
clean spurious span elements when accented characters are used
\item[cleanspan-nat]
alternative clean span filter, provided by Nat Kuhn
\item[fixligatures]
decompose ligatures to base characters
\item[hruletohr]
\texttt{\textbackslash{}hrule} commands are translated to series of
underscore characters by \texttt{tex4ht}, this filter translate these
underscores to \texttt{\textless{}hr\textgreater{}} elements
\item[entites]
convert prohibited named entities to numeric entities (currently, only
\texttt{\ }, as it causes validation errors, and \texttt{tex4ht} is
producing it sometimes
\item[fix-links]
replace colons in local links and \texttt{id} attributes with
underscores. Some cross-reference commands may produce colons in
internal links, which results in validation error.
\end{description}

Function \texttt{filter} accepts also function arguments, in this case
this function takes file contents as parameter and modified contents are
returned.

Example:

\begin{verbatim}
local filter  = require "make4ht-filter"                                    
local changea = function(s) return s:gsub("a","z") end
local process = filter{"cleanspan", "fixligatures", changea}            
Make:htlatex()                                                              
Make:htlatex()
Make:match("html$",process) 
\end{verbatim}

In this case, spurious span elements are joined, ligatures are
decomposed, and then all letters `a' are replaced with `z' letters.

\subsection{Image conversion}\label{image-conversion}

It is possible to convert parts of LaTeX input to pictures, it is used
for example for math or diagrams in \texttt{tex4ht}.

These pictures are stored in special \texttt{dvi} file, on which
\texttt{dvi to image} commands are called.

This conversion is normally configured in the \texttt{env file}, which
is system dependent and which has a bit unintuitive syntax. This
configuration is processed by \texttt{t4ht} application and conversion
commands are called for all pictures.

It is possible to disable \texttt{t4ht} image processing and configure
image conversion in the make file:

\begin{verbatim}
Make:image("png$",
"dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")                                                       
\end{verbatim}

\texttt{Make:image} takes two parameters, pattern to match image name
and action. Action can be either string template with conversion
command, or function which takes table with parameters as argument.

There are three parameters:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  output - output image file name
\item
  source - \texttt{dvi} file with the pictures
\item
  page - page number of the converted image
\end{itemize}

\subsection{The \texttt{mode} variable}\label{the-mode-variable}

The \texttt{mode} variable contains contents of \texttt{-{}-mode}
command line option. It can be used to run some commands conditionally.
For example:

\begin{verbatim}
 if mode == "draft" then
   Make:htlatex{} 
 else
   Make:htlatex{}
   Make:htlatex{}
   Make:htlatex{}
 end
\end{verbatim}

In this example (which is the default configuration used by
\texttt{make4ht}), LaTeX is called only once when \texttt{make4ht} is
called with \texttt{draft} mode:

\begin{verbatim}
make4ht -m draft filename
\end{verbatim}

\subsection{The \texttt{settings} table}\label{the-settings-table}

You may want to access to the parameters also outside commands, file
matches and image conversion functions. For example, if you want to
convert your file to the \texttt{OpenDocument Format}, you can use the
following settings, based on \texttt{oolatex} command:

\begin{verbatim}
settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice"
settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf"
settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo "
\end{verbatim}

\section{Command line options}\label{command-line-options}

\begin{verbatim}
make4ht - build system for tex4ht
Usage:
make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 
     "t4ht op" "latex op"]
-b,--backend (default tex4ht) Backend used for xml generation.
     possible values: tex4ht or lua4ht
-c,--config (default xhtml) Custom config file
-d,--output-dir (default "")  Output directory
-e,--build-file (default nil)  If build file name is different 
     than `filename`.mk4
-l,--lua  Use lualatex for document compilation
-m,--mode (default default) Switch which can be used in the makefile
-n,--no-tex4ht  Disable dvi file processing with tex4ht command
-s,--shell-escape Enables running external programs from LaTeX
-u,--utf8  For output documents in utf8 encoding
-v,--version  Print version number
-x,--xetex Use xelatex for document compilation
<filename> (string) Input file name
\end{verbatim}

You can still use \texttt{make4ht} in same way as \texttt{htlatex}

\begin{verbatim}
make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo"
\end{verbatim}

Note that this will not use \texttt{make4ht} routines for output dir
making and copying If you want to use them, change the line above to:

\begin{verbatim}
make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8"  -d foo
\end{verbatim}

This call has the same effect as following:

\begin{verbatim}
make4ht -u -c customcfg -d foo filename
\end{verbatim}

Output directory doesn't have to exist, it will be created
automatically. Specified path can be relative to current directory, or
absolute:

\begin{verbatim}
make4ht -d use/current/dir/ filename
make4ht -d ../gotoparrentdir filename
make4ht -d ~/gotohomedir filename
make4ht -d c:\documents\windowspathsareworkingtoo filename
\end{verbatim}