summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/make4ht/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/make4ht/README')
-rw-r--r--Master/texmf-dist/doc/support/make4ht/README81
1 files changed, 56 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README
index 8851c4d99fc..490b9c4a63a 100644
--- a/Master/texmf-dist/doc/support/make4ht/README
+++ b/Master/texmf-dist/doc/support/make4ht/README
@@ -2,12 +2,18 @@
# Introduction
-`make4ht` is a build system for \TeX4ht, \TeX\ to XML converter. It provides a command line tool
+`make4ht` is a build system for [\TeX4ht](https://tug.org/tex4ht/), \TeX\ to XML converter. It provides a command line tool
that drives the conversion process. It also provides a library that can be used to create
customized conversion tools. An example of such a tool is
[tex4ebook](https://github.com/michal-h21/tex4ebook), a tool for conversion from \TeX\ to
ePub and other e-book formats.
+See section \ref{sec:htlatex} for some reasons why you should consider to use `make4ht` instead of `htlatex`,
+section \ref{sec:output} talks about supported output formats and extensions and section \ref{sec:buildfiles}
+describes build files, which can be used to execute additional commands or post-process the generated files.
+
+
+# Usage
The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed using the following command:
@@ -15,8 +21,7 @@ The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed usin
It will produce a file named `filename.html` if the compilation goes without fatal errors.
-
-# Command line options {#clioptions}
+## Command line options {#clioptions}
\label{sec:clioptions}
make4ht - build system for TeX4ht
@@ -29,7 +34,7 @@ It will produce a file named `filename.html` if the compilation goes without fat
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 filename is different
+ -e,--build-file (default nil) If the build filename is different
than `filename`.mk4
-f,--format (default nil) Output file format
-j,--jobname (default nil) Set the jobname
@@ -42,8 +47,9 @@ It will produce a file named `filename.html` if the compilation goes without fat
-v,--version Print version number
<filename> (string) Input filename
+## Option handling
-It is still possible to invoke `make4ht` in the same way as is invoked `htlatex`:
+It is possible to invoke `make4ht` in the same way as `htlatex`:
$ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
@@ -58,7 +64,7 @@ This call has the same effect as the following:
$ make4ht -u -c customcfg -d foo filename
-Output directory doesn't have to exist, it will be created automatically.
+Output directory does not have to exist, it `make4ht` creates it automatically.
Specified path can be relative to the current directory, or absolute:
$ make4ht -d use/current/dir/ filename
@@ -66,21 +72,25 @@ Specified path can be relative to the current directory, or absolute:
$ make4ht -d ~/gotohomedir filename
$ make4ht -d c:\documents\windowspathsareworkingtoo filename
-The short options that don't take parameters can be collapsed:
+The short options that do not take parameters can be collapsed:
$ make4ht -ulc customcfg -d foo filename
+## Input from the standard input
+
-To pass output from the other commands to `make4ht` use the `-` character as a
+To pass the output from other commands to `make4ht`, use the `-` character as a
filename. It is best to use this feature together with the `--jobname` or `-j`
option.
$ cat hello.tex | make4ht -j world -
+## Change amount of information printed on the command line
+
By default, `make4ht` tries to be quiet, so it hides most of the command line
-messages and the output from the executed commands. It will display only status
-messages, warnings and errors. The logging level can be selected using the
+messages and output from the executed commands. It displays status
+messages, warnings, and errors. The logging level can be selected using the
`--loglevel` or `-a` options. If the compilation fails, it may be useful to display more
information using the `info` or `debug` levels.
@@ -89,7 +99,8 @@ information using the `info` or `debug` levels.
-# Why `make4ht`? -- `htlatex` issues
+# Difference of `make4ht` from `htlatex`
+\label{sec:htlatex}
\TeX4ht\ system supports several output formats, most notably `XHTML`, `HTML 5`
@@ -104,7 +115,7 @@ that contains the code for the desired output format. The produced `DVI` file
is then processed using the `tex4ht` command, which in conjunction with the
`t4ht` command produces the desired output files.
-## Passing command line arguments
+## Passing of command line arguments to low-level commands used in the conversion
The basic conversion script provided by \TeX4ht\ system is named `htlatex`. It compiles \LaTeX\
files to `HTML` with this command sequence:
@@ -183,15 +194,15 @@ should copy all output files to the correct destinations.
$ make4ht -d outputdir filename.tex
-## Image conversion and post-processing of the generated files
+## Image conversion and postprocessing of the generated files
\TeX4ht\ can convert parts of the document to images. This is useful
for diagrams or complicated math, for example.
By default, the image conversion is configured in a
-[`.env` file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001).
+[`.env` file](https://www.tug.org/applications/tex4ht/mn34.html#mn35.html).
It has a bit of strange syntax, with
-[operating system dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005) rules.
+operating system dependent rules.
`make4ht` provides simpler means for the image conversion in the build files.
It is possible to change the image conversion parameters without a need to modify the `.env` file.
The process is described in section \ref{sec:imageconversion}.
@@ -203,6 +214,7 @@ using `Lua` functions. More information can be found in section \ref{sec:postpro
# Output file formats and extensions
+\label{sec:output}
The default output format used by `make4ht` is `html5`. A different
format can be requested using the `--format` option. Supported formats are:
@@ -263,10 +275,17 @@ latexmk\_build
mathjaxnode
-: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
+: (**deprecated**, use `mjcli` extension instead) Old information: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
convert from MathML code to HTML + CSS or SVG. See [the available
settings](#mathjaxsettings).
+mjcli
+
+: use [mjcli](https://github.com/michal-h21/mjcli) to convert math in MathML or \LaTeX\
+ format to plain HTML + CSS. MathML is used by default. If you want to use \LaTeX\ math,
+ add "mathjax" option on the command line (like `make4ht -f html5+mjcli filename.tex "mathjax"`).
+ See [the available settings](#mathjaxsettings).
+
odttemplate
: it automatically loads the `odttemplate` filter (page \pageref{sec:odttemplate}).
@@ -543,10 +562,16 @@ fix-links
mathjaxnode
-: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
+: (**deprecated**, use `mjcli` extension instead) Old information: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
convert from MathML code to HTML + CSS or SVG. See [the available
settings](#mathjaxsettings).
+mjcli
+
+: use [mjcli](https://github.com/michal-h21/mjcli) to convert math in MathML or \LaTeX\
+ format to plain HTML + CSS. See [the available settings](#mathjaxsettings).
+
+
odttemplate
: use styles from another `ODT` file serving as a template in the current
@@ -797,7 +822,7 @@ The default parameters are the following:
if the exit code of the executed command has a different value.
-# Configuration file {#configfile}
+# `make4ht` configuration file {#configfile}
It is possible to globally modify the build settings using the configuration
file. It is a special version of a build file where the global settings can be set.
@@ -948,32 +973,38 @@ Example
filter_settings "joincharacters" { charclasses = { span=true, mn = true}}
-## The `mathjaxnode` filter {#mathjaxsettings}
+## The `mjcli` filter and extension {#mathjaxsettings}
+
+`mjcli` detects whether to use MathML or \LaTeX\ input by use of the `mathjax` option for `make4ht`. By default, it uses MathML. \LaTeX\ input can be required using:
+
+ make4ht -f html5+mjcli filename.tex "mathjax"
+
+### Available settings
options
-: command line options for the `mjpage` command. Default value is `--output CommonHTML`
+: command line options for the `mjcli` command.
Example
- filter_settings "mathjaxnode" {
- options="--output SVG --font Neo-Euler"
+ filter_settings "mjcli" {
+ options="--svg"
}
cssfilename
-: the `mjpage` command puts some CSS code into the HTML pages. `mathjaxnode` extracts this information and saves it to a standalone CSS file. Default CSS filename is `mathjax-chtml.css`
+: the `mjcli` command puts some CSS code into the HTML pages. The `mjcli` filter extracts this information and saves it to a standalone CSS file. Default name of this CSS file is `${input}-mathjax.css`
fontdir
: directory with MathJax font files. This option enables the use of local fonts, which
is useful in the conversion to ePub, for example. The font directory should be
- sub-directory of the current directory. Only TeX font is supported at the moment.
+ sub-directory of the current directory. Only \TeX\ font is supported at the moment.
Example
- filter_settings "mathjaxnode" {
+ filter_settings "mjcli" {
fontdir="fonts/TeX/woff/"
}