All of lore.kernel.org
 help / color / mirror / Atom feed
* [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
@ 2026-11-15 21:01 Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 1/7] reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds Ferenc Fejes
                   ` (7 more replies)
  0 siblings, 8 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Hi!

This RFC series adds experimental reflowable EPUB3 and HTML build targets
("make epub", "make epub-endnotes", and "make html") derived from the
ebook-size variant via TeX Live's lwarp package and Pandoc, without
modifying any of the book's existing .tex or .sty files.

Overview of the pipeline:

- reflow.ltx hooks into the generated perfbook-epub.tex wrapper to adapt
  print-oriented macros, listings, tables, figures, equations, footnotes,
  Quick Quizzes, and cross-references for HTML/EPUB output.
- Makefile stages SVG figures in parallel under epub-figs/ and invokes
  utilities/runlwarp.sh to run lwarp, render math SVGs via lwarpmk,
  package the chapter-split EPUB3 with Pandoc, and run structural
  validation checks (plus epubcheck when installed).
- utilities/epub-fixhtml.pl and utilities/epub.css perform post-Pandoc
  XHTML/SVG/CSS adjustments tested in KOReader and Foliate, including
  EPUB3 popup footnotes and Quick Quiz answers (and a plain endnote
  variant in perfbook-endnotes.epub for readers without popup support).

This is an RFC so I would be happy to hear ideas how I can improve this
experiment. Few things:

1. Does this non-invasive lwarp + Pandoc approach look acceptable for
   maintaining experimental EPUB support alongside the PDF builds?
2. Is it worth keeping both perfbook.epub (popup footnotes/quizzes) and
   perfbook-endnotes.epub (linked chapter endnotes), or would a single
   target be preferable?
3. Are the Dockerfile package additions and non-blocking GitLab CI job
   (allow_failure: true) aligned with how you would like this tested?

AI: This RFC generated by language models and I verified the result on
my physical epub reader and on Linux in Foliate and KOReader epub
readers. I used several models and refined the set for months, and with
the latest and greatest frontier I was unable to trim ot further. The downside
of this work is that I cannot tell with full confidence this is the
simplest form. With more knowledge it might be improved further.

I tried three approach to get to a working epub target:
- tex4ht: it required heavy modifications of the already existing LaTeX
  source so I abandoned this approach. After aroung 2k LoC change it was
  able to produce a reasonable HTML and ePUB, but it was too intrusive
  for my taste
- lwrap (this one): this felt the best and required the least change
  compared to the upstream. It hooks into the build flow in the right
  spot so no changes required in the upstream LaTeX code
- LateXML: this is what arXiv uses to compile the paper sources to HTML
  and they improve it in quite a fast pace. This target was intrusive
  and a reasonable looking output required many small changes in the
  upstream source and what worse, in the LateXML toolchain. I abandoned
  this approach as well
These trials executed 2-3 months ago, and lwrap was the winner, but
models might improved since making LateXML feasible. In the past months
I only improved the lwrap based approach, resulting this RFC.

Thanks,
Ferenc

Ferenc Fejes (7):
  reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds
  utilities: Add EPUB3 post-processor and stylesheet
  utilities/runlwarp.sh: Add lwarp and Pandoc build driver
  Makefile, .gitignore: Add epub and html build targets
  epub: Add endnote variant for readers without popup footnotes
  FAQ-BUILD.txt: Document HTML and EPUB build targets
  docker, gitlab-ci: Add EPUB build dependencies and CI job

 .gitignore                |  14 ++
 FAQ-BUILD.txt             |  45 ++++++
 Makefile                  |  68 ++++++++-
 docker/Dockerfile         |   2 +-
 reflow.ltx                | 255 ++++++++++++++++++++++++++++++++
 utilities/epub-fixhtml.pl |  93 ++++++++++++
 utilities/epub.css        |  63 ++++++++
 utilities/gitlab-ci.yml   |  17 +++
 utilities/runlwarp.sh     | 299 ++++++++++++++++++++++++++++++++++++++
 9 files changed, 852 insertions(+), 4 deletions(-)
 create mode 100644 reflow.ltx
 create mode 100755 utilities/epub-fixhtml.pl
 create mode 100644 utilities/epub.css
 create mode 100644 utilities/runlwarp.sh


base-commit: 94d572e236ab8e26fa79ff0776a3bba221647315
--
2.55.0


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [RFC PATCH 1/7] reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 2/7] utilities: Add EPUB3 post-processor and stylesheet Ferenc Fejes
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Add reflow.ltx to configure lwarp via LaTeX2e package hooks and adapt
print-oriented macros for reflowable HTML and EPUB output without
modifying existing .tex or .sty files.  It normalizes HTML containers
and anchor IDs for Pandoc, scales figures proportionally, unwraps table
and listing boxes, emits HTML equation numbers, and drops page-number
phrases from cross-references.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 reflow.ltx | 255 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 reflow.ltx

diff --git a/reflow.ltx b/reflow.ltx
new file mode 100644
index 00000000..022d4801
--- /dev/null
+++ b/reflow.ltx
@@ -0,0 +1,255 @@
+% SPDX-License-Identifier: GPL-2.0-or-later
+%
+% reflow.ltx -- HTML-mode shims for the lwarp reflowable (EPUB) build.
+% Input before \documentclass by perfbook-epub.tex; print builds never
+% load this file.
+%
+% Copyright (C) Ferenc Fejes, 2026
+%
+% Authors: Ferenc Fejes <ferenc@fejes.dev>
+
+\makeatletter
+\@ifpackageloaded{lwarp}{}{%
+  \AddToHook{package/fontenc/after}{%
+    \usepackage{fontaxes}%
+    \usepackage[HTMLFilename=perfbook-epub-]{lwarp}%
+    \ifbool{warpingHTML}{}{%
+      \LWR@writeconf{lwarpmk.conf}\LWR@writeconf{\jobname.lwarpmkconf}\stop}%
+    \setcounter{FileDepth}{0}%
+    \boolfalse{FileSectionNames}%
+    \booltrue{FormatEPUB}%
+    \HTMLAuthor{Paul E. McKenney}%
+    \HTMLLanguage{en-US}%
+    \RenewDocumentCommand{\usepackage}{o m o}{%
+      \IfValueT{#1}{\PassOptionsToPackage{#1}{#2}\PassOptionsToPackage{#1}{lwarp-#2}}%
+      \IfValueTF{#3}{\RequirePackage{#2}[#3]}{\RequirePackage{#2}}}%
+    \providecommand{\SetWatermarkVerCenter}[1]{}%
+    \providecommand{\bottomtitlespace}{0pt}%
+    \let\LWR@saved@l@section\l@section
+    \let\LWR@saved@l@subsection\l@subsection}%
+  \AddToHook{package/lwarp-subfig/after}{\let\@newsubfloat\LWR@orig@newsubfloat}%
+  \AddToHook{package/lwarp-enumitem/after}{%
+    \let\enit@style@unboxed\enit@style@standard
+    \let\enit@style@sameline\enit@style@standard
+    \let\enit@style@multiline\enit@style@standard
+    \let\enit@style@nextline\enit@style@standard}%
+  \AddToHook{package/booktabs/after}{\setboolean{usecleveref}{true}}%
+  \AddToHook{package/lwarp-fancyhdr/before}{\let\headrule\relax\let\footrule\relax}%
+  \AddToHook{file/glsdict.tex/after}{\input{reflow.ltx}}%
+  \makeatother\endinput}
+
+% Restore lwarp's TOC entries (overwritten by perfbook-lt.tex's \@dottedtocline)
+% and suppress hyphenation tables in HTML mode.
+\let\l@section\LWR@saved@l@section
+\let\l@subsection\LWR@saved@l@subsection
+\renewcommand{\hyphenation}[1]{}
+
+% Emit <div> instead of <main>, <section>, <nav> so Pandoc (-f html-native_divs)
+% unwraps lwarp's structural containers and splits chapters directly; drop
+% invalid EPUB3 attributes (role="note", role="math", target="_blank"); and
+% emit local #id hrefs so Pandoc resolves cross-file links to chNNN.xhtml.
+\RenewDocumentCommand{\LWR@htmlelementclass}{m o D(){} m}{%
+  \LWR@stoppars\LWR@subhtmlelementclass{div}[#2]{#4}\LWR@startpars}
+\renewcommand*{\LWR@htmlelementclassend}[2]{\LWR@stoppars\LWR@htmltag{/div}\LWR@startpars}
+\renewcommand*{\LWR@htmlrefsectionfilename}[1]{}
+\patchcmd{\LWR@subinlineimage}{\ifblank{#6}}{\ifblank{}}{}{}
+\expandafter\patchcmd\csname LWR@subhyperref code\endcsname
+  {target=\textquotedbl\_{}blank\textquotedbl\ }{}{}{}
+
+% Sanitize XML NCName characters in HTML IDs/hrefs (preserving "??" so the build
+% can detect unresolved references).
+\ExplSyntaxOn
+\cs_new_protected:Npn \pfb@cleanid #1 {
+  \str_if_eq:VnF #1 { ?? } {
+    \str_replace_all:Nnn #1 { ~ } { - }
+    \str_map_inline:nn { ?;()!/+=@`' } { \str_replace_all:Nnn #1 {##1} { - } }
+  }
+}
+\ExplSyntaxOff
+\apptocmd{\LWR@sanitize}{\pfb@cleanid\LWR@sanitized}{}{}
+
+% Drop \hbox wrappers around inline code so lwarp's inline listing tag survives,
+% and allow unescaped $ inside \lstinline (\co/\nbco/\qco).
+\AddToHook{file/ushyphex.tex/before}{%
+  \renewcommand{\nbco}[1]{\lstinline[breaklines=false,breakatwhitespace=false]{#1}}%
+  \renewcommand{\qtco}[1]{``\tco{#1}''}}
+
+\AtBeginDocument{%
+  \renewcommand{\printindex}[1][]{}%
+  \def\lst@InlineG{\lst@Init\relax\let\lst@arg\@empty\lst@InlineGJ}%
+  \patchcmd{\lst@Init}{span class=\textquotedbl{}inlineprogramlisting\textquotedbl}{code}{}{}%
+  \let\lst@DeInit\LWR@origlst@DeInit
+  \patchcmd{\lst@DeInit}{\lst@EOLUpdate}{\lst@EOLUpdate
+    \lst@ifdisplaystyle\let\lsthk@EveryPar\relax\LWR@afterendverbatim\let\lsthk@EveryPar\LWR@origlsthkEveryPar
+    \else\ifbool{LWR@verbtags}{\noindent\LWR@htmltag{/code}}{}\fi}{}{}%
+  \RenewDocumentCommand{\LWR@HTML@resizebox}{s m m}{\pfb@setigpct{#2}}%
+  \renewcommand{\epsfbox}[1]{\resizebox{\epsfxsize}{!}{\includegraphics{#1}}}%
+  \define@key{igraph}{scale}{\ifdefempty{\pfb@igwidthstyle}{\pfb@setigpct{#1\twocolumnwidth}}{}}%
+  \renewenvironment{sidewaystable*}[1][]{\begin{table*}[#1]}{\end{table*}}%
+  \let\pfb@lstcap\lst@MakeCaption
+  \renewcommand*\lst@MakeCaption[1]{%
+    \lst@ifdisplaystyle\pfb@lstcap{#1}\else\caption@ORI@lst@MakeCaption{#1}\fi}%
+  \renewcommand{\epigraph}[2]{%
+    \LWR@stoppars\LWR@htmltag{figure class=\textquotedbl{}epigraph\textquotedbl}\LWR@startpars
+    \emph{#1}\par\LWR@htmlelement{figcaption}#2\LWR@htmlelementend{figcaption}%
+    \LWR@stoppars\LWR@htmltag{/figure}\LWR@startpars}%
+  \NoIndentAfterCmd{\epigraph}%
+  \let\pfb@label\label@noarg
+  \def\label@noarg#1{\LWR@clean@arg{#1}\pfb@label{\LWR@on@arg}}}
+
+% Bibliography: avoid math in alphapf.bst labels, link citations to entries,
+% and format thebibliography as a <dl> description list.
+\AtBeginEnvironment{thebibliography}{%
+  \@ifundefined{etalchar}{}{\renewcommand{\etalchar}[1]{\textsuperscript{#1}}}%
+  \LWR@descriptionstart
+  \renewcommand{\@biblabel}[1]{[#1]}}
+\patchcmd{\@lbibitem}{\ignorespaces}{\hypertarget{cite.#2}{}\ignorespaces}{}{}
+\def\@cite@ofmt#1{%
+  \ifnumcomp{\value{LWR@linkdepth}}{>}{0}{#1}{%
+    \edef\pfb@citelink{\noexpand\hyperlink{cite.\@citeb}}\pfb@citelink{#1}}}
+
+% Scale figures proportionally to their LaTeX \resizebox/\includegraphics target
+% width (relative to \onecolumntextwidth = 4.1in, clamped to [35%, 85%]), and
+% unlink images and \path{} so they do not point to files outside the EPUB.
+\def\pfb@igwidthstyle{}
+\def\pfb@setigpct#1{%
+  \begingroup
+    \setlength{\dimen@}{#1}%
+    \count@=\numexpr\dimen@*100/\onecolumntextwidth\relax
+    \ifnum\count@>85 \count@=85 \fi
+    \ifnum\count@<35 \count@=35 \fi
+    \xdef\pfb@igwidthstyle{width:\the\count@\@percentchar}%
+  \endgroup}
+\AtBeginEnvironment{tabular}{%
+  \gdef\pfb@igwidthstyle{}%
+  \ifdef{\lockfml}{\renewcommand{\lockfml}[1]{\begin{picture}(6,8)(0,0)\rotatebox{90}{#1}\end{picture}}}{}}
+\AtBeginEnvironment{lateximage}{\boolfalse{LWR@in@multirow@par}}
+\AtBeginEnvironment{figure}{%
+  \patchcmd{\LWR@lateximage@oneimageb}{{lateximage}}{{inlineimage}}{}{}%
+  \patchcmd{\LWR@lateximage@oneimageb}{{#3}}{{width:60\@percentchar}}{}{}}
+\pretocmd{\LWR@ig@htmltag}{%
+  \ifdefempty{\pfb@igwidthstyle}%
+    {\def\LWR@igwidthstyle{width:75\@percentchar}}%
+    {\let\LWR@igwidthstyle\pfb@igwidthstyle\gdef\pfb@igwidthstyle{}}}{}{}
+\expandafter\patchcmd\csname LWR@includegraphicsb code\endcsname
+  {\LWR@href@partsanitized{\LWR@parsedfilename}}{\@firstofone}{}{}
+\LetLtxMacro\LWR@HTML@path\nolinkurl
+\LWR@formatted{path}
+
+% Numbered display math: keep the equation number out of the SVG (lwarp bakes
+% it into a full-width minipage image) and emit it as HTML text instead.
+\AtBeginEnvironment{lateximage}{\let\tagform@\@gobble}
+\AfterEndEnvironment{lateximage}{%
+  \ifboolexpr{bool{LWR@indisplaymathimage} and test{\ifnumequal{\value{LWR@lateximagedepth}}{0}}
+      and not test{\ifnumless{\value{equation}}{\value{LWR@startingequation}}}}{%
+    \InlineClass{eqnum}{(\ifnumequal{\value{equation}}{\value{LWR@startingequation}}%
+      {\theequation}{\thechapter.\arabic{LWR@startingequation}--\theequation})}}{}}
+
+% Head appendices "Appendix" instead of "Chapter".
+\renewcommand*{\LWR@printchaptername}{\@chapapp~}
+
+% Unwrap table scaling/framing macros so tabular & tokens are read in place,
+% emit <span class="figurecaption"> inside <figcaption> so Pandoc keeps
+% <figcaption>, and preserve \cellcolor via data-bg.
+\renewcommand{\tcresizewidth}{}
+\renewcommand{\ebresizewidth}{}
+\renewcommand{\ebresizewidthsw}{}
+\renewcommand{\ebresizeverb}[1]{}
+\RenewDocumentCommand{\LWR@HTML@framebox}{d() o o}{}
+\renewenvironment*{LWR@figcaption}%
+  {\LWR@stoppars\LWR@htmltagc{figcaption}\LWR@startpars\hbadness=10000\relax}%
+  {\LWR@stoppars\LWR@htmltagc{/figcaption}\LWR@startpars}
+\renewcommand*{\LWR@subaddtabularcellcolor}[1]{%
+  \LWR@htmltag{span class=\textquotedbl{}cellcolor\textquotedbl\ data-bg=\textquotedbl\LWR@origpound#1\textquotedbl}\LWR@htmltag{/span}}
+
+% Support \multirow nested inside \multicolumn and empty multirow-spanned cells.
+\NewCommandCopy\LWR@orig@htmlmulticolumn\LWR@htmlmulticolumn
+\def\LWR@mc@row#1#2#3\multirow\@nil{\LWR@HTML@multicolumnrow{\LWR@mc@n}{\LWR@mc@a}{#1}{#2}{#3}}
+\def\LWR@chkmrow#1\multirow#2\@nil{%
+  \ifblank{#2}{\LWR@orig@htmlmulticolumn{\LWR@mc@n}{\LWR@mc@a}{#1}}{\LWR@mc@row#2\@nil}}
+\RenewDocumentCommand{\LWR@htmlmulticolumn}{m m +m}{%
+  \def\LWR@mc@n{#1}\def\LWR@mc@a{#2}\LWR@chkmrow#3\multirow\@nil}
+\StartDefiningTabulars
+\patchcmd{\LWR@tabledatacolumntag}{\ifdefequal{\LWR@mynexttoken}{\end}}{%
+  \ifboolexpr{bool{LWR@usedmultirow} and bool{LWR@doingcmidrule} and test {\ifdefequal{\LWR@mynexttoken}{&}}}%
+    {\global\let\LWR@mynextaction\mrowcell}{}%
+  \ifdefequal{\LWR@mynexttoken}{\end}}{}{}
+\StopDefiningTabulars
+
+% Wrap <pre> contents in <code> so Pandoc preserves code blocks without
+% parsing inner anchors, defer \lnlbl (<a id="ln:...">) tags to immediately
+% after </pre>, keep fvextra/verbbox line numbers on their own lines, wrap
+% verbbox in <pre>, hang boxed verbatim from top, and prevent \midrule from
+% eating "(1)".
+\def\pfb@lnlbls{}
+\expandafter\patchcmd\csname\string\LWR@atbeginverbatim\endcsname{\par}{\LWR@htmltag{code}\par}{}{}
+\expandafter\patchcmd\csname\string\LWR@atbeginverbatim\endcsname{\begingroup}{\begingroup
+  \renewcommand*{\LWR@label@createtag}[1]{%
+    \LWR@sanitize{##1}\xappto\pfb@lnlbls{\noexpand\LWR@htmltag{a id=\textquotedbl\LWR@sanitized\textquotedbl}\noexpand\LWR@htmltag{/a}}}}{}{}
+\patchcmd{\LWR@afterendverbatim}{\LWR@htmltag{/pre}}{\LWR@htmltag{/code}\LWR@htmltag{/pre}\pfb@lnlbls\gdef\pfb@lnlbls{}}{}{}
+\renewcommand*{\LWR@FV@linethensep}{\hbox to 1em{\hss\theFancyVerbLine}\kern\FV@NumberSep}
+\define@key{FV}{baseline}{}
+\let\FV@baseline\@ne
+\AtBeginDocument{%
+  \renewcommand{\LstLineNo}{\leavevmode\hbox to 1em{\hss\arabic{VerbboxLineNo}}\kern\FV@NumberSep}%
+  \patchcmd{\verbbox}{\let\my@par\par}{\let\my@par\endgraf}{}{}%
+  \patchcmd{\verbbox}{\verbatim\verbbox@inner}{\LWR@atbeginverbatim{verbatim}\verbatim\verbbox@inner}{}{}%
+  \patchcmd{\endverbbox}{\egroup}{\LWR@afterendverbatim\egroup}{}{}%
+  \pretocmd{\theverbbox}{\LWR@forcenewpage}{}{}%
+  \DeclareDocumentCommand{\LWR@HTML@midrule}{o}{%
+    \IfValueTF{#1}{\LWR@docmidrule[#1](){1-\arabic{LWR@tabletotalLaTeXcols}}}%
+                  {\defaddtocounter{LWR@hlines}{1}}%
+    \LWR@getmynexttoken}}
+
+% Alias inline enumerate* to block enumerate, and no-op \phantomsection.
+\RenewDocumentEnvironment{enumerate*}{o}{%
+  \IfNoValueTF{#1}{\begin{enumerate}}{\begin{enumerate}[#1]}}{\end{enumerate}}
+\renewcommand{\phantomsection}{}
+\renewcommand{\LWR@phantomsection}{}
+
+% Page-dropping variants of perfbook's cross-reference, quiz, and credit macros,
+% direct footnote & Quick Quiz answer anchor linkage, plus ASCII normalization
+% of \" in label keys and removal of " on \cpageref{}".
+\renewcommand{\pararef}[1]{paragraph ``\nameref{#1}''}
+\renewcommand{\Pararef}[1]{Paragraph ``\nameref{#1}''}
+\renewcommand{\QuickQHeadingPage}[3]{\hyperref[#2.#3]{\textbf{Quick Quiz #3:}}}
+\patchcmd{\QuickQuizAnswer}{\rule{7pt}{7pt}}{\textbf{[Answer]}}{}{}
+\patchcmd{\QuickA}{\rule{7pt}{7pt}}{\textbf{[Question]}}{}{}
+\patchcmd{\QuickA}{\noindent}{\noindent\label{QQA.\QuickQuizAnswerChapter.\thequickquizctrC}}{}{}
+\patchcmd{\QuickE}{\ding{113}}{\HTMLunicode{2751}}{}{}
+\def\pfb@fnid{footnote-\arabic{LWR@htmlfilenumber}-\@thefnmark}
+\def\@makefnmark{\LWR@htmltag{a id=\textquotedbl{}fnref-\pfb@fnid\textquotedbl\ href=\textquotedbl\LWR@origpound\pfb@fnid\textquotedbl}\textsuperscript{\@thefnmark}\LWR@htmltag{/a}}
+\long\def\@makefntext#1{\LWR@htmltag{a id=\textquotedbl\pfb@fnid\textquotedbl\ href=\textquotedbl\LWR@origpound{}fnref-\pfb@fnid\textquotedbl}\@thefnmark.\LWR@htmltag{/a}~{#1}}
+\renewcommand{\OrigPubItem}[4]{\item \Cref{#1} (``#2'') originally appeared in #3~\cite{#4}.}
+\renewcommand{\RangeOrigPub}[5]{\item \Cref{#1}--\ref{#2} (``#3'') originally appeared in #4~\cite{#5}.}
+\renewcommand{\ContribItem}[2]{\item \Cref{#1} by #2.}
+
+\def\LWR@clean@arg#1{{\def\"##1{##1}\xdef\LWR@on@arg{#1}}}
+\let\LWR@orig@cref\cref
+\let\LWR@orig@Cref\Cref
+\renewcommand{\cref}[1]{\LWR@clean@arg{#1}\LWR@orig@cref{\LWR@on@arg}\futurelet\LWR@tok\LWR@on@a}
+\renewcommand{\Cref}[1]{\LWR@clean@arg{#1}\LWR@orig@Cref{\LWR@on@arg}\futurelet\LWR@tok\LWR@on@a}
+\def\LWR@on@a{\ifx\LWR@tok\@sptoken\expandafter\LWR@on@b\fi}
+\expandafter\def\expandafter\LWR@on@b\space{\futurelet\LWR@tok\LWR@on@c}
+\def\LWR@on@c{\ifx\LWR@tok o\expandafter\LWR@on@d\else\space\fi}
+\def\LWR@on@d o#1{\ifx n#1\expandafter\LWR@on@e\else\space o#1\fi}
+\def\LWR@on@e{\futurelet\LWR@tok\LWR@on@f}
+\def\LWR@on@f{\ifx\LWR@tok\@sptoken\expandafter\LWR@on@g\else\space on\fi}
+\expandafter\def\expandafter\LWR@on@g\space{\futurelet\LWR@tok\LWR@on@h}
+\def\LWR@on@h{\ifx\LWR@tok\cpageref\expandafter\LWR@on@i\else\space on \fi}
+\def\LWR@on@i\cpageref#1{\edef\LWR@tmp{#1}\ifx\LWR@tmp\LWR@on@arg\else\space on \cpageref{#1}\fi}
+\renewcommand{\cpageref}[1]{\cref{#1}}
+
+\crefname{quickquizctr}{Quick Quiz}{Quick Quizzes}
+\crefname{quickquizctrC}{Quick Quiz}{Quick Quizzes}
+\crefname{quickquizctrP}{Quick Quiz}{Quick Quizzes}
+\crefname{paragraph}{paragraph}{paragraphs}
+\Crefname{paragraph}{Paragraph}{Paragraphs}
+\appto\appendix{%
+  \crefalias{chapter}{appendix}%
+  \crefalias{section}{subappendix}%
+  \crefalias{subsection}{subsubappendix}%
+  \crefalias{subsubsection}{subsubsubappendix}}
+\makeatother
+
+\graphicspath{{epub-figs/}{./}}
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 2/7] utilities: Add EPUB3 post-processor and stylesheet
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 1/7] reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 3/7] utilities/runlwarp.sh: Add lwarp and Pandoc build driver Ferenc Fejes
                   ` (5 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Add utilities/epub-fixhtml.pl to adjust Pandoc's unpacked EPUB3 XHTML
and SVG files: rotate landscape SVGs upright, cap tall portrait figures,
merge multi-snippet listings, apply table cell colors, lay out numbered
display equations, and wrap footnotes and Quick Quiz answers in EPUB3
popup asides.  Also add utilities/epub.css to style epigraphs, figures,
listings, tables, equations, and chapter headings across KOReader and
Foliate.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 utilities/epub-fixhtml.pl | 80 +++++++++++++++++++++++++++++++++++++++
 utilities/epub.css        | 63 ++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+)
 create mode 100755 utilities/epub-fixhtml.pl
 create mode 100644 utilities/epub.css

diff --git a/utilities/epub-fixhtml.pl b/utilities/epub-fixhtml.pl
new file mode 100755
index 00000000..64428efc
--- /dev/null
+++ b/utilities/epub-fixhtml.pl
@@ -0,0 +1,80 @@
+#!/usr/bin/env perl
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Post-Pandoc XHTML and SVG adjustments for the EPUB package directory.
+#
+# Copyright (C) Ferenc Fejes, 2026
+#
+# Authors: Ferenc Fejes <ferenc@fejes.dev>
+
+use strict;
+use warnings;
+
+my $pkg = shift(@ARGV) or die "Usage: $0 <epub-pkg-dir>\n";
+
+sub slurp { open my $fh, '<:raw', $_[0] or die "$_[0]: $!"; local $/; <$fh> }
+sub spurt { open my $fh, '>:raw', $_[0] or die "$_[0]: $!"; print $fh $_[1] }
+
+my (%w, %h, %rot90, %fig);
+for my $f (glob("$pkg/EPUB/media/*.svg")) {
+    my ($n) = $f =~ m{([^/]+)$};
+    my $s = slurp($f);
+    ($w{$n}) = $s =~ /\bwidth=['"]([0-9.]+)/;
+    ($h{$n}) = $s =~ /\bheight=['"]([0-9.]+)/;
+}
+
+for my $f (glob("$pkg/EPUB/text/*.xhtml")) {
+    my $x = slurp($f);
+    $x =~ s{<span\s+style="[^"]*transform:rotate\(-90deg\)[^"]*">\s*(<img\b[^>]*\bsrc="\.\./media/([^"]+)"[^>]*>)\s*</span>}{
+        $rot90{$2} = 1; ($w{$2}, $h{$2}) = ($h{$2}, $w{$2}); $1
+    }gse;
+    $x =~ s{(<img src="\.\./media/([^"]+\.svg)" class="inlineimage" style="width:)(\d+)(%;?")}{
+        $fig{$2} = 1;
+        my $r = ($w{$2} && $h{$2}) ? $h{$2} / $w{$2} : 1;
+        my $c = $r > 1.15 ? int(65 / $r + 0.5) : $3;
+        $c = 25 if $c < 25;
+        $1 . ($3 > $c ? $c : $3) . $4
+    }ge;
+    $x =~ s{</code></pre>\s*((?:<span id="ln:[^"]+"></span>\s*)*)<pre class="verbatim"><code>\n?(.*?</code></pre>)}{
+        my ($p, $b) = ($1, $2);
+        $b =~ s/^(  \d+) (?=\S)/$1   /gm;
+        "\n$b$p"
+    }gse;
+    $x =~ s{<td([^>]*)>((?:\s*<p>)?)\s*<span class="cellcolor" data-bg="(#[0-9A-Fa-f]+)"></span>\s*(.*?</td>)}{
+        my ($a, $p, $c, $r) = ($1, $2, uc($3), $4);
+        $a =~ s/\s*background:\s*#[0-9A-Fa-f]+;?\s*//;
+        $a =~ s/\s*style="\s*"//;
+        ($a =~ s/style="/style="background: $c; / or $a .= qq( style="background: $c")) if $c ne '#FFFFFF';
+        $r = ($p ? "&#160;$r" : "<p>&#160;</p>$r") if $r =~ m{^(?:</p>\s*)?</td>$};
+        "<td$a>$p$r"
+    }gse;
+    $x =~ s{(?:<p>(<span id="[^"]+"></span>)</p>\s*)?<p>(<span id="lateximage-[^"]*" class="lateximagesource"><img src="\.\./media/([^"]+\.svg)"[^>]*/></span>)\s*<span class="eqnum">(.*?)</span></p>}{
+        my ($id, $img, $svg, $num) = ($1 // '', $2, $3, $4);
+        $img =~ s|style=""|sprintf('style="width:%.2fem"', $w{$svg} / 8.5)|e if $w{$svg};
+        qq(<table class="displaymath"><tbody><tr><td class="eqpad">$id</td><td class="eqbody">$img</td><td class="eqnum">$num</td></tr></tbody></table>)
+    }gse;
+    $x =~ s{<a\s+href="([^"]*#(?:footnote-[^"]+|QQA\.[^"]+))"(?=\s+id="fnref-|><strong>\[Answer\]</strong>)}{<a href="$1" epub:type="noteref" role="doc-noteref"}g;
+    $x =~ s{<p><a\s+(href="[^"]*#fnref-[^"]+")\s+id="(footnote-[^"]+)">(.*?)</p>}{<aside id="$2" epub:type="footnote" role="doc-footnote"><p><a $1 epub:type="backlink" role="doc-backlink">$3</p></aside>}gs;
+    $x =~ s{<p><span id="(QQA\.[^"]+)"></span>(?:</p>\s*<p>)?(<strong>Answer:</strong>.*?)<a\s+(href="[^"]*#QQE\.[^"]*")>(❑</a></p>(?:\s*</li>\s*</[uo]l>)?)}{<aside class="quiz-answer" id="$1" epub:type="footnote" role="doc-footnote"><p>$2<a $3 epub:type="backlink" role="doc-backlink">$4</aside>}gs;
+    spurt($f, $x);
+}
+
+for my $f (glob("$pkg/EPUB/media/*.svg")) {
+    my ($n) = $f =~ m{([^/]+)$};
+    my $s = slurp($f);
+    my $orig = $s;
+    $s =~ s{(<svg\b[^>]*?\swidth=")([0-9.]+)(pt"\s+height=")([0-9.]+)(pt"\s+viewBox="0 0 )([0-9.]+)\s+([0-9.]+)("[^>]*>)(.*)(</svg>)}{$1$4$3$2$5$7 $6$8\n<g transform="translate(0,$6) rotate(-90)">$9</g>\n$10}s if $rot90{$n};
+    $s =~ s{<svg\b([^>]*)>}{
+        my $a = $1;
+        if ($w{$n} && $h{$n}) {
+            $a .= qq( viewBox="0 0 $w{$n} $h{$n}") if $a !~ /\bviewBox=/;
+            if ($fig{$n}) {
+                my $th = int(800 * $h{$n} / $w{$n} + 0.5);
+                $a =~ s/\bwidth="[^"]*"/width="800pt"/;
+                $a =~ s/\bheight="[^"]*"/height="${th}pt"/;
+            }
+        }
+        "<svg$a>"
+    }se;
+    spurt($f, $s) if $s ne $orig;
+}
diff --git a/utilities/epub.css b/utilities/epub.css
new file mode 100644
index 00000000..c30a3f0f
--- /dev/null
+++ b/utilities/epub.css
@@ -0,0 +1,63 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+/* Chapter/section epigraphs (see reflow.ltx): right-flushed narrow box
+   with ruled small-caps attribution, like the print edition. */
+figure.epigraph { margin: 1.5em 0 1.5em auto; max-width: 27em; font-size: .85em; text-align: left; }
+figure.epigraph p { margin: 0; padding: .25ex 0; text-indent: 0; }
+figure.epigraph figcaption { border-top: 1px solid #A0A0A0; font-variant: small-caps; font-size: .92em; margin-top: .5ex; }
+figure.epigraph figcaption, figure.epigraph figcaption p { text-align: right; }
+
+/* Figures: center all images and captions, cap width at 85%, and keep
+   captions attached to their images across page breaks. */
+figure.figure { text-align: center; margin: 1.2em auto; page-break-inside: avoid; break-inside: avoid; }
+figure.figure p { margin: 0 0 .4em 0; text-indent: 0; text-align: center; }
+figure.figure img.inlineimage { display: inline-block; margin: 0 auto; max-width: 85%; height: auto; }
+
+/* Listings and tables: use smaller relative font sizes to minimize line
+   wraps while scaling with the reader's user-configured font size, and
+   avoid scroll boxes (WebKit-based readers like Foliate paint only the
+   first page of an overflow:auto box split across pages). */
+figure.listing, figure.table { margin: 1em 0; }
+figure.figure figcaption, figure.figure span.figurecaption,
+figure.listing figcaption, figure.listing span.figurecaption,
+figure.table figcaption, figure.table span.figurecaption {
+  display: block; text-align: center; font-size: .9em; margin: .35em 0;
+  page-break-before: avoid; break-before: avoid;
+}
+figure.listing.ruled { border-top: 1px solid #A0A0A0; border-bottom: 1px solid #A0A0A0; padding: .35em 0; }
+figure.listing pre { margin: .35em 0; }
+figure.listing table td { font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace; }
+pre, table { overflow: visible; line-height: 1.25; }
+pre { font-size: .75em; }
+pre code { font-size: 100%; overflow-wrap: anywhere; }
+kbd { font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace; font-size: 85%; }
+table { display: table; width: 100%; font-size: .8em; }
+th, td { overflow-wrap: break-word; padding: .2em .35em; text-align: left; }
+td.tdc { text-align: center; }
+td.tdr { text-align: right; }
+tr.hline td, tr.tbrule td { border-top: 1px solid #808080; }
+tbody tr.tbrule:first-child td { border-top: none; }
+tbody tr.tbrule:last-child td { padding: 0; }
+td.tdrule, td.tdrulel, td.tdruler, td.tdrulelr { border-top: 1px solid #A0A0A0; }
+td.tvertbarr { border-right: 1px solid #808080; }
+td.tvertbarrdouble { border-right: 3px double #808080; }
+th p, td p { margin: 0; text-align: inherit; line-height: inherit; }
+
+/* Numbered display equations: center math expression and flush equation
+   number to the right margin while scaling math with the body font. */
+table.displaymath { width: 100%; margin: .8em 0; border: none; border-collapse: collapse; font-size: 1em; page-break-inside: avoid; break-inside: avoid; }
+table.displaymath tbody, table.displaymath tr, table.displaymath td { border: none; padding: 0; vertical-align: middle; }
+table.displaymath td.eqpad { width: 12%; }
+table.displaymath td.eqbody { width: 76%; text-align: center; }
+table.displaymath td.eqbody img.lateximage { max-width: 100%; height: auto; vertical-align: middle; }
+table.displaymath td.eqnum { width: 12%; text-align: right; white-space: nowrap; }
+
+/* KOReader: never typeset Quick Quiz answers as in-page footnotes (they
+   would spoil the answer below the question); tap-to-popup still works
+   because detection uses the epub:type/role attributes. */
+aside.quiz-answer { -cr-hint: none !important; }
+
+/* Each chapter is already a separate spine document (Pandoc --split-level=1);
+   override Pandoc's default h1 { page-break-before: always } so headings
+   inside a chapter file never force an extra page break. */
+h1 { page-break-before: auto; break-before: auto; }
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 3/7] utilities/runlwarp.sh: Add lwarp and Pandoc build driver
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 1/7] reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 2/7] utilities: Add EPUB3 post-processor and stylesheet Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 4/7] Makefile, .gitignore: Add epub and html build targets Ferenc Fejes
                   ` (4 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Add utilities/runlwarp.sh to drive multi-pass lwarp HTML compilation,
background SVG math rendering, and Pandoc EPUB3 packaging.  After
running epub-fixhtml.pl and appending epub.css, the script verifies
anchor, equation, footnote, Quick Quiz, and epigraph counts and runs
epubcheck when available.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 utilities/runlwarp.sh | 286 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 286 insertions(+)
 create mode 100644 utilities/runlwarp.sh

diff --git a/utilities/runlwarp.sh b/utilities/runlwarp.sh
new file mode 100644
index 00000000..7e0dbd65
--- /dev/null
+++ b/utilities/runlwarp.sh
@@ -0,0 +1,286 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Build a reflowable EPUB (or browsable HTML) from perfbook-epub.tex.
+# Usage: sh utilities/runlwarp.sh perfbook-epub [epub|html]
+#
+# Copyright (C) Ferenc Fejes, 2026
+#
+# Authors: Ferenc Fejes <ferenc@fejes.dev>
+
+: "${LATEX:=pdflatex}"
+: "${MAXPASS:=6}"
+: "${PANDOC:=pandoc}"
+
+BOOK_TITLE="Is Parallel Programming Hard, And, If So, What Can You Do About It?"
+BOOK_AUTHOR="Paul E. McKenney"
+BOOK_COVER="cartoons/r-2014-Book-cover-front.png"
+MIN_LWARP_VERSION="0.921"
+
+if [ -z "$1" ]; then
+	echo "Usage: sh utilities/runlwarp.sh <file[.tex]> [epub|html]" >&2
+	exit 2
+fi
+
+base=${1%.tex}
+html=${base}_html
+tmp=epub-tmp
+mode=${2:-epub}
+
+# ---------------------------------------------------------------------------
+# Logging and assertion helpers
+# ---------------------------------------------------------------------------
+
+die () {   # $1 = message, $2 = optional exit code (default: 2)
+	echo "----- $1 -----" >&2
+	exit "${2:-2}"
+}
+
+check_count () {   # $1 = label, $2 = expected, $3 = actual
+	if [ "$2" -ne "$3" ]; then
+		die "$1: expected $2, found $3" 1
+	fi
+}
+
+check_positive () {   # $1 = label, $2 = expected, $3 = actual
+	check_count "$1" "$2" "$3"
+	if [ "$2" -le 0 ]; then
+		die "$1: count is zero" 1
+	fi
+}
+
+count_matches () {   # $1 = grep regex, $2... = files
+	pattern=$1
+	shift
+	grep -rho "$pattern" "$@" 2>/dev/null | wc -l
+}
+
+# ---------------------------------------------------------------------------
+# Prerequisite checks
+# ---------------------------------------------------------------------------
+
+check_prerequisites () {
+	tools="$LATEX bibtex lwarpmk pdftocairo unzip zip"
+	if [ "$mode" = epub ]; then
+		tools="$tools $PANDOC"
+	fi
+	for tool in $tools; do
+		command -v "$tool" >/dev/null 2>&1 ||
+			die "Required tool not found: $tool (prerequisites: #15 in FAQ-BUILD.txt)"
+	done
+
+	lwarp_ver=$(lwarpmk --version 2>/dev/null | sed -n 's/.*v\([0-9][0-9.]*\).*/\1/p')
+	if [ -z "$lwarp_ver" ] || ! awk -v v="$lwarp_ver" -v min="$MIN_LWARP_VERSION" 'BEGIN { exit !(v >= min) }'; then
+		die "lwarp >= $MIN_LWARP_VERSION is required (found ${lwarp_ver:-unknown})"
+	fi
+}
+
+# ---------------------------------------------------------------------------
+# LaTeX, BibTeX, glossary, and lwarp HTML compilation
+# ---------------------------------------------------------------------------
+
+# Run $LATEX with $3 flags on job $1; abort on fatal TeX errors in $1.log.
+run_latex () {   # $1 = jobname, $2 = step description, $3 = extra flags
+	job=$1
+	label=$2
+	flags=$3
+
+	echo "$LATEX $flags for $job # $label"
+	$LATEX $flags -interaction=nonstopmode "$job" >/dev/null 2>&1 </dev/null ||
+		die "!!! LaTeX failed for $job !!!"
+	[ -r "$job.log" ] ||
+		die "no log produced for $job"
+
+	if grep -q '^! ' "$job.log"; then
+		echo "----- !!! TeX error in $job.log !!! -----" >&2
+		grep -A 6 '^! ' "$job.log" | head -n 60 >&2
+		exit 2
+	fi
+}
+
+# Run BibTeX and normalize single-page endashes and double-braced \href in .bbl.
+build_bbl () {
+	if grep -q '\\bibdata' "$html.aux"; then
+		bibtex "$html" >/dev/null &&
+		sed -i \
+			-e 's/\bpage \([0-9]*\)–/pages \1--/g' \
+			-e 's/\\href {{\([^}]*\)}}/\\href {\1}/g' \
+			"$html.bbl"
+	fi
+}
+
+# Build acronyms/glossary via makeglossaries, falling back to makeindex.
+build_glossary () {
+	if [ -r "$html.acn" ]; then
+		makeglossaries "$html" >/dev/null 2>&1 || {
+			[ -r "$html.ist" ] &&
+			makeindex -s "$html.ist" -t "$html.alg" -o "$html.acr" "$html.acn" >/dev/null 2>&1
+		}
+	fi
+}
+
+# Return 0 when all LaTeX references and lwarp's math-image list have stabilized.
+is_html_stable () {
+	! grep -q 'Rerun to get\|Label(s) may have changed\|There were undefined' "$html.log" &&
+	tail -n 1 "$base-images.txt" 2>/dev/null | grep -q '|end|end|end|'
+}
+
+# Wait for backgrounded pdfcrop/pdftocairo jobs spawned by `lwarpmk limages`.
+wait_limages () {
+	while find "$base-images" -name '*.pdf' -o -size 0 2>/dev/null | grep -q .; do
+		sleep 0.1
+	done
+}
+
+build_html () {
+	if [ ! -r "$html.html" ]; then
+		rm -f "$html.aux" "$html.bbl" "$html.toc" "$html.lof" "$html.lot" "$html.out"
+	fi
+
+	# 1. Print pass: lwarp generates ${html}.tex and lwarpmk.conf.
+	run_latex "$base" "lwarp wrapper generation" -draftmode
+	[ -r "$html.tex" ] || die "lwarp did not write $html.tex"
+
+	# 2. HTML passes: iterate until cross-references and image list converge.
+	html_passes=0
+	draft=-draftmode
+	[ -r "$html.bbl" ] && draft=
+
+	while :; do
+		html_passes=$((html_passes + 1))
+		[ "$html_passes" -ge 3 ] && draft=
+		run_latex "$html" "HTML pass $html_passes" "$draft"
+
+		if [ "$html_passes" -eq 1 ]; then
+			build_bbl &
+			bib_pid=$!
+			build_glossary &
+			gls_pid=$!
+			wait "$bib_pid" || die "bibtex failed for $html"
+			wait "$gls_pid" || die "glossary generation failed for $html"
+		fi
+
+		if is_html_stable; then
+			break
+		fi
+		if [ "$html_passes" -ge "$MAXPASS" ]; then
+			die "Still unstable after $MAXPASS passes, giving up." 1
+		fi
+	done
+
+	if grep -q 'LaTeX Warning: Reference\|LaTeX Warning: Citation' "$html.log"; then
+		grep -A 2 'LaTeX Warning: Reference\|LaTeX Warning: Citation' "$html.log" | head -n 40 >&2
+		die "Undefined references/citations remain in $html.log" 1
+	fi
+
+	# 3. Render math SVGs (backgrounded by lwarpmk) while splitting HTML chapters.
+	find "$base-images" -name '*.pdf' -o -size 0 -delete 2>/dev/null
+	lwarpmk limages   -p "$base" >"$tmp-limages.log"   2>&1 || { tail -n 20 "$tmp-limages.log"   >&2; exit 2; }
+	lwarpmk pdftohtml -p "$base" >"$tmp-pdftohtml.log" 2>&1 || { tail -n 20 "$tmp-pdftohtml.log" >&2; exit 2; }
+}
+
+# ---------------------------------------------------------------------------
+# EPUB packaging and validation
+# ---------------------------------------------------------------------------
+
+# Zip an unpacked EPUB directory ($1) into $2 with an uncompressed mimetype
+# entry first, as required by the EPUB OCF specification.
+repack_epub () {   # $1 = package dir, $2 = output epub
+	pkg_dir=$1
+	out_epub=$2
+	root=$(pwd)
+	tmp_epub="$out_epub.tmp"
+
+	rm -f "$tmp_epub"
+	(
+		cd "$pkg_dir" || exit 2
+		zip -X0 "$root/$tmp_epub" mimetype >/dev/null &&
+		zip -Xr9D "$root/$tmp_epub" META-INF EPUB >/dev/null
+	) || exit 2
+	mv -f "$tmp_epub" "$out_epub" || exit 2
+
+	if command -v epubcheck >/dev/null 2>&1; then
+		epubcheck "$out_epub" || die "epubcheck failed for $out_epub" 1
+	fi
+}
+
+# Verify that structural counts in packaged XHTML ($2...) match lwarp HTML ($html_chapters).
+validate_epub () {   # $1 = package dir
+	set -- "$1"/EPUB/text/*.xhtml
+
+	check_count "line-anchor preservation" \
+		"$(count_matches 'id="ln:' $html_chapters)" \
+		"$(count_matches 'id="ln:' "$@")"
+
+	check_positive "display equation formatting" \
+		"$(count_matches 'class="displaymathnumbered"' $html_chapters)" \
+		"$(count_matches '<table class="displaymath">' "$@")"
+
+	check_positive "footnote preservation" \
+		"$(count_matches 'id="fnref-' $html_chapters)" \
+		"$(count_matches '<aside[^>]*id="footnote-' "$@")"
+
+	check_positive "quiz answers on asides" \
+		"$(count_matches 'id="QQA\.' $html_chapters)" \
+		"$(count_matches '<aside[^>]*id="QQA\.' "$@")"
+
+	check_positive "epigraph preservation" \
+		"$(count_matches '<figure class="epigraph"' $html_chapters)" \
+		"$(count_matches '<figure class="epigraph"' "$@")"
+
+	check_count "unresolved references in HTML" 0 \
+		"$(count_matches 'href="#??"' $html_chapters)"
+
+	check_count "page-number phrases" 0 \
+		"$(count_matches 'page\(&nbsp;\| \)for' $html_chapters)"
+}
+
+build_epub () {
+	# Space-separated list of split chapter HTML files in reading order.
+	html_chapters=$(grep -o '<!--|Start file|[^|]*|' "$html.html" | cut -d'|' -f3 | awk '!seen[$0]++')
+	wait_limages
+
+	$PANDOC -f html-native_divs --shift-heading-level-by=-2 \
+		--split-level=1 --toc --toc-depth=3 \
+		--metadata title="$BOOK_TITLE" \
+		--metadata author="$BOOK_AUTHOR" \
+		--metadata lang=en-US \
+		--epub-cover-image="$BOOK_COVER" \
+		--resource-path=epub-figs:. \
+		-o "$base.epub" $html_chapters || exit 2
+
+	package="$tmp/package"
+	rm -rf "$package" && mkdir -p "$package"
+	unzip -q "$base.epub" -d "$package" || exit 2
+	perl utilities/epub-fixhtml.pl "$package" || exit 2
+
+	epub_css="$package/EPUB/styles/stylesheet1.css"
+	[ -r "$epub_css" ] || die "missing packaged stylesheet" 1
+	{ echo; cat utilities/epub.css; } >>"$epub_css" || exit 2
+
+	validate_epub "$package"
+	repack_epub "$package" perfbook.epub
+	rm -f "$base.epub"
+	echo "perfbook.epub built ($html_passes HTML passes)."
+}
+
+# ---------------------------------------------------------------------------
+# Main dispatch
+# ---------------------------------------------------------------------------
+
+case "$mode" in
+epub)
+	check_prerequisites
+	build_html
+	build_epub
+	;;
+html)
+	check_prerequisites
+	build_html
+	wait_limages
+	echo "HTML ready: $html.html (split chapters ${base}-*.html, images ${base}-images/)."
+	;;
+*)
+	die "Unknown mode '$mode' (want epub|html)"
+	;;
+esac
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 4/7] Makefile, .gitignore: Add epub and html build targets
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
                   ` (2 preceding siblings ...)
  2026-11-15 21:01 ` [RFC PATCH 3/7] utilities/runlwarp.sh: Add lwarp and Pandoc build driver Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 5/7] epub: Add endnote variant for readers without popup footnotes Ferenc Fejes
                   ` (3 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Wire make epub, make html, and make epub-clean into Makefile, staging
converted and flowRoot-sanitized SVG figures under epub-figs/ so make -j
builds them in parallel before invoking runlwarp.sh.  Ignore lwarp and
EPUB build artifacts in .gitignore.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 .gitignore | 14 ++++++++++++
 Makefile   | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index ce93394f..6624a175 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,6 +25,20 @@
 *.pdfp
 *.pdfq
 *.synctex*
+*.epub
+*.sidetoc
+*.lwarpmkconf
+lwarpmk.conf
+comment_*.cut
+lwarp*.css
+sample_project.css
+lwarp.ist
+*.xdy
+core
+core.*
+/perfbook-epub-images/
+/epub-tmp/
+/epub-figs/
 perfbook_flat.tex
 qqz*.tex
 sub_qqz
diff --git a/Makefile b/Makefile
index b4f34c51..cf1282d1 100644
--- a/Makefile
+++ b/Makefile
@@ -53,7 +53,7 @@ FIGSOURCES := $(wildcard */*.fig) $(wildcard */*/*.fig)
 
 EPSSOURCES_FROM_FIG := $(FIGSOURCES:%.fig=%.eps)
 
-SVGSOURCES_ALL := $(wildcard */*.svg)
+SVGSOURCES_ALL := $(filter-out perfbook-epub-images/%,$(wildcard */*.svg))
 SVG_EMERGENCY := $(wildcard */*.svg*.svg)
 SVG_GENERATED := CodeSamples/formal/data/RCU-test-ratio.svg
 SVGSOURCES := $(filter-out $(SVG_EMERGENCY) $(SVG_GENERATED),$(SVGSOURCES_ALL)) $(SVG_GENERATED)
@@ -252,8 +252,9 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
 .PHONY: qq perfbook-qq.pdf qqmsg
 .PHONY: help help-official help-full help-semiofficial help-paper help-draft
 .PHONY: help-experimental help-prefixed
+.PHONY: epub epub-clean html html-clean
 .PHONY: paper-clean periodcheck punctcheck punctcheck-auto
-.PHONY: cleanfigs cleanfigs-eps cleanfigs-svg figs precheck
+.PHONY: cleanfigs cleanfigs-eps cleanfigs-svg cleanfigs-epub figs precheck
 
 all: punctcheck-auto
 
@@ -652,9 +653,63 @@ help-experimental:
 	@echo "  - \"sf\" requires \"newtxsf\"."
 	@echo "  - All the targets except for \"msn\" use \"Latin Modern Typewriter\" font"
 	@echo "    for code snippets."
+	@echo
+	@echo "Reflowable EPUB (experimental, lwarp + pandoc; see FAQ-BUILD.txt #15):"
+	@echo "  perfbook.epub,     epub: chapter-split EPUB3 from the ebook-size variant"
+	@echo "  perfbook-epub_html.html, html: lwarp HTML only, no EPUB packaging"
+
+PDFTOCAIRO := $(shell $(WHICH) pdftocairo 2>/dev/null)
+EPUB_SVGS := $(addprefix epub-figs/,$(EPSSOURCES:%.eps=%.svg))
+EPUB_SVG_CROP := epub-figs/CodeSamples/formal/data/RCU-test-ratio-crop.svg
+EPUB_SVG_CLEAN := intro/PPGrelation.svg defer/RCUListDeleteClassic.svg \
+	memorder/RCU2G2R.svg formal/cbmc.svg formal/nidhugg.svg
+EPUB_SVG_STAGED := $(addprefix epub-figs/,$(EPUB_SVG_CLEAN))
+
+$(EPUB_SVG_STAGED): epub-figs/%.svg: %.svg
+	@echo "$< --> $@ (sanitize flowRoot)"
+	@mkdir -p $(dir $@)
+	@perl -0777 -pe 's{<flowRoot\b.*?</flowRoot>}{}gs' $< > $@
+
+$(EPUB_SVGS): epub-figs/%.svg: %.pdf
+	@echo "$< --> $@ (pdftocairo)"
+ifndef PDFTOCAIRO
+	$(error pdftocairo (poppler-utils) not found. Please install it)
+endif
+	@mkdir -p $(dir $@)
+	@pdftocairo -svg $< $@
+
+$(EPUB_SVG_CROP): CodeSamples/formal/data/RCU-test-ratio.svg
+	@echo "$< --> $@ (copy, uncropped)"
+	@mkdir -p $(dir $@)
+	@cp $< $@
+
+epub: perfbook.epub
+html: perfbook-epub_html.html
+
+perfbook-epub.tex: perfbook-eb.tex
+	echo '\input{reflow.ltx}\input{perfbook-eb}' > $@
+
+perfbook.epub perfbook-epub_html.html: perfbook-epub.tex $(LATEXGENERATED) $(BIBSOURCES) \
+    $(EPUB_SVGS) $(EPUB_SVG_CROP) $(EPUB_SVG_STAGED) reflow.ltx utilities/runlwarp.sh \
+    utilities/epub-fixhtml.pl utilities/epub.css
+perfbook.epub:
+	LATEX=$(LATEX) sh utilities/runlwarp.sh perfbook-epub
+perfbook-epub_html.html:
+	LATEX=$(LATEX) sh utilities/runlwarp.sh perfbook-epub html
+
+cleanfigs-epub:
+	rm -rf epub-figs
+
+html-clean: epub-clean
+epub-clean:
+	rm -rf epub-tmp perfbook-epub-images perfbook-epub-images.txt \
+		lwarpmk.conf perfbook-epub.lwarpmkconf perfbook-epub*.html \
+		perfbook-epub.tex perfbook-epub_html.* epub-tmp-*.log comment_*.cut \
+		lwarp*.css sample_project.css lwarp.ist lwarp.xdy *.xdy core core.*
 
 help-full: help-official help-paper help-semiofficial help-draft help-prefixed help-experimental
 
+clean: epub-clean
 clean:
 	find . -name '*.aux' -o -name '*.blg' \
 		-o -name '*.dvi' -o -name '*.log' \
@@ -677,6 +732,7 @@ paper-clean:
 distclean: clean
 	sh utilities/cleanpdf.sh
 	rm -f $(EPSSOURCES_FROM_DOT) $(EPSSOURCES_FROM_TEX) $(EPSSOURCES_FROM_FIG)
+	rm -rf epub-figs
 	find . -name '*.fcv' -o -name '*.ltms' | xargs rm -f
 
 touchsvg:
@@ -687,6 +743,7 @@ ls-unused:
 
 neatfreak: distclean
 	find . -name '*.pdf' | xargs rm -f
+	rm -f perfbook.epub
 
 cleanfigs-eps:
 	rm -f $(EPSSOURCES_FROM_TEX) $(EPSSOURCES_FROM_DOT) $(EPSSOURCES_FROM_FIG)
@@ -695,7 +752,7 @@ cleanfigs-eps:
 cleanfigs-svg:
 	rm -f $(PDFTARGETS_OF_SVG) $(SVG_EMERGENCY) $(SVG_GENERATED) $(PDFTARGETS_OF_SVG_CROP)
 
-cleanfigs: cleanfigs-eps cleanfigs-svg
+cleanfigs: cleanfigs-eps cleanfigs-svg cleanfigs-epub
 
 figs: $(PDFTARGETS_OF_EPS) $(PDFTARGETS_OF_SVG) $(PDFTARGETS_OF_SVG_CROP)
 
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 5/7] epub: Add endnote variant for readers without popup footnotes
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
                   ` (3 preceding siblings ...)
  2026-11-15 21:01 ` [RFC PATCH 4/7] Makefile, .gitignore: Add epub and html build targets Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 6/7] FAQ-BUILD.txt: Document HTML and EPUB build targets Ferenc Fejes
                   ` (2 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Add make epub-endnotes to transform perfbook.epub into
perfbook-endnotes.epub without re-running LaTeX or Pandoc.  It moves
chapter footnote asides into linked end-of-chapter sections and unwraps
Quick Quiz answer asides into regular blocks for e-readers without EPUB3
popup support.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 Makefile                  |  9 +++++++--
 utilities/epub-fixhtml.pl | 15 ++++++++++++++-
 utilities/runlwarp.sh     | 19 ++++++++++++++++---
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index cf1282d1..358fab3a 100644
--- a/Makefile
+++ b/Makefile
@@ -252,7 +252,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
 .PHONY: qq perfbook-qq.pdf qqmsg
 .PHONY: help help-official help-full help-semiofficial help-paper help-draft
 .PHONY: help-experimental help-prefixed
-.PHONY: epub epub-clean html html-clean
+.PHONY: epub epub-endnotes epub-clean html html-clean
 .PHONY: paper-clean periodcheck punctcheck punctcheck-auto
 .PHONY: cleanfigs cleanfigs-eps cleanfigs-svg cleanfigs-epub figs precheck
 
@@ -656,6 +656,8 @@ help-experimental:
 	@echo
 	@echo "Reflowable EPUB (experimental, lwarp + pandoc; see FAQ-BUILD.txt #15):"
 	@echo "  perfbook.epub,     epub: chapter-split EPUB3 from the ebook-size variant"
+	@echo "  perfbook-endnotes.epub, epub-endnotes: same, with plain linked endnotes and"
+	@echo "                    inline Quick Quiz answers instead of popup footnotes"
 	@echo "  perfbook-epub_html.html, html: lwarp HTML only, no EPUB packaging"
 
 PDFTOCAIRO := $(shell $(WHICH) pdftocairo 2>/dev/null)
@@ -684,6 +686,7 @@ $(EPUB_SVG_CROP): CodeSamples/formal/data/RCU-test-ratio.svg
 	@cp $< $@
 
 epub: perfbook.epub
+epub-endnotes: perfbook-endnotes.epub
 html: perfbook-epub_html.html
 
 perfbook-epub.tex: perfbook-eb.tex
@@ -696,6 +699,8 @@ perfbook.epub:
 	LATEX=$(LATEX) sh utilities/runlwarp.sh perfbook-epub
 perfbook-epub_html.html:
 	LATEX=$(LATEX) sh utilities/runlwarp.sh perfbook-epub html
+perfbook-endnotes.epub: perfbook.epub utilities/runlwarp.sh utilities/epub-fixhtml.pl
+	LATEX=$(LATEX) sh utilities/runlwarp.sh perfbook-epub endnotes
 
 cleanfigs-epub:
 	rm -rf epub-figs
@@ -743,7 +748,7 @@ ls-unused:
 
 neatfreak: distclean
 	find . -name '*.pdf' | xargs rm -f
-	rm -f perfbook.epub
+	rm -f perfbook.epub perfbook-endnotes.epub
 
 cleanfigs-eps:
 	rm -f $(EPSSOURCES_FROM_TEX) $(EPSSOURCES_FROM_DOT) $(EPSSOURCES_FROM_FIG)
diff --git a/utilities/epub-fixhtml.pl b/utilities/epub-fixhtml.pl
index 64428efc..4940681a 100755
--- a/utilities/epub-fixhtml.pl
+++ b/utilities/epub-fixhtml.pl
@@ -10,11 +10,24 @@
 use strict;
 use warnings;
 
-my $pkg = shift(@ARGV) or die "Usage: $0 <epub-pkg-dir>\n";
+my $endnotes = (@ARGV && $ARGV[0] eq '--endnotes') ? shift(@ARGV) : 0;
+my $pkg = shift(@ARGV) or die "Usage: $0 [--endnotes] <epub-pkg-dir>\n";
 
 sub slurp { open my $fh, '<:raw', $_[0] or die "$_[0]: $!"; local $/; <$fh> }
 sub spurt { open my $fh, '>:raw', $_[0] or die "$_[0]: $!"; print $fh $_[1] }
 
+if ($endnotes) {
+    for my $f (glob("$pkg/EPUB/text/*.xhtml")) {
+        my ($x, @fn) = slurp($f);
+        $x =~ s{<aside id="(footnote-[^"]+)"[^>]*>(.*?)</aside>\n?}{push @fn, qq(<div class="endnote" id="$1">$2</div>); ''}gse;
+        $x =~ s{</body>}{<section class="endnotes">\n<hr />\n@{[join "\n", @fn]}\n</section>\n</body>} if @fn;
+        $x =~ s{<aside class="quiz-answer" id="([^"]+)"[^>]*>(.*?)</aside>}{<div class="quiz-answer" id="$1">$2</div>}gs;
+        $x =~ s/\s+(?:epub:type|role)="(?:doc-)?(?:noteref|footnote|backlink)"//g;
+        spurt($f, $x);
+    }
+    exit 0;
+}
+
 my (%w, %h, %rot90, %fig);
 for my $f (glob("$pkg/EPUB/media/*.svg")) {
     my ($n) = $f =~ m{([^/]+)$};
diff --git a/utilities/runlwarp.sh b/utilities/runlwarp.sh
index 7e0dbd65..d55d87f7 100644
--- a/utilities/runlwarp.sh
+++ b/utilities/runlwarp.sh
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 #
 # Build a reflowable EPUB (or browsable HTML) from perfbook-epub.tex.
-# Usage: sh utilities/runlwarp.sh perfbook-epub [epub|html]
+# Usage: sh utilities/runlwarp.sh perfbook-epub [epub|endnotes|html]
 #
 # Copyright (C) Ferenc Fejes, 2026
 #
@@ -18,7 +18,7 @@ BOOK_COVER="cartoons/r-2014-Book-cover-front.png"
 MIN_LWARP_VERSION="0.921"
 
 if [ -z "$1" ]; then
-	echo "Usage: sh utilities/runlwarp.sh <file[.tex]> [epub|html]" >&2
+	echo "Usage: sh utilities/runlwarp.sh <file[.tex]> [epub|endnotes|html]" >&2
 	exit 2
 fi
 
@@ -264,6 +264,16 @@ build_epub () {
 	echo "perfbook.epub built ($html_passes HTML passes)."
 }
 
+build_endnotes () {
+	package="$tmp/endnotes"
+	rm -rf "$package" && mkdir -p "$package"
+	unzip -q perfbook.epub -d "$package" || exit 2
+	perl utilities/epub-fixhtml.pl --endnotes "$package" || exit 2
+	repack_epub "$package" perfbook-endnotes.epub
+	rm -rf "$package"
+	echo "perfbook-endnotes.epub built."
+}
+
 # ---------------------------------------------------------------------------
 # Main dispatch
 # ---------------------------------------------------------------------------
@@ -280,7 +290,10 @@ html)
 	wait_limages
 	echo "HTML ready: $html.html (split chapters ${base}-*.html, images ${base}-images/)."
 	;;
+endnotes)
+	build_endnotes
+	;;
 *)
-	die "Unknown mode '$mode' (want epub|html)"
+	die "Unknown mode '$mode' (want epub|endnotes|html)"
 	;;
 esac
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 6/7] FAQ-BUILD.txt: Document HTML and EPUB build targets
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
                   ` (4 preceding siblings ...)
  2026-11-15 21:01 ` [RFC PATCH 5/7] epub: Add endnote variant for readers without popup footnotes Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-15 21:01 ` [RFC PATCH 7/7] docker, gitlab-ci: Add EPUB build dependencies and CI job Ferenc Fejes
  2026-11-16  4:41 ` [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Akira Yokosawa
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Add FAQ #15 describing the epub, epub-endnotes, and html build targets,
their TeX Live, Pandoc, and Poppler prerequisites, e-reader settings for
KOReader and Foliate, and known limitations.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 FAQ-BUILD.txt | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/FAQ-BUILD.txt b/FAQ-BUILD.txt
index 6845db14..20673dec 100644
--- a/FAQ-BUILD.txt
+++ b/FAQ-BUILD.txt
@@ -370,3 +370,48 @@
 		Code samples under CodeSamples/ were originally written for
 		Linux and a QNX compat layer was added in 2022.  Compat layers
 		for other OSes are more than welcome!
+
+15.	How can I build a reflowable EPUB for my e-reader?
+
+	A.	Typing "make epub" will build "perfbook.epub", a chapter-split
+		EPUB3 derived from the ebook-size variant via lwarp and pandoc.
+		Typing "make html" stops after the lwarp HTML output (no pandoc
+		needed), leaving perfbook-epub_html.html, perfbook-epub-*.html,
+		and perfbook-epub-images/ ready to open in a browser.
+
+		In addition to #5 above, prerequisites are pandoc, poppler-utils
+		(pdftocairo, pdftotext, pdfseparate), unzip, zip, lwarp/lwarpmk
+		(>= 0.921, in texlive-latex-extra on Debian/Ubuntu, texlive-meta
+		on Arch, texlive-collection-latexextra on Fedora), and ifptex.sty
+		(texlive-lang-japanese on Debian/Ubuntu, texlive-langjapanese on
+		Arch).  docker/Dockerfile includes all of these.
+
+		Intermediates go to epub-tmp/, epub-figs/, perfbook-epub-images/,
+		and perfbook-epub_html.*.  "make epub-clean" (or "make html-clean",
+		also run by "make clean") removes them; "make neatfreak" also
+		removes "perfbook.epub" and "perfbook-endnotes.epub".
+
+		Footnotes and Quick Quiz answers are EPUB 3 popup footnotes
+		(epub:type="noteref"/"footnote").  Readers without popup
+		support, or that typeset footnotes at the bottom of the page,
+		can use "make epub-endnotes" instead.  It builds
+		"perfbook-endnotes.epub", where footnotes are plain linked
+		notes at the end of each chapter and Quick Quiz answers are
+		ordinary text in the answers appendix, as in the PDF.
+
+		KOReader shows the popup footnotes when "Show footnotes in popup"
+		is on (Settings > Taps and gestures > Links).  Its default
+		"In-page EPUB footnotes" style tweak (Style tweaks > In-page
+		footnotes) puts footnote text at the bottom of the page instead;
+		turn it off and turn on "Hide non-linear fragments" (Navigation
+		menu) to keep the text out of the page flow.  Quick Quiz answers
+		are never placed in-page.
+
+		Foliate 3.3 (WebKitGTK 2.54) leaves blank space where a scroll
+		box continues on the next page, so listings and tables wrap
+		long lines rather than scroll horizontally.
+
+		Known limitations: page-number indexes are omitted (the acronym
+		list is kept), math is rendered as SVG images, and SVG cartoons
+		fall back to the reader's font.  pdftocairo may dump git-ignored
+		core files on exit while still writing valid SVGs.
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [RFC PATCH 7/7] docker, gitlab-ci: Add EPUB build dependencies and CI job
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
                   ` (5 preceding siblings ...)
  2026-11-15 21:01 ` [RFC PATCH 6/7] FAQ-BUILD.txt: Document HTML and EPUB build targets Ferenc Fejes
@ 2026-11-15 21:01 ` Ferenc Fejes
  2026-11-16  4:41 ` [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Akira Yokosawa
  7 siblings, 0 replies; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-15 21:01 UTC (permalink / raw)
  To: perfbook; +Cc: Paul E . McKenney, Akira Yokosawa, Leonardo Bras, Ferenc Fejes

Install pandoc, unzip, zip, and texlive-lang-japanese in
docker/Dockerfile for EPUB builds.  Add a non-blocking generate_epub job
in utilities/gitlab-ci.yml that builds and archives perfbook.epub and
perfbook-endnotes.epub.

Signed-off-by: Ferenc Fejes <ferenc@fejes.dev>
---
 docker/Dockerfile       |  2 +-
 utilities/gitlab-ci.yml | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docker/Dockerfile b/docker/Dockerfile
index ee120e4b..063a678b 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -9,7 +9,7 @@ RUN apt-get update && DEBIAN_FRONTEND=noninteractive TZ=UTC apt-get install -y t
     rm -rf /var/lib/apt/lists/*
 RUN apt-get update && apt-get install -y fig2ps inkscape xfig graphviz psutils \
     texlive-publishers texlive-pstricks texlive-science texlive-fonts-extra \
-    make nano vim git curl gnuplot-nox time poppler-utils librsvg2-bin && \
+    make nano vim git curl gnuplot-nox time poppler-utils librsvg2-bin pandoc unzip zip texlive-lang-japanese && \
     rm -rf /var/lib/apt/lists/*
 COPY steel-city-comic.regular.ttf /usr/local/share/fonts/
 RUN fc-cache /usr/local/share/fonts/
diff --git a/utilities/gitlab-ci.yml b/utilities/gitlab-ci.yml
index f03e39a9..6068b215 100644
--- a/utilities/gitlab-ci.yml
+++ b/utilities/gitlab-ci.yml
@@ -31,3 +31,20 @@ generate_pdfs:
           - perfbook.pdf
           - perfbook-1c.pdf
           - perfbook-eb.pdf
+
+generate_epub:
+    stage: build
+    allow_failure: true
+
+    before_script:
+        - pacman --noconfirm -Syu texlive-meta fig2dev ghostscript graphviz librsvg gnuplot wget make which fontconfig git ttf-dejavu gnu-free-fonts ttf-liberation pandoc poppler texlive-langjapanese unzip zip epubcheck
+        - mkdir -p ~/.local/share/fonts && cp fonts/steel-city-comic.regular.ttf ~/.local/share/fonts/ && fc-cache
+
+    script:
+        - source /etc/profile
+        - make epub epub-endnotes
+
+    artifacts:
+      paths:
+          - perfbook.epub
+          - perfbook-endnotes.epub
-- 
2.55.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
                   ` (6 preceding siblings ...)
  2026-11-15 21:01 ` [RFC PATCH 7/7] docker, gitlab-ci: Add EPUB build dependencies and CI job Ferenc Fejes
@ 2026-11-16  4:41 ` Akira Yokosawa
  2026-11-16 17:21   ` Ferenc Fejes
  7 siblings, 1 reply; 14+ messages in thread
From: Akira Yokosawa @ 2026-11-16  4:41 UTC (permalink / raw)
  To: Ferenc Fejes, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

Hi!

On 11/16/26 06:01, Ferenc Fejes wrote:
> Hi!
> 
> This RFC series adds experimental reflowable EPUB3 and HTML build targets
> ("make epub", "make epub-endnotes", and "make html") derived from the
> ebook-size variant via TeX Live's lwarp package and Pandoc, without
> modifying any of the book's existing .tex or .sty files.
> 
> Overview of the pipeline:
> 
> - reflow.ltx hooks into the generated perfbook-epub.tex wrapper to adapt
>   print-oriented macros, listings, tables, figures, equations, footnotes,
>   Quick Quizzes, and cross-references for HTML/EPUB output.
> - Makefile stages SVG figures in parallel under epub-figs/ and invokes
>   utilities/runlwarp.sh to run lwarp, render math SVGs via lwarpmk,
>   package the chapter-split EPUB3 with Pandoc, and run structural
>   validation checks (plus epubcheck when installed).
> - utilities/epub-fixhtml.pl and utilities/epub.css perform post-Pandoc
>   XHTML/SVG/CSS adjustments tested in KOReader and Foliate, including
>   EPUB3 popup footnotes and Quick Quiz answers (and a plain endnote
>   variant in perfbook-endnotes.epub for readers without popup support).
> 
> This is an RFC so I would be happy to hear ideas how I can improve this
> experiment. Few things:
> 
> 1. Does this non-invasive lwarp + Pandoc approach look acceptable for
>    maintaining experimental EPUB support alongside the PDF builds?
> 2. Is it worth keeping both perfbook.epub (popup footnotes/quizzes) and
>    perfbook-endnotes.epub (linked chapter endnotes), or would a single
>    target be preferable?
> 3. Are the Dockerfile package additions and non-blocking GitLab CI job
>    (allow_failure: true) aligned with how you would like this tested?
> 
> AI: This RFC generated by language models and I verified the result on
> my physical epub reader and on Linux in Foliate and KOReader epub
> readers. I used several models and refined the set for months, and with
> the latest and greatest frontier I was unable to trim ot further. The downside
> of this work is that I cannot tell with full confidence this is the
> simplest form. With more knowledge it might be improved further.
> 
> I tried three approach to get to a working epub target:
> - tex4ht: it required heavy modifications of the already existing LaTeX
>   source so I abandoned this approach. After aroung 2k LoC change it was
>   able to produce a reasonable HTML and ePUB, but it was too intrusive
>   for my taste
> - lwrap (this one): this felt the best and required the least change
>   compared to the upstream. It hooks into the build flow in the right
>   spot so no changes required in the upstream LaTeX code
> - LateXML: this is what arXiv uses to compile the paper sources to HTML
>   and they improve it in quite a fast pace. This target was intrusive
>   and a reasonable looking output required many small changes in the
>   upstream source and what worse, in the LateXML toolchain. I abandoned
>   this approach as well
> These trials executed 2-3 months ago, and lwrap was the winner, but
> models might improved since making LateXML feasible. In the past months
> I only improved the lwrap based approach, resulting this RFC.

Sounds interesting!

That said, I couldn't complete "make epub" with debian/testing's TeX Live.

In perfbook-epub_html.log, there are a couple of warnings from lwarp
as follows:

-----
(/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
Package: fancyvrb 2026/08/13 4.7 verbatim text (tvz,hv)
\FV@CodeLineNo=\count416
\FV@InFile=\read5
\FV@TabBox=\box69
\c@FancyVerbLine=\count417
\FV@StepNumber=\count418
\FV@OutFile=\write7
)

Package lwarp Warning: A definition has changed:
(lwarp)                fancyvrb: \FV@ListProcessLine
(lwarp)                (9A9947A55E3D6D1C92E99F16EDC0BC68)
(lwarp)                 on input line 118.
-----

, and at the bottom of the log:

--------------------------------
Package verifycommand Warning: Definitions have changed.
Patches for the following macros may need to be updated.
See the previous warnings for line numbers.

Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
-----
(verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
                   (9A9947A55E3D6D1C92E99F16EDC0BC68)
-----
Look for updates to these packages.
--------------------------------

FYI, fancyvrb of upstream TeX Live is v4.8 released on
2026/10/20, which does not satisty lwarp ...

Which version of fancyvrb does lwarp expect?
("lwarpmk --version" says: lwarpmk: v0.922)

I tried debian/testing because lwarpmk in debian/latest
is v0.918.

Thanks, Akira

> 
> Thanks,
> Ferenc
> 
> Ferenc Fejes (7):
>   reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds
>   utilities: Add EPUB3 post-processor and stylesheet
>   utilities/runlwarp.sh: Add lwarp and Pandoc build driver
>   Makefile, .gitignore: Add epub and html build targets
>   epub: Add endnote variant for readers without popup footnotes
>   FAQ-BUILD.txt: Document HTML and EPUB build targets
>   docker, gitlab-ci: Add EPUB build dependencies and CI job
> 
>  .gitignore                |  14 ++
>  FAQ-BUILD.txt             |  45 ++++++
>  Makefile                  |  68 ++++++++-
>  docker/Dockerfile         |   2 +-
>  reflow.ltx                | 255 ++++++++++++++++++++++++++++++++
>  utilities/epub-fixhtml.pl |  93 ++++++++++++
>  utilities/epub.css        |  63 ++++++++
>  utilities/gitlab-ci.yml   |  17 +++
>  utilities/runlwarp.sh     | 299 ++++++++++++++++++++++++++++++++++++++
>  9 files changed, 852 insertions(+), 4 deletions(-)
>  create mode 100644 reflow.ltx
>  create mode 100755 utilities/epub-fixhtml.pl
>  create mode 100644 utilities/epub.css
>  create mode 100644 utilities/runlwarp.sh
> 
> 
> base-commit: 94d572e236ab8e26fa79ff0776a3bba221647315
> --
> 2.55.0


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-16  4:41 ` [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Akira Yokosawa
@ 2026-11-16 17:21   ` Ferenc Fejes
  2026-11-17  2:41     ` Akira Yokosawa
  0 siblings, 1 reply; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-16 17:21 UTC (permalink / raw)
  To: Akira Yokosawa, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

On Mon, 2026-11-16 at 13:41 +0900, Akira Yokosawa wrote:
> Hi!
> 
> On 11/16/26 06:01, Ferenc Fejes wrote:
> > Hi!
> > 
> > This RFC series adds experimental reflowable EPUB3 and HTML build
> > targets
> > ("make epub", "make epub-endnotes", and "make html") derived from
> > the
> > ebook-size variant via TeX Live's lwarp package and Pandoc, without
> > modifying any of the book's existing .tex or .sty files.
> > 
> > Overview of the pipeline:
> > 
> > - reflow.ltx hooks into the generated perfbook-epub.tex wrapper to
> > adapt
> >   print-oriented macros, listings, tables, figures, equations,
> > footnotes,
> >   Quick Quizzes, and cross-references for HTML/EPUB output.
> > - Makefile stages SVG figures in parallel under epub-figs/ and
> > invokes
> >   utilities/runlwarp.sh to run lwarp, render math SVGs via lwarpmk,
> >   package the chapter-split EPUB3 with Pandoc, and run structural
> >   validation checks (plus epubcheck when installed).
> > - utilities/epub-fixhtml.pl and utilities/epub.css perform post-
> > Pandoc
> >   XHTML/SVG/CSS adjustments tested in KOReader and Foliate,
> > including
> >   EPUB3 popup footnotes and Quick Quiz answers (and a plain endnote
> >   variant in perfbook-endnotes.epub for readers without popup
> > support).
> > 
> > This is an RFC so I would be happy to hear ideas how I can improve
> > this
> > experiment. Few things:
> > 
> > 1. Does this non-invasive lwarp + Pandoc approach look acceptable
> > for
> >    maintaining experimental EPUB support alongside the PDF builds?
> > 2. Is it worth keeping both perfbook.epub (popup footnotes/quizzes)
> > and
> >    perfbook-endnotes.epub (linked chapter endnotes), or would a
> > single
> >    target be preferable?
> > 3. Are the Dockerfile package additions and non-blocking GitLab CI
> > job
> >    (allow_failure: true) aligned with how you would like this
> > tested?
> > 
> > AI: This RFC generated by language models and I verified the result
> > on
> > my physical epub reader and on Linux in Foliate and KOReader epub
> > readers. I used several models and refined the set for months, and
> > with
> > the latest and greatest frontier I was unable to trim ot further.
> > The downside
> > of this work is that I cannot tell with full confidence this is the
> > simplest form. With more knowledge it might be improved further.
> > 
> > I tried three approach to get to a working epub target:
> > - tex4ht: it required heavy modifications of the already existing
> > LaTeX
> >   source so I abandoned this approach. After aroung 2k LoC change
> > it was
> >   able to produce a reasonable HTML and ePUB, but it was too
> > intrusive
> >   for my taste
> > - lwrap (this one): this felt the best and required the least
> > change
> >   compared to the upstream. It hooks into the build flow in the
> > right
> >   spot so no changes required in the upstream LaTeX code
> > - LateXML: this is what arXiv uses to compile the paper sources to
> > HTML
> >   and they improve it in quite a fast pace. This target was
> > intrusive
> >   and a reasonable looking output required many small changes in
> > the
> >   upstream source and what worse, in the LateXML toolchain. I
> > abandoned
> >   this approach as well
> > These trials executed 2-3 months ago, and lwrap was the winner, but
> > models might improved since making LateXML feasible. In the past
> > months
> > I only improved the lwrap based approach, resulting this RFC.
> 
> Sounds interesting!
> 
> That said, I couldn't complete "make epub" with debian/testing's TeX
> Live.

Sorry for that, I'm using Debian unstable which is a little bit ahead
of tasting. I compiled it on Ubuntu 26.04 as well, but AFAIR there I
have to install lwrap from source.

> 
> In perfbook-epub_html.log, there are a couple of warnings from lwarp
> as follows:
> 
> -----
> (/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
> Package: fancyvrb 2026/08/13 4.7 verbatim text (tvz,hv)
> \FV@CodeLineNo=\count416
> \FV@InFile=\read5
> \FV@TabBox=\box69
> \c@FancyVerbLine=\count417
> \FV@StepNumber=\count418
> \FV@OutFile=\write7
> )
> 
> Package lwarp Warning: A definition has changed:
> (lwarp)                fancyvrb: \FV@ListProcessLine
> (lwarp)                (9A9947A55E3D6D1C92E99F16EDC0BC68)
> (lwarp)                 on input line 118.
> -----
> 
> , and at the bottom of the log:
> 
> --------------------------------
> Package verifycommand Warning: Definitions have changed.
> Patches for the following macros may need to be updated.
> See the previous warnings for line numbers.
> 
> Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
> -----
> (verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
>                    (9A9947A55E3D6D1C92E99F16EDC0BC68)
> -----
> Look for updates to these packages.
> --------------------------------
> 
> FYI, fancyvrb of upstream TeX Live is v4.8 released on
> 2026/10/20, which does not satisty lwarp ...
> 
> Which version of fancyvrb does lwarp expect?
> ("lwarpmk --version" says: lwarpmk: v0.922)

Same for me: v0.922 like you have and 

share/doc/texlive-doc/latex/fancyvrb/Changes head say:
--- fancyvrb.sty
4.8  2026/10/20   - fix for line references with \cref

Its strange the same versions not working on your env. Will take a look
in debian testing docker and lets see if I can do something with it.

> 
> I tried debian/testing because lwarpmk in debian/latest
> is v0.918.

Here I have texlive-latex-recommended (2026.20261111-1) installed which
include compatible versions.

> 
> Thanks, Akira
> 
> > 
> > Thanks,
> > Ferenc
> > 
> > Ferenc Fejes (7):
> >   reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds
> >   utilities: Add EPUB3 post-processor and stylesheet
> >   utilities/runlwarp.sh: Add lwarp and Pandoc build driver
> >   Makefile, .gitignore: Add epub and html build targets
> >   epub: Add endnote variant for readers without popup footnotes
> >   FAQ-BUILD.txt: Document HTML and EPUB build targets
> >   docker, gitlab-ci: Add EPUB build dependencies and CI job
> > 
> >  .gitignore                |  14 ++
> >  FAQ-BUILD.txt             |  45 ++++++
> >  Makefile                  |  68 ++++++++-
> >  docker/Dockerfile         |   2 +-
> >  reflow.ltx                | 255 ++++++++++++++++++++++++++++++++
> >  utilities/epub-fixhtml.pl |  93 ++++++++++++
> >  utilities/epub.css        |  63 ++++++++
> >  utilities/gitlab-ci.yml   |  17 +++
> >  utilities/runlwarp.sh     | 299
> > ++++++++++++++++++++++++++++++++++++++
> >  9 files changed, 852 insertions(+), 4 deletions(-)
> >  create mode 100644 reflow.ltx
> >  create mode 100755 utilities/epub-fixhtml.pl
> >  create mode 100644 utilities/epub.css
> >  create mode 100644 utilities/runlwarp.sh
> > 
> > 
> > base-commit: 94d572e236ab8e26fa79ff0776a3bba221647315
> > --
> > 2.55.0
> 

Ferenc

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-16 17:21   ` Ferenc Fejes
@ 2026-11-17  2:41     ` Akira Yokosawa
  2026-11-17  9:44       ` Akira Yokosawa
  0 siblings, 1 reply; 14+ messages in thread
From: Akira Yokosawa @ 2026-11-17  2:41 UTC (permalink / raw)
  To: Ferenc Fejes, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

Hi,

On 11/17/26 02:21, Ferenc Fejes wrote:
> On Mon, 2026-11-16 at 13:41 +0900, Akira Yokosawa wrote:
[...]

>> That said, I couldn't complete "make epub" with debian/testing's TeX
>> Live.
> 
> Sorry for that, I'm using Debian unstable which is a little bit ahead
> of tasting. I compiled it on Ubuntu 26.04 as well, but AFAIR there I
> have to install lwrap from source.

Tested "make html" under debian/unstable.  It aborts with:

------------
[...]
LATEX=pdflatex sh utilities/runlwarp.sh perfbook-epub html
pdflatex -draftmode for perfbook-epub # lwarp wrapper generation
pdflatex -draftmode for perfbook-epub_html # HTML pass 1
----- glossary generation failed for perfbook-epub_html -----
make: *** [Makefile:701: perfbook-epub_html.html] Error 2
------------

So, build_glossary in runlwarp.sh returned error.

Can't you reproduce it?

> 
>>
>> In perfbook-epub_html.log, there are a couple of warnings from lwarp
>> as follows:
>>
>> -----
>> (/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
>> Package: fancyvrb 2026/08/13 4.7 verbatim text (tvz,hv)
>> \FV@CodeLineNo=\count416
>> \FV@InFile=\read5
>> \FV@TabBox=\box69
>> \c@FancyVerbLine=\count417
>> \FV@StepNumber=\count418
>> \FV@OutFile=\write7
>> )
>>
>> Package lwarp Warning: A definition has changed:
>> (lwarp)                fancyvrb: \FV@ListProcessLine
>> (lwarp)                (9A9947A55E3D6D1C92E99F16EDC0BC68)
>> (lwarp)                 on input line 118.
>> -----

I might have been confused by this warning.  This "Warning" is
actually an "Info"-level message from lwarp, isn't it?

>>
>> , and at the bottom of the log:
>>
>> --------------------------------
>> Package verifycommand Warning: Definitions have changed.
>> Patches for the following macros may need to be updated.
>> See the previous warnings for line numbers.
>>
>> Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
>> -----
>> (verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
>>                    (9A9947A55E3D6D1C92E99F16EDC0BC68)
>> -----
>> Look for updates to these packages.
>> --------------------------------

I have no idea if this warning from verifycommand can be ignored ...

In the log under debian/stable, this warning looks like this:

--------------------------------
Package verifycommand Warning: Definitions have changed.
Patches for the following macros may need to be updated.
See the previous warnings for line numbers.

Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
-----
(verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
                   (8FA4321A9DA36AB98D372ECA1C77A9A1)
(verifycommand)  lwarp -> siunitx: \siunitx_quantity:nn
                   (FF98A02B319EFF149546639C91E88F02)
-----
Look for updates to these packages.
--------------------------------

Thanks, Akira

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-17  2:41     ` Akira Yokosawa
@ 2026-11-17  9:44       ` Akira Yokosawa
  2026-11-18  3:55         ` Ferenc Fejes
  0 siblings, 1 reply; 14+ messages in thread
From: Akira Yokosawa @ 2026-11-17  9:44 UTC (permalink / raw)
  To: Ferenc Fejes, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

On 11/17/26 11:41, Akira Yokosawa wrote:
> Hi,
> 
> On 11/17/26 02:21, Ferenc Fejes wrote:
>> On Mon, 2026-11-16 at 13:41 +0900, Akira Yokosawa wrote:
> [...]
> 
>>> That said, I couldn't complete "make epub" with debian/testing's TeX
>>> Live.
>>
>> Sorry for that, I'm using Debian unstable which is a little bit ahead
>> of tasting. I compiled it on Ubuntu 26.04 as well, but AFAIR there I
>> have to install lwrap from source.
> 
> Tested "make html" under debian/unstable.  It aborts with:
> 
> ------------
> [...]
> LATEX=pdflatex sh utilities/runlwarp.sh perfbook-epub html
> pdflatex -draftmode for perfbook-epub # lwarp wrapper generation
> pdflatex -draftmode for perfbook-epub_html # HTML pass 1
> ----- glossary generation failed for perfbook-epub_html -----
> make: *** [Makefile:701: perfbook-epub_html.html] Error 2
> ------------
> 
> So, build_glossary in runlwarp.sh returned error.
> 
> Can't you reproduce it?
> 
>>
>>>
>>> In perfbook-epub_html.log, there are a couple of warnings from lwarp
>>> as follows:
>>>
>>> -----
>>> (/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
>>> Package: fancyvrb 2026/08/13 4.7 verbatim text (tvz,hv)
>>> \FV@CodeLineNo=\count416
>>> \FV@InFile=\read5
>>> \FV@TabBox=\box69
>>> \c@FancyVerbLine=\count417
>>> \FV@StepNumber=\count418
>>> \FV@OutFile=\write7
>>> )
>>>
>>> Package lwarp Warning: A definition has changed:
>>> (lwarp)                fancyvrb: \FV@ListProcessLine
>>> (lwarp)                (9A9947A55E3D6D1C92E99F16EDC0BC68)
>>> (lwarp)                 on input line 118.
>>> -----
> 
> I might have been confused by this warning.  This "Warning" is
> actually an "Info"-level message from lwarp, isn't it?
> 
>>>
>>> , and at the bottom of the log:
>>>
>>> --------------------------------
>>> Package verifycommand Warning: Definitions have changed.
>>> Patches for the following macros may need to be updated.
>>> See the previous warnings for line numbers.
>>>
>>> Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
>>> -----
>>> (verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
>>>                    (9A9947A55E3D6D1C92E99F16EDC0BC68)
>>> -----
>>> Look for updates to these packages.
>>> --------------------------------
> 
> I have no idea if this warning from verifycommand can be ignored ...
> 
> In the log under debian/stable, this warning looks like this:

I meant            debian/unstable

Akira

> 
> --------------------------------
> Package verifycommand Warning: Definitions have changed.
> Patches for the following macros may need to be updated.
> See the previous warnings for line numbers.
> 
> Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
> -----
> (verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
>                    (8FA4321A9DA36AB98D372ECA1C77A9A1)
> (verifycommand)  lwarp -> siunitx: \siunitx_quantity:nn
>                    (FF98A02B319EFF149546639C91E88F02)
> -----
> Look for updates to these packages.
> --------------------------------
> 
> Thanks, Akira

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-17  9:44       ` Akira Yokosawa
@ 2026-11-18  3:55         ` Ferenc Fejes
  2026-11-18 10:32           ` Akira Yokosawa
  0 siblings, 1 reply; 14+ messages in thread
From: Ferenc Fejes @ 2026-11-18  3:55 UTC (permalink / raw)
  To: Akira Yokosawa, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

Hi,

On Tue, 2026-11-17 at 18:44 +0900, Akira Yokosawa wrote:
> On 11/17/26 11:41, Akira Yokosawa wrote:
> > Hi,
> > 
> > On 11/17/26 02:21, Ferenc Fejes wrote:
> > > On Mon, 2026-11-16 at 13:41 +0900, Akira Yokosawa wrote:
> > [...]
> > 
> > > > That said, I couldn't complete "make epub" with
> > > > debian/testing's TeX
> > > > Live.
> > > 
> > > Sorry for that, I'm using Debian unstable which is a little bit
> > > ahead
> > > of tasting. I compiled it on Ubuntu 26.04 as well, but AFAIR
> > > there I
> > > have to install lwrap from source.
> > 
> > Tested "make html" under debian/unstable.  It aborts with:
> > 
> > ------------
> > [...]
> > LATEX=pdflatex sh utilities/runlwarp.sh perfbook-epub html
> > pdflatex -draftmode for perfbook-epub # lwarp wrapper generation
> > pdflatex -draftmode for perfbook-epub_html # HTML pass 1
> > ----- glossary generation failed for perfbook-epub_html -----
> > make: *** [Makefile:701: perfbook-epub_html.html] Error 2
> > ------------
> > 
> > So, build_glossary in runlwarp.sh returned error.
> > 
> > Can't you reproduce it?

Unfortunately I cannot reproduce it. It builds cleanly both on my
machine and with a small docker build I put together. Its a bit
complicated because I dont wanted to install and configure docker on my
machine, nor put an alternative texlive on to my disk. But feel free to
use only the docker file and build the image with docker, if you have
it installed already.

Here I use podman, the script grab a pre-built binary from github,
build the dockerfile to a debian:unstable container then build the epub
target. It works within the /tmp folder,  I put here the content of
both file s/verbatim:

Dockerfile.debian-unstable

FROM docker.io/library/debian:unstable

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates locales tzdata && \
    localedef -i en_US -c -f UTF-8 en_US.UTF-8 && \
    rm -rf /var/lib/apt/lists/*
ENV LANG=en_US.utf8

RUN apt-get update && apt-get install -y --no-install-recommends \
    fig2ps inkscape xfig graphviz psutils \
    texlive-publishers texlive-pstricks texlive-science texlive-fonts-
extra \
    texlive-latex-extra texlive-lang-japanese tex-gyre xindy \
    make git gnuplot-nox time poppler-utils librsvg2-bin pandoc unzip
zip \
    fontconfig fonts-freefont-ttf fonts-dejavu-core fonts-liberation &&
\
    rm -rf /var/lib/apt/lists/*

COPY steel-city-comic.regular.ttf /usr/local/share/fonts/
RUN fc-cache /usr/local/share/fonts/

WORKDIR /work
CMD ["/bin/bash"]



And the build script (which also have a clean argument to delete the
whole image, containers etc.). Again, this is optional, makes things
easier if you dont have docker installed and do not want to install for
this experiment.

#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
#
# Build perfbook EPUB inside a disposable rootless Debian unstable
Podman
# container, keeping podman-static, container storage, and the build
tree
# under /tmp (tmpfs) to avoid writing to SSD.
#
# Usage: ./docker/build-epub-podman.sh [branch] [make-target]
#        ./docker/build-epub-podman.sh clean
#   Defaults: branch=epub-rfc, make-target=epub

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

BRANCH="${1:-epub-rfc}"
TARGET="${2:-epub}"

PODMAN_BASE="/tmp/podman-static/podman-linux-amd64"
PODMAN_BIN="$PODMAN_BASE/usr/local/bin/podman"
BUILD_DIR="/tmp/perfbook-build"
IMAGE_NAME="perfbook-debian-unstable"

export
PATH="$PODMAN_BASE/usr/local/bin:$PODMAN_BASE/usr/local/lib/podman:$PAT
H"
export XDG_CONFIG_HOME="/tmp/podman-cfg"
export XDG_DATA_HOME="/tmp/podman-data"
export XDG_RUNTIME_DIR="/tmp/podman-run"
export TMPDIR="/tmp/podman-tmp"
export CONTAINERS_CONF="$XDG_CONFIG_HOME/containers/containers.conf"
export CONTAINERS_POLICY="$XDG_CONFIG_HOME/containers/policy.json"
export
CONTAINERS_REGISTRIES_CONF="$XDG_CONFIG_HOME/containers/registries.conf
"

if [ "$BRANCH" = "clean" ]; then
    echo "==> Cleaning up /tmp podman and build artifacts..."
    if [ -x "$PODMAN_BIN" ]; then
        "$PODMAN_BIN" --root=/tmp/podman-root --
runroot="$XDG_RUNTIME_DIR" \
            unshare rm -rf /tmp/podman-root "$XDG_RUNTIME_DIR"
"$XDG_DATA_HOME" 2>/dev/null || true
    fi
    rm -rf /tmp/podman-static /tmp/podman-root "$XDG_RUNTIME_DIR" \
        "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$TMPDIR" "$BUILD_DIR"
    echo "==> Clean complete."
    exit 0
fi

if [ ! -x "$PODMAN_BIN" ]; then
    echo "==> Downloading and configuring podman-static in /tmp..."
    mkdir -p /tmp/podman-static /tmp/podman-root "$XDG_RUNTIME_DIR" \
        "$XDG_CONFIG_HOME/containers" "$XDG_DATA_HOME" "$TMPDIR"

    curl -fsSL
"https://github.com/mgoltzsche/podman-static/releases/latest/download/podman-linux-amd64.tar.gz
" \
        | tar -xz -C /tmp/podman-static
else
    mkdir -p /tmp/podman-root "$XDG_RUNTIME_DIR" \
        "$XDG_CONFIG_HOME/containers" "$XDG_DATA_HOME" "$TMPDIR"
fi

cp -r "$PODMAN_BASE/etc/containers/"* "$XDG_CONFIG_HOME/containers/"
cat <<EOF >> "$CONTAINERS_CONF"
helper_binaries_dir = ["$PODMAN_BASE/usr/local/lib/podman",
"$PODMAN_BASE/usr/local/bin"]
EOF

PODMAN=("$PODMAN_BIN" --root=/tmp/podman-root --
runroot="$XDG_RUNTIME_DIR")

echo "==> Cloning repository ($BRANCH -> $BUILD_DIR)..."
rm -rf "$BUILD_DIR"
git clone --no-hardlinks --branch "$BRANCH" "$REPO_ROOT" "$BUILD_DIR"

echo "==> Building Debian unstable container image ($IMAGE_NAME)..."
"${PODMAN[@]}" build \
    -t "$IMAGE_NAME" \
    -f "$SCRIPT_DIR/Dockerfile.debian-unstable" \
    "$SCRIPT_DIR"

echo "==> Running make -j$(nproc) $TARGET in container..."
"${PODMAN[@]}" run --rm \
    -v "$BUILD_DIR:/work" \
    -w /work \
    "$IMAGE_NAME" \
    make -j"$(nproc)" "$TARGET"

echo "==> Done: $BUILD_DIR/perfbook.epub"


> > 
> > > 
> > > > 
> > > > In perfbook-epub_html.log, there are a couple of warnings from
> > > > lwarp
> > > > as follows:
> > > > 
> > > > -----
> > > > (/usr/share/texlive/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
> > > > Package: fancyvrb 2026/08/13 4.7 verbatim text (tvz,hv)
> > > > \FV@CodeLineNo=\count416
> > > > \FV@InFile=\read5
> > > > \FV@TabBox=\box69
> > > > \c@FancyVerbLine=\count417
> > > > \FV@StepNumber=\count418
> > > > \FV@OutFile=\write7
> > > > )
> > > > 
> > > > Package lwarp Warning: A definition has changed:
> > > > (lwarp)                fancyvrb: \FV@ListProcessLine
> > > > (lwarp)                (9A9947A55E3D6D1C92E99F16EDC0BC68)
> > > > (lwarp)                 on input line 118.
> > > > -----
> > 
> > I might have been confused by this warning.  This "Warning" is
> > actually an "Info"-level message from lwarp, isn't it?
> > 
> > > > 
> > > > , and at the bottom of the log:
> > > > 
> > > > --------------------------------
> > > > Package verifycommand Warning: Definitions have changed.
> > > > Patches for the following macros may need to be updated.
> > > > See the previous warnings for line numbers.
> > > > 
> > > > Syntax:  Patching pkg -> Defining pkg: Macro (checksum)
> > > > -----
> > > > (verifycommand)  lwarp -> fancyvrb: \FV@ListProcessLine
> > > >                    (9A9947A55E3D6D1C92E99F16EDC0BC68)
> > > > -----
> > > > Look for updates to these packages.
> > > > --------------------------------
> > 
> > I have no idea if this warning from verifycommand can be ignored
> > ...
> > 
> > In the log under debian/stable, this warning looks like this:
> 
> I meant            debian/unstable
> 
> Akira

I still concerned about why not build cleanly on your env. Cant you
have some local modifications/patches in the latex packages provided by
debian?

Oh and here is my fork to make things easier:
https://github.com/SPYFF/perfbook/tree/epub-rfc

Best,
Ferenc

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target
  2026-11-18  3:55         ` Ferenc Fejes
@ 2026-11-18 10:32           ` Akira Yokosawa
  0 siblings, 0 replies; 14+ messages in thread
From: Akira Yokosawa @ 2026-11-18 10:32 UTC (permalink / raw)
  To: Ferenc Fejes, perfbook; +Cc: Paul E . McKenney, Leonardo Bras

On Wed, 18 Nov 2026 04:55:54 +0100, Ferenc Fejes wrote:
> Hi,
> 
> On Tue, 2026-11-17 at 18:44 +0900, Akira Yokosawa wrote:
>> On 11/17/26 11:41, Akira Yokosawa wrote:
[...]

>>> So, build_glossary in runlwarp.sh returned error.
>>>
>>> Can't you reproduce it?
> 
> Unfortunately I cannot reproduce it. It builds cleanly both on my
> machine and with a small docker build I put together. Its a bit
> complicated because I dont wanted to install and configure docker on my
> machine, nor put an alternative texlive on to my disk. But feel free to
> use only the docker file and build the image with docker, if you have
> it installed already.
> 
> Here I use podman, the script grab a pre-built binary from github,
> build the dockerfile to a debian:unstable container then build the epub
> target. It works within the /tmp folder,  I put here the content of
> both file s/verbatim:
> 
> Dockerfile.debian-unstable
> 
> FROM docker.io/library/debian:unstable
> 
> ENV DEBIAN_FRONTEND=noninteractive
> RUN apt-get update && apt-get install -y --no-install-recommends \
>     ca-certificates locales tzdata && \
>     localedef -i en_US -c -f UTF-8 en_US.UTF-8 && \
>     rm -rf /var/lib/apt/lists/*
> ENV LANG=en_US.utf8
> 
> RUN apt-get update && apt-get install -y --no-install-recommends \
>     fig2ps inkscape xfig graphviz psutils \
>     texlive-publishers texlive-pstricks texlive-science texlive-fonts-
> extra \
>     texlive-latex-extra texlive-lang-japanese tex-gyre xindy \

Wait!  There is no mention of xindy anywhere in your changes ...

"make html" and "make epub" complete on my side after I added xindy
in the prereq list.

Now I can build and inspect HTML and EPUB output.

Thanks!

Akira

[...]

^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2026-11-18 10:33 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-15 21:01 [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 1/7] reflow.ltx: Add LaTeX-to-HTML shims for lwarp builds Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 2/7] utilities: Add EPUB3 post-processor and stylesheet Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 3/7] utilities/runlwarp.sh: Add lwarp and Pandoc build driver Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 4/7] Makefile, .gitignore: Add epub and html build targets Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 5/7] epub: Add endnote variant for readers without popup footnotes Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 6/7] FAQ-BUILD.txt: Document HTML and EPUB build targets Ferenc Fejes
2026-11-15 21:01 ` [RFC PATCH 7/7] docker, gitlab-ci: Add EPUB build dependencies and CI job Ferenc Fejes
2026-11-16  4:41 ` [RFC PATCH 0/7] Add reflowable HTML and EPUB3 build target Akira Yokosawa
2026-11-16 17:21   ` Ferenc Fejes
2026-11-17  2:41     ` Akira Yokosawa
2026-11-17  9:44       ` Akira Yokosawa
2026-11-18  3:55         ` Ferenc Fejes
2026-11-18 10:32           ` Akira Yokosawa

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.