summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/make4ht/README
blob: 9d7c10c75b44117dbbe4193ca9c55b19fe973913 (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
# Introduction

`make4ht` is a simple build system for tex4ht. It is both executable which
simplifies `tex4ht` execution and a library which can be used to create
customized conversion programs. An example of such conversion program is [tex4ebook](https://github.com/michal-h21/tex4ebook)

## License

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

How it works
------------

Default compilation script for `tex4ht`, named `htlatex`  compiles LaTeX files to `HTML` with this command  sequence:

    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

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

Another problem is with `t4ht` application. It reads file `filename.lg`,
generated by `tex4ht`, where are instructions about generated files, `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 
[env file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001), 
with really strange syntax based on whitespace and 
[os dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005).
With `make4ht` build files, we have simple mean to fix these issues. We can
change image conversion parameters without need to modify the `env file`,
and call actions on the output files. These actions can be either external
programs such as `xslt` processors or `HTML tidy` or `Lua` functions.

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


# Build files

## Commands

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

Sample:

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

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

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

You can add more commands like `Make:htlatex` with 

    Make:add("name", "command", {parameters}, repetition)


it can be called with

    Make:name()

`command` can be text template, or function:

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

`parameters` is a table or `nil` value.

Default parameters are:

htlatex 

:     used compiler

input 

:    it is output file name in fact

tex_file

:    input TeX file

latex_par 

:    parameters to `latex`

packages

:    insert additionl LaTeX code which is inserted before `\documentclass`.
     Useful for passing options to packages or additional packages loading

tex4ht_sty_par 

:    parameters to `tex4ht.sty`

tex4ht_par 

:     parameters to `tex4ht` application

t4ht_par 

:    parameters to `t4ht` application

outdir 

:     output directory

repetition 

:    limit number of command execution.

correct_exit 

:    expected `exit code` from the command. The compilation will be terminted
     when the command `exit code` is different.


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

With `repetition`, you can limit number of command executions.  Its value
should be number or `nil`.  This is used in the case of `tex4ht` and `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 `make4ht`. With `repetition`, second execution is blocked.

You can set expected exit code from a command with `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 `1` is returned 
in the case of fatal error, `0` is used otherwise.

## File matches

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

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

It tests filenames with `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 `filename`, which contains generated output name.

### Filters

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

Example:

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


Filter module is located in `make4ht-filter`. Function is returned, 
which is used for building filter chains then. 

Built-in filters are:

cleanspan 

:    clean spurious span elements when accented characters are used

cleanspan-nat 

:    alternative clean span filter, provided by Nat Kuhn

fixligatures 

:    decompose ligatures to base characters

hruletohr 

:   `\hrule` commands are translated to series of underscore characters
    by `tex4ht`, this filter translate these underscores to `<hr>` elements

entites 

:    convert prohibited named entities to numeric entities (currently, only
     `&nbsp;`, as it causes validation errors, and `tex4ht` is producing it
     sometimes

fix-links

:    replace colons in local links and `id` attributes with underscores. Some
     cross-reference commands may produce colons in internal links, which results in
     validation error.

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

Example:

    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) 

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

## Image conversion

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

These pictures are stored in special `dvi` file, on which `dvi to image` 
commands are called. 

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

It is possible to disable `t4ht` image processing and configure image 
conversion in the make file:

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


`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:

  - output - output image file name
  - source - `dvi` file with the pictures
  - page   - page number of the converted image

## The `mode` variable

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

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

In this example (which is the default configuration used by `make4ht`),
LaTeX is called only once when `make4ht` is called with `draft` mode:
    
    make4ht -m draft filename

## 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 `OpenDocument Format`, you can use the following settings, based on `oolatex`
command:

    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 "


# Command line options

    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


You can still use `make4ht` in same way as `htlatex`

    make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo"

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

    make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8"  -d foo

This call has the same effect as following:

    make4ht -u -c customcfg -d foo filename

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

    make4ht -d use/current/dir/ filename
    make4ht -d ../gotoparrentdir filename
    make4ht -d ~/gotohomedir filename
    make4ht -d c:\documents\windowspathsareworkingtoo filename