diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/make4ht/readme.tex')
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/readme.tex | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex new file mode 100644 index 00000000000..fc2f72727f3 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/readme.tex @@ -0,0 +1,322 @@ +\section{Introduction}\label{introduction} + +\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} + +\subsection{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. + +\subsection{How it works}\label{how-it-works} + +Default compilation script for \texttt{tex4ht}, named \texttt{htlatex} +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 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 +\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{env +file}, with really strange syntax based on whitespace and +\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. +These actions can be either external programs such as \texttt{xslt} +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. + +\section{Build files}\label{build-files} + +\subsection{Commands}\label{commands} + +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. + +Sample: + +\begin{verbatim} +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, \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 + +\begin{verbatim} +Make:add("name", "command", {parameters}, repetition) +\end{verbatim} + +it can be called with + +\begin{verbatim} +Make:name() +\end{verbatim} + +\texttt{command} can be text template, or function: + +\begin{verbatim} +Make:add("text", "hello, input file: ${input}") +Make:add("function", function(params) for k, v in pairs(params) do print(k..": "..v) end) +\end{verbatim} + +\texttt{parameters} is a table or \texttt{nil} value. + +Default parameters are: + +\begin{description} +\item[htlatex] +used compiler +\item[input] +input file +\item[latex\_par] +parameters to \texttt{latex} +\item[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] +limit number of command execution. +\item[correct\_exit] +expected \texttt{exit code} from the command. +\end{description} + +You may add your own parameters, they will be accessible in templates +and functions. + +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. + +You can set expected exit code from a command with +\texttt{correct\_exit}. Compilation is stopped when command returns +different exit code. Situation is little bit difficult with LaTeX (all +engines and formats in fact), because it doesn't differentiate between +fatal and non fatal errors and returns 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. + +\subsection{File matches}\label{file-matches} + +Other type of action which can be specified in the build file are +matches which may 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. Parameters are the same as in previous section, except +\texttt{filename}, which contains generated output name. + +\subsubsection{Filters}\label{filters} + +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. + +Example: + +\begin{verbatim} +local filter = require "make4ht-filter" +local process = filter{"cleanspan", "fixligatures", "hruletohr"} +Make:htlatex() +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. + +Built-in filters are: + +\begin{description} +\item[cleanspan] +clean spurious span elements when accented characters are used +\item[cleanspan-nat] +alternative clean span filter, provided by Nat Kuhn +\item[fixligatures] +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 +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 +\end{description} + +Function \texttt{filter} accepts also function arguments, in this case +this function takes file contents as 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 case, spurious span elements are joined, ligatures are +decomposed, and then all letters `a' are replaced with `z' letters. + +\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. + +This conversion is normally configured in the \texttt{env file}, which +is system dependent and which has a little bit unintuitive syntax. This +configuration is processed by \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: + +\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 table with parameters as argument. + +There are three parameters: + +\begin{itemize} +\itemsep1pt\parskip0pt\parsep0pt +\item + output - output image file name +\item + source - \texttt{dvi} file with the pictures +\item + page - page number of the converted image +\end{itemize} + +\subsection{\texttt{mode} variable}\label{mode-variable} + +Variable \texttt{mode} contains contents of \texttt{-mode} command line +option. It can be used to run some commands conditionally. For example: + +\begin{verbatim} + if mode == "draft" then + Make:htlatex{} + else + Make:htlatex{} + Make:htlatex{} + Make:htlatex{} + end +\end{verbatim} + +In this example (which is default configuration used by +\texttt{make4ht}), LaTeX is called only once when \texttt{make4ht} is +called with + +\begin{verbatim} +make4ht -m draft filename +\end{verbatim} + +\section{Command line options}\label{command-line-options} + +\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 +-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 +<filename> (string) Input file name +\end{verbatim} + +You can still use \texttt{make4ht} in same way as \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 output dir +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 +\end{verbatim} + +This call has the same effect as 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 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} |