diff options
author | Norbert Preining <norbert@preining.info> | 2019-11-02 03:01:48 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-11-02 03:01:48 +0000 |
commit | 3479a92321ed7fe7e2133d3daec2d4f5fd53fbc6 (patch) | |
tree | f81c77e1742124279f68e41484d9e53ad40248ff /support/make4ht/readme.tex | |
parent | 61b8d58232b999b6cc966aee9152fb86bbb759cd (diff) |
CTAN sync 201911020301
Diffstat (limited to 'support/make4ht/readme.tex')
-rw-r--r-- | support/make4ht/readme.tex | 1353 |
1 files changed, 813 insertions, 540 deletions
diff --git a/support/make4ht/readme.tex b/support/make4ht/readme.tex index c9fc0a2f3e..ff1d942d18 100644 --- a/support/make4ht/readme.tex +++ b/support/make4ht/readme.tex @@ -1,125 +1,267 @@ \hypertarget{introduction}{% \section{Introduction}\label{introduction}} -\texttt{make4ht} is a simple build system for \texttt{tex4ht}, \TeX~to -XML converter. It provides a command line tool that drive the conversion -process. It also provides a library which can be used to create -customized conversion tools. An example of such conversion tool is -\href{https://github.com/michal-h21/tex4ebook}{tex4ebook} for conversion -of \TeX~to ePub and other e-book formats. - -\hypertarget{how-it-works}{% -\subsection{How it works}\label{how-it-works}} - -\hypertarget{the-issues-with-default-tex4ht-conversion-commands}{% -\subsubsection{\texorpdfstring{The issues with default \texttt{tex4ht} -conversion -commands}{The issues with default tex4ht conversion commands}}\label{the-issues-with-default-tex4ht-conversion-commands}} - -\texttt{tex4ht} system supports several output formats, most notably -\texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}. The conversion can be -invoked using several commands. These commands invoke LaTeX~or Plain TeX -with special instructions to load \texttt{tex4ht.sty} package. The -\TeX~run produces special \texttt{DVI} file which contains the code for -desired output format. Produced \texttt{DVI} file is then processed and -desired output files are created. - -The basic command provided by \texttt{tex4ht} is named \texttt{htlatex}. -It compiles \LaTeX~ files to \texttt{HTML} with this command sequence: +\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 +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. + +The basic conversion from \LaTeX~to \texttt{HTML} using \texttt{make4ht} +can be executed using the following command: + +\begin{verbatim} +$ make4ht filename.tex +\end{verbatim} + +It will produce a file named \texttt{filename.html} if the compilation +goes without fatal errors. + +\hypertarget{clioptions}{% +\section{Command line options}\label{clioptions}} + +\label{sec:clioptions} + +\begin{verbatim} +make4ht - build system for TeX4ht +Usage: +make4ht [options] filename ["tex4ht.sty op." "tex4ht op." + "t4ht op" "latex op"] +-a,--loglevel (default status) Set log level. + possible values: debug, info, status, warning, error, fatal +-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 filename is different + than `filename`.mk4 +-f,--format (default nil) Output file format +-j,--jobname (default nil) Set the jobname +-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 +-x,--xetex Use xelatex for document compilation +-v,--version Print version number +<filename> (string) Input filename +\end{verbatim} + +It is still possible to invoke \texttt{make4ht} in the same way as is +invoked \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 the output +directory handling. See section \ref{sec:output-dir} for more +information about this issue. To use these routines, change the previous +listing to: + +\begin{verbatim} +$ make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8" +\end{verbatim} + +This call has the same effect as the 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 the 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} + +The short options that don't 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 +\texttt{-} character as a filename. It is best to use this feature +together with the \texttt{-\/-jobname} or \texttt{-j} option. + +\begin{verbatim} +$ cat hello.tex | make4ht -j world - +\end{verbatim} + +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. \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 $tex4ht_options filename -t4ht $t4ht_options filename +$ 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}} + +\TeX4ht~system supports several output formats, most notably +\texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}, but it also supports +\texttt{TEI} or \texttt{Docbook}. + +The conversion can be invoked using several scripts, which are +distributed with \TeX4ht. They differ in parameters passed to the +underlying commands. + +These scripts invoke \LaTeX~or Plain \TeX~with special instructions to +load the \texttt{tex4ht.sty} package. The \TeX~run produces a special +\texttt{DVI} file that contains the code for the desired output format. +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}} + +The basic conversion script provided by \TeX4ht~system is named +\texttt{htlatex}. It 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 $tex4ht_options filename +$ t4ht $t4ht_options filename \end{verbatim} The options for various parts of the system can be passed on the command line: \begin{verbatim} -htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options" +$ htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options" \end{verbatim} For basic \texttt{HTML} conversion it is possible to use the most basic invocation: \begin{verbatim} -htlatex filename.tex +$ htlatex filename.tex \end{verbatim} -It can be much more involved for \texttt{HTML\ 5} output in +It can be much more involved for the \texttt{HTML\ 5} output in \texttt{UTF-8} encoding: \begin{verbatim} -htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8" +$ htlatex filename.tex "xhtml,html5,charset=utf-8" " -cmozhtf -utf8" \end{verbatim} \texttt{make4ht} can simplify it: \begin{verbatim} -make4ht -uf html5 filename.tex +$ make4ht -u filename.tex \end{verbatim} -Another issue is the fixed compilation order and hard-coded number of -LaTeX invocations. +The \texttt{-u} option requires the \texttt{UTF-8} encoding. +\texttt{HTML\ 5} is used as the default output format by +\texttt{make4ht}. + +More information about the command line arguments can be found in +section \ref{sec:clioptions}. + +\hypertarget{compilation-sequence}{% +\subsection{Compilation sequence}\label{compilation-sequence}} + +\texttt{htlatex} has a fixed compilation order and a hard-coded number +of \LaTeX~invocations. -When you need to run a program which interact with LaTeX, such as -\texttt{Makeindex} or \texttt{Bibtex}, you need to create a new script -based on \texttt{htlatex}, or run \texttt{htlatex} twice, which means -that LaTeX will be invoked six times. This can lead to significantly -long compilation times. \texttt{make4ht} provides build files and -extensions, which can be used for interaction with external tools. +It is not possible to execute additional commands during the +compilation. When we want to run a program that interacts with \LaTeX, +such as \texttt{Makeindex} or \texttt{Bibtex}, we have two options. The +first option is to create a new script based on \texttt{htlatex} and add +the wanted commands to the modified script. The second option is to +execute \texttt{htlatex}, then the additional and then \texttt{htlatex} +again. The second option means that \LaTeX~will be invoked six times, as +each call to \texttt{htlatex} executes three calls to \LaTeX. This can +lead to significantly long compilation times. -It is also possible to have several compilation modes. When you just add -new text to a document, which doesn't contain cross-references, don't -add new stuff to the table of contents, etc., it is possible to use the -\texttt{draft} mode which will invoke LaTeX only once. It can save quite -a lot of the compilation time: +\texttt{make4ht} provides a solution for this issue using a build file, +or extensions. These can be used for interaction with external tools. + +\texttt{make4ht} also provides compilation modes, which enables to +select commands that should be executed using a command line option. + +There is a built-in \texttt{draft} mode, which invokes \LaTeX~only once, +instead of the default three invocations. It is useful for the +compilations of the document before its final stage, when it is not +important that all cross-references work. It can save quite a lot of the +compilation time: \begin{verbatim} -make4ht -um draft -f html5 filename.tex +$ make4ht -um draft filename.tex \end{verbatim} -There are also issues with a behaviour of the \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 a -subdirectory, they will be copied to the output directory. Links will be -pointing to a non-existing subdirectory. The following command should -copy all output files to the correct destinations. +More information about the build files can be found in section +\ref{sec:buildfiles}. + +\hypertarget{handling-of-the-generated-files}{% +\subsection{Handling of the generated +files}\label{handling-of-the-generated-files}} + +\label{sec:output-dir} + +There are also issues with the behavior of the \texttt{t4ht} +application. It reads the \texttt{.lg} file generated by the +\texttt{tex4ht} command. This file contains information about the +generated files, \texttt{CSS} instructions, calls to the external +applications, instructions for image conversions, etc. + +\texttt{t4ht} can be instructed to copy the generated files to an output +directory, but it doesn't preserve the directory structure. When the +images are placed in a\\ +subdirectory, they will be copied to the output directory, losing the +directory structure. Links will be pointing to a non-existing +subdirectory. The following command should copy all output files to the +correct destinations. \begin{verbatim} -make4ht -d outputdir filename.tex +$ make4ht -d outputdir filename.tex \end{verbatim} -The image conversion is configured in the -\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{env -file}, which has really strange syntax based and the rules are -\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{os -dependent}. \texttt{make4ht} provides simpler means for the image -conversion in the build files. +\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}} + +\TeX4ht~can convert parts of the document to images. This is useful for +diagrams or complicated math, for example. -With \texttt{make4ht} build files, we have simple mean to fix these -issues. We can change image conversion parameters without the need to -modify the \texttt{env\ file}, or execute 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. +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}. -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 the build scripts are written. +It is also possible to post-process the generated output files. The +post-processing can be done either using external programs such as +\texttt{XSLT} processors and \texttt{HTML\ Tidy} or using \texttt{Lua} +functions. More information can be found in section +\ref{sec:postprocessing}. \hypertarget{output-file-formats-and-extensions}{% \section{Output file formats and extensions}\label{output-file-formats-and-extensions}} -The default output format used by \texttt{make4ht} is \texttt{html5}. -Different format can be requested using the \texttt{-\/-format} option. +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: \begin{itemize} @@ -149,50 +291,63 @@ The extensions can be enabled or disabled by appending \texttt{+EXTENSION} or \texttt{-EXTENSION} after the output format name: \begin{verbatim} - make4ht -uf html5+tidy filename.tex + $ make4ht -uf html5+tidy filename.tex \end{verbatim} Available extensions: \begin{description} -\item[latexmk\_build] -use \texttt{Latexmk} for \LaTeX~compilation. -\item[tidy] -clean the \texttt{HTML} files using the \texttt{tidy} command. -\item[dvisvgm\_hashes] -efficient generation of SVG pictures using Dvisvgm. It can utilize -multiple processor cores and generates only changed images. \item[common\_filters] clean the output HTML files using filters. \item[common\_domfilters] clean the HTML file using DOM filters. It is more powerful than \texttt{common\_filters}. Used DOM filters are \texttt{fixinlines}, -\texttt{idcolons} and \texttt{joincharacters}. +\texttt{idcolons}, \texttt{joincharacters}, and \texttt{tablerows}. +\item[dvisvgm\_hashes] +efficient generation of SVG pictures using Dvisvgm. It can utilize +multiple processor cores and generates only changed images. \item[join\_colors] load the \texttt{joincolors} domfilter for all HTML files. +\item[latexmk\_build] +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 \protect\hyperlink{mathjaxsettings}{the available settings}. \item[odttemplate] -automatically load the \texttt{odttemplate} filter. +it automatically loads the \texttt{odttemplate} filter (page +\pageref{sec:odttemplate}). +\item[preprocess\_input] +compilation of the formats supported by +\href{https://yihui.name/knitr/}{Knitr} (\texttt{.Rnw}, \texttt{.Rtex}, +\texttt{.Rmd}, \texttt{.Rrst}) and also Markdown and reStructuredText +formats. It requires \href{https://www.r-project.org/}{R} + +\href{https://yihui.name/knitr/}{Knitr} installation, it requires also +\href{https://pandoc.org/}{Pandoc} for formats based on Markdown or +reStructuredText. \item[staticsite] -build the document in form suitable for static site generators like +build the document in a form suitable for static site generators like \href{https://jekyllrb.com/}{Jekyll}. +\item[tidy] +clean the \texttt{HTML} files using the \texttt{tidy} command. \end{description} \hypertarget{build-files}{% \section{Build files}\label{build-files}} +\label{sec:buildfiles} + \texttt{make4ht} supports build files. These are \texttt{Lua} scripts -which can adjust the build process. You can request external -applications like \texttt{bibtex} or \texttt{makeindex}, pass options to +that can adjust the build process. They can request external +applications like \texttt{BibTeX} or \texttt{Makeindex}, pass options to the commands, modify the image conversion process, or post-process the generated files. \texttt{make4ht} tries to load default build file named as -\texttt{filename\ +\ .mk4\ extension}. You can choose different build -file with \texttt{-e} or \texttt{-\/-build-file} command line option. +\texttt{filename\ +\ .mk4\ extension}. It is possible to select a +different build file with \texttt{-e} or \texttt{-\/-build-file} command +line option. Sample build file: @@ -201,184 +356,228 @@ 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, the \texttt{tidy} command is -executed on the output \texttt{HTML} file. +\texttt{Make:htlatex()} is preconfigured command for calling \LaTeX~with +the \texttt{tex4ht.sty} package loaded. In this example, it will be +executed only once. After the compilation, the \texttt{tidy} command is +executed on the output \texttt{HTML} files. -Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht} +Note that it is not necessary to call \texttt{tex4ht} and \texttt{t4ht} commands explicitly in the build file, they are called automatically. \hypertarget{user-commands}{% \subsection{User commands}\label{user-commands}} -You can add more commands like \texttt{Make:htlatex} using +It is possible to add more commands like \texttt{Make:htlatex} using the \texttt{Make:add} command: \begin{verbatim} -Make:add("name", "command", {parameters}, repetition) +Make:add("name", "command", {settings table}, repetition) \end{verbatim} -The \texttt{name} and \texttt{command} parameters are required, rest of -the parameters are optional. +This defines the \texttt{name} command, which can be then executed using +\texttt{Make:name()} command in the build file. -This defines \texttt{name} command, which can be then executed as -\texttt{Make:name()} command. +The \texttt{name} and \texttt{command} parameters are required, the rest +of the parameters are optional. -\hypertarget{provided-commands}{% -\subsubsection{Provided commands}\label{provided-commands}} +The defined command receives a table with settings as a parameter at the +call time. The default settings are provided by \texttt{make4ht}. +Additional settings can be declared in the \texttt{Make:add} commands, +user can also override the default settings when the command is executed +in the build file: -\begin{description} -\item[\texttt{Make:htlatex}] -One call to TeX engine with special configuration for \texttt{tex4ht} -loading. -\item[\texttt{Make:latexmk}] -Use \texttt{Latexmk} for the document compilation. \texttt{tex4ht} will -be loaded automatically. -\item[\texttt{Make:tex4ht}] -Process the \texttt{DVI} file and creates the output files. -\item[\texttt{Make:t4ht}] -Creates the CSS file. -\end{description} +\begin{verbatim} +Make:name({hello="world"}) +\end{verbatim} + +More information about settings, including the default settings provided +by \texttt{make4ht}, can be found in section \ref{sec:settings} on page +\pageref{sec:settings}. -\hypertarget{command-function}{% -\subsubsection{Command function}\label{command-function}} +\hypertarget{the-command-function}{% +\subsubsection{\texorpdfstring{The \texttt{command} +function}{The command function}}\label{the-command-function}} -The \texttt{command} parameter can be either string template or +\label{sec:commandfunction} + +The \texttt{command} parameter can be either a string template or function: \begin{verbatim} Make:add("text", "echo hello, input file: ${input}") -Make:add("function", function(params) - for k, v in pairs(params) do - print(k..": "..v) - end, {custom="Hello world"} -) \end{verbatim} -The template can get variable value from the parameters table using a -\texttt{\$\{var\_name\}} placeholder. Templates are executed using -operating system, so they should invoke existing OS commands. Function -commands may execute system commands using \texttt{os.execute} function. - -\hypertarget{parameters-table}{% -\subsubsection{Parameters table}\label{parameters-table}} +The template can get a variable value from the parameters table using a +\texttt{\$\{var\_name\}} placeholder. Templates are executed using the +operating system, so they should invoke existing OS commands. -\texttt{parameters} parameter is optional, it can be table or -\texttt{nil} value, which should be used if you want to use the -\texttt{repetition} parameter, but don't want to modify the parameters -table. +\hypertarget{the-settings-table-table}{% +\subsubsection{\texorpdfstring{The \texttt{settings\ table} +table}{The settings table table}}\label{the-settings-table-table}} -The table with default parameters is passed to all commands, they can be -accessed from command functions or templates. When you specify your own -parameters in the command definition, these additional parameters are -added to the default parameters table for this particular command. You -can override the default parameters in the parameters table. +The \texttt{settings\ table} parameter is optional. If it is present, it +should be a table with new settings available in the command. It can +also override the default \texttt{make4ht} settings for the defined +command. -The default parameters are following: - -\begin{description} -\item[\texttt{htlatex}] -used compiler -\item[\texttt{input}] -it is output file name in fact -\item[\texttt{tex\_file}] -input TeX file -\item[\texttt{latex\_par}] -parameters to \texttt{latex} -\item[\texttt{packages}] -insert additional LaTeX code which is inserted before -\texttt{\textbackslash{}documentclass}. Useful for passing options to -packages or additional packages loading -\item[\texttt{tex4ht\_sty\_par}] -parameters to \texttt{tex4ht.sty} -\item[\texttt{tex4ht\_par}] -parameters to the \texttt{tex4ht} application -\item[\texttt{t4ht\_par}] -parameters to the \texttt{t4ht} application -\item[\texttt{outdir}] -the output directory -\item[\texttt{repetition}] -limit number of command execution. -\item[\texttt{correct\_exit}] -expected \texttt{exit\ code} from the command. The compilation will be -terminated if the command \texttt{exit\ code} is different. -\end{description} +\begin{verbatim} +Make:add("sample_function", function(params) + for k, v in pairs(params) do + print(k..": "..v) + end, {custom="Hello world"} +) +\end{verbatim} \hypertarget{repetition}{% \subsubsection{Repetition}\label{repetition}} -Repetition is number which specifies a maximal number of executions of -the particular command. This is used for instance for \texttt{tex4ht} -and \texttt{t4ht} commands, as they should be executed only once in the -compilation. They would be executed multiple times if you include them -in the build file because they are called by \texttt{make4ht} by -default. Because these commands allow only one \texttt{repetition}, the -second execution will be blocked. +The \texttt{repetition} parameter specifies the maximum number of +executions of the particular command. This is used for instance for +\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed +only once in the compilation. They would be executed multiple times when +they are included in the build file, as they are called by +\texttt{make4ht} by default. Because these commands allow only one +\texttt{repetition}, the second execution is blocked. \hypertarget{expected-exit-code}{% \subsubsection{Expected exit code}\label{expected-exit-code}} You can set the expected exit code from a command with a -\texttt{correct\_exit} key in the parameters table. The compilation will -be stopped when the command returns a different exit code. - -This mechanism isn't used 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. The \texttt{Make.testlogfile} +\texttt{correct\_exit} key in the settings table. The compilation will +be terminated when the command returns a different exit code. + +\begin{verbatim} +Make:add("biber", "biber ${input}", {correct_exit=0}) +\end{verbatim} + +Commands that execute lua functions can return the numerical values +using the \texttt{return} statement. + +This mechanism isn't used for \TeX, because it doesn't differentiate +between fatal and non-fatal errors. It returns the same exit code in all +cases. Because of this, log parsing is used for a fatal error detection +instead. Error code value \texttt{1} is returned in the case of a fatal +error, \texttt{0} is used otherwise. The \texttt{Make.testlogfile} function can be used in the build file to detect compilation errors in the TeX log file. +\hypertarget{provided-commands}{% +\subsection{Provided commands}\label{provided-commands}} + +\begin{description} +\item[\texttt{Make:htlatex}] +One call to the TeX engine with special configuration for loading of the +\texttt{tex4ht.sty} package. +\item[\texttt{Make:latexmk}] +Use \texttt{Latexmk} for the document compilation. \texttt{tex4ht.sty} +will be loaded automatically. +\item[\texttt{Make:tex4ht}] +Process the \texttt{DVI} file and create output files. +\item[\texttt{Make:t4ht}] +Create the CSS file and generate images. +\item[\texttt{Make:biber}] +Process bibliography using the \texttt{biber} command. +\item[\texttt{Make:bibtex}] +Process bibliography using the \texttt{bibtex} command. +\item[\texttt{Make:xindy}] +Generate index using Xindy index processor. +\item[\texttt{Make:makeindex}] +Generate index using the Makeindex command. +\item[\texttt{Make:xindex}] +Generate index using the Xindex command. +\end{description} + \hypertarget{file-matches}{% \subsection{File matches}\label{file-matches}} -Another type of action which can be specified in the build file is -\texttt{match}. It can be called on the generated files: +\label{sec:postprocessing} + +Another type of action that can be specified in the build file is +\texttt{Make:match}. It can be used to post-process the generated files: \begin{verbatim} Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}") \end{verbatim} -It tests output file names with \texttt{Lua} pattern matching and on -matched items will execute a command or a function, specified in the -second argument. Commands may be specified as strings, the templates -will be expanded, \texttt{\$\{var\_name\}} placeholders will be replaced -with corresponding variables from the \texttt{parameters} table, -described in the previous subsection. One additional variable is -available: \texttt{filename}. It contains the name of the current output -file. - The above example will clean all output \texttt{HTML} files using the \texttt{tidy} command. -If function is used instead, it will get two parameters. The first one -is a current filename, the second one table with parameters. +The \texttt{Make:match} action tests output filenames using a +\texttt{Lua} pattern matching function.\\ +It executes a command or a function, specified in the second argument, +on files whose filenames match the pattern. + +The commands to be executed can be specified as strings. They can +contain \texttt{\$\{var\_name\}} placeholders, which are replaced with +corresponding variables from the \texttt{settings} table. The templating +system was described in subsection \ref{sec:commandfunction}. There is +an additional variable available in this table, called +\texttt{filename}. It contains the name of the current output file. + +If a function is used instead, it will get two parameters. The first one +is the current filename, the second one is the \texttt{settings} table. + +\begin{verbatim} +Make:match("html$", function(filename, settings) + print("Post-processing file: ".. filename) + print("Available settings") + for k,v in pairs(settings) + print(k,v) + end + return true +\end{verbatim} + +end) + +Multiple post-processing actions can be executed on each filename. The +Lua action functions can return an exit code. If the exit code is false, +the execution of the post-processing chain for the current file will be +terminated. \hypertarget{filters}{% \subsubsection{Filters}\label{filters}} -Some default \texttt{match} actions which can be used are available from -the \texttt{make4ht-filter} module. It contains some functions which are -useful for fixing some \texttt{tex4ht} bugs or shortcomings. +\label{sec:filters} -Example: +To make it easier to post-process the generated files using the +\texttt{match} actions, \texttt{make4ht} provides a filtering mechanism +thanks to the \texttt{make4ht-filter} module. + +The \texttt{make4ht-filter} module returns a function that can be used +for the filter chain building. Multiple filters can be chained into a +pipeline. Each filter can modify the string that is passed to it from +the previous filters. The changes are then saved to the processed file. + +Several built-in filters are available, it is also possible to create +new ones. + +Example that use only the built-in filters: \begin{verbatim} local filter = require "make4ht-filter" local process = filter{"cleanspan", "fixligatures", "hruletohr"} Make:htlatex() +Make:match("html$",process) +\end{verbatim} + +Function \texttt{filter} accepts also function arguments, in this case +this function takes file contents as a parameter and modified contents +are returned. + +Example with custom filter: + +\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:match("html$",process) \end{verbatim} -The \texttt{make4ht-filter} module return a function which can be used -for the filter chain building. Multiple filters can be chained, each of -them can modify the string which was modified by the previous filters. -The changes are then saved to the processed file. +In this example, spurious span elements are joined, ligatures are +decomposed, and then all letters ``a'' are replaced with ``z'' letters. -Built-in filters are: +Built-in filters are the following: \begin{description} \item[cleanspan] @@ -389,16 +588,15 @@ alternative clean span filter, provided by Nat Kuhn 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 +underscore characters by \TeX4ht, this filter translates 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) +convert prohibited named entities to numeric entities (only +\texttt{\ } currently). \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. +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 @@ -407,39 +605,22 @@ to convert from MathML code to HTML + CSS or SVG. See use styles from another \texttt{ODT} file serving as a template in the current document. It works for the \texttt{styles.xml} file in the \texttt{ODT} file. During the compilation, this file is named as -\texttt{\textbackslash{}jobname.4oy}. +\texttt{\textbackslash{}jobname.4oy}. \label{sec:odttemplate} \item[staticsite] -create HTML files in format suitable for static site generators such as -\href{https://jekyllrb.com/}{Jekyll} +create HTML files in a format suitable for static site generators such +as \href{https://jekyllrb.com/}{Jekyll} \item[svg-height] some SVG images produced by \texttt{dvisvgm} seem to have wrong dimensions. This filter tries to set the correct image size. \end{description} -Function \texttt{filter} accepts also function arguments, in this case -this function takes file contents as a 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 example, spurious span elements are joined, ligatures are -decomposed, and then all letters `a' are replaced with `z' letters. - \hypertarget{dom-filters}{% \subsubsection{DOM filters}\label{dom-filters}} -DOM filters use the \href{https://ctan.org/pkg/luaxml}{\texttt{LuaXML}} -library to modify directly the XML object. This enables more powerful -operations than the regex based filters from the previous section. +DOM filters are variants of filters that use the +\href{https://ctan.org/pkg/luaxml}{\texttt{LuaXML}} library to modify +directly the XML object. This enables more powerful operations than the +regex-based filters from the previous section. Example: @@ -455,7 +636,10 @@ Available DOM filters: \item[aeneas] \href{https://www.readbeyond.it/aeneas/}{Aeneas} is a tool for automagical synchronization of text and audio. This filter modifies the -HTML code to support the synchronization. +HTML code to support synchronization. +\item[collapsetoc] +collapse table of contents to contain only top-level sectioning level +and sections on the current page. \item[fixinlines] put all inline elements which are direct children of the \texttt{\textless{}body\textgreater{}} elements to a paragraph. @@ -464,198 +648,65 @@ replace the colon (\texttt{:}) character in internal links and \texttt{id} attributes. They cause validation issues. \item[joincharacters] join consecutive \texttt{\textless{}span\textgreater{}} or -\texttt{\textless{}mn\textgreater{}} elements. +\texttt{\textless{}mn\textgreater{}} elements. This DOM filter +supersedes the \texttt{cleanspan} filter. \item[joincolors] many \texttt{\textless{}span\textgreater{}} elements with unique -\texttt{id} attribute are created when \LaTeX~colors are being used in -the document. CSS rule is added for each of these elements, which may -result in substantial grow of the CSS file. This filter replace these +\texttt{id} attributes are created when \LaTeX~colors are being used in +the document. A CSS rule is added for each of these elements, which may +result in substantial growth of the CSS file. This filter replaces these rules with a common one for elements with the same color value. \item[odtimagesize] set correct dimensions for images in the ODT format. It is loaded by default for the ODT output. +\item[odtpartable] +resolve tables nested inside paragraphs, which is invalid in the ODT +format. +\item[tablerows] +remove spurious rows from HTML tables. \item[t4htlinks] fix hyperlinks in the ODT format. \end{description} -\hypertarget{make4ht-aeneas-config-package}{% -\subsubsection{make4ht-aeneas-config -package}\label{make4ht-aeneas-config-package}} - -Companion for the \texttt{aeneas} DOM filter is the -\texttt{make4ht-aeneas-config} plugin. It can be used to write Aeneas -configuration file or execute Aeneas on the generated HTML files. - -Available functions: - -\begin{description} -\item[write\_job(parameters)] -write Aenas job configuration to \texttt{config.xml} file. See the -\href{https://www.readbeyond.it/aeneas/docs/clitutorial.html\#processing-jobs}{Aeneas -documentation} for more information about jobs. -\item[execute(parameters)] -execute Aeneas. -\item[process\_files(parameters)] -process the audio and generated subtitle files. -\end{description} - -By default, the \texttt{smil} file is created. It is assumed that there -is audio file in \texttt{mp3} format named as the TeX file. It is -possible to use different formats and file names using mapping. - -The configuration options can be passed directly to the functions or set -using \texttt{filter\_settings\ "aeneas-config"\ \{parameters\}} -function. - -Available parameters: - -\begin{description} -\item[lang] -document language. It is interfered from the HTML file, so it is not -necessary to set it. -\item[map] -mapping between HTML, audio and subtitle files. More info bellow. -\item[text\_type] -type of the input. The \texttt{aeneas} DOM filter produces -\texttt{unparsed} text type. -\item[id\_sort] -sorting of id attributes. Default value is \texttt{numeric}. -\item[id\_regex] -regular expression to parse the id attributes. -\item[sub\_format] -generated subtitle format. Default \texttt{smil}. -\end{description} - -Additional parameters for the job configuration file: - -\begin{itemize} -\tightlist -\item - description -\item - prefix -\item - config\_name -\item - keep\_config -\end{itemize} - -It is possible to generate multiple HTML files from the LaTeX source. -For example, \texttt{tex4ebook} generates separate file for each chapter -or section. It is possible to set options for each HTML file, in -particular names of the corresponding audio files. This mapping is done -using \texttt{map} parameter. - -Example: - -\begin{verbatim} -filter_settings "aeneas-config" { - map = { - ["sampleli1.html"] = {audio_file="sample.mp3"}, - ["sample.html"] = false - } -} -\end{verbatim} - -Table keys are the configured file names. It is necessary to insert them -as \texttt{{[}"filename.html"{]}}, because of Lua syntax rules. - -This example maps audio file \texttt{sample.mp3} to a section subpage. -The main HTML file, which may contain title and table of contents -doesn't have a corresponding audio file. - -Filenames of the sub files corresponds to the chapter numbers, so they -are not stable when a new chapter is added. It is possible to request -file names interfered from the chapter titles using the -\texttt{sec-filename} option or \texttt{tex4ht}. - -Available \texttt{map} options: - -\begin{description} -\item[audio\_file] -the corresponding audio file -\item[sub\_file] -name of the generated subtitle file -\end{description} - -The following options are same as their counter-parts from the main -parameters table and generally don't need to be set: - -\begin{itemize} -\tightlist -\item - prefix -\item - file\_desc -\item - file\_id -\item - text\_type -\item - id\_sort -\item - id\_prefix -\item - sub\_format -\end{itemize} - -Full example: - -\begin{verbatim} -local domfilter = require "make4ht-domfilter" -local aeneas_config = require "make4ht-aeneas-config" - -filter_settings "aeneas-config" { - map = { - ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, - ["krecek.xhtml"] = false - } -} - -local process = domfilter {"aeneas"} -Make:match("html$", process) - -if mode == "draft" then - aeneas_config.process_files {} -else - aeneas_config.execute {} -end -\end{verbatim} - \hypertarget{image-conversion}{% \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}. +\label{sec:imageconversion} -These pictures are stored in a special \texttt{dvi} file, which can be -processed by the \texttt{dvi\ to\ image} commands. +It is possible to convert parts of the \LaTeX~input as pictures. It can +be used for preserving the appearance of math or diagrams, for example. -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 the \texttt{t4ht} application and -conversion commands are called for all pictures. +These pictures are stored in a special \texttt{DVI} file, which can be +processed by a \texttt{DVI} to image commands, such as \texttt{dvipng} +or \texttt{dvisvgm}. + +This conversion is normally configured in the \texttt{tex4ht.env} file. +This file is system dependent and it has quite an unintuitive syntax. +The configuration is processed by the \texttt{t4ht} application and the +conversion command is called for all pictures. It is possible to disable \texttt{t4ht} image processing and configure -image conversion in the build file: +image conversion in the build file using the \texttt{image} action: \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 a table with parameters as an argument. +\texttt{Make:image} takes two parameters, a \texttt{Lua} pattern to +match the image name, and the action. + +Action can be either a string template with the conversion command or a +function that takes a table with parameters as an argument. There are three parameters: \begin{itemize} \tightlist \item - \texttt{output} - output image file name + \texttt{output} - output image filename \item - \texttt{source} - \texttt{dvi} file with the pictures + \texttt{source} - \texttt{DVI} file with the pictures \item \texttt{page} - page number of the converted image \end{itemize} @@ -664,9 +715,9 @@ There are three parameters: \subsection{\texorpdfstring{The \texttt{mode} variable}{The mode variable}}\label{the-mode-variable}} -There is global \texttt{mode} variable available in the build file. It -contains contents of the \texttt{-\/-mode} command line option. It can -be used to run some commands conditionally. For example: +The \texttt{mode} variable available in the build process contains +contents of the \texttt{-\/-mode} command line option. It can be used to +run some commands conditionally. For example: \begin{verbatim} if mode == "draft" then @@ -679,8 +730,8 @@ be used to run some commands conditionally. For example: \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: +\texttt{make4ht}), \LaTeX~is called only once when \texttt{make4ht} is +called with the \texttt{draft} mode: \begin{verbatim} make4ht -m draft filename @@ -690,10 +741,12 @@ make4ht -m draft filename \subsection{\texorpdfstring{The \texttt{settings} table}{The 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\ (ODT)}, you can -use the following settings, based on the \texttt{oolatex} command: +\label{sec:settings} + +It is possible to access the parameters outside commands, file matches +and image conversion functions. For example, to convert the document to +the \texttt{OpenDocument\ Format\ (ODT)}, the following settings can be +used. They are based on the \texttt{oolatex} command: \begin{verbatim} settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice" @@ -701,7 +754,11 @@ settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf" settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo " \end{verbatim} -There are some functions to ease access to the settings: +(Note that it is possible to use the \texttt{-\/-format\ odt} option +which is superior to the previous code. This example is intended just as +an illustration) + +There are some functions to simplify access to the settings: \begin{description} \item[\texttt{set\_settings\{parameters\}}] @@ -714,8 +771,8 @@ set settings for a filter get settings for a filter \end{description} -Using these functions, it is possible to simplify the settings for the -\texttt{ODT} format: +For example, it is possible to simplify the sample from the previous +code listings: \begin{verbatim} settings_add { @@ -734,8 +791,8 @@ filter_settings "test" { } \end{verbatim} -These settings can be read in the extensions and filters using -\texttt{get\_filter\_settings}: +These settings can be retrieved in the extensions and filters using the +\texttt{get\_filter\_settings} function: \begin{verbatim} function test(input) @@ -746,14 +803,153 @@ end \end{verbatim} +\hypertarget{default-settings}{% +\subsubsection{Default settings}\label{default-settings}} + +The default parameters are the following: + +\begin{description} +\item[\texttt{htlatex}] +used \TeX~engine +\item[\texttt{input}] +content of \texttt{\textbackslash{}jobname}, see also the +\texttt{tex\_file} parameter. +\item[\texttt{interaction}] +interaction mode for the \TeX~engine. The default value is +\texttt{batchmode} to suppress user input on compilation errors. It also +suppresses most of the \TeX~ compilation log output. Use the +\texttt{errorstopmode} for the default behavior. +\item[\texttt{tex\_file}] +input \TeX~filename +\item[\texttt{latex\_par}] +command line parameters to the \TeX~engine +\item[\texttt{packages}] +additional \LaTeX~code inserted before +\texttt{\textbackslash{}documentclass}. Useful for passing options to +packages used in the document or to load additional packages. +\item[\texttt{tex4ht\_sty\_par}] +options for \texttt{tex4ht.sty} +\item[\texttt{tex4ht\_par}] +command line options for the \texttt{tex4ht} command +\item[\texttt{t4ht\_par}] +command line options for the \texttt{t4ht} command +\item[\texttt{outdir}] +the output directory +\item[\texttt{correct\_exit}] +expected \texttt{exit\ code} from the command. The compilation will be +terminated if the exit code of the executed command has a different +value. +\end{description} + +\hypertarget{configfile}{% +\section{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 +global settings can be set. + +Common tasks for the configuration file can be a declaration of the new +commands, loading of the default filters or specification of a default +build sequence. + +One additional functionality not available in the build files are +commands for enabling and disabling of extensions. + +\hypertarget{location}{% +\subsection{Location}\label{location}} + +The configuration file can be saved either in the +\texttt{\$HOME/.config/make4ht/config.lua} file, or in the +\texttt{.make4ht} file placed in the current directory or it's parent +directories (up to the \texttt{\$HOME} directory). + +\hypertarget{additional-commands}{% +\subsection{Additional commands}\label{additional-commands}} + +There are two additional commands: + +\begin{description} +\item[\texttt{Make:enable\_extension(name)}] +require extension +\item[\texttt{Make:disable\_extension(name)}] +disable extension +\end{description} + +\hypertarget{example}{% +\subsection{Example}\label{example}} + +The following example of the configuration file adds support for the +\texttt{biber} command, requires \texttt{common\_domfilters} extension +and requires MathML output for math. + +\begin{verbatim} +Make:add("biber", "biber ${input}") +Make:enable_extension "common_domfilters" +settings_add { + tex4ht_sty_par =",mathml" +} +\end{verbatim} + \hypertarget{list-of-available-settings-for-filters-and-extensions.}{% -\subsection{List of available settings for filters and +\section{List of available settings for filters and extensions.}\label{list-of-available-settings-for-filters-and-extensions.}} -These settings may be set using \texttt{filter\_settings} function. +These settings may be set using \texttt{filter\_settings} function in a +build file or in the \texttt{make4ht} configuration file. + +\hypertarget{indexing-commands}{% +\subsection{Indexing commands}\label{indexing-commands}} + +The indexing commands (like \texttt{xindy} or \texttt{makeindex}) use +some common settings. + +\begin{description} +\item[idxfile] +name of the \texttt{.idx} file. Default value is +\texttt{\textbackslash{}jobname.idx}. +\item[indfile] +name of the \texttt{.ind} file. Default value is the same as +\texttt{idxfile} with the file extension changed to \texttt{.ind}. +\end{description} + +Each indexing command can have some additional settings. + +\hypertarget{the-xindy-command}{% +\subsubsection{\texorpdfstring{The \texttt{xindy} +command}{The xindy command}}\label{the-xindy-command}} + +\begin{description} +\item[encoding] +text encoding of the \texttt{.idx} file. Default value is \texttt{utf8}. +\item[language] +index language. Default language is English. +\item[modules] +table with names of additional \texttt{Xindy} modules to be used. +\end{description} + +\hypertarget{the-makeindex-command}{% +\subsubsection{\texorpdfstring{The \texttt{makeindex} +command}{The makeindex command}}\label{the-makeindex-command}} + +options + +: additional command line options for the Makeindex command. + +\hypertarget{the-xindex-command}{% +\subsubsection{\texorpdfstring{The \texttt{xindex} +command}{The xindex command}}\label{the-xindex-command}} + +options + +: additional command line options for the Xindex command. + +\begin{description} +\item[language] +document language +\end{description} \hypertarget{the-tidy-extension}{% -\subsubsection{\texorpdfstring{The \texttt{tidy} +\subsection{\texorpdfstring{The \texttt{tidy} extension}{The tidy extension}}\label{the-tidy-extension}} \begin{description} @@ -762,13 +958,37 @@ command line options for the \texttt{tidy} command. Default value is \texttt{-m\ -utf8\ -w\ 512\ -q}. \end{description} +\hypertarget{the-collapsetoc-dom-filter}{% +\subsection{\texorpdfstring{The \texttt{collapsetoc} dom +filter}{The collapsetoc dom filter}}\label{the-collapsetoc-dom-filter}} + +\begin{description} +\item[\texttt{toc\_query}] +CSS selector for selecting the table of contents container. +\item[\texttt{title\_query}] +CSS selector for selecting all elements that contain the section ID +attribute. +\item[\texttt{toc\_levels}] +table containing a hierarchy of classes used in TOC +\end{description} + +Default values: + +\begin{verbatim} +filter_settings "collapsetoc" { + toc_query = ".tableofcontents", + title_query = ".partHead a, .chapterHead a, .sectionHead a, .subsectionHead a", + toc_levels = {"partToc", "chapterToc", "sectionToc", "subsectionToc", "subsubsectionToc"} +} +\end{verbatim} + \hypertarget{the-fixinlines-dom-filter}{% -\subsubsection{\texorpdfstring{The \texttt{fixinlines} dom +\subsection{\texorpdfstring{The \texttt{fixinlines} dom filter}{The fixinlines dom filter}}\label{the-fixinlines-dom-filter}} \begin{description} \item[inline\_elements] -table of inline elements which shouldn't be direct descendants of the +table of inline elements that shouldn't be direct descendants of the \texttt{body} element. The element names should be table keys, the values should be true. \end{description} @@ -780,23 +1000,24 @@ filter_settings "fixinlines" {inline_elements = {a = true, b = true}} \end{verbatim} \hypertarget{the-joincharacters-dom-filter}{% -\subsubsection{\texorpdfstring{The \texttt{joincharacters} dom +\subsection{\texorpdfstring{The \texttt{joincharacters} dom filter}{The joincharacters dom filter}}\label{the-joincharacters-dom-filter}} \begin{description} -\item[charelements] -table of elements which should be joined if several instances with the -same value of \texttt{class} attribute are side by side. +\item[charclasses] +table of elements that should be concatenated when two or more of such +elements with the same value of the \texttt{class} attribute are placed +one after another. \end{description} Example \begin{verbatim} -filter_settings "joincharacters" { charclases = { span=true, mn = true}} +filter_settings "joincharacters" { charclasses = { span=true, mn = true}} \end{verbatim} \hypertarget{mathjaxsettings}{% -\subsubsection{\texorpdfstring{The \texttt{mathjaxnode} +\subsection{\texorpdfstring{The \texttt{mathjaxnode} filter}{The mathjaxnode filter}}\label{mathjaxsettings}} \begin{description} @@ -815,12 +1036,12 @@ filter_settings "mathjaxnode" { \begin{description} \item[cssfilename] -\texttt{mjpage} puts some CSS code into the HTML pages. +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} \item[fontdir] -directory with MathJax font files. This option enables use of local -fonts, which is usefull in Epub conversion, for example. The font +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. \end{description} @@ -833,37 +1054,22 @@ filter_settings "mathjaxnode" { } \end{verbatim} -\hypertarget{the-aeneas-filter}{% -\subsubsection{\texorpdfstring{The \texttt{aeneas} -filter}{The aeneas filter}}\label{the-aeneas-filter}} - -\begin{description} -\item[skip\_elements] -List of CSS selectors that match elements which shouldn't be processed. -Default value: \texttt{\{\ "math",\ "svg"\}}. -\item[id\_prefix] -prefix used in the ID attribute forming. -\item[sentence\_match] -Lua pattern used to match a sentence. Default value: -\texttt{"({[}\^{}\%.\^{}\%?\^{}!{]}*)({[}\%.\%?!{]}?)"}. -\end{description} - \hypertarget{the-staticsite-filter-and-extension}{% -\subsubsection{\texorpdfstring{The \texttt{staticsite} filter and +\subsection{\texorpdfstring{The \texttt{staticsite} filter and extension}{The staticsite filter and extension}}\label{the-staticsite-filter-and-extension}} \begin{description} \item[site\_root] directory where generated files should be copied. \item[map] -table where keys are patterns that match filenames, value contains -destination directoryfor matched files, relative to the -\texttt{site\_root} (it is possible to use \texttt{..} to swich to -parent directory). +a hash table where keys contain patterns that match filenames and values +contain destination directory for the matched files. The destination +directories are relative to the \texttt{site\_root} (it is possible to +use \texttt{..} to switch to a parent directory). \item[file\_pattern] -pattern used for filename generation. It is possible to use string -templates and format strings for \texttt{os.date} function. Default -value of \texttt{\%Y-\%m-\%d-\$\{input\}} creates names in the form of +a pattern used for filename generation. It is possible to use string +templates and format strings for \texttt{os.date} function. The default +pattern \texttt{\%Y-\%m-\%d-\$\{input\}} creates names in the form of \texttt{YYYY-MM-DD-file\_name}. \item[header] table with variables to be set in the YAML header in HTML files. If the @@ -891,7 +1097,7 @@ filter_settings "staticsite" { \end{verbatim} \hypertarget{the-dvisvgm_hashes-extension}{% -\subsubsection{\texorpdfstring{The \texttt{dvisvgm\_hashes} +\subsection{\texorpdfstring{The \texttt{dvisvgm\_hashes} extension}{The dvisvgm\_hashes extension}}\label{the-dvisvgm_hashes-extension}} \begin{description} @@ -899,18 +1105,18 @@ extension}{The dvisvgm\_hashes extension}}\label{the-dvisvgm_hashes-extension}} command line options for Dvisvgm. The default value is \texttt{-n\ -\/-exact\ -c\ 1.15,1.15}. \item[cpu\_cnt] -number of processor cores used for conversion. The extension tries to -detect the available cores automatically by default. +the number of processor cores used for the conversion. The extension +tries to detect the available cores automatically by default. \item[parallel\_size] -number of pages used in each Dvisvgm call. The extension detects changed -pages in the DVI file and construct multiple calls to Dvisvgm with only -changed pages. +the number of pages used in each Dvisvgm call. The extension detects +changed pages in the DVI file and constructs multiple calls to Dvisvgm +with only changed pages. \item[scale] SVG scaling. \end{description} \hypertarget{the-odttemplate-filter-and-extension}{% -\subsubsection{\texorpdfstring{The \texttt{odttemplate} filter and +\subsection{\texorpdfstring{The \texttt{odttemplate} filter and extension}{The odttemplate filter and extension}}\label{the-odttemplate-filter-and-extension}} \begin{description} @@ -920,108 +1126,175 @@ filename of the template \texttt{ODT} file \texttt{odttemplate} can also get the template filename from the \texttt{odttemplate} option from \texttt{tex4ht\_sty\_par} parameter. It -can be set useing following command line call, for example: +can be set using the following command line call: \begin{verbatim} make4ht -f odt+odttemplate filename.tex "odttemplate=template.odt" \end{verbatim} -\hypertarget{configfile}{% -\section{Configuration file}\label{configfile}} +\hypertarget{the-aeneas-filter}{% +\subsection{\texorpdfstring{The \texttt{aeneas} +filter}{The aeneas filter}}\label{the-aeneas-filter}} -It is possible to globally modify the build settings using the -configuration file. New compilation commands can be added, extensions -can be loaded or disabled and settings can be set. +\begin{description} +\item[skip\_elements] +List of CSS selectors that match elements that shouldn't be processed. +Default value: \texttt{\{\ "math",\ "svg"\}}. +\item[id\_prefix] +prefix used in the ID attribute forming. +\item[sentence\_match] +Lua pattern used to match a sentence. Default value: +\texttt{"({[}\^{}\%.\^{}\%?\^{}!{]}*)({[}\%.\%?!{]}?)"}. +\end{description} -\hypertarget{location}{% -\subsection{Location}\label{location}} +\hypertarget{the-make4ht-aeneas-config-package}{% +\subsection{\texorpdfstring{The \texttt{make4ht-aeneas-config} +package}{The make4ht-aeneas-config package}}\label{the-make4ht-aeneas-config-package}} -The configuration file can be saved either in -\texttt{\$HOME/.config/make4ht/config.lua} or in \texttt{.make4ht} in -the current directory or it's parents (up to \texttt{\$HOME}). +Companion for the \texttt{aeneas} DOM filter is the +\texttt{make4ht-aeneas-config} plugin. It can be used to write the +Aeneas configuration file or execute Aeneas on the generated HTML files. -\hypertarget{additional-commands}{% -\subsection{Additional commands}\label{additional-commands}} +Available functions: -There are two additional commands: +\begin{description} +\item[write\_job(parameters)] +write Aenas job configuration to \texttt{config.xml} file. See the +\href{https://www.readbeyond.it/aeneas/docs/clitutorial.html\#processing-jobs}{Aeneas +documentation} for more information about jobs. +\item[execute(parameters)] +execute Aeneas. +\item[process\_files(parameters)] +process the audio and generated subtitle files. +\end{description} + +By default, a \texttt{SMIL} file is created. It is assumed that there is +an audio file in the \texttt{mp3} format, named as the \TeX~file. It is +possible to use different formats and filenames using mapping. + +The configuration options can be passed directly to the functions or set +using \texttt{filter\_settings\ "aeneas-config"\ \{parameters\}} +function. + +\hypertarget{available-parameters}{% +\subsubsection{Available parameters}\label{available-parameters}} \begin{description} -\item[\texttt{Make:enable\_extension(name)}] -require extension -\item[\texttt{Make:disable\_extension(name)}] -disable extension +\item[lang] +document language. It is interfered from the HTML file, so it is not +necessary to set it. +\item[map] +mapping between HTML, audio and subtitle files. More info below. +\item[text\_type] +type of input. The \texttt{aeneas} DOM filter produces an +\texttt{unparsed} text type. +\item[id\_sort] +sorting of id attributes. The default value is \texttt{numeric}. +\item[id\_regex] +regular expression to parse the id attributes. +\item[sub\_format] +generated subtitle format. The default value is \texttt{smil}. \end{description} -\hypertarget{example}{% -\subsection{Example}\label{example}} +\hypertarget{additional-parameters-for-the-job-configuration-file}{% +\subsubsection{Additional parameters for the job configuration +file}\label{additional-parameters-for-the-job-configuration-file}} + +\begin{itemize} +\tightlist +\item + description +\item + prefix +\item + config\_name +\item + keep\_config +\end{itemize} -The following configuration add support for the \texttt{biber} command, -requires \texttt{common\_domfilters} extension and requires MathML -output for math. +It is possible to generate multiple HTML files from the \LaTeX~source. +For example, \texttt{tex4ebook} generates a separate file for each +chapter or section. It is possible to set options for each HTML file, in +particular names of the corresponding audio files. This mapping is done +using the \texttt{map} parameter. + +Example: \begin{verbatim} -Make:add("biber", "biber ${input}") -Make:enable_extension "common_domfilters" -settings_add { - tex4ht_sty_par =",mathml" +filter_settings "aeneas-config" { + map = { + ["sampleli1.html"] = {audio_file="sample.mp3"}, + ["sample.html"] = false + } } \end{verbatim} -\hypertarget{command-line-options}{% -\section{Command line options}\label{command-line-options}} +Table keys are the configured filenames. It is necessary to insert them +as \texttt{{[}"filename.html"{]}}, because of Lua syntax rules. -\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 --f,--format (default nil) Output file format --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} +This example maps audio file \texttt{sample.mp3} to a section subpage. +The main HTML file, which may contain title and table of contents +doesn't have a corresponding audio file. -You can still invoke \texttt{make4ht} in the same way as -\texttt{htlatex}: +Filenames of the subfiles correspond to the chapter numbers, so they are +not stable when a new chapter is added. It is possible to request +filenames derived from the chapter titles using the +\texttt{sec-filename} option for \texttt{tex4ht.sty}. -\begin{verbatim} -make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo" -\end{verbatim} +\hypertarget{available-map-options}{% +\subsubsection{\texorpdfstring{Available \texttt{map} +options}{Available map options}}\label{available-map-options}} -Note that this will not use \texttt{make4ht} routines for output -directory making and copying. If you want to use them, change the line -above to: +\begin{description} +\item[audio\_file] +the corresponding audio file +\item[sub\_file] +name of the generated subtitle file +\end{description} -\begin{verbatim} -make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8" -\end{verbatim} +The following options are the same as their counterparts from the main +parameters table and generally, don't need to be set: -This call has the same effect as the following: +\begin{itemize} +\tightlist +\item + prefix +\item + file\_desc +\item + file\_id +\item + text\_type +\item + id\_sort +\item + id\_prefix +\item + sub\_format +\end{itemize} + +\hypertarget{full-example}{% +\subsubsection{Full example}\label{full-example}} \begin{verbatim} -make4ht -u -c customcfg -d foo filename -\end{verbatim} +local domfilter = require "make4ht-domfilter" +local aeneas_config = require "make4ht-aeneas-config" -Output directory doesn't have to exist, it will be created -automatically. Specified path can be relative to current directory, or -absolute: +filter_settings "aeneas-config" { + map = { + ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, + ["krecek.xhtml"] = false + } +} -\begin{verbatim} -make4ht -d use/current/dir/ filename -make4ht -d ../gotoparrentdir filename -make4ht -d ~/gotohomedir filename -make4ht -d c:\documents\windowspathsareworkingtoo filename +local process = domfilter {"aeneas"} +Make:match("html$", process) + +if mode == "draft" then + aeneas_config.process_files {} +else + aeneas_config.execute {} +end \end{verbatim} \hypertarget{troubleshooting}{% @@ -1041,23 +1314,23 @@ make4ht:unrecognized parameter: i It may be caused by a following \texttt{make4ht} invocation: \begin{verbatim} -make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo +$ make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo \end{verbatim} The command line option parser is confused by mixing options for -\texttt{make4ht} and \texttt{tex4ht} in this case and tries to interpret -the \texttt{-cunihtf\ -utf8}, which are options for \texttt{tex4ht} -command as \texttt{make4ht} options. To fix that, you can either move -the \texttt{-d\ foo} directly after \texttt{make4ht} command: +\texttt{make4ht} and \TeX4ht~in this case. It tries to interpret the +\texttt{-cunihtf\ -utf8}, which are options for the \texttt{tex4ht} +command, as \texttt{make4ht} options. To fix that, try to move the +\texttt{-d\ foo} directly after the \texttt{make4ht} command: \begin{verbatim} -make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" +$ make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" \end{verbatim} -Another option is to add a space before \texttt{tex4ht} options: +Another option is to add a space before the \texttt{tex4ht} options: \begin{verbatim} -make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo +$ make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo \end{verbatim} The former way is preferable, though. @@ -1066,10 +1339,10 @@ The former way is preferable, though. \subsection{Filenames containing spaces}\label{filenames-containing-spaces}} -\texttt{tex4ht} cannot handle filenames containing spaces. -\texttt{make4ht} thus replaces spaces in input file names with -underscores, so generated XML files use underscores instead of spaces as -well. +\texttt{tex4ht} command cannot handle filenames containing spaces. to +fix this issue, \texttt{make4ht} replaces spaces in the input filenames +with underscores. The generated XML filenames use underscores instead of +spaces as well. \hypertarget{filenames-containing-non-ascii-characters}{% \subsection{Filenames containing non-ASCII |