diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/README.md | 297 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/changelog.tex | 11 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf | bin | 0 -> 61644 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex | 24 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/readme.tex | 322 |
5 files changed, 654 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/README.md b/Master/texmf-dist/doc/support/make4ht/README.md new file mode 100644 index 00000000000..13840cd2e58 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/README.md @@ -0,0 +1,297 @@ +# Introduction + +`make4ht` is a simple build system for tex4ht. It is both executable which +simplifies `tex4ht` execution and a library which can be used to create +customized conversion programs. An example of such conversion program is [tex4ebook](https://github.com/michal-h21/tex4ebook) + +## License + +Permission is granted to copy, distribute and/or modify this software +under the terms of the LaTeX Project Public License, version 1.3. + +How it works +------------ + +Default compilation script for `tex4ht`, named `htlatex` compiles LaTeX files to `HTML` with this command sequence: + + 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 + +The problem is that this is inefficient when you need to run program which +interact with LaTeX, such as `Makeindex` or `Bibtex`. In that case, you need to +create new script based on the default one, or run `htlatex` twice, which means +six LaTeX runs. + +Another problem is with `t4ht` application. It reads file `filename.lg`, +generated by `tex4ht`, where are instructions about generated files, `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 +[env file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001), +with really strange syntax based on whitespace and +[os dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005). +With `make4ht` build files, we have simple mean to fix these issues. We can +change image conversion parameters without need to modify the `env file`, +and call actions on the output files. These actions can be either external +programs such as `xslt` processors or `HTML tidy` or `Lua` functions. + +The idea is to make system controlled by a build file. Because `Lua` +interpreter is included in modern TeX distributions and `Lua` is ideal language +for such task, it was chosen as language in which build script are written. + + +# Build files + +## Commands + +By default, build file is saved in file named `filename + .mk4 extension`. +You can choose different build file with `-e` or `--build-file` command line +option. + +Sample: + + Make:htlatex() + Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}") + + `Make:htlatex()` is preconfigured command for calling LaTeX with `tex4ht` loaded on the input file. In this case it will be called one time. After compilation, `tidy` command is executed on the output `html` file. + +Note that you don't have to call `tex4ht` and `t4ht` commands explicitly in the build file, they are called automatically. + +You can add more commands like `Make:htlatex` with + + Make:add("name", "command", {parameters}, repetition) + + +it can be called with + + Make:name() + +`command` can be text template, or function: + + Make:add("text", "hello, input file: ${input}") + Make:add("function", function(params) for k, v in pairs(params) do print(k..": "..v) end) + +`parameters` is a table or `nil` value. + +Default parameters are: + +htlatex + +: used compiler + +input + +: input file + +latex_par + +: parameters to `latex` + +tex4ht_sty_par + +: parameters to `tex4ht.sty` + +tex4ht_par + +: parameters to `tex4ht` application + +t4ht_par + +: parameters to `t4ht` application + +outdir + +: output directory + +repetition + +: limit number of command execution. + +correct_exit + +: expected `exit code` from the command. + + +You may add your own parameters, they will be accessible in templates and +functions. + +With `repetition`, you can limit number of command executions. Its value +should be number or `nil`. This is used in the case of `tex4ht` and `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 `make4ht`. With `repetition`, second execution is blocked. + +You can set expected exit code from a command with `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 `1` is returned +in the case of fatal error, `0` is used otherwise. + +## File matches + +Other type of action which can be specified in the build file are +matches which may be called on the generated files: + + Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}") + +It tests filenames with `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 `filename`, which contains generated +output name. + +### Filters + +Some default match actions which you can use are in the `filter` module. It +contains some functions which ares useful for fixing some `tex4ht` bugs or +shortcomings. + +Example: + + local filter = require "make4ht-filter" + local process = filter{"cleanspan", "fixligatures", "hruletohr"} + Make:htlatex() + Make:htlatex() + Make:match("html$",process) + + +Filter module is located in `make4ht-filter`. Function is returned, +which is used for building filter chains then. + +Built-in filters are: + +cleanspan + +: clean spurious span elements when accented characters are used + +cleanspan-nat + +: alternative clean span filter, provided by Nat Kuhn + +fixligatures + +: decompose ligatures to base characters + +hruletohr + +: `\hrule` commands are translated to series of underscore characters + by `tex4ht`, this filter translate these underscores to `<hr>` elements +entites + +: convert prohibited named entities to numeric entities (currently, only ` `, as it causes validation errors, and `tex4ht` is producing it sometimes + + +Function `filter` accepts also function arguments, in this case this function +takes file contents as parameter and modified contents are returned. + +Example: + + 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) + +In this case, spurious span elements are joined, ligatures are decomposed, +and then all letters 'a' are replaced with 'z' letters. + +## Image conversion + +It is possible to convert parts of LaTeX input to pictures, it is used +for example for math or diagrams in `tex4ht`. + +These pictures are stored in special `dvi` file, on which `dvi to image` +commands are called. + +This conversion is normally configured in the `env file`, +which is system dependent and which has a little bit unintuitive syntax. +This configuration is processed by `t4ht` application and conversion +commands are called for all pictures. + +It is possible to disable `t4ht` image processing and configure image +conversion in the make file: + + Make:image("png$", + "dvipng -bg Transparent -T tight -o ${output} -pp ${page} ${source}") + + +`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: + + - output - output image file name + - source - `dvi` file with the pictures + - page - page number of the converted image + +## `mode` variable + +Variable `mode` contains contents of `-mode` command line option. +It can be used to run some commands conditionally. For example: + + if mode == "draft" then + Make:htlatex{} + else + Make:htlatex{} + Make:htlatex{} + Make:htlatex{} + end + +In this example (which is default configuration used by `make4ht`), +LaTeX is called only once when `make4ht` is called with + + make4ht -m draft filename + + +# Command line options + + 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 + + +You can still use `make4ht` in same way as `htlatex` + + make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo" + +Note that this will not use `make4ht` routines for output dir making and +copying If you want to use them, change the line above to: + + make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" -d foo + +This call has the same effect as following: + + make4ht -u -c customcfg -d foo filename + +Output directory doesn't have to exist, it will be created automatically. +Specified path can be relative to current directory, or absolute: + + make4ht -d use/current/dir/ filename + make4ht -d ../gotoparrentdir filename + make4ht -d ~/gotohomedir filename + make4ht -d c:\documents\windowspathsareworkingtoo filename + + diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex new file mode 100644 index 00000000000..8687ad10ec9 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex @@ -0,0 +1,11 @@ +\section{Changelog}\label{changelog} + +\subsection{2015/06/26}\label{section} + +\begin{itemize} +\itemsep1pt\parskip0pt\parsep0pt +\item + added Makefile +\item + moved INSTALL instructions from README to INSTALL +\end{itemize} diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf Binary files differnew file mode 100644 index 00000000000..cca309660e2 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex new file mode 100644 index 00000000000..e89626c7a96 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex @@ -0,0 +1,24 @@ +\documentclass{ltxdoc} + + +\usepackage[english]{babel} +\usepackage{hyperref} +\ifdefined\HCode +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\else +\usepackage{fontspec} +\setmainfont{TeX Gyre Schola} +\fi +\usepackage{microtype} + +\title{The \texttt{make4ht} build system} +\author{Michal Hoftich\footnote{\url{michal.h21@gmail.com}}} +\date{Version 0.1\\29/06/2015} +\begin{document} +\maketitle +\tableofcontents +\input{readme} + +\input{changelog} +\end{document} 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} |