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

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.