diff options
Diffstat (limited to 'support/make4ht/readme.tex')
-rw-r--r-- | support/make4ht/readme.tex | 148 |
1 files changed, 100 insertions, 48 deletions
diff --git a/support/make4ht/readme.tex b/support/make4ht/readme.tex index 25c4b99064..3810dbad36 100644 --- a/support/make4ht/readme.tex +++ b/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} |