diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/make4ht')
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/README | 81 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/changelog.tex | 111 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf | bin | 132815 -> 137946 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/make4ht/readme.tex | 148 |
4 files changed, 267 insertions, 73 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README index 8851c4d99fc..490b9c4a63a 100644 --- a/Master/texmf-dist/doc/support/make4ht/README +++ b/Master/texmf-dist/doc/support/make4ht/README @@ -2,12 +2,18 @@ # Introduction -`make4ht` is a build system for \TeX4ht, \TeX\ to XML converter. It provides a command line tool +`make4ht` is a build system for [\TeX4ht](https://tug.org/tex4ht/), \TeX\ to XML converter. It provides a command line tool that drives the conversion process. It also provides a library that can be used to create customized conversion tools. An example of such a tool is [tex4ebook](https://github.com/michal-h21/tex4ebook), a tool for conversion from \TeX\ to ePub and other e-book formats. +See section \ref{sec:htlatex} for some reasons why you should consider to use `make4ht` instead of `htlatex`, +section \ref{sec:output} talks about supported output formats and extensions and section \ref{sec:buildfiles} +describes build files, which can be used to execute additional commands or post-process the generated files. + + +# Usage The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed using the following command: @@ -15,8 +21,7 @@ The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed usin It will produce a file named `filename.html` if the compilation goes without fatal errors. - -# Command line options {#clioptions} +## Command line options {#clioptions} \label{sec:clioptions} make4ht - build system for TeX4ht @@ -29,7 +34,7 @@ It will produce a file named `filename.html` if the compilation goes without fat 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 filename is different + -e,--build-file (default nil) If the build filename is different than `filename`.mk4 -f,--format (default nil) Output file format -j,--jobname (default nil) Set the jobname @@ -42,8 +47,9 @@ It will produce a file named `filename.html` if the compilation goes without fat -v,--version Print version number <filename> (string) Input filename +## Option handling -It is still possible to invoke `make4ht` in the same way as is invoked `htlatex`: +It is possible to invoke `make4ht` in the same way as `htlatex`: $ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo" @@ -58,7 +64,7 @@ This call has the same effect as the following: $ make4ht -u -c customcfg -d foo filename -Output directory doesn't have to exist, it will be created automatically. +Output directory does not have to exist, it `make4ht` creates it automatically. Specified path can be relative to the current directory, or absolute: $ make4ht -d use/current/dir/ filename @@ -66,21 +72,25 @@ Specified path can be relative to the current directory, or absolute: $ make4ht -d ~/gotohomedir filename $ make4ht -d c:\documents\windowspathsareworkingtoo filename -The short options that don't take parameters can be collapsed: +The short options that do not take parameters can be collapsed: $ make4ht -ulc customcfg -d foo filename +## Input from the standard input + -To pass output from the other commands to `make4ht` use the `-` character as a +To pass the output from other commands to `make4ht`, use the `-` character as a filename. It is best to use this feature together with the `--jobname` or `-j` option. $ cat hello.tex | make4ht -j world - +## Change amount of information printed on the command line + By default, `make4ht` tries to be quiet, so it hides most of the command line -messages and the output from the executed commands. It will display only status -messages, warnings and errors. The logging level can be selected using the +messages and output from the executed commands. It displays status +messages, warnings, and errors. The logging level can be selected using the `--loglevel` or `-a` options. If the compilation fails, it may be useful to display more information using the `info` or `debug` levels. @@ -89,7 +99,8 @@ information using the `info` or `debug` levels. -# Why `make4ht`? -- `htlatex` issues +# Difference of `make4ht` from `htlatex` +\label{sec:htlatex} \TeX4ht\ system supports several output formats, most notably `XHTML`, `HTML 5` @@ -104,7 +115,7 @@ that contains the code for the desired output format. The produced `DVI` file is then processed using the `tex4ht` command, which in conjunction with the `t4ht` command produces the desired output files. -## Passing command line arguments +## Passing of command line arguments to low-level commands used in the conversion The basic conversion script provided by \TeX4ht\ system is named `htlatex`. It compiles \LaTeX\ files to `HTML` with this command sequence: @@ -183,15 +194,15 @@ should copy all output files to the correct destinations. $ make4ht -d outputdir filename.tex -## Image conversion and post-processing of the generated files +## Image conversion and postprocessing of the generated files \TeX4ht\ can convert parts of the document to images. This is useful for diagrams or complicated math, for example. By default, the image conversion is configured in a -[`.env` file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001). +[`.env` file](https://www.tug.org/applications/tex4ht/mn34.html#mn35.html). It has a bit of strange syntax, with -[operating system dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005) rules. +operating system dependent rules. `make4ht` provides simpler means for the image conversion in the build files. It is possible to change the image conversion parameters without a need to modify the `.env` file. The process is described in section \ref{sec:imageconversion}. @@ -203,6 +214,7 @@ using `Lua` functions. More information can be found in section \ref{sec:postpro # Output file formats and extensions +\label{sec:output} The default output format used by `make4ht` is `html5`. A different format can be requested using the `--format` option. Supported formats are: @@ -263,10 +275,17 @@ latexmk\_build mathjaxnode -: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to +: (**deprecated**, use `mjcli` extension instead) Old information: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to convert from MathML code to HTML + CSS or SVG. See [the available settings](#mathjaxsettings). +mjcli + +: use [mjcli](https://github.com/michal-h21/mjcli) to convert math in MathML or \LaTeX\ + format to plain HTML + CSS. MathML is used by default. If you want to use \LaTeX\ math, + add "mathjax" option on the command line (like `make4ht -f html5+mjcli filename.tex "mathjax"`). + See [the available settings](#mathjaxsettings). + odttemplate : it automatically loads the `odttemplate` filter (page \pageref{sec:odttemplate}). @@ -543,10 +562,16 @@ fix-links mathjaxnode -: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to +: (**deprecated**, use `mjcli` extension instead) Old information: use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to convert from MathML code to HTML + CSS or SVG. See [the available settings](#mathjaxsettings). +mjcli + +: use [mjcli](https://github.com/michal-h21/mjcli) to convert math in MathML or \LaTeX\ + format to plain HTML + CSS. See [the available settings](#mathjaxsettings). + + odttemplate : use styles from another `ODT` file serving as a template in the current @@ -797,7 +822,7 @@ The default parameters are the following: if the exit code of the executed command has a different value. -# Configuration file {#configfile} +# `make4ht` configuration file {#configfile} It is possible to globally modify the build settings using the configuration file. It is a special version of a build file where the global settings can be set. @@ -948,32 +973,38 @@ Example filter_settings "joincharacters" { charclasses = { span=true, mn = true}} -## The `mathjaxnode` filter {#mathjaxsettings} +## The `mjcli` filter and extension {#mathjaxsettings} + +`mjcli` detects whether to use MathML or \LaTeX\ input by use of the `mathjax` option for `make4ht`. By default, it uses MathML. \LaTeX\ input can be required using: + + make4ht -f html5+mjcli filename.tex "mathjax" + +### Available settings options -: command line options for the `mjpage` command. Default value is `--output CommonHTML` +: command line options for the `mjcli` command. Example - filter_settings "mathjaxnode" { - options="--output SVG --font Neo-Euler" + filter_settings "mjcli" { + options="--svg" } cssfilename -: the `mjpage` command puts some CSS code into the HTML pages. `mathjaxnode` extracts this information and saves it to a standalone CSS file. Default CSS filename is `mathjax-chtml.css` +: the `mjcli` command puts some CSS code into the HTML pages. The `mjcli` filter extracts this information and saves it to a standalone CSS file. Default name of this CSS file is `${input}-mathjax.css` fontdir : directory with MathJax font files. This option enables the use of local fonts, which is useful in the conversion to ePub, for example. The font directory should be - sub-directory of the current directory. Only TeX font is supported at the moment. + sub-directory of the current directory. Only \TeX\ font is supported at the moment. Example - filter_settings "mathjaxnode" { + filter_settings "mjcli" { fontdir="fonts/TeX/woff/" } diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex index 9752285cf35..ead753239ac 100644 --- a/Master/texmf-dist/doc/support/make4ht/changelog.tex +++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex @@ -3,6 +3,117 @@ \begin{itemize} \item + 2021/03/19 + + \begin{itemize} + \tightlist + \item + version \texttt{0.3g} released. + \end{itemize} +\item + 2021/02/08 + + \begin{itemize} + \tightlist + \item + remove \texttt{\textless{}?xtpipes\ ?\textgreater{}} processing + instructions from the generated ODT file. + \end{itemize} +\item + 2021/02/01 + + \begin{itemize} + \tightlist + \item + better error messages when extension cannot be loaded. + \item + added \texttt{mjcli} extension. + \item + \texttt{mjcli} filter supports \LaTeX~syntax. + \item + updated documentation. + \end{itemize} +\item + 2021/01/31 + + \begin{itemize} + \tightlist + \item + added new MathJax Node filter, \texttt{mjcli}. + \end{itemize} +\item + 2020/12/19 + + \begin{itemize} + \tightlist + \item + build web documentation only when documentation sources change. + \end{itemize} +\item + 2020/11/22 + + \begin{itemize} + \tightlist + \item + set exit status for the \texttt{make4ht} command. + \end{itemize} +\item + 2020/11/22 + + \begin{itemize} + \tightlist + \item + new extension, \texttt{build\_changed}. + \end{itemize} +\item + 2020/11/01 + + \begin{itemize} + \tightlist + \item + fix deprecated \texttt{\textless{}mfenced\textgreater{}} element in + MathML + \item + convert \texttt{\textless{}mo\ fence\textgreater{}} elements to + \texttt{\textless{}mfenced\textgreater{}} in \texttt{ODT} format. + \end{itemize} +\item + 2020/10/28 + + \begin{itemize} + \tightlist + \item + fixed handling of nested \texttt{\textless{}span\textgreater{}} + elements in \texttt{joincharacters} DOM filter. + \end{itemize} +\item + 2020/10/25 + + \begin{itemize} + \tightlist + \item + fixed command name for \texttt{Make:httex}, it was + \texttt{Make:htttex}. + \end{itemize} +\item + 2020/10/17 + + \begin{itemize} + \tightlist + \item + generate YAML header for all generated files with the + \texttt{staticsite} extension. + \end{itemize} +\item + 2020/09/17 + + \begin{itemize} + \tightlist + \item + require \texttt{mathml} option when \texttt{mathjaxnode} extension + is used. + \end{itemize} +\item 2020/09/07 \begin{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 differindex 7399a5b8792..6643f672038 100644 --- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf +++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex index 25c4b99064e..3810dbad365 100644 --- a/Master/texmf-dist/doc/support/make4ht/readme.tex +++ b/Master/texmf-dist/doc/support/make4ht/readme.tex @@ -1,13 +1,24 @@ \hypertarget{introduction}{% \section{Introduction}\label{introduction}} -\texttt{make4ht} is a build system for \TeX4ht, \TeX~to XML converter. -It provides a command line tool that drives the conversion process. It -also provides a library that can be used to create customized conversion +\texttt{make4ht} is a build system for +\href{https://tug.org/tex4ht/}{\TeX4ht}, \TeX~to XML converter. It +provides a command line tool that drives the conversion process. It also +provides a library that can be used to create customized conversion tools. An example of such a tool is \href{https://github.com/michal-h21/tex4ebook}{tex4ebook}, a tool for conversion from \TeX~to ePub and other e-book formats. +See section \ref{sec:htlatex} for some reasons why you should consider +to use \texttt{make4ht} instead of \texttt{htlatex},\\ +section \ref{sec:output} talks about supported output formats and +extensions and section \ref{sec:buildfiles} describes build files, which +can be used to execute additional commands or post-process the generated +files. + +\hypertarget{usage}{% +\section{Usage}\label{usage}} + The basic conversion from \LaTeX~to \texttt{HTML} using \texttt{make4ht} can be executed using the following command: @@ -19,7 +30,7 @@ It will produce a file named \texttt{filename.html} if the compilation goes without fatal errors. \hypertarget{clioptions}{% -\section{Command line options}\label{clioptions}} +\subsection{Command line options}\label{clioptions}} \label{sec:clioptions} @@ -34,7 +45,7 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 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 filename is different +-e,--build-file (default nil) If the build filename is different than `filename`.mk4 -f,--format (default nil) Output file format -j,--jobname (default nil) Set the jobname @@ -48,8 +59,11 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op." <filename> (string) Input filename \end{verbatim} -It is still possible to invoke \texttt{make4ht} in the same way as is -invoked \texttt{htlatex}: +\hypertarget{option-handling}{% +\subsection{Option handling}\label{option-handling}} + +It is possible to invoke \texttt{make4ht} in the same way as +\texttt{htlatex}: \begin{verbatim} $ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo" @@ -70,7 +84,7 @@ This call has the same effect as the following: $ make4ht -u -c customcfg -d foo filename \end{verbatim} -Output directory doesn't have to exist, it will be created +Output directory does not have to exist, it \texttt{make4ht} creates it automatically. Specified path can be relative to the current directory, or absolute: @@ -81,13 +95,17 @@ $ make4ht -d ~/gotohomedir filename $ make4ht -d c:\documents\windowspathsareworkingtoo filename \end{verbatim} -The short options that don't take parameters can be collapsed: +The short options that do not take parameters can be collapsed: \begin{verbatim} $ make4ht -ulc customcfg -d foo filename \end{verbatim} -To pass output from the other commands to \texttt{make4ht} use the +\hypertarget{input-from-the-standard-input}{% +\subsection{Input from the standard +input}\label{input-from-the-standard-input}} + +To pass the output from other commands to \texttt{make4ht}, use the \texttt{-} character as a filename. It is best to use this feature together with the \texttt{-\/-jobname} or \texttt{-j} option. @@ -95,20 +113,26 @@ together with the \texttt{-\/-jobname} or \texttt{-j} option. $ cat hello.tex | make4ht -j world - \end{verbatim} +\hypertarget{change-amount-of-information-printed-on-the-command-line}{% +\subsection{Change amount of information printed on the command +line}\label{change-amount-of-information-printed-on-the-command-line}} + By default, \texttt{make4ht} tries to be quiet, so it hides most of the -command line messages and the output from the executed commands. It will -display only status messages, warnings and errors. The logging level can -be selected using the \texttt{-\/-loglevel} or \texttt{-a} options. If -the compilation fails, it may be useful to display more information -using the \texttt{info} or \texttt{debug} levels. +command line messages and output from the executed commands. It displays +status messages, warnings, and errors. The logging level can be selected +using the \texttt{-\/-loglevel} or \texttt{-a} options. If the +compilation fails, it may be useful to display more information using +the \texttt{info} or \texttt{debug} levels. \begin{verbatim} $ make4ht -a debug faulty.tex \end{verbatim} -\hypertarget{why-make4ht-htlatex-issues}{% -\section{\texorpdfstring{Why \texttt{make4ht}? -- \texttt{htlatex} -issues}{Why make4ht? -- htlatex issues}}\label{why-make4ht-htlatex-issues}} +\hypertarget{difference-of-make4ht-from-htlatex}{% +\section{\texorpdfstring{Difference of \texttt{make4ht} from +\texttt{htlatex}}{Difference of make4ht from htlatex}}\label{difference-of-make4ht-from-htlatex}} + +\label{sec:htlatex} \TeX4ht~system supports several output formats, most notably \texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}, but it also supports @@ -125,9 +149,10 @@ The produced \texttt{DVI} file is then processed using the \texttt{tex4ht} command, which in conjunction with the \texttt{t4ht} command produces the desired output files. -\hypertarget{passing-command-line-arguments}{% -\subsection{Passing command line -arguments}\label{passing-command-line-arguments}} +\hypertarget{passing-of-command-line-arguments-to-low-level-commands-used-in-the-conversion}{% +\subsection{Passing of command line arguments to low-level commands used +in the +conversion}\label{passing-of-command-line-arguments-to-low-level-commands-used-in-the-conversion}} The basic conversion script provided by \TeX4ht~system is named \texttt{htlatex}. It compiles \LaTeX~ files to \texttt{HTML} with this @@ -234,21 +259,20 @@ correct destinations. $ make4ht -d outputdir filename.tex \end{verbatim} -\hypertarget{image-conversion-and-post-processing-of-the-generated-files}{% -\subsection{Image conversion and post-processing of the generated -files}\label{image-conversion-and-post-processing-of-the-generated-files}} +\hypertarget{image-conversion-and-postprocessing-of-the-generated-files}{% +\subsection{Image conversion and postprocessing of the generated +files}\label{image-conversion-and-postprocessing-of-the-generated-files}} \TeX4ht~can convert parts of the document to images. This is useful for diagrams or complicated math, for example. By default, the image conversion is configured in a -\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{\texttt{.env} -file}. It has a bit of strange syntax, with -\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{operating -system dependent} rules. \texttt{make4ht} provides simpler means for the -image conversion in the build files. It is possible to change the image -conversion parameters without a need to modify the \texttt{.env} file. -The process is described in section \ref{sec:imageconversion}. +\href{https://www.tug.org/applications/tex4ht/mn34.html\#mn35.html}{\texttt{.env} +file}. It has a bit of strange syntax, with operating system dependent +rules. \texttt{make4ht} provides simpler means for the image conversion +in the build files. It is possible to change the image conversion +parameters without a need to modify the \texttt{.env} file. The process +is described in section \ref{sec:imageconversion}. It is also possible to post-process the generated output files. The post-processing can be done either using external programs such as @@ -260,6 +284,8 @@ functions. More information can be found in section \section{Output file formats and extensions}\label{output-file-formats-and-extensions}} +\label{sec:output} + The default output format used by \texttt{make4ht} is \texttt{html5}. A different format can be requested using the \texttt{-\/-format} option. Supported formats are: @@ -322,9 +348,17 @@ load the \texttt{joincolors} domfilter for all HTML files. use \href{https://ctan.org/pkg/latexmk?lang=en}{Latexmk} for the \LaTeX~compilation. \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 +(\textbf{deprecated}, use \texttt{mjcli} extension instead) Old +information: 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[mjcli] +use \href{https://github.com/michal-h21/mjcli}{mjcli} to convert math in +MathML or \LaTeX~ format to plain HTML + CSS. MathML is used by default. +If you want to use \LaTeX~math, add ``mathjax'' option on the command +line (like \texttt{make4ht\ -f\ html5+mjcli\ filename.tex\ "mathjax"}). +See \protect\hyperlink{mathjaxsettings}{the available settings}. \item[odttemplate] it automatically loads the \texttt{odttemplate} filter (page \pageref{sec:odttemplate}). @@ -612,8 +646,14 @@ replace colons in local links and \texttt{id} attributes with underscores. Some cross-reference commands may produce colons in internal links, which results in a 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 +(\textbf{deprecated}, use \texttt{mjcli} extension instead) Old +information: 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[mjcli] +use \href{https://github.com/michal-h21/mjcli}{mjcli} to convert math in +MathML or \LaTeX~ format to plain HTML + CSS. See \protect\hyperlink{mathjaxsettings}{the available settings}. \item[odttemplate] use styles from another \texttt{ODT} file serving as a template in the @@ -861,7 +901,8 @@ value. \end{description} \hypertarget{configfile}{% -\section{Configuration file}\label{configfile}} +\section{\texorpdfstring{\texttt{make4ht} configuration +file}{make4ht configuration file}}\label{configfile}} It is possible to globally modify the build settings using the configuration file. It is a special version of a build file where the @@ -1035,39 +1076,50 @@ filter_settings "joincharacters" { charclasses = { span=true, mn = true}} \end{verbatim} \hypertarget{mathjaxsettings}{% -\subsection{\texorpdfstring{The \texttt{mathjaxnode} -filter}{The mathjaxnode filter}}\label{mathjaxsettings}} +\subsection{\texorpdfstring{The \texttt{mjcli} filter and +extension}{The mjcli filter and extension}}\label{mathjaxsettings}} + +\texttt{mjcli} detects whether to use MathML or \LaTeX~input by use of +the \texttt{mathjax} option for \texttt{make4ht}. By default, it uses +MathML. \LaTeX~input can be required using: + +\begin{verbatim} +make4ht -f html5+mjcli filename.tex "mathjax" +\end{verbatim} + +\hypertarget{available-settings}{% +\subsubsection{Available settings}\label{available-settings}} \begin{description} \item[options] -command line options for the \texttt{mjpage} command. Default value is -\texttt{-\/-output\ CommonHTML} +command line options for the \texttt{mjcli} command. \end{description} Example \begin{verbatim} -filter_settings "mathjaxnode" { - options="--output SVG --font Neo-Euler" +filter_settings "mjcli" { + options="--svg" } \end{verbatim} \begin{description} \item[cssfilename] -the \texttt{mjpage} command 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} +the \texttt{mjcli} command puts some CSS code into the HTML pages. The +\texttt{mjcli} filter extracts this information and saves it to a +standalone CSS file. Default name of this CSS file is +\texttt{\$\{input\}-mathjax.css} \item[fontdir] directory with MathJax font files. This option enables the use of local fonts, which is useful in the conversion to ePub, for example. The font -directory should be sub-directory of the current directory. Only TeX -font is supported at the moment. +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" { +filter_settings "mjcli" { fontdir="fonts/TeX/woff/" } \end{verbatim} |