summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-07-26 20:29:50 +0000
committerKarl Berry <karl@freefriends.org>2021-07-26 20:29:50 +0000
commit6190adeb5ec3b9128a55a4add7f367f18491742b (patch)
treeba33478aa6e56e39fe01b6232cebe59578aff904 /Master/texmf-dist/doc/support
parente50d32b956ce2adb17364c5fc9eb070ba490a00a (diff)
make4ht (26jul21)
git-svn-id: svn://tug.org/texlive/trunk@60077 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/make4ht/README77
-rw-r--r--Master/texmf-dist/doc/support/make4ht/changelog.tex134
-rw-r--r--Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdfbin137946 -> 144186 bytes
-rw-r--r--Master/texmf-dist/doc/support/make4ht/readme.tex78
4 files changed, 279 insertions, 10 deletions
diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README
index 490b9c4a63a..89cfac91417 100644
--- a/Master/texmf-dist/doc/support/make4ht/README
+++ b/Master/texmf-dist/doc/support/make4ht/README
@@ -175,6 +175,19 @@ cross-references work. It can save quite a lot of the compilation time:
$ make4ht -um draft filename.tex
+Another buil-in mode is `clean`. It executes the `Make:clean()` command to
+remove all generated and temporary files from the current directory.
+No \LaTeX\ compilation happens in this mode.
+
+It should be used in this way:
+
+ # copy generated files to a direcory
+ $ make4ht -d outdir filename.tex
+ # remove all generated files in the current dir
+ # the -a info option will print files that are removed
+ $ make4ht -m clean -a info filename.tex
+
+
More information about the build files can be found in section \ref{sec:buildfiles}.
## Handling of the generated files
@@ -248,7 +261,7 @@ common\_domfilters
: clean the HTML file using DOM filters. It is more powerful than
`common_filters`. Used DOM filters are `fixinlines`, `idcolons`,
-`joincharacters`, and `tablerows`.
+`joincharacters`, `sectionid` and `tablerows`.
detect\_engine
@@ -416,6 +429,12 @@ detect compilation errors in the TeX log file.
: One call to the TeX engine with special configuration for loading of the `tex4ht.sty` package.
+`Make:clean`
+
+: This command removes all generated files, including images, HTML files and
+ various auxilary files, from the current directory. It keeps files whose
+ file names don't match the input file name.
+
`Make:httex`
: Variant of `Make:htlatex` suitable for Plain \TeX.
@@ -653,6 +672,12 @@ mathmlfixes
: fix common issues for MathML.
+sectionid
+
+: create `id` attribute for HTML sectioning elements derived from the section
+ title. It also updates links to these sections. Use the `notoc` command line
+ option to prevent that.
+
t4htlinks
: fix hyperlinks in the ODT format.
@@ -935,7 +960,7 @@ options
`toc_query`
-: CSS selector for selecting the table of contents container.
+: CSS selector for selection of element that contains the table of contents.
`title_query`
@@ -945,12 +970,33 @@ options
: table containing a hierarchy of classes used in TOC
+`max_depth`
+
+: set detph of displayed children TOC levels
+
Default values:
filter_settings "collapsetoc" {
toc_query = ".tableofcontents",
- title_query = ".partHead a, .chapterHead a, .sectionHead a, .subsectionHead a",
- toc_levels = {"partToc", "chapterToc", "sectionToc", "subsectionToc", "subsubsectionToc"}
+ title_query = "h1 a, h2 a, h3 a, h4 a, h5 a, h6 a",
+ max_depth = 1,
+ toc_levels = {
+ tocpart = 1,
+ toclikepart = 1,
+ tocappendix = 1,
+ toclikechapter = 2,
+ tocchapter = 2,
+ tocsection = 3,
+ toclikesection = 3,
+ tocsubsection = 4,
+ toclikesubsection = 4,
+ tocsubsubsection = 5,
+ toclikesubsubsection = 5,
+ tocparagraph = 6,
+ toclikeparagraph = 6,
+ tocsubparagraph = 7,
+ toclikesubparagraph = 7,
+ }
}
## The `fixinlines` dom filter
@@ -1034,15 +1080,22 @@ header
table value is a function, it is executed with current parameters and HTML page
DOM object as arguments.
+remove\_maketitle
+
+: the `staticsite` extension removes text produced by the `\maketitle` command by default. Set this
+option to `false` to disable the removal.
+
Example:
+ -- set the environmental variable 'blog_root' with path to
+ -- the directory that should hold the generated HTML files
local outdir = os.getenv "blog_root"
filter_settings "staticsite" {
site_root = outdir,
map = {
- [".css$"] = "../css/"
+ [".css$"] = "/css/"
},
header = {
layout="post",
@@ -1262,6 +1315,20 @@ Another option is to add a space before the `tex4ht` options:
The former way is preferable, though.
+## Table of Contents points to a wrong destination
+
+The `sectionid` DOM filter creates better link destinations for sectioning commands.
+In some cases, for example if you use Pandoc, the document may already contain the
+link destination with the same name. In such cases the original destination is preserved
+in the file. In this case links to the section will point to that place, instead of
+correct destination in the section. This may happen for example if you use Pandoc for
+the Markdown to \LaTeX\ conversion. It creates `\hypertarget` commands that are placed
+just before section. The links points to that place, instead of the actual section.
+
+In this case you don't want to update links. Use the `notoc` option to prevent that.
+
+
+
## Filenames containing spaces
`tex4ht` command cannot handle filenames containing spaces. to fix this issue, `make4ht`
diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex
index ead753239ac..61dbcdaa3b7 100644
--- a/Master/texmf-dist/doc/support/make4ht/changelog.tex
+++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex
@@ -3,6 +3,140 @@
\begin{itemize}
\item
+ 2021/07/25
+
+ \begin{itemize}
+ \tightlist
+ \item
+ version \texttt{0.3h} released.
+ \end{itemize}
+\item
+ 2021/07/25
+
+ \begin{itemize}
+ \tightlist
+ \item
+ use current directory as default output dir in \texttt{staticsite}
+ extension.
+ \end{itemize}
+\item
+ 2021/07/23
+
+ \begin{itemize}
+ \tightlist
+ \item
+ fixed detection of single paragraphs inside
+ \texttt{\textless{}li\textgreater{}} in the \texttt{itemparagraphs}
+ DOM filter.
+ \end{itemize}
+\item
+ 2021/07/18
+
+ \begin{itemize}
+ \tightlist
+ \item
+ remove elements produced by \texttt{\textbackslash{}maketitle} in
+ the \texttt{staticsite} extension.
+ \end{itemize}
+\item
+ 2021/07/05
+
+ \begin{itemize}
+ \tightlist
+ \item
+ sort colors alphabetically in the \texttt{joincolors} DOM filter to
+ enable reproducible builds.
+ \end{itemize}
+\item
+ 2021/06/26
+
+ \begin{itemize}
+ \tightlist
+ \item
+ rewrote the \texttt{collapsetoc} DOM filter.
+ \end{itemize}
+\item
+ 2021/06/20
+
+ \begin{itemize}
+ \tightlist
+ \item
+ test for the \texttt{svg} picture mode in the \texttt{tex4ht}
+ command. Use the \texttt{-g.svg} option if it is detected. This is
+ necessary for correct support of pictorial characters.
+ \end{itemize}
+\item
+ 2021/06/16
+
+ \begin{itemize}
+ \tightlist
+ \item
+ better handling of duplicate ID attributes in \texttt{sectionid} DOM
+ filter.
+ \item
+ support \texttt{notoc} option in \texttt{sectionid}.
+ \end{itemize}
+\item
+ 2021/06/13
+
+ \begin{itemize}
+ \tightlist
+ \item
+ added \texttt{itemparagraphs} DOM filter. It removes unnecessary
+ paragraphs from \texttt{\textless{}li\textgreater{}} elements.
+ \end{itemize}
+\item
+ 2021/05/06
+
+ \begin{itemize}
+ \tightlist
+ \item
+ remove \texttt{\textless{}hr\textgreater{}} elements in
+ \texttt{.hline} rows in \texttt{tablerows} DOM filter.
+ \end{itemize}
+\item
+ 2021/05/01
+
+ \begin{itemize}
+ \tightlist
+ \item
+ added function \texttt{mkutils.isModuleAvailable}. It checks if Lua
+ library is available.
+ \item
+ check for \texttt{char-def} library in \texttt{sectionid} DOM
+ filter.
+ \end{itemize}
+\item
+ 2021/04/08
+
+ \begin{itemize}
+ \tightlist
+ \item
+ removed \texttt{build\_changed}. New script,
+ \href{https://github.com/michal-h21/siterebuild}{siterebuild},
+ should be used instead.
+ \item
+ new DOM filter, \texttt{sectionid}. It uses sanitized titles instead
+ of automatically generated numbers as section IDs.
+ \item
+ added \texttt{sectionid} to \texttt{common\_domfilters}.
+ \item
+ use \texttt{context} in the Docker file, because it contains the
+ \texttt{char-def.lua} file.
+ \end{itemize}
+\item
+ 2021/03/20
+
+ \begin{itemize}
+ \tightlist
+ \item
+ use \texttt{kpse} library when files are copied to the output
+ directory.
+ \item
+ added \texttt{clean} mode. It removes all generated, temporary and
+ auxilary files.
+ \end{itemize}
+\item
2021/03/19
\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 6643f672038..cc0d7d1b504 100644
--- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
+++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex
index 3810dbad365..1938c98a0ab 100644
--- a/Master/texmf-dist/doc/support/make4ht/readme.tex
+++ b/Master/texmf-dist/doc/support/make4ht/readme.tex
@@ -232,6 +232,21 @@ compilation time:
$ make4ht -um draft filename.tex
\end{verbatim}
+Another buil-in mode is \texttt{clean}. It executes the
+\texttt{Make:clean()} command to remove all generated and temporary
+files from the current directory. No \LaTeX~compilation happens in this
+mode.
+
+It should be used in this way:
+
+\begin{verbatim}
+# copy generated files to a direcory
+$ make4ht -d outdir filename.tex
+# remove all generated files in the current dir
+# the -a info option will print files that are removed
+$ make4ht -m clean -a info filename.tex
+\end{verbatim}
+
More information about the build files can be found in section
\ref{sec:buildfiles}.
@@ -328,7 +343,8 @@ clean the output HTML files using filters.
\item[common\_domfilters]
clean the HTML file using DOM filters. It is more powerful than
\texttt{common\_filters}. Used DOM filters are \texttt{fixinlines},
-\texttt{idcolons}, \texttt{joincharacters}, and \texttt{tablerows}.
+\texttt{idcolons}, \texttt{joincharacters}, \texttt{sectionid} and
+\texttt{tablerows}.
\item[detect\_engine]
detect engine and format necessary for the document compilation from the
magic comments supported by \LaTeX~editors such as TeXShop or TeXWorks.
@@ -512,6 +528,10 @@ the TeX log file.
\item[\texttt{Make:htlatex}]
One call to the TeX engine with special configuration for loading of the
\texttt{tex4ht.sty} package.
+\item[\texttt{Make:clean}]
+This command removes all generated files, including images, HTML files
+and various auxilary files, from the current directory. It keeps files
+whose file names don't match the input file name.
\item[\texttt{Make:httex}]
Variant of \texttt{Make:htlatex} suitable for Plain \TeX.
\item[\texttt{Make:latexmk}]
@@ -723,6 +743,10 @@ format.
remove spurious rows from HTML tables.
\item[mathmlfixes]
fix common issues for MathML.
+\item[sectionid]
+create \texttt{id} attribute for HTML sectioning elements derived from
+the section title. It also updates links to these sections. Use the
+\texttt{notoc} command line option to prevent that.
\item[t4htlinks]
fix hyperlinks in the ODT format.
\end{description}
@@ -1023,12 +1047,15 @@ filter}{The collapsetoc dom filter}}\label{the-collapsetoc-dom-filter}}
\begin{description}
\item[\texttt{toc\_query}]
-CSS selector for selecting the table of contents container.
+CSS selector for selection of element that contains the table of
+contents.
\item[\texttt{title\_query}]
CSS selector for selecting all elements that contain the section ID
attribute.
\item[\texttt{toc\_levels}]
table containing a hierarchy of classes used in TOC
+\item[\texttt{max\_depth}]
+set detph of displayed children TOC levels
\end{description}
Default values:
@@ -1036,8 +1063,25 @@ Default values:
\begin{verbatim}
filter_settings "collapsetoc" {
toc_query = ".tableofcontents",
- title_query = ".partHead a, .chapterHead a, .sectionHead a, .subsectionHead a",
- toc_levels = {"partToc", "chapterToc", "sectionToc", "subsectionToc", "subsubsectionToc"}
+ title_query = "h1 a, h2 a, h3 a, h4 a, h5 a, h6 a",
+ max_depth = 1,
+ toc_levels = {
+ tocpart = 1,
+ toclikepart = 1,
+ tocappendix = 1,
+ toclikechapter = 2,
+ tocchapter = 2,
+ tocsection = 3,
+ toclikesection = 3,
+ tocsubsection = 4,
+ toclikesubsection = 4,
+ tocsubsubsection = 5,
+ toclikesubsubsection = 5,
+ tocparagraph = 6,
+ toclikeparagraph = 6,
+ tocsubparagraph = 7,
+ toclikesubparagraph = 7,
+ }
}
\end{verbatim}
@@ -1145,17 +1189,23 @@ pattern \texttt{\%Y-\%m-\%d-\$\{input\}} creates names in the form of
table with variables to be set in the YAML header in HTML files. If the
table value is a function, it is executed with current parameters and
HTML page DOM object as arguments.
+\item[remove\_maketitle]
+the \texttt{staticsite} extension removes text produced by the
+\texttt{\textbackslash{}maketitle} command by default. Set this option
+to \texttt{false} to disable the removal.
\end{description}
Example:
\begin{verbatim}
+-- set the environmental variable 'blog_root' with path to
+-- the directory that should hold the generated HTML files
local outdir = os.getenv "blog_root"
filter_settings "staticsite" {
site_root = outdir,
map = {
- [".css$"] = "../css/"
+ [".css$"] = "/css/"
},
header = {
layout="post",
@@ -1405,6 +1455,24 @@ $ make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
The former way is preferable, though.
+\hypertarget{table-of-contents-points-to-a-wrong-destination}{%
+\subsection{Table of Contents points to a wrong
+destination}\label{table-of-contents-points-to-a-wrong-destination}}
+
+The \texttt{sectionid} DOM filter creates better link destinations for
+sectioning commands. In some cases, for example if you use Pandoc, the
+document may already contain the link destination with the same name. In
+such cases the original destination is preserved in the file. In this
+case links to the section will point to that place, instead of correct
+destination in the section. This may happen for example if you use
+Pandoc for the Markdown to \LaTeX~conversion. It creates
+\texttt{\textbackslash{}hypertarget} commands that are placed just
+before section. The links points to that place, instead of the actual
+section.
+
+In this case you don't want to update links. Use the \texttt{notoc}
+option to prevent that.
+
\hypertarget{filenames-containing-spaces}{%
\subsection{Filenames containing
spaces}\label{filenames-containing-spaces}}