diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-09 21:09:51 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-09 21:09:51 +0000 |
commit | 4d2d4764dde3caf40817a1ef84719e1319b10d2f (patch) | |
tree | 096967b6679e1e110b75e42e1747936323508fc4 /Master/texmf-dist/doc/support/make4ht/readme.tex | |
parent | 1e0147a88c7bc3a3e2986968f697ef5fbcef2bcb (diff) |
make4ht (9apr18)
git-svn-id: svn://tug.org/texlive/trunk@47398 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/make4ht/readme.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/make4ht/readme.tex | 888 |
1 files changed, 746 insertions, 142 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex index 77e1ecdc6b1..df67a151b87 100644 --- a/Master/texmf-dist/doc/support/make4ht/readme.tex +++ b/Master/texmf-dist/doc/support/make4ht/readme.tex @@ -1,68 +1,186 @@ -\section{Introduction}\label{introduction} +\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. The \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 simple build system for tex4ht. It is both -executable which simplifies \texttt{tex4ht} execution and a library -which can be used to create customized conversion programs. An example -of such conversion program is -\href{https://github.com/michal-h21/tex4ebook}{tex4ebook} +\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} -\subsection{License}\label{license} +The options for various parts of the system can be passed on the command +line: -Permission is granted to copy, distribute and/or modify this software -under the terms of the LaTeX Project Public License, version 1.3. +\begin{verbatim} +htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options" +\end{verbatim} -\subsection{How it works}\label{how-it-works} +For basic \texttt{HTML} conversion it is possible to use the most basic +invocation: -Default compilation script for \texttt{tex4ht}, named \texttt{htlatex} -compiles LaTeX files to \texttt{HTML} with this command sequence: +\begin{verbatim} +htlatex filename.tex +\end{verbatim} + +It can be much more involved for \texttt{HTML\ 5} output in +\texttt{UTF-8} encoding: \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 options filename -t4ht options filename -\end{verbatim} - -The problem is that this is inefficient when you need to run program -which interact with LaTeX, such as \texttt{Makeindex} or -\texttt{Bibtex}. In that case, you need to create new script based on -the default one, or run \texttt{htlatex} twice, which means six LaTeX -runs. - -Another problem is with \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 some -subdirectory, they will be copied to the output directory, but links -will be pointing to non existing subdirectory. - -Image conversion is directed with the +htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8" +\end{verbatim} + +\texttt{make4ht} can simplify it: + +\begin{verbatim} +make4ht -uf html5 filename.tex +\end{verbatim} + +Another issue is the fixed compilation order and 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 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: + +\begin{verbatim} +make4ht -um draft -f html5 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. + +\begin{verbatim} +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}, with really strange syntax based on whitespace and +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}. With \texttt{make4ht} build files, we have simple mean to -fix these issues. We can change image conversion parameters without need -to modify the \texttt{env file}, and call actions on the output files. +dependent}. \texttt{make4ht} provides simpler means for the image +conversion in the build files. + +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. +processors or \texttt{HTML\ tidy} or \texttt{Lua} functions. 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 build script are written. +in which the build scripts are written. + +\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. +Supported formats are: + +\begin{itemize} +\tightlist +\item + \texttt{xhtml} +\item + \texttt{html5} +\item + \texttt{odt} +\end{itemize} + +The \texttt{-\/-format} option can be also used for extension loading. + +\hypertarget{extensions}{% +\subsection{Extensions}\label{extensions}} -\section{Build files}\label{build-files} +Extensions can be used to modify the build process without the need to +use a build file. They may post-process the output files or request +additional commands for the compilation. -\subsection{Commands}\label{commands} +The extensions can be enabled or disabled by appending +\texttt{+EXTENSION} or \texttt{-EXTENSION} after the output format name: -By default, build file is saved in file named -\texttt{filename + .mk4 extension}. You can choose different build file -with \texttt{-e} or \texttt{-{}-build-file} command line option. +\begin{verbatim} + make4ht -uf html5+tidy filename.tex +\end{verbatim} + +Available extensions: + +\begin{description} +\item[latexmk] +use \texttt{Latexmk} for \LaTeX~compilation. +\item[tidy] +clean the \texttt{HTML} files using the \texttt{tidy} command. +\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}. +\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}. +\end{description} + +\hypertarget{build-files}{% +\section{Build files}\label{build-files}} -Sample: +\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 +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. + +Sample build file: \begin{verbatim} Make:htlatex() @@ -70,107 +188,166 @@ 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, \texttt{tidy} command is executed on the -output \texttt{html} file. +\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. Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht} commands explicitly in the build file, they are called automatically. -You can add more commands like \texttt{Make:htlatex} with +\hypertarget{user-commands}{% +\subsection{User commands}\label{user-commands}} + +You can add more commands like \texttt{Make:htlatex} using +\texttt{Make:add} command: \begin{verbatim} Make:add("name", "command", {parameters}, repetition) \end{verbatim} -it can be called with +The \texttt{name} and \texttt{command} parameters are required, rest of +the parameters are optional. -\begin{verbatim} -Make:name() -\end{verbatim} +This defines \texttt{name} command, which can be then executed as +\texttt{Make:name()} command. -\texttt{command} can be text template, or function: +\hypertarget{provided-commands}{% +\subsubsection{Provided commands}\label{provided-commands}} + +\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} + +\hypertarget{command-function}{% +\subsubsection{Command function}\label{command-function}} + +The \texttt{command} parameter can be either string template or +function: \begin{verbatim} -Make:add("text", "hello, input file: ${input}") +Make:add("text", "echo hello, input file: ${input}") Make:add("function", function(params) for k, v in pairs(params) do print(k..": "..v) - end + end, {custom="Hello world"} ) \end{verbatim} -\texttt{parameters} is a table or \texttt{nil} value. +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}} -Default parameters are: +\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. + +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 default parameters are following: \begin{description} -\item[htlatex] +\item[\texttt{htlatex}] used compiler -\item[input] +\item[\texttt{input}] it is output file name in fact -\item[tex\_file] +\item[\texttt{tex\_file}] input TeX file -\item[latex\_par] +\item[\texttt{latex\_par}] parameters to \texttt{latex} -\item[packages] -insert additionl LaTeX code which is inserted before +\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[tex4ht\_sty\_par] +\item[\texttt{tex4ht\_sty\_par}] parameters to \texttt{tex4ht.sty} -\item[tex4ht\_par] -parameters to \texttt{tex4ht} application -\item[t4ht\_par] -parameters to \texttt{t4ht} application -\item[outdir] -output directory -\item[repetition] +\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[correct\_exit] -expected \texttt{exit code} from the command. The compilation will be -terminted when the command \texttt{exit code} is different. +\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} -You may add your own parameters, they will be accessible in templates -and functions. +\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. -With \texttt{repetition}, you can limit number of command executions. -Its value should be number or \texttt{nil}. This is used in the case of -\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed -only once and they would be executed multiple times if you include them -in the build file, because they would be called also by -\texttt{make4ht}. With \texttt{repetition}, second execution is blocked. +\hypertarget{expected-exit-code}{% +\subsubsection{Expected exit code}\label{expected-exit-code}} -You can set expected exit code from a command with -\texttt{correct\_exit}. Compilation is stopped when command returns -different exit code. The situation is different for LaTeX (for all TeX -engines and formats, in fact), because it doesn't differentiate between -fatal and non fatal errors, and it returns the same exit code in all -cases. Log parsing is used because of that, error code \texttt{1} is -returned in the case of fatal error, \texttt{0} is used otherwise. +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. -\subsection{File matches}\label{file-matches} +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} +function can be used in the build file to detect compilation errors in +the TeX log file. -Other type of action which can be specified in the build file are -matches which may be called on the generated files: +\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: \begin{verbatim} Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}") \end{verbatim} -It tests filenames with \texttt{Lua} pattern matching and on matched -items will execute command or function, specified in the second -argument. For functions, two arguments are passed, first one is the -current filename, the second one table with parameters. These parameters -are the same as in previous section, except for \texttt{filename}, which -contains generated output name. +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. -\subsubsection{Filters}\label{filters} +If function is used instead, it will get two parameters. The first one +is a current filename, the second one table with parameters. -Some default match actions which you can use are in the \texttt{filter} -module. It contains some functions which ares useful for fixing some -\texttt{tex4ht} bugs or shortcomings. +\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. Example: @@ -182,8 +359,10 @@ Make:htlatex() Make:match("html$",process) \end{verbatim} -Filter module is located in \texttt{make4ht-filter}. Function is -returned, which is used for building filter chains then. +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. Built-in filters are: @@ -201,73 +380,260 @@ 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 +producing it sometimes) \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. +\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[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 parameter and modified contents are -returned. +this function takes file contents as a parameter and modified contents +are returned. Example: \begin{verbatim} -local filter = require "make4ht-filter" +local filter = require "make4ht-filter" local changea = function(s) return s:gsub("a","z") end -local process = filter{"cleanspan", "fixligatures", changea} -Make:htlatex() +local process = filter{"cleanspan", "fixligatures", changea} +Make:htlatex() Make:htlatex() -Make:match("html$",process) +Make:match("html$",process) \end{verbatim} -In this case, spurious span elements are joined, ligatures are +In this example, spurious span elements are joined, ligatures are decomposed, and then all letters `a' are replaced with `z' letters. -\subsection{Image conversion}\label{image-conversion} +\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. + +Example: + +\begin{verbatim} +local domfilter = require "make4ht-domfilter" +local process = domfilter {"joincharacters"} +Make:match("html$", process) +\end{verbatim} + +Available DOM filters: + +\begin{description} +\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. +\item[fixinlines] +put all inline elements which are direct children of the +\texttt{\textless{}body\textgreater{}} elements to a paragraph. +\item[idcolons] +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. +\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 an corresponding audio file. + +The filenames of sub files corresponds to 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}. -These pictures are stored in special \texttt{dvi} file, on which -\texttt{dvi to image} commands are called. +These pictures are stored in a special \texttt{dvi} file, which can be +processed by the \texttt{dvi\ to\ image} commands. -This conversion is normally configured in the \texttt{env file}, which +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 \texttt{t4ht} application and conversion -commands are called for all pictures. +configuration is processed by the \texttt{t4ht} application and +conversion commands are called for all pictures. It is possible to disable \texttt{t4ht} image processing and configure -image conversion in the make file: +image conversion in the build file: \begin{verbatim} Make:image("png$", -"dvipng -bg Transparent -T tight -o ${output} -pp ${page} ${source}") +"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 table with parameters as argument. +command, or function which takes a table with parameters as an argument. There are three parameters: \begin{itemize} -\itemsep1pt\parskip0pt\parsep0pt +\tightlist \item - output - output image file name + \texttt{output} - output image file name \item - source - \texttt{dvi} file with the pictures + \texttt{source} - \texttt{dvi} file with the pictures \item - page - page number of the converted image + \texttt{page} - page number of the converted image \end{itemize} -\subsection{The \texttt{mode} variable}\label{the-mode-variable} +\hypertarget{the-mode-variable}{% +\subsection{\texorpdfstring{The \texttt{mode} +variable}{The mode variable}}\label{the-mode-variable}} -The \texttt{mode} variable contains contents of \texttt{-{}-mode} -command line option. It can be used to run some commands conditionally. -For example: +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: \begin{verbatim} if mode == "draft" then @@ -287,12 +653,14 @@ called with \texttt{draft} mode: make4ht -m draft filename \end{verbatim} -\subsection{The \texttt{settings} table}\label{the-settings-table} +\hypertarget{the-settings-table}{% +\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}, you can use the -following settings, based on \texttt{oolatex} command: +convert your file to the \texttt{OpenDocument\ Format\ (ODT)}, you can +use the following settings, based on the \texttt{oolatex} command: \begin{verbatim} settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice" @@ -300,7 +668,196 @@ settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf" settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo " \end{verbatim} -\section{Command line options}\label{command-line-options} +There are some functions to ease access to the settings: + +\begin{description} +\item[\texttt{set\_settings\{parameters\}}] +overwrite settings with values from a passed table +\item[\texttt{settings\_add\{parameters\}}] +add values to the current settings +\item[\texttt{filter\_settings\ "filter\ name"\ \{parameters\}}] +set settings for a filter +\item[\texttt{get\_filter\_settings(name)}] +get settings for a filter +\end{description} + +Using these functions, it is possible to simplify the settings for the +\texttt{ODT} format: + +\begin{verbatim} +settings_add { + tex4ht_sty_par =",ooffice", + tex4ht_par = " ooffice/! -cmozhtf", + t4ht_par = " -cooxtpipes -coo " +} +\end{verbatim} + +Settings for filters and extensions can be set using +\texttt{filter\_settings}: + +\begin{verbatim} +filter_settings "test" { + hello = "world" +} +\end{verbatim} + +These settings can be read in the extensions and filters using +\texttt{get\_filter\_settings}: + +\begin{verbatim} +function test(input) + local options = get_filter_settings("test") + print(options.hello) + return input +end + +\end{verbatim} + +\hypertarget{list-of-available-settings-for-filters-and-extensions.}{% +\subsection{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. + +\hypertarget{the-tidy-extension}{% +\subsubsection{\texorpdfstring{The \texttt{tidy} +extension}{The tidy extension}}\label{the-tidy-extension}} + +\begin{description} +\item[options] +command line options for the \texttt{tidy} command. Default value is +\texttt{-m\ -utf8\ -w\ 512\ -q}. +\end{description} + +\hypertarget{the-fixinlines-dom-filter}{% +\subsubsection{\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 +\texttt{body} element. The element names should be table keys, the +values should be true. +\end{description} + +Example + +\begin{verbatim} +filter_settings "fixinlines" {inline_elements = {a = true, b = true}} +\end{verbatim} + +\hypertarget{the-joincharacters-dom-filter}{% +\subsubsection{\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. +\end{description} + +Example + +\begin{verbatim} +filter_settings "joincharacters" { charclases = { span=true, mn = true}} +\end{verbatim} + +\hypertarget{mathjaxsettings}{% +\subsubsection{\texorpdfstring{The \texttt{mathjaxnode} +filter}{The mathjaxnode filter}}\label{mathjaxsettings}} + +\begin{description} +\item[options] +command line options for the \texttt{mjpage} command. Default value is +\texttt{-\/-output\ CommonHTML} +\end{description} + +Example + +\begin{verbatim} +filter_settings "mathjaxnode" { + options="--output SVG --font Neo-Euler" +} +\end{verbatim} + +\begin{description} +\item[cssfilename] +\texttt{mjpage} 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 should be sub-directory of the current directory. Only TeX +font is supported at the moment. +\end{description} + +Example + +\begin{verbatim} +filter_settings "mathjaxnode" { + fontdir="fonts/TeX/woff/" +} +\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{configfile}{% +\section{Configuration file}\label{configfile}} + +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. + +\hypertarget{location}{% +\subsection{Location}\label{location}} + +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}). + +\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 configuration add 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{command-line-options}{% +\section{Command line options}\label{command-line-options}} \begin{verbatim} make4ht - build system for tex4ht @@ -313,6 +870,7 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op." -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 @@ -323,20 +881,22 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op." <filename> (string) Input file name \end{verbatim} -You can still use \texttt{make4ht} in same way as \texttt{htlatex} +You can still invoke \texttt{make4ht} in the same way as +\texttt{htlatex}: \begin{verbatim} -make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo" +make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo" \end{verbatim} -Note that this will not use \texttt{make4ht} routines for output dir -making and copying If you want to use them, change the line above to: +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{verbatim} -make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" -d foo +make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8" \end{verbatim} -This call has the same effect as following: +This call has the same effect as the following: \begin{verbatim} make4ht -u -c customcfg -d foo filename @@ -352,3 +912,47 @@ make4ht -d ../gotoparrentdir filename make4ht -d ~/gotohomedir filename make4ht -d c:\documents\windowspathsareworkingtoo filename \end{verbatim} + +\hypertarget{troubleshooting}{% +\section{Troubleshooting}\label{troubleshooting}} + +\hypertarget{incorrect-handling-of-command-line-arguments-for-tex4ht-t4ht-or-latex}{% +\subsection{\texorpdfstring{Incorrect handling of command line arguments +for \texttt{tex4ht}, \texttt{t4ht} or +\texttt{latex}}{Incorrect handling of command line arguments for tex4ht, t4ht or latex}}\label{incorrect-handling-of-command-line-arguments-for-tex4ht-t4ht-or-latex}} + +Sometimes, you may get a similar error: + +\begin{verbatim} +make4ht:unrecognized parameter: i +\end{verbatim} + +It may be caused by a following \texttt{make4ht} invocation: + +\begin{verbatim} +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: + +\begin{verbatim} +make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" +\end{verbatim} + +Another option is to add a space before \texttt{tex4ht} options: + +\begin{verbatim} +make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo +\end{verbatim} + +The former way is preferable, though. + +\hypertarget{license}{% +\section{License}\label{license}} + +Permission is granted to copy, distribute and/or modify this software +under the terms of the LaTeX Project Public License, version 1.3. |