From f2c1bd0a1a94f92d81946cb9195117f87f5d2471 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 23 Sep 2015 23:35:39 +0000 Subject: make4ht (23sep15) git-svn-id: svn://tug.org/texlive/trunk@38446 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/support/make4ht/README | 303 +++++++++++++++++++++ Master/texmf-dist/doc/support/make4ht/README.md | 297 -------------------- .../texmf-dist/doc/support/make4ht/changelog.tex | 19 ++ .../texmf-dist/doc/support/make4ht/make4ht-doc.pdf | Bin 61644 -> 62996 bytes .../texmf-dist/doc/support/make4ht/make4ht-doc.tex | 2 +- Master/texmf-dist/doc/support/make4ht/readme.tex | 10 +- Master/texmf-dist/scripts/make4ht/mkparams.lua | 2 +- 7 files changed, 332 insertions(+), 301 deletions(-) create mode 100644 Master/texmf-dist/doc/support/make4ht/README delete mode 100644 Master/texmf-dist/doc/support/make4ht/README.md (limited to 'Master') diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README new file mode 100644 index 00000000000..ab25739d857 --- /dev/null +++ b/Master/texmf-dist/doc/support/make4ht/README @@ -0,0 +1,303 @@ +# 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` + +packages + +: insert additionl LaTeX code which is inserted before `\documentclass`. + useful for passing options to packages or additional packages loading + +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. 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 `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 `
` 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 + (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/README.md b/Master/texmf-dist/doc/support/make4ht/README.md deleted file mode 100644 index 13840cd2e58..00000000000 --- a/Master/texmf-dist/doc/support/make4ht/README.md +++ /dev/null @@ -1,297 +0,0 @@ -# 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 `
` 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 - (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 index 8687ad10ec9..77fffc0a8dd 100644 --- a/Master/texmf-dist/doc/support/make4ht/changelog.tex +++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex @@ -1,5 +1,24 @@ \section{Changelog}\label{changelog} +\subsection{2015/09/23 version 0.1a}\label{version-0.1a} + +\begin{itemize} +\itemsep1pt\parskip0pt\parsep0pt +\item + various documentation updates +\item + \texttt{mozhtf} profile for unicode output is used, this should + prevent ligatures in the output files +\end{itemize} + +\subsection{2015/06/29 version 0.1}\label{version-0.1} + +\begin{itemize} +\itemsep1pt\parskip0pt\parsep0pt +\item + major README file update +\end{itemize} + \subsection{2015/06/26}\label{section} \begin{itemize} diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf index cca309660e2..028c505ad49 100644 Binary files a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf and b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf differ diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex index e89626c7a96..b2af0201069 100644 --- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex +++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex @@ -14,7 +14,7 @@ \title{The \texttt{make4ht} build system} \author{Michal Hoftich\footnote{\url{michal.h21@gmail.com}}} -\date{Version 0.1\\29/06/2015} +\date{Version 0.1a\\23/09/2015} \begin{document} \maketitle \tableofcontents diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex index fc2f72727f3..c47517c8840 100644 --- a/Master/texmf-dist/doc/support/make4ht/readme.tex +++ b/Master/texmf-dist/doc/support/make4ht/readme.tex @@ -107,6 +107,10 @@ used compiler input file \item[latex\_par] parameters to \texttt{latex} +\item[packages] +insert additionl LaTeX code which is inserted before +\texttt{\textbackslash{}documentclass}. useful for passing options to +packages or additional packages loading \item[tex4ht\_sty\_par] parameters to \texttt{tex4ht.sty} \item[tex4ht\_par] @@ -150,8 +154,10 @@ Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}") 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. +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. \subsubsection{Filters}\label{filters} diff --git a/Master/texmf-dist/scripts/make4ht/mkparams.lua b/Master/texmf-dist/scripts/make4ht/mkparams.lua index 5b614192029..04b2827e102 100755 --- a/Master/texmf-dist/scripts/make4ht/mkparams.lua +++ b/Master/texmf-dist/scripts/make4ht/mkparams.lua @@ -93,7 +93,7 @@ local function process_args(args) if args[2] and args[2] ~="" then tex4ht = args[2] else - tex4ht = args.utf8 and " -cunihtf -utf8" or "" + tex4ht = args.utf8 and " -cmozhtf -utf8" or "" local xdv = args.xetex and " -.xdv" or "" tex4ht = tex4ht .. xdv end -- cgit v1.2.3