make4ht (26jul21)

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

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
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}}