[tex4ht-commits] [SCM] tex4ht updated: r688 - in trunk/doc: . tex4ht-doc tex4ht-doc/section [more]
michal_h21 at gnu.org.ua
michal_h21 at gnu.org.ua
Tue May 5 21:54:36 CEST 2020
Author: michal_h21
Date: 2020-05-05 22:54:36 +0300 (Tue, 05 May 2020)
New Revision: 688
Modified:
trunk/doc/tex4ht-configure1.tex
trunk/doc/tex4ht-doc/Makefile
trunk/doc/tex4ht-doc/README
trunk/doc/tex4ht-doc/build.mk4
trunk/doc/tex4ht-doc/config.cfg
trunk/doc/tex4ht-doc/sections/tex4ht-commands.tex
trunk/doc/tex4ht-doc/style.css
trunk/doc/tex4ht-doc/tex4ht-doc.tex
trunk/doc/tex4ht-doc/tex4ht-styles.sty
Log:
Added missing closing paren in HTML listing
Modified: trunk/doc/tex4ht-configure1.tex
===================================================================
--- trunk/doc/tex4ht-configure1.tex 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-configure1.tex 2020-05-05 19:54:36 UTC (rev 688)
@@ -47,7 +47,7 @@
\begin{verbatim}
\Configure{section}
{\EndP\IgnorePar\Tg<section id="sec\thesection">}
- {\EndP\Tg</section}
+ {\EndP\Tg</section>}
{\Tg<title>}
{\Tg</title>\ShowPar}
\end{verbatim}
Modified: trunk/doc/tex4ht-doc/Makefile
===================================================================
--- trunk/doc/tex4ht-doc/Makefile 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/Makefile 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,6 +1,10 @@
-mode = final
+mode = draft
engine =
+outputdir = out
+IMAGESUBDIRS := $(wildcard images/*/.)
+
+
ifeq (lualatex, lualatex)
engine = -l
endif
@@ -9,21 +13,27 @@
engine = -x
endif
-sections = sections/tex4ht-commands.tex
+# sections = sections/tex4ht-commands.tex sections/tex4ht-options.tex sections/webfonts.tex sections/configuration-files.tex sections/tex4ht-development.tex sections/calling-commands.tex sections/graphics.tex
+sections = $(wildcard sections/*.tex)
+filters = $(wildcard filters/*.lua)
-all: tex4ht-doc.pdf tex4ht-doc.html
+all: $(IMAGESUBDIRS) tex4ht-doc.pdf tex4ht-doc.html
-.PHONY: final
+$(IMAGESUBDIRS):
+ $(MAKE) -C $@
+.PHONY: final all $(IMAGESUBDIRS)
+
tex4ht-doc.pdf: tex4ht-doc.tex tex4ht-styles.sty ${sections}
- lualatex tex4ht-doc.tex
+ lualatex -shell-escape tex4ht-doc.tex
-tex4ht-doc.html: tex4ht-doc.tex config.cfg tex4ht-styles.sty ${sections}
- make4ht -um $(mode) -c config $(engine) -f html5+common_domfilters -e build.mk4 tex4ht-doc.tex
+tex4ht-doc.html: tex4ht-doc.tex config.cfg tex4ht-styles.sty build.mk4 ${sections} ${filters}
+ make4ht -usm $(mode) -c config $(engine) -d $(outputdir) -f html5+common_domfilters -e build.mk4 tex4ht-doc.tex
+
# use only one LaTeX run by default, request three compilations with final rule
-final: mode=final
-final: tex4ht-doc.html
+final: tex4ht-doc.html
+ make4ht -usm final -c config $(engine) -d $(outputdir) -f html5+common_domfilters -e build.mk4 tex4ht-doc.tex
clean:
rm *.html *.aux *.4tc *.4ct *.xref
Modified: trunk/doc/tex4ht-doc/README
===================================================================
--- trunk/doc/tex4ht-doc/README 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/README 2020-05-05 19:54:36 UTC (rev 688)
@@ -2,5 +2,7 @@
Clone this repository and run `make` command to get the documentation in PDF and HTMl formats.
-At least `make4ht` version 0.2 is necessary to compile the HTML version.
+## Requirements
+Full TeX distribution, GNU Make and [Pygments](http://pygments.org/).
+
Modified: trunk/doc/tex4ht-doc/build.mk4
===================================================================
--- trunk/doc/tex4ht-doc/build.mk4 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/build.mk4 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,81 +1,21 @@
-local domobject = require "luaxml-domobject"
+-- local domobject = require "luaxml-domobject"
+
local filter = require "make4ht-filter"
+local domfilter = require "make4ht-domfilter"
--- return toc element type and it's id
-local function get_id(el)
- local name = el:get_attribute "class"
- local a = el:query_selector "a" or {}
- local first = a[1]
- local href = first:get_attribute "href"
- local id = href:match("#(.+)$")
- return name, id
-end
+-- this probably isn't necessary anymore, as we replaced listings with minted
+local fix_code_blocks = require "filters.fix_code_blocks"
+-- Keep only top section levels from other than current chapter
+local toc_sections = require "filters.collapse_toc"
+-- clean CSS file from duplicate colors
+local join_colors = require "filters.join_colors"
-local function remove_sections(part_elements, currentpart)
- -- we need to remove toc entries from the previous part if the
- -- current document isn't part of it
- if currentpart == false then
- for _, part in ipairs(part_elements) do
- part:remove_node()
- end
- end
-end
+filter_settings "collapsetoc" {
+ toc_query = "nav.TOC"
+}
+-- local process = domfilter{toc_sections, fix_code_blocks, join_colors}
+local process = domfilter{"collapsetoc", fix_code_blocks, join_colors}
-
-
-local process = filter{ function(s)
- local dom = domobject.parse(s)
- -- search sectioning elements
- local titles = dom:query_selector(".partHead a, .chapterHead a, .sectionHead a")
- local section_ids = {}
- for _, x in ipairs(titles) do
- -- get their id attributes and save them in a table
- section_ids[#section_ids+1] = x:get_attribute("id")
- end
- -- we need to retrieve the first table of contents
- local toctables = dom:query_selector(".tableofcontents") or {}
- -- process only when we got a TOC
- if #toctables > 0 then
- local tableofcontents = toctables[1]
- -- all toc entries are in span elements
- local toc = tableofcontents:query_selector("span")
- local currentpart = false
- local part_elements = {}
- for _, el in ipairs(toc) do
- -- get sectioning level and id of the current TOC entry
- local name, id = get_id(el)
- -- change span to div
- el._name = "div"
- if name == "partToc" then
- remove_sections(part_elements,currentpart)
- -- resert toc list
- currentpart = false
- part_elements = {}
- else
- -- add child elements of part to table
- part_elements[#part_elements+1] = el
- end
- for _, sectid in ipairs(section_ids) do
- -- detect if the current TOC entry match some sectioning element in the current document
- if id == sectid then
- currentpart = true
- print("match", id)
- end
- end
- end
- -- remove sections from the last part
- remove_sections(part_elements,currentpart)
- -- remove unneeded br elements
- local br = tableofcontents:query_selector("br")
- for _, el in ipairs(br) do el:remove_node() end
- -- remove unneded whitespace
- for _, el in ipairs(tableofcontents:get_children()) do
- if el:is_text() then el:remove_node() end
- end
- end
- return dom:serialize()
-end }
-
-- it removed the whole TOC. What is the issue?
--- Make:match("html$", process)
+Make:match("html$", process)
Modified: trunk/doc/tex4ht-doc/config.cfg
===================================================================
--- trunk/doc/tex4ht-doc/config.cfg 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/config.cfg 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,10 +1,57 @@
\Preamble{xhtml,html5,mathml,2,sec-filename,info,fn-in,fonts}
-\special{t4ht+ at File: style.css}
-\Configure{@HEAD}{\HCode{<link rel="stylesheet" type="text/css" href="style.css" />}}
+
+% Logical elements
+\NewLogicalBlock{codesample}
+\SetTag{codesample}{figure}
+\SetBlockProperty{codesample}{role}{doc-example}% set dPub property
+
+\NewLogicalBlock{acknowledgements}
+\SetTag{acknowledgements}{section}
+\SetBlockProperty{acknowledgements}{role}{doc-acknowledgements}
+
+\NewLogicalBlock{warning}
+\SetTag{warning}{section}
+\SetBlockProperty{warning}{role}{doc-notice}
+
+% external stylesheet
+\Configure{AddCss}{style.css}
+
+% Declare graphics extensions
+\DeclareGraphicsExtensions{.svg,.png,.jpg}
+
+% Mini TOC
+\Configure{crosslinks+}{%
+ \bgroup
+ % container for the page toc
+ \Configure{tableofcontents}{\IgnorePar\EndP\HCode{<nav class="TOC">}\IgnorePar}
+ {\HCode{\Hnewline}}{\IgnorePar\HCode{</nav>\Hnewline}\ShowPar}{}{}%
+ \TableOfContents[chapter,section,subsection]% Print table of contents before crosslinks
+ \egroup
+ \ifvmode\IgnorePar\fi\EndP%
+ \HCode{<main class="main-content">\Hnewline<nav class="crosslinks-top">} }
+ {\HCode{</nav>\Hnewline}}
+{\ifvmode\IgnorePar\fi\EndP%
+ \HCode{<nav class="crosslinks-bottom">}}{\HCode{</nav>}}{}{}
+
+% configuration for TOC on the main page
+\Configure{tableofcontents}{\IgnorePar\EndP\HCode{<nav class="TOC">}\IgnorePar}
+{}{\IgnorePar\HCode{</nav>\Hnewline<main class="main-content">\Hnewline}\ShowPar}{}{}%
+
+% close the <main> element started in \Configure{crosslinks+}
+\Configure{@/BODY}{\ifvmode\IgnorePar\fi\EndP\HCode{</main>}}
+
+% show only crosslinks to prev, main and next pages
+\Configure{crosslinks*}{prev}{up}{next}{}
+
+
\Configure{texttt}{\HCode{<code>}\NoFonts}{\EndNoFonts\HCode{</code>}}
-\ConfigureEnv{texsource}{\ifvmode\IgnorePar\fi\EndP\HCode{<figure class="texsource">}}{\ifvmode\IgnorePar\fi\EndP\HCode{</figure>}}{}{}
-\ConfigureEnv{shellcommand}{\ifvmode\IgnorePar\fi\EndP\HCode{<figure>}}{\ifvmode\IgnorePar\fi\EndP\HCode{</figure>}}{}{}
-\ConfigureEnv{htmlsource}{\ifvmode\IgnorePar\fi\EndP\HCode{<figure>}}{\ifvmode\IgnorePar\fi\EndP\HCode{</figure>}}{}{}
+\Configure{verb}{\HCode{<code>}\NoFonts}{\EndNoFonts\HCode{</code>}}
+\ConfigureEnv{texsource}{\BlockElementStart{codesample}{class="texsource"}}{\BlockElementEnd{codesample}{}}{}{}
+\ConfigureEnv{shellcommand}{\BlockElementStart{codesample}{class="shellcommand"}}{\BlockElementEnd{codesample}{}}{}{}
+\ConfigureEnv{htmlsource}{\BlockElementStart{codesample}{class="htmlsource"}}{\BlockElementEnd{codesample}{}}{}{}
+\ConfigureEnv{acknowledgements}{\BlockElementStart{acknowledgements}{}}{\BlockElementEnd{acknowledgements}{}}{}{}
+\ConfigureEnv{warning}{\BlockElementStart{warning}{}}{\BlockElementEnd{warning}{}}{}{}
+
\begin{document}
\EndPreamble
Modified: trunk/doc/tex4ht-doc/sections/tex4ht-commands.tex
===================================================================
--- trunk/doc/tex4ht-doc/sections/tex4ht-commands.tex 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/sections/tex4ht-commands.tex 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,3 +1,39 @@
+\subsection{Low-level \texfourht\ Commands}
+
+\texcommand{\HCode}
+
+This command allows only for the expansion of macros, before sending its content to the output. The instruction \texcommand{\Hnewline} may be introduced there for requesting line breaks, and the command \texcommand{\#} may be used for the sharp symbol ‘\#’.
+
+\begin{texsource}
+ Two lines of text \HCode{<br />}
+ separated by a horizontal line.
+
+ You probably don't want a '<br>'.
+\end{texsource}
+
+\texcommand{\Tg}
+
+\subsection{Hyperlinks}
+\texcommand{\Link[target-file arguments]{target-loc}{cur-loc}anchor\EndLink}
+
+This command requests an anchor that links to \verb|‘target-file#target-loc’|, and marks the current location with the name \texttt{‘cur-loc’}.
+
+The component \texttt{‘[...]’} is optional when it is empty, and the target file need not be mentioned if it is created from the current source file.
+
+
+\texcommand{\LinkCommand}
+
+
+\subsection{Paragraph Handling}
+
+% https://tex.stackexchange.com/a/66172/2891
+
+\texcommand{\Configure{HtmlPar}}
+\texcommand{\IgnorePar}
+\texcommand{\EndP}
+etc.
+
+\subsection{Logical Document Structure Commands}
I've created some alternative commands to \texcommand{\HCode} or \texcommand{\Tg}. The idea is to define
semantic names for logical elements of the document, such as titles, authors,
sections etc. It is possible to assign HTML elements and attributes to these
@@ -25,8 +61,6 @@
\Configure{maketitle}{%
{\Configure{maketitle}{}{}{}{}%
-
-
\Tag{TITLE+}{\@title}}
\BlockElementStart{maketitle}{}}
{\BlockElementEnd{maketitle}}
@@ -38,8 +72,19 @@
The \texcommand{\NewLogicalBlock} creates a new logical element. The used tag is configured
using \texcommand{\SetTag}, the attributes are set using \texcommand{\SetBlockProperty}. The blocks are
-inserted to the document using \texcommand{\InlineElementStart} ... \texcommand{\InlineElementEnd} or
-\texcommand{\BlockElementStart} ... \texcommand{\BlockElementEnd} pairs. The start commands take two
+inserted to the document using
+
+\begin{texsource}
+\InlineElementStart ... \InlineElementEnd
+\end{texsource}
+
+\noindent or
+
+\begin{texsource}
+\BlockElementStart ... \BlockElementEnd
+\end{texsource}
+
+\noindent pairs. The start commands take two
parameters, first is the logical block name, the second can be local
parameters which shouldn't be used for the given logical block globally.
Modified: trunk/doc/tex4ht-doc/style.css
===================================================================
--- trunk/doc/tex4ht-doc/style.css 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/style.css 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,5 +1,127 @@
-body{max-width:50rem;margin:0 auto;}
+/*
+Color scheme
+#bab5a9;
+#d5e3c6
+
+ */
+
+/* ************** */
+/* *** Fonts *** */
+/* ************** */
+
+/* Font size tricks from https://www.madebymike.com.au/writing/precise-control-responsive-typography/
+ * The font size will be adjusted to the screen size.
+ * */
+:root{
+ font-size: 16px;
+}
+
+/* the min width is calculated as:
+ * font-size / ( number of viewport units / 100 )
+ * it means 16 / (1.5/100)
+ */
+ at media (min-width: 1200px){
+ :root {
+ font-size: 1.5vw;
+ }
+}
+
+/* Maximal font size should be 24px, so stop font scalling at some point (24 / (1.5/100)) */
+
+ at media (min-width: 1500px){
+ :root {
+ font-size: 20px;
+ }
+}
+
+/* ************** */
+/* *** Layout *** */
+/* ************** */
+
+body{
+ /* max-width:52rem; */
+ margin:0;
+ padding:0;
+ /* display:grid; */
+ /* grid-auto-rows: auto; */
+}
+
+ at media screen and (min-width: 57rem) {
+ body{
+ display:grid;
+ grid-template-columns: 15rem 1fr;
+ }
+ main.main-content{max-width:40rem;}
+ nav.TOC{
+ grid-row:1;
+ min-height:100vh;
+ }
+}
+
+
+/* ****************** */
+/* *** Formatting *** */
+/* ****************** */
+
+main.main-content{
+ padding:1rem;
+}
+
p.indent, p.noindent{text-indent:0}
-code{font-size:1.4em;}
-figure pre.listings{font-size: 1.4em;}
+/* code{font-size:1.4rem;} */
+/* figure pre.listings{font-size: 1.4rem;} */
+figure.texsource, figure.shellcommand, figure.htmlsource{
+ margin:0.5rem;
+ padding-left:0.5rem;
+ overflow:auto;
+}
+figure pre.listings{font-size: 1em;}
+.chapterToc, .sectionToc, .subsectionToc{margin:0;padding:0;}
+nav.TOC{
+ padding:0.5rem;
+ font-size:0; /* trick to remove vertical space above TOC entries */
+}
+
+ .chapterToc ~ .likesectionToc, .chapterToc ~ .sectionToc, .likechapterToc ~ .likesectionToc, .likechapterToc ~ .sectionToc {padding-left:2em;margin-left:0}
+ .chapterToc ~ .likesectionToc ~ .likesubsectionToc, .chapterToc ~ .likesectionToc ~ .subsectionToc, .chapterToc ~ .sectionToc ~ .likesubsectionToc, .chapterToc ~ .sectionToc ~ .subsectionToc, .likechapterToc ~ .likesectionToc ~ .likesubsectionToc, .likechapterToc ~ .likesectionToc ~ .subsectionToc, .likechapterToc ~ .sectionToc ~ .likesubsectionToc, .likechapterToc ~ .sectionToc ~ .subsectionToc {padding-left:4em;margin-left:0;}
+
+nav.TOC span{
+ display:block;
+ margin-top:0;
+ font-size:0.8rem;
+}
+
+nav.TOC a, nav.TOC a:visited{
+ text-decoration:none;
+}
+
+/* ************** */
+/* *** Colors *** */
+/* ************** */
+
+
+/* body{background-color:#dce8d0;} */
+/* It seems that dark background is better to my eyes */
+body{background-color:#B8CDA3;}
+
+main.main-content{
+ background-color:white;
+}
+
+nav.TOC,nav.TOC a, nav.TOC a:visited{
+ background-color:#22211f;
+ color:#cec1aa;
+}
+
+nav.TOC span:hover, nav.TOC span:hover *{
+ background-color:#66635d;
+}
+
+
+
+figure.texsource, figure.shellcommand, figure.htmlsource{
+ border:1px solid #cec1aa;
+ background-color:#d5e3c6;
+}
+
Modified: trunk/doc/tex4ht-doc/tex4ht-doc.tex
===================================================================
--- trunk/doc/tex4ht-doc/tex4ht-doc.tex 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/tex4ht-doc.tex 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,8 +1,18 @@
\documentclass{book}
\usepackage{url}
\usepackage{xcolor}
+\usepackage{array}
+\usepackage{graphicx}
+
+% \usepackage[T1]{fontenc}
+\usepackage{upquote}
+\usepackage{textcomp}
+\usepackage{hyperref}
+\usepackage{csquotes}
\usepackage{tex4ht-styles}
+
+
\usepackage{glossaries}
\title{TeX4ht Documentation}
@@ -12,26 +22,158 @@
\maketitle
-\tableofcontents
+% Don't introduce table of contents in the HTML mode, as it introduces another page
+\ifdefined\HCode\else\tableofcontents\fi
+
\chapter{Introduction}
-\chapter{Basic tutorial}
-\chapter{Basic usage}
-\section{Calling commands}
-\section{Output Formats}
-\section{Command Line Options}
+\begin{acknowledgements}
+This work was supported with a financial support from \href{https://cstug.cz/}{CSTUG}.
+\end{acknowledgements}
+\chapter{Basic Tutorial}
+\chapter{Calling Commands}
+\input{sections/calling-commands}
+\label{sec:calling-commands}
+\chapter{Output Formats}
+\chapter{\texfourht\ Options}
+
+\input{sections/tex4ht-options}
+
\chapter{Configurations}
-\section{tex4ht commands}
-\include{sections/tex4ht-commands}
-\section{Configuration files}
+\input{sections/configuration-files}
+\section{tex4ht Commands}
+\input{sections/tex4ht-commands}
\section{Styling the Document}
-\section{Use Webfonts}
+\texfourht\ provides several commands that can be used for changing of the
+document appearance using Cascading Style Sheets (\css). Only basic styling for
+the document is provided by default. Additional styles are added by configurations for the
+fonts, packages and commands used in the document. Full control of the document
+styling can be achieved using following commands and configurations.
+
+
+\texcommand{\Css{content}}
+
+This command sends its content to the CSS file of the document.
+
+\texcommand{\CssFile[list-of-css-files]content\EndCssFile}
+
+The CSS file \texfourht\ used by default initially consists just
+a single line, \texcommand{/* css.sty */}. This line is later
+replaced with the code submitted by the \texcommand{\Css{...}} commands.
+
+The \texcommand{\CssFile} command allows to specify an alternative to the initial CSS file.
+The alternative file consists of the code loaded from listed files, and of the
+content explicitly specified in its body.
+
+\begin{texsource}
+\ConfigureList{mylist}
+{\HCode{<div class="mylist">}} {\HCode{</div>}} {* }{}
+
+\begin{document}
+
+\CssFile
+/* css.sty */
+.mylist { color : red; }
+\EndCssFile
+\end{texsource}
+
+The names in the list of files should be separated by commas, and the rectangular brackets are optional when the list is empty.
+
+The file should include a line having the content of \verb|/* css.sty */|. If
+more than one such line is included, the content of the \texcommand{\Css{...}} commands
+replace the first occurrence of this line. Arbitrary many space characters may
+appear around the substrings ‘/*’ and ‘*/’.
+
+\DocConfigure{AddCss} {CSS file name}\EndDoc
+
+Require external CSS file.
+
+\section{Webfonts}
+\input{sections/webfonts}
\section{Use JavaScript}
\section{Document Navigation}
+
+\subsection{Cross-links}
+
+The following configurations modify behaviour of cross-links between pages in a multi page document.
+
+\DocConfigure{crosslinks} {left-delimiter} {right-delimiter} {next} {prev} {prev-tail} {front} {tail} {up}\EndDoc
+
+This command configures the appearance of the cross-links between hypertext pages obtained for sectioning commands.
+
+\begin{texsource}
+ \Configure{crosslinks}
+ {}{}{$\scriptstyle\Rightarrow$}
+ {$\scriptstyle\Leftarrow$}
+ {}{}{}{$\scriptstyle\Uparrow$}
+\end{texsource}
+
+\DocConfigure{crosslinks*} {1--7 arguments}\EndDoc
+
+ Links to be included and their order. Available
+ options: next, prev, prevtail, tail, front, up.
+ The last argument must be empty.
+
+ Default:
+
+\begin{texsource}
+\Configure{crosslinks*}{next}
+ {prev}{prevtail}
+ {tail}{front}
+ {up}{}
+\end{texsource}
+
+\DocConfigure{crosslinks+} {before-top-links} {after-top-links} {before-bottom-links} {after-bottob-links}\EndDoc
+
+The top cross links are omitted, if both \verb|#1| and \verb|#2| are empty.
+The bottom cross links are omitted, if both \verb|#3| and \verb|#4| are empty.
+
+\DocConfigure{next} {the anchor of the next button of the front page}\EndDoc
+
+Default: The value provided in \texcommand{\Configure{crosslinks}}
+
+\DocConfigure{next+}{before} {after}\EndDoc
+
+\begin{description}
+ \item[\#1] before the next button of the front page, when the `next'
+ option is active.
+ \item[\#2] after the button
+\end{description}
+
+ Default: The values provided in \texcommand{\Configure{crosslinks}}
+
+\begin{texsource}
+\Configure{crosslinks:next}..................1
+\Configure{crosslinks:prev}..................1
+\Configure{crosslinks:prevtail}..............1
+\Configure{crosslinks:tail}..................1
+\Configure{crosslinks:front}.................1
+\Configure{crosslinks:up}....................1
+\end{texsource}
+
+ \verb|#1| local configurations for the delimiters and hooks
+
+\DocConfigure{crosslinks-}{before} {after}\EndDoc
+
+Asks to show linkless buttons with the following insertions.
+
+The default values are used, if both \verb|#1| and \verb|#2| are empty
+
+ Examples:
+
+\begin{texsource}
+\Configure{crosslinks-}{}{}
+
+\Configure{crosslinks-}
+ {\HCode{<span class="hidden">}[}
+ {]\HCode{</span>} }
+\Css{span.hidden {visibility:hidden;}}
+\end{texsource}
+
\section{Tables of Contents}
\section{Sections}
@@ -41,147 +183,219 @@
\section{Fonts}
\subsection{Basic font commands}
-Information about the \option{fonts} option and \term{MathML} issues. Example configuration:
+Information about the \option{fonts} option and \term{MathML} issues.
+Example configuration:
\url{https://tex.stackexchange.com/a/416613/2891}
-\section{Colors}
-\section{Graphics}
-\section{TikZ }
+\section{Multi-lingual support}
-Animations using Animate package: \url{https://tex.stackexchange.com/a/404600/2891}
-\section{Pstricks}
+RTL support in the ODT output: \url{https://tex.stackexchange.com/a/470434/2891}.
-\section{Math}
-\section{MathML}
-\section{MathJax}
+\subsection{Right-to-left text}
-\section{Bibliographies}
-\section{Indexing}
+There is a difference in the RTL support for HTML and ODT output formats. In HTML, RTL can be requested using:
-\chapter{Make4ht Build Files}
-\section{Calling commands}
-\section{Filters}
+\DocConfigure{LRdir} { value for the dir attribute}\EndDoc
-Some samples:
+Example:
-\begin{itemize}
- \item Render math by Mathjax during tex4ht compilation \url{https://tex.stackexchange.com/a/402159/2891}
-\end{itemize}
-\section{Image conversion}
+\begin{texsource}
+\ConfigureEnv{arab}
+{\Configure{LRdir}{ dir="rtl"}}
+{\Configure{LRdir}{}}{}{}
+\end{texsource}
-\chapter{For developers}
+This configuration sets the direction to \term{rtl} inside the \term{arab} environment and resets it after the environment end.
-\section{Writing basic support for a new package}
-\begin{itemize}
- \item \url{https://tex.stackexchange.com/a/402283/2891}
-\end{itemize}
+In the ODT output, different mechanism is used:
-\section{Two types of .4ht files}
+\begin{texsource}
+\ConfigureEnv{arab}{\@rltrue}{\@rlfalse}{}{}
+\end{texsource}
-\subsection{Inserting configurable hooks for packages}
+\subsection{Unicode}
-\subsection{Configure the hooks in output format configuration files}
+Generally speaking, \texfourht\ supports \term{Unicode}, but there are some
+issues to be aware of. Most complete support exists for Lua\LaTeX, thanks to
+special Lua script which is automatically loaded during the compilation. No
+additional packages are necessary.
-\section{How to add support for a package to the \texfourht\ literate sources}
+PDF\LaTeX\ doesn't support nativelly, but it is possible to emulate it using the
+\package{inputenc} and \package{fontenc} packages:
-To add a proper support for a new package, it is necessary to edit the
-\texfourht\ literate sources. The configurable hooks need to be placed in the \file{tex4ht-4ht.tex},
-the configuration of these hooks must be added to the output format configuration files.
-The most common output format is \HTML, which can be configured in \file{tex4ht-html4.tex}, or
-\file{tex4ht-html5.tex} if \HTMLV\ features are used. It is also necessary to update the
-\file{mktex4ht-cnf.tex}.
+\begin{texsource}
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\begin{document}
+Unicode text
+\end{document}
+\end{texsource}
-\subsection{Example}
+Xe\LaTeX\ is an Unicode format, similarly to Lua\LaTeX. The supporting
+mechanism for \texfourht\ is different in this case and full Unicode range is
+not supported out of the box. By default, only most Latin based characters are
+supported. For other scripts, such as Greek or Cyrillic, two ways to enable
+support exists.
-Given following package \file{sample.sty}:
+First option is to define new font family using \package{fontspec} \texcommand{\newfontfamily} with the \texttt{Script} option.
\begin{texsource}
-\ProvidesPackage{sample}
-\newcommand\hello{world}
-\endinput
+\newfontfamily\greekfont{Linux Libertine O}[Script=Greek]
\end{texsource}
-This simple package defines command \texcommand{\hello}, which simply prints the word \textit{hello} when used in a document.
-Let's say that we want to insert some \HTML\ tags before and after the text content printed by the command.
+The second option is to declare load support for a script in the custom config
+file using the \texcommand{\xeuniuseblock}:
-Basic template for \file{tex4ht-4ht.tex}
-% examples/basicpackage/sample.4ht
\begin{texsource}
-\<sample.4ht\><<<
-% sample.4ht (|version), generated from |jobname.tex
-% Copyright 2017 TeX Users Group
-|<TeX4ht license text|>
-\NewConfigure{hello}{2}
-\pend:def\hello{\a:hello}
-\append:def\hello{\b:hello}
-\Hinput{sample}
->>> \AddFile{9}{sample}
+\xeuniuseblock{Greek}
\end{texsource}
-Configuration for each package must follow this basic template. The \ProTeX\ system is used as system for literate programming.
+The block names are based on \href{https://en.wikipedia.org/wiki/Unicode_block}{Unicode blocks}.
-The \texcommand{\<name\><<<code>>>} block defines new macro which can be then called using \texcommand{|<name|>}. The license text
-is included in the example this way. In order to generate the \file{sample.4ht} file, we need to use \texttt{sample.4ht} as a name
-in the code block and command \texcommand{\AddFile{9}{sample}} after the block definition\footnote{I have no idea what the number
-in the first parameter means.}.
+It is also possible to declare all characters in an Unicode range. The command
+\texcommand{\xeuniregisterblockhex} takes two hexadecimal parameters with
+Unicode range to be declared.
-Each package configuration must include \texcommand{\Hinput{packagename}}, in order to load the configurations for the package.
+\begin{texsource}
+\xeuniregisterblockhex{0100}{017F}
+\end{texsource}
-The command \texcommand{\NewConfigure{hello}{2}} declares new configuration \texttt{hello}, with two configurable hooks.
-These hooks are named \texcommand{\a:hello} and \texcommand{\b:hello}. The hooks must be inserted into the
-\texcommand{\hello}, which can be easily done using the \texcommand{\pend:def} and \texcommand{\append:def} commands. These
-commands can insert code at the beginning, respective at the end of the redefined command.
+Individual character can be declared using the \texcommand{\xeuniregisterchar} command:
-The configuration for \HTML\ must be placed in the \file{tex4ht-html4.tex} file:
+\begin{texsource}
+\xeuniregisterchar{"1F00}
+\end{texsource}
+In contrast to \texcommand{\xeuniregisterblockhex}, it uses decimal numbers by
+default, so it is necessary to use the \texttt{"} character in front of
+a hexadecimal number.
-% examples/basicpackage/config.cfg
+\begin{warning}
+It is possible to run into issues because of the way how Xe\LaTeX\ Unicode
+support works. Common problem is filename support, for example in included
+graphics. In general, it is better to avoid such filenames. If it is not possible, try to use the \texcommand{\detokenize} command.
\begin{texsource}
-\<configure html4 sample\><<<
-\Configure{hello}{\HCode{<span class="hello">}}{\HCode{</span>}}
-\Css{.hello{color:red;}}
->>>
+ \includegraphics{\detokenize{háček.jpg}}
\end{texsource}
+\end{warning}
-The configuration for a package must be placed in \texcommand{\<configure html4 packagename\>} block.
-% ToDo: write more info
+\section{Colors}
+Information about the \texcommand{\color} command:
+\url{https://tex.stackexchange.com/a/195677/2891}.
+Example of possible configuration for the \texcommand{\color} command:
+\url{https://tex.stackexchange.com/q/470179/2891}.
-The package name must be also included in \file{mktex4ht-cnf.tex}:
+Example of extracting color information to the CSS and custom color environment support:
+\url{https://tex.stackexchange.com/a/422281/2891}. Extracting of color information to the HTML attributes:
+\url{https://tex.stackexchange.com/a/390151/2891}.
+
+
+\section{Graphics and Pictures}
+
+\input{sections/graphics}
+\section{TikZ }
+
+Animations using Animate package: \url{https://tex.stackexchange.com/a/404600/2891}
+
+Issues with drivers: \url{https://tex.stackexchange.com/a/471460/2891}.
+\section{Pstricks}
+
+\section{Math}
+\subsection{Default math handling}
+\subsection{MathML}
+
+\mathml\ is a XML markup for the math encoding. It is supported in many
+aplications including OpenOffice Writer or Firefox web browser.
+The advantage over use of images % Todo: write about advantages of MathML.
+
+The \mathml\ code produced by \texfourht\ may contain some issues. For example,
+one common issue may happen when the math contain unmatched delimiters:
+
\begin{texsource}
-\AddFile{9}{sample}
+ Mail address: $\lparen$hello at world.com$\rparen$
\end{texsource}
-The \file{.4ht} files can be generated simply using
+In such cases, the \option{matml-} may help.
-\begin{shellcommand}
-make
-\end{shellcommand}
+It is also advisable to always use \extension{common\_domfilters}
+\term{make4ht} extension (see section \ref{sec:make4ht-extensions} for more
+information about \term{make4ht} extensions), as it fixes some common \mathml\
+errors that cannot be easily fixed on the \TeX\ level.
-command.
-The following sample \TeX\ file:
+Add information about the \url{https://github.com/pshihn/math-ml} - it adds
+support for MathML in all modern web browsers with HTML 5.
-% examples/basicpackage/hello.tex
+\subsection{MathJax}
+
+The \term{MathJax} processing can be required using \option{mathjax} option.
+The address of \term{MathJax} script with its configuration string can be
+specified in \configuration{MathjaxSource}. The default value of this configuration is:
+
\begin{texsource}
-\documentclass{article}
-\usepackage{sample}
-\begin{document}
- \hello\ world.
-\end{document}
+\Configure{MathjaxSource}
+{https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/%
+latest.js?config=TeX-AMS-MML_HTMLorMML}
\end{texsource}
-Produces a following \HTML\ code:
+By default, inline and display math, as well as math environments, are kept as
+raw LaTeX code in the \HTML\ output. \term{MathJax} then transforms this code
+and displays it. In the \term{MathML} mode, \term{MathJax} is used only for the
+rendering in browsers without \term{MathML} support.
-\begin{htmlsource}
-<!--l. 4--><p class="noindent" >
-<span class="hello">world</span> world.
-</p>
-\end{htmlsource}
+The additional configuration for \term{MathJax} can be provided in special
+script environment in the \HTML\ page header. The following example provides
+support for some custom \LaTeX\ macros.
+
+\begin{texsource}
+\Configure{@HEAD}{\HCode{\detokenize{%
+<script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ TeX: {
+ Macros: {
+ sc : "\\small\\rm",
+ sl: "\\it",
+ }
+ },
+ }
+ );
+</script>
+}}}
+\end{texsource}
+
+The \texcommand{\detokenize} macro is used to avoid issues with backslash
+characters used in the macro definitions. Backslashes must be doubled in the
+JavaScript strings.
+
+
+\section{Bibliographies}
+\section{Indexing}
+
+\section{OpenDocument Format}
+\input{sections/odt}
+
+\chapter{Make4ht Build Files}
+\section{Commands execution}
+\section{Filters}
+
+Some samples:
+
+\begin{itemize}
+ \item Render math by Mathjax during tex4ht compilation \url{https://tex.stackexchange.com/a/402159/2891}
+\end{itemize}
+\section{Image conversion}
+
+\chapter{FAQ}
+\input{sections/faq}
+\chapter{For developers}
+\input{sections/tex4ht-development}
+
\chapter{Glossary}
\chapter{Bibliography}
\chapter{Index}
Modified: trunk/doc/tex4ht-doc/tex4ht-styles.sty
===================================================================
--- trunk/doc/tex4ht-doc/tex4ht-styles.sty 2020-05-05 19:50:14 UTC (rev 687)
+++ trunk/doc/tex4ht-doc/tex4ht-styles.sty 2020-05-05 19:54:36 UTC (rev 688)
@@ -1,28 +1,54 @@
\ProvidesPackage{tex4ht-styles}
-\RequirePackage{listings}
+\RequirePackage{minted}
+
+\usemintedstyle{lovelace}
\RequirePackage{xparse}
-% shortcuts
-\newcommand\texfourht{\texttt{tex4ht}}
-\newcommand\HTML{\texttt{HTML}}
-\newcommand\HTMLV{\texttt{HTML5}}
-\newcommand\ProTeX{\texttt{ProTeX}}
-
-
% formatting commands
\newcommand\file[1]{\texttt{#1}}
\newcommand\option[1]{\emph{#1}}
\newcommand\term[1]{\emph{#1}}
+\newcommand\configuration[1]{\texttt{#1}}
+\newcommand\package[1]{\texttt{#1}}
+\newcommand\extension[1]{\texttt{#1}}
% this trick will enable us to take verbatim arguments
% https://tex.stackexchange.com/a/45292/2891
\NewDocumentCommand\texcommand{v}{\texttt{#1}}
+\NewDocumentCommand\shellcmd{v}{\texttt{#1}}
-\lstnewenvironment{texsource}{\lstset{language=TeX,escapechar=*}}{}
-\lstnewenvironment{htmlsource}{\lstset{language=HTML,escapechar=*}}{}
-\lstnewenvironment{shellcommand}{\lstset{language=bash}}{}
-\newcommand\texinput[1]{\lstinputlisting[language=TeX]{#1}}
+\newenvironment{warning}{\bigskip\noindent\textbf{Warning:}}{\bigskip}
+\newenvironment{acknowledgements}{\section{Acknowledgements}}{}
+\newenvironment{issue}[1]{\bigskip\noindent\textbf{#1}}{\bigskip}
+% shortcuts
+\newcommand\texfourht{\texttt{tex4ht}}
+\newcommand\fourhtsty{\file{tex4ht.sty}}
+\newcommand\fourhtfile{\file{.4ht}}
+\newcommand\cfgfile{\term{custom configuration file}}
+\newcommand\HTML{\texttt{HTML}}
+\newcommand\HTMLV{\texttt{HTML5}}
+\newcommand\ProTeX{\texttt{ProTeX}}
+\newcommand\css{\texttt{CSS}}
+\newcommand\xml{\texttt{XML}}
+\newcommand\mathml{\texttt{MathML}}
+\newcommand\svg{\texttt{SVG}}
+\let\latex\LaTeX
+
+% this was used by CVR in the options page
+\let\chfont\texttt
+
+
+
+\newminted[texsource]{latex}{}
+\newminted[htmlsource]{html}{}
+\newminted[shellcommand]{shell}{}
+\newmintedfile[texinput]{latex}{}
+
+% Document \Configure commands. They have variable number of arguments, so it is necessary to process them as a list
+\def\PrintConfigures#1#2\@nil{\{#1\}\allowbreak\ifx\relax#2\relax\else\expandafter\PrintConfigures#2\@nil\fi}
+\def\DocConfigure#1#2\EndDoc{\par\bigskip\noindent\texttt{\textbf{\textbackslash Configure}\{\textit{#1}\}\PrintConfigures#2{}\@nil}}
+
\endinput
More information about the tex4ht-commits
mailing list.