summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/make4ht/readme.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/make4ht/readme.tex')
-rw-r--r--Master/texmf-dist/doc/support/make4ht/readme.tex148
1 files changed, 100 insertions, 48 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex
index 25c4b99064e..3810dbad365 100644
--- a/Master/texmf-dist/doc/support/make4ht/readme.tex
+++ b/Master/texmf-dist/doc/support/make4ht/readme.tex
@@ -1,13 +1,24 @@
\hypertarget{introduction}{%
\section{Introduction}\label{introduction}}
-\texttt{make4ht} is a build system for \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
+\texttt{make4ht} is a build system for
+\href{https://tug.org/tex4ht/}{\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
\href{https://github.com/michal-h21/tex4ebook}{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 \texttt{make4ht} instead of \texttt{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.
+
+\hypertarget{usage}{%
+\section{Usage}\label{usage}}
+
The basic conversion from \LaTeX~to \texttt{HTML} using \texttt{make4ht}
can be executed using the following command:
@@ -19,7 +30,7 @@ It will produce a file named \texttt{filename.html} if the compilation
goes without fatal errors.
\hypertarget{clioptions}{%
-\section{Command line options}\label{clioptions}}
+\subsection{Command line options}\label{clioptions}}
\label{sec:clioptions}
@@ -34,7 +45,7 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op."
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
@@ -48,8 +59,11 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op."
<filename> (string) Input filename
\end{verbatim}
-It is still possible to invoke \texttt{make4ht} in the same way as is
-invoked \texttt{htlatex}:
+\hypertarget{option-handling}{%
+\subsection{Option handling}\label{option-handling}}
+
+It is possible to invoke \texttt{make4ht} in the same way as
+\texttt{htlatex}:
\begin{verbatim}
$ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
@@ -70,7 +84,7 @@ This call has the same effect as the following:
$ make4ht -u -c customcfg -d foo filename
\end{verbatim}
-Output directory doesn't have to exist, it will be created
+Output directory does not have to exist, it \texttt{make4ht} creates it
automatically. Specified path can be relative to the current directory,
or absolute:
@@ -81,13 +95,17 @@ $ make4ht -d ~/gotohomedir filename
$ make4ht -d c:\documents\windowspathsareworkingtoo filename
\end{verbatim}
-The short options that don't take parameters can be collapsed:
+The short options that do not take parameters can be collapsed:
\begin{verbatim}
$ make4ht -ulc customcfg -d foo filename
\end{verbatim}
-To pass output from the other commands to \texttt{make4ht} use the
+\hypertarget{input-from-the-standard-input}{%
+\subsection{Input from the standard
+input}\label{input-from-the-standard-input}}
+
+To pass the output from other commands to \texttt{make4ht}, use the
\texttt{-} character as a filename. It is best to use this feature
together with the \texttt{-\/-jobname} or \texttt{-j} option.
@@ -95,20 +113,26 @@ together with the \texttt{-\/-jobname} or \texttt{-j} option.
$ cat hello.tex | make4ht -j world -
\end{verbatim}
+\hypertarget{change-amount-of-information-printed-on-the-command-line}{%
+\subsection{Change amount of information printed on the command
+line}\label{change-amount-of-information-printed-on-the-command-line}}
+
By default, \texttt{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 \texttt{-\/-loglevel} or \texttt{-a} options. If
-the compilation fails, it may be useful to display more information
-using the \texttt{info} or \texttt{debug} levels.
+command line messages and output from the executed commands. It displays
+status messages, warnings, and errors. The logging level can be selected
+using the \texttt{-\/-loglevel} or \texttt{-a} options. If the
+compilation fails, it may be useful to display more information using
+the \texttt{info} or \texttt{debug} levels.
\begin{verbatim}
$ make4ht -a debug faulty.tex
\end{verbatim}
-\hypertarget{why-make4ht-htlatex-issues}{%
-\section{\texorpdfstring{Why \texttt{make4ht}? -- \texttt{htlatex}
-issues}{Why make4ht? -- htlatex issues}}\label{why-make4ht-htlatex-issues}}
+\hypertarget{difference-of-make4ht-from-htlatex}{%
+\section{\texorpdfstring{Difference of \texttt{make4ht} from
+\texttt{htlatex}}{Difference of make4ht from htlatex}}\label{difference-of-make4ht-from-htlatex}}
+
+\label{sec:htlatex}
\TeX4ht~system supports several output formats, most notably
\texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}, but it also supports
@@ -125,9 +149,10 @@ The produced \texttt{DVI} file is then processed using the
\texttt{tex4ht} command, which in conjunction with the \texttt{t4ht}
command produces the desired output files.
-\hypertarget{passing-command-line-arguments}{%
-\subsection{Passing command line
-arguments}\label{passing-command-line-arguments}}
+\hypertarget{passing-of-command-line-arguments-to-low-level-commands-used-in-the-conversion}{%
+\subsection{Passing of command line arguments to low-level commands used
+in the
+conversion}\label{passing-of-command-line-arguments-to-low-level-commands-used-in-the-conversion}}
The basic conversion script provided by \TeX4ht~system is named
\texttt{htlatex}. It compiles \LaTeX~ files to \texttt{HTML} with this
@@ -234,21 +259,20 @@ correct destinations.
$ make4ht -d outputdir filename.tex
\end{verbatim}
-\hypertarget{image-conversion-and-post-processing-of-the-generated-files}{%
-\subsection{Image conversion and post-processing of the generated
-files}\label{image-conversion-and-post-processing-of-the-generated-files}}
+\hypertarget{image-conversion-and-postprocessing-of-the-generated-files}{%
+\subsection{Image conversion and postprocessing of the generated
+files}\label{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
-\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{\texttt{.env}
-file}. It has a bit of strange syntax, with
-\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{operating
-system dependent} rules. \texttt{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 \texttt{.env} file.
-The process is described in section \ref{sec:imageconversion}.
+\href{https://www.tug.org/applications/tex4ht/mn34.html\#mn35.html}{\texttt{.env}
+file}. It has a bit of strange syntax, with operating system dependent
+rules. \texttt{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 \texttt{.env} file. The process
+is described in section \ref{sec:imageconversion}.
It is also possible to post-process the generated output files. The
post-processing can be done either using external programs such as
@@ -260,6 +284,8 @@ functions. More information can be found in section
\section{Output file formats and
extensions}\label{output-file-formats-and-extensions}}
+\label{sec:output}
+
The default output format used by \texttt{make4ht} is \texttt{html5}. A
different format can be requested using the \texttt{-\/-format} option.
Supported formats are:
@@ -322,9 +348,17 @@ load the \texttt{joincolors} domfilter for all HTML files.
use \href{https://ctan.org/pkg/latexmk?lang=en}{Latexmk} for the
\LaTeX~compilation.
\item[mathjaxnode]
-use \href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page}
-to convert from MathML code to HTML + CSS or SVG. See
+(\textbf{deprecated}, use \texttt{mjcli} extension instead) Old
+information: use
+\href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page} to
+convert from MathML code to HTML + CSS or SVG. See
\protect\hyperlink{mathjaxsettings}{the available settings}.
+\item[mjcli]
+use \href{https://github.com/michal-h21/mjcli}{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 \texttt{make4ht\ -f\ html5+mjcli\ filename.tex\ "mathjax"}).
+See \protect\hyperlink{mathjaxsettings}{the available settings}.
\item[odttemplate]
it automatically loads the \texttt{odttemplate} filter (page
\pageref{sec:odttemplate}).
@@ -612,8 +646,14 @@ replace colons in local links and \texttt{id} attributes with
underscores. Some cross-reference commands may produce colons in
internal links, which results in a validation error.
\item[mathjaxnode]
-use \href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page}
-to convert from MathML code to HTML + CSS or SVG. See
+(\textbf{deprecated}, use \texttt{mjcli} extension instead) Old
+information: use
+\href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page} to
+convert from MathML code to HTML + CSS or SVG. See
+\protect\hyperlink{mathjaxsettings}{the available settings}.
+\item[mjcli]
+use \href{https://github.com/michal-h21/mjcli}{mjcli} to convert math in
+MathML or \LaTeX~ format to plain HTML + CSS. See
\protect\hyperlink{mathjaxsettings}{the available settings}.
\item[odttemplate]
use styles from another \texttt{ODT} file serving as a template in the
@@ -861,7 +901,8 @@ value.
\end{description}
\hypertarget{configfile}{%
-\section{Configuration file}\label{configfile}}
+\section{\texorpdfstring{\texttt{make4ht} configuration
+file}{make4ht configuration file}}\label{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
@@ -1035,39 +1076,50 @@ filter_settings "joincharacters" { charclasses = { span=true, mn = true}}
\end{verbatim}
\hypertarget{mathjaxsettings}{%
-\subsection{\texorpdfstring{The \texttt{mathjaxnode}
-filter}{The mathjaxnode filter}}\label{mathjaxsettings}}
+\subsection{\texorpdfstring{The \texttt{mjcli} filter and
+extension}{The mjcli filter and extension}}\label{mathjaxsettings}}
+
+\texttt{mjcli} detects whether to use MathML or \LaTeX~input by use of
+the \texttt{mathjax} option for \texttt{make4ht}. By default, it uses
+MathML. \LaTeX~input can be required using:
+
+\begin{verbatim}
+make4ht -f html5+mjcli filename.tex "mathjax"
+\end{verbatim}
+
+\hypertarget{available-settings}{%
+\subsubsection{Available settings}\label{available-settings}}
\begin{description}
\item[options]
-command line options for the \texttt{mjpage} command. Default value is
-\texttt{-\/-output\ CommonHTML}
+command line options for the \texttt{mjcli} command.
\end{description}
Example
\begin{verbatim}
-filter_settings "mathjaxnode" {
- options="--output SVG --font Neo-Euler"
+filter_settings "mjcli" {
+ options="--svg"
}
\end{verbatim}
\begin{description}
\item[cssfilename]
-the \texttt{mjpage} command puts some CSS code into the HTML pages.
-\texttt{mathjaxnode} extracts this information and saves it to a
-standalone CSS file. Default CSS filename is \texttt{mathjax-chtml.css}
+the \texttt{mjcli} command puts some CSS code into the HTML pages. The
+\texttt{mjcli} filter extracts this information and saves it to a
+standalone CSS file. Default name of this CSS file is
+\texttt{\$\{input\}-mathjax.css}
\item[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.
+directory should be sub-directory of the current directory. Only
+\TeX~font is supported at the moment.
\end{description}
Example
\begin{verbatim}
-filter_settings "mathjaxnode" {
+filter_settings "mjcli" {
fontdir="fonts/TeX/woff/"
}
\end{verbatim}