make4ht (29jul15)

git-svn-id: svn://tug.org/texlive/trunk@37750 c570f23f-e606-0410-a88d-b1316a301751

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 `&nbsp;`, 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
new 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{\&nbsp;}, 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}